| |
commit a03ab3b4988f47237fbd3dabe1b6cbdbb9b03fde
Author: Albrecht Schlosser <albrechts.fltk@online.de>
AuthorDate: Sun Nov 8 15:43:34 2020 +0100
Commit: Albrecht Schlosser <albrechts.fltk@online.de>
CommitDate: Sun Nov 8 15:43:34 2020 +0100
Clarify offscreen drawing documentation
... and rename drawing chapters (sections + subsections) according
to our documentation conventions (prefix "drawing_").
documentation/make_pdf: fix copyright year.
documentation/make_pdf | 2 +-
documentation/src/common.dox | 4 +-
documentation/src/drawing.dox | 134 +++++++++++++++++++++++---------------
documentation/src/opengl.dox | 4 +-
documentation/src/osissues.dox | 6 +-
documentation/src/subclassing.dox | 2 +-
6 files changed, 89 insertions(+), 63 deletions(-)
diff --git documentation/make_pdf documentation/make_pdf
index 7580cb1..a5487ba 100755
--- documentation/make_pdf
+++ documentation/make_pdf
@@ -2,7 +2,7 @@
#
# Makefile helper script for the Fast Light Tool Kit (FLTK) documentation.
#
-# Copyright 1998-2015 by Bill Spitzak and others.
+# Copyright 1998-2020 by Bill Spitzak and others.
#
# This library is free software. Distribution and use rights are outlined in
# the file "COPYING" which should have been included with this file. If this
diff --git documentation/src/common.dox documentation/src/common.dox
index 4f7a590..96880b6 100644
--- documentation/src/common.dox
+++ documentation/src/common.dox
@@ -441,7 +441,7 @@ image that is shown when the widget is inactive, while the \p image()
method sets the image that is shown when the widget is active.
To make an image you use a subclass of
-\ref ssect_Fl_Image "Fl_Image".
+\ref drawing_Fl_Image "Fl_Image".
\par Making Your Own Label Types
@@ -509,7 +509,7 @@ any label.
To create a new symbol, you implement a drawing function
<tt>void drawit(Fl_Color c)</tt> which typically uses the
-functions described in \ref ssect_Complex
+functions described in \ref drawing_complex
to generate a vector shape inside a two-by-two units sized box
around the origin. This function is then linked into the symbols
table using fl_add_symbol():
diff --git documentation/src/drawing.dox documentation/src/drawing.dox
index 3ec17d6..8476478 100644
--- documentation/src/drawing.dox
+++ documentation/src/drawing.dox
@@ -4,7 +4,7 @@
This chapter covers the drawing functions that are provided with FLTK.
-\section sect_WhenCanYouDraw When Can You Draw Things in FLTK?
+\section drawing_WhenCanYouDraw When Can You Draw Things in FLTK?
There are only certain places you can execute FLTK code
that draws to the computer's display.
@@ -35,20 +35,20 @@ these will operate on the new current drawing surface;
Fl_Surface_Device::pop_current().
</ol>
-\subsection ssect_DrawingUnit What Drawing Unit do FLTK drawing functions use?
+\section drawing_DrawingUnit What Drawing Units Do FLTK Drawing Functions Use?
-Before version 1.4, all graphical quantities used by FLTK are in pixel units:
-a window of width 500 units is 500-pixel wide, a line of length 10 units is
-10-pixel long, lines of text written using a 14-point font are 14 pixels below
-each other. This organization is not sufficient to support GUI apps that can be drawn on
-screens of varying pixel density, especially on High-DPI screens, because
+Before version 1.4 all graphical quantities used by FLTK were in pixel units:
+a window of width 500 units was 500 pixels wide, a line of length 10 units was
+10 pixels long, lines of text written using a 14-point font were 14 pixels below
+each other. This organization is not sufficient to support GUI apps that can be
+drawn on screens of varying pixel density, especially on High-DPI screens, because
widgets become very small and text becomes unreadable.
FLTK version 1.4 introduces a new feature, a screen-specific <b>scale factor</b> which is
a float number with a typical value in the 1-2.5 range and is used as follows: any graphical
element with an FLTK value of \e v units is drawn on the screen with \e v * \e scale units.
-Thus, a window with width 500 units is 500*scale-pixel wide, a line of length 10 units is
-10*scale-pixel long, lines of text written using a 14-point font are 14*scale pixels below
+Thus, a window with width 500 units is 500*scale pixels wide, a line of length 10 units is
+10*scale pixels long, lines of text written using a 14-point font are 14*scale pixels below
each other. Consider a system with two screens, one with regular DPI and one with
a twice higher DPI. If the first screen's scale factor is set to 1 and that of the
second screen to 2, the GUI of any FLTK app appears equally sized on the two screens.
@@ -60,12 +60,14 @@ clipping regions) are in <b>FLTK units</b> which are both system- and DPI-indepe
expressed in FLTK units by the current value of the scale factor
for the screen in use and obtains quantities in <b>drawing units</b>.
The current scale factor value, for an Fl_Window named \e window, is given by
+
\code
-int nscreen = window->screen_num(); // the screen where window is mapped
-float s = Fl::screen_scale(nscreen); // this screen's scale factor
+ int nscreen = window->screen_num(); // the screen where window is mapped
+ float s = Fl::screen_scale(nscreen); // this screen's scale factor
\endcode
-One drawing unit generally corresponds to one screen pixel...
-<li>...but not on Mac OS X and for retina displays, where one drawing unit corresponds
+
+One drawing unit generally corresponds to one screen pixel ...
+<li>... but not on macOS and for retina displays, where one drawing unit corresponds
to two pixels.
</ul>
@@ -79,7 +81,7 @@ it's possible to set the
it's possible to change the scale factor value of any screen at run time
with ctrl/+/-/0/ keystrokes which enlarge, shrink, and reset, respectively,
all FLTK windows on a screen and their content.
-Under Mac OS X, the corresponding GUI scaling shortcuts are â??/+/-/0/.
+Under macOS, the corresponding GUI scaling shortcuts are â??/+/-/0/.
GUI rescaling involves also image drawing: the screen area covered by the drawn image
contains a number of pixels that grows with the scale factor. When FLTK draws images,
@@ -107,28 +109,28 @@ When drawing to Fl_Printer or Fl_PostScript_File_Device, the drawing unit
is initially one point, that is, 1/72 of an inch. This unit is changed
by calls to Fl_Paged_Device::scale().
-\section sect_DrawingFunctions Drawing Functions
+\section drawing_DrawingFunctions Drawing Functions
To use the drawing functions you must first include the <FL/fl_draw.H>
header file. FLTK provides the following types of drawing functions:
-\li \ref ssect_Boxes
-\li \ref ssect_Clipping
+\li \ref drawing_boxes
+\li \ref drawing_clipping
\li \ref drawing_colors
-\li \ref ssect_Lines
-\li \ref ssect_Fast
-\li \ref ssect_Complex
-\li \ref ssect_Text
-\li \ref ssect_Fonts
-\li \ref ssect_CharacterEncoding
-\li \ref ssect_Overlay
+\li \ref drawing_lines
+\li \ref drawing_fast
+\li \ref drawing_complex
+\li \ref drawing_text
+\li \ref drawing_fonts
+\li \ref drawing_character_encoding
+\li \ref drawing_overlay
\li \ref drawing_images
-\li \ref ssect_DirectImageDrawing
-\li \ref ssect_DirectImageReading
-\li \ref ssect_Fl_Image
-\li \ref ssect_Offscreen
+\li \ref drawing_direct_image_drawing
+\li \ref drawing_direct_image_reading
+\li \ref drawing_Fl_Image
+\li \ref drawing_offscreen
-\subsection ssect_Boxes Boxes
+\subsection drawing_boxes Boxes
FLTK provides three functions that can be used to draw boxes for buttons
and other UI controls. Each function uses the supplied upper-lefthand corner
@@ -166,12 +168,12 @@ Note that
is described in the \ref common_boxtypes section.
-\subsection ssect_Clipping Clipping
+\subsection drawing_clipping Clipping
You can limit all your drawing to a rectangular region by calling
\p %fl_push_clip(), and put the drawings back by using
\p %fl_pop_clip().
-This rectangle is measured in \ref ssect_DrawingUnit "FLTK units" and is unaffected by the current
+This rectangle is measured in \ref drawing_DrawingUnit "FLTK units" and is unaffected by the current
transformation matrix.
In addition, the system may provide clipping when updating windows
@@ -235,7 +237,7 @@ Fl_Region is an operating system specific type. The second form returns
the current clipping region.
-\section drawing_colors Colors
+\subsection drawing_colors Colors
FLTK manages colors as 32-bit unsigned integers, encoded as RGBI.
When the "RGB" bytes are non-zero, the value is treated as RGB.
@@ -362,7 +364,7 @@ button->color(0xffffff00); // RGB: white
If TrueColor is not available, any RGB colors will be set to
the nearest entry in the colormap.
-\subsection ssect_Lines Line Dashes and Thickness
+\subsection drawing_lines Line Dashes and Thickness
FLTK supports drawing of lines with different styles and
widths. Full functionality is not available under Windows 95, 98,
@@ -403,13 +405,13 @@ system-defined default of whatever value is fastest.
\li <tt>FL_JOIN_BEVEL</tt> (flat)
\par
-\p width is the number of \ref ssect_DrawingUnit "FLTK units" thick to draw the lines.
+\p width is the number of \ref drawing_DrawingUnit "FLTK units" thick to draw the lines.
Zero results in the system-defined default, which on both X and
Windows is somewhat different and nicer than 1.
\par
\p dashes is a pointer to an array of dash lengths, measured in
-\ref ssect_DrawingUnit "FLTK units". The first location is how long to draw a solid portion, the
+\ref drawing_DrawingUnit "FLTK units". The first location is how long to draw a solid portion, the
next is how long to draw the gap, then the solid, etc. It is
terminated with a zero-length entry. A \p NULL pointer or a zero-length
array results in a solid line. Odd array sizes are not supported and
@@ -421,13 +423,13 @@ The dashes array does not work under Windows 95, 98, or Me, since those
operating systems do not support complex line styles.
-\subsection ssect_Fast Drawing Fast Shapes
+\subsection drawing_fast Drawing Fast Shapes
These functions are used to draw almost all the FLTK widgets.
They draw on exact pixel boundaries and are as fast as possible.
Their behavior is duplicated exactly on all platforms FLTK is
ported. It is undefined whether these are affected by the
-\ref ssect_Complex "transformation matrix",
+\ref drawing_complex "transformation matrix",
so you should only call these while the matrix is set to the
identity matrix (the default).
@@ -530,11 +532,11 @@ void \ref fl_scroll(int X, int Y, int W, int H, int dx, int dy, void (*draw_area
\par
Scroll a rectangle and draw the newly exposed portions. The contents
of the rectangular area is first shifted by \p dx and
-\p dy \ref ssect_DrawingUnit "FLTK units". The callback is then called for every newly
+\p dy \ref drawing_DrawingUnit "FLTK units". The callback is then called for every newly
exposed rectangular area,
-\subsection ssect_Complex Drawing Complex Shapes
+\subsection drawing_complex Drawing Complex Shapes
The complex drawing functions let you draw arbitrary shapes
with 2-D linear transformations. The functionality matches that
@@ -669,7 +671,7 @@ a circle as part of a complex polygon you must use \p %fl_arc().
\p %fl_circle() draws incorrectly if the transformation is both rotated and
non-square scaled.
-\subsection ssect_Text Drawing Text
+\subsection drawing_text Drawing Text
All text is drawn in the
\ref drawing_fl_font "current font".
@@ -767,7 +769,7 @@ Determines the minimum dimensions of a nul-terminated string,
ie. the 'inked area'.
\par
Given a string "txt" drawn using fl_draw(txt, x, y) you would determine
-its extents in \ref ssect_DrawingUnit "FLTK units" on the display using fl_text_extents(txt, dx, dy, wo, ho)
+its extents in \ref drawing_DrawingUnit "FLTK units" on the display using fl_text_extents(txt, dx, dy, wo, ho)
such that a bounding box that exactly fits around the inked area of the text
could be drawn with fl_rect(x+dx, y+dy, wo, ho).
\par
@@ -786,7 +788,7 @@ key. If the shortcut is zero an empty string is returned. The
return value points at a static buffer that is overwritten with
each call.
-\subsection ssect_Fonts Fonts
+\subsection drawing_fonts Fonts
FLTK supports a set of standard fonts based on the Times,
Helvetica/Arial, Courier, and Symbol typefaces, as well as
@@ -821,7 +823,7 @@ the display.
\par
The font is identified by a \p face and a \p size.
-The size of the font is measured in \ref ssect_DrawingUnit "FLTK units" and not "points".
+The size of the font is measured in \ref drawing_DrawingUnit "FLTK units" and not "points".
Lines should be spaced \p size FLTK units apart or more.
int fl_font() <br>
@@ -831,7 +833,7 @@ int fl_size()
Returns the face and size set by the most recent call to
\p fl_font(a,b). This can be used to save/restore the font.
-\subsection ssect_CharacterEncoding Character Encoding
+\subsection drawing_character_encoding Character Encoding
FLTK 1.3 expects all text in Unicode UTF-8 encoding. UTF-8 is
ASCII compatible for the first 128 characters. International
@@ -855,7 +857,7 @@ left-to-right scripts only.
For more information about character encodings, see the chapter on
\ref unicode.
-\subsection ssect_Overlay Drawing Overlays
+\subsection drawing_overlay Drawing Overlays
These functions allow you to draw interactive selection rectangles
without using the overlay hardware. FLTK will XOR a single rectangle
@@ -890,7 +892,7 @@ advantage of using the object is that FLTK will cache translated
forms of the image (on X it uses a server pixmap) and thus
redrawing is \e much faster.
-\subsection ssect_DirectImageDrawing Direct Image Drawing
+\subsection drawing_direct_image_drawing Direct Image Drawing
The behavior when drawing images when the current
transformation matrix is not the identity is not defined, so you
@@ -1010,7 +1012,7 @@ function finds and returns the width and height. The return
value is non-zero if the dimensions were parsed ok and zero if
there was any problem.
-\subsection ssect_DirectImageReading Direct Image Reading
+\subsection drawing_direct_image_reading Direct Image Reading
FLTK provides a single function for reading from the current
window or off-screen buffer into a RGB(A) image buffer.
@@ -1030,7 +1032,7 @@ The \p alpha parameter controls whether an alpha
channel is created and the value that is placed in the alpha
channel. If 0, no alpha channel is generated.
-\subsection ssect_Fl_Image Image Classes
+\subsection drawing_Fl_Image Image Classes
FLTK provides a base image class called Fl_Image which supports
creating, copying, and drawing images of various kinds, along
@@ -1124,21 +1126,47 @@ Draws the image with the upper-left corner at <tt>x, y</tt>.
This is the same as doing <tt>img->draw(x, y, img->w(), img->h(), 0, 0)</tt>
where img is a pointer to any Fl_Image type.
-\subsection ssect_Offscreen Offscreen Drawing
+\section drawing_offscreen Offscreen Drawing
Sometimes it can be very useful to generate a complex drawing
in memory first and copy it to the screen at a later point in
time. This technique can significantly reduce the amount of repeated
drawing. Offscreen drawing functions are declared in <FL/fl_draw.H>.
-Fl_Double_Window uses offscreen rendering to avoid flickering on
-systems that don't support double-buffering natively.
+Fl_Double_Window uses offscreen rendering to avoid flickering on systems
+that don't support double-buffering natively.
+
+FLTK can draw into an offscreen buffer at any time. There is no need to
+wait for an Fl_Widget::draw() to occur.
+
+\note In FLTK 1.3.x and earlier versions all offscreen drawing functions
+described below were implemented as macros and created certain temporary
+variables to save context information. You needed to create local scope
+blocks with curly braces { ... } if you used offscreen functions more than
+once in a function or method. This is no longer necessary since offscreen
+drawing is now implemented in real functions (no macros).
+
+Example:
+\code
+ Fl_Offscreen oscr = fl_create_offscreen(120, 120);
+ fl_begin_offscreen(oscr);
+ fl_color(FL_WHITE);
+ fl_rectf(0, 0, 120, 120);
+ fl_end_offscreen();
+ // other code here
+ fl_begin_offscreen(oscr);
+ fl_color(FL_BLACK);
+ fl_rectf(10, 10, 100, 100);
+ fl_end_offscreen();
+ // other code here
+ fl_delete_offscreen(oscr);
+\endcode
Fl_Offscreen fl_create_offscreen(int w, int h)
\par
Create an RGB offscreen buffer containing as many pixels as in a screen area
-of size \p w,h \ref ssect_DrawingUnit "FLTK units".
+of size \p w,h \ref drawing_DrawingUnit "FLTK units".
void fl_delete_offscreen(Fl_Offscreen)
@@ -1149,8 +1177,6 @@ void fl_begin_offscreen(Fl_Offscreen)
\par
Send all subsequent drawing commands to this offscreen buffer.
-FLTK can draw into a buffer at any time. There is no need to wait for
-an Fl_Widget::draw() to occur.
void fl_end_offscreen()
diff --git documentation/src/opengl.dox documentation/src/opengl.dox
index 9d727d8..793b983 100644
--- documentation/src/opengl.dox
+++ documentation/src/opengl.dox
@@ -283,7 +283,7 @@ void gl_font(Fl_Font fontid, int size)
\par
Sets the current OpenGL font to the same font you get by calling
-\ref ssect_Fonts "fl_font()".
+\ref drawing_fonts "fl_font()".
int gl_height() <br>
int gl_descent() <br>
@@ -317,7 +317,7 @@ void gl_draw(const char *s, int x, int y, int w, int h, Fl_Align)
Draws a string formatted into a box, with newlines and tabs
expanded, other control characters changed to ^X, and aligned
with the edges or center. Exactly the same output as
-\ref ssect_Text "fl_draw()".
+\ref drawing_text "fl_draw()".
\section opengl_speed Speeding up OpenGL
diff --git documentation/src/osissues.dox documentation/src/osissues.dox
index d629acf..069d797 100644
--- documentation/src/osissues.dox
+++ documentation/src/osissues.dox
@@ -162,10 +162,10 @@ extern XFontStruct *fl_xfont
\par
Points to the font selected by the most recent
-\ref ssect_Fonts "fl_font()".
+\ref drawing_fonts "fl_font()".
This is not necessarily the current font of \c fl_gc,
which is not set until
-\ref ssect_Text "fl_draw()"
+\ref drawing_text "fl_draw()"
is called. If FLTK was compiled with Xft support, \c fl_xfont
will usually be 0 and \c fl_xftfont will contain a pointer
to the \c XftFont structure instead.
@@ -175,7 +175,7 @@ extern void *fl_xftfont
\par
If FLTK was compiled with Xft support enabled, \c fl_xftfont
points to the xft font selected by the most recent
-\ref ssect_Fonts "fl_font()".
+\ref drawing_fonts "fl_font()".
Otherwise it will be 0. \c fl_xftfont should be cast to
<tt>XftFont*</tt>.
diff --git documentation/src/subclassing.dox documentation/src/subclassing.dox
index f2a4147..4834731 100644
--- documentation/src/subclassing.dox
+++ documentation/src/subclassing.dox
@@ -330,7 +330,7 @@ be redrawn, e.g. for an expose event.
Expose events (and the
\ref subclassing_damage "damage(mask,x,y,w,h)" function described
above) will cause \p draw() to be called with FLTK's
-\ref ssect_Clipping "clipping"
+\ref drawing_clipping "clipping"
turned on. You can greatly speed up redrawing in some
cases by testing \p fl_not_clipped(x,y,w,h) or \p %fl_clip_box()
and skipping invisible parts.
[ Direct Link to Message ] | |
