From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. Converted the descriptive chapters of the html docs to doxygen format and modified index.dox accordingly. This checkin includes only trivial reformatting, no major rewriting. Added a chapter "Migrating Code from FLTK 1.1 to 1.3". All links on the main page are working now. Todo: - Check doxygen error messages, rewrite pages (html tags, contents). - Fill the new "Migrating..." chapter. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/drawing.dox | 967 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 documentation/drawing.dox (limited to 'documentation/drawing.dox') diff --git a/documentation/drawing.dox b/documentation/drawing.dox new file mode 100644 index 000000000..29694cc00 --- /dev/null +++ b/documentation/drawing.dox @@ -0,0 +1,967 @@ +/** + + \page drawing 5 - Drawing Things in FLTK + +

This chapter covers the drawing functions that are provided with FLTK. + +

When Can You Draw Things in FLTK?

+ +

There are only certain places you can execute drawing code in FLTK. +Calling these functions at other places will result in undefined +behavior! + +

+ +

FLTK 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: + +

+ +

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 and width and height to determine +where to draw the box. + +

void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c);

+ +

The first box drawing function is fl_draw_box() +which draws a standard boxtype c in the specified +color c. + +

void fl_frame(const char *s, int x, int y, int w, int h);

+ +

The fl_frame() function draws a series of line +segments around the given box. The string s must +contain groups of 4 letters which specify one of 24 standard +grayscale values, where 'A' is black and 'X' is white. The order +of each set of 4 characters is: top, left, bottom, right. The +results of calling fl_frame() with a string that is +not a multiple of 4 characters in length are undefined. + +

The only difference between this function and +fl_frame2() is the order of the line segments. + +

See also: fl_frame boxtype. + +

void fl_frame2(const char *s, int x, int y, int w, int h);

+ +

The fl_frame2() function draws a series of line +segments around the given box. The string s must +contain groups of 4 letters which specify one of 24 standard +grayscale values, where 'A' is black and 'X' is white. The order +of each set of 4 characters is: bottom, right, top, left. The +results of calling fl_frame2() with a string that is +not a multiple of 4 characters in length are undefined. + +

The only difference between this function and +fl_frame() is the order of the line segments. + +

Clipping

+ +

You can limit all your drawing to a rectangular region by calling +fl_push_clip, and put the drawings back by using fl_pop_clip. +This rectangle is measured in pixels and is unaffected by the current +transformation matrix. + +

In addition, the system may provide clipping when updating windows +which may be more complex than a simple rectangle.

+ +

void fl_clip(int x, int y, int w, int h)
+void fl_push_clip(int x, int y, int w, int h)

+ +

Intersect the current clip region with a rectangle and push this new +region onto the stack. The fl_clip() name is deprecated and +will be removed from future releases. + +

void fl_push_no_clip()

+ +

Pushes an empty clip region on the stack so nothing will be clipped. + +

void fl_pop_clip()

+ +

Restore the previous clip region. + +

+ + + +
Note: + +

You must call fl_pop_clip() once for every + time you call fl_push_clip(). If you return to FLTK + with the clip stack not empty unpredictable results + occur. + +

+ +

int fl_not_clipped(int x, int y, int w, int h)

+ +

Returns non-zero if any of the rectangle intersects the current clip +region. If this returns 0 you don't have to draw the object. + +

+ + + +
Note: + +

Under X this returns 2 if the rectangle is partially + clipped, and 1 if it is entirely inside the clip region. + +

+ +

int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, +int &H)

+ +

Intersect the rectangle x,y,w,h with the current +clip region and returns the bounding box of the result in +X,Y,W,H. Returns non-zero if the resulting rectangle is +different than the original. This can be used to limit the +necessary drawing to a rectangle. W and H are +set to zero if the rectangle is completely outside the region. + +

void fl_clip_region(Fl_Region r) +
Fl_Region fl_clip_region()

+ +

Replace the top of the clip stack with a clipping region of any shape. +Fl_Region is an operating system specific type. The second form returns +the current clipping region. + +

Colors

+ +

FLTK manages colors as 32-bit unsigned integers. Values from +0 to 255 represent colors from the FLTK 1.0.x standard colormap +and are allocated as needed on screens without TrueColor +support. The Fl_Color enumeration type defines the +standard colors and color cube for the first 256 colors. All of +these are named with symbols in <FL/Enumerations.H>. + +

Color values greater than 255 are treated as 24-bit RGB +values. These are mapped to the closest color supported by the +screen, either from one of the 256 colors in the FLTK 1.0.x +colormap or a direct RGB value on TrueColor screens. You can +generate 24-bit RGB color values using the fl_rgb_color() +function. + +

void fl_color(Fl_Color)

+ +

Sets the color for all subsequent drawing operations. + +

For colormapped displays, a color cell will be allocated out +of fl_colormap the first time you use a color. If the +colormap fills up then a least-squares algorithm is used to find +the closest color.

+ +

Fl_Color fl_color()

+ +

Returns the last fl_color() that was set. This can +be used for state save/restore. + +

void fl_color(uchar r, uchar g, uchar b)

+ +

Set the color for all subsequent drawing operations. The +closest possible match to the RGB color is used. The RGB color +is used directly on TrueColor displays. For colormap visuals the +nearest index in the gray ramp or color cube is used. + +

Line Dashes and Thickness

+ +

FLTK supports drawing of lines with different styles and +widths. Full functionality is not available under Windows 95, 98, +and Me due to the reduced drawing functionality these operating +systems provide. + +

void fl_line_style(int style, int width=0, char* dashes=0)

+ +

Set how to draw lines (the "pen"). If you change this it is your +responsibility to set it back to the default with +fl_line_style(0). + +

+ + + +
Note: + +

Because of how line styles are implemented on WIN32 + systems, you must set the line style after + setting the drawing color. If you set the color after + the line style you will lose the line style settings! + +

+ +

style is a bitmask which is a bitwise-OR of the following +values. If you don't specify a dash type you will get a solid +line. If you don't specify a cap or join type you will get a +system-defined default of whatever value is fastest. + +

+ +

width is the number of pixels 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. + + + +

dashes is a pointer to an array of dash lengths, measured in +pixels. 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 NULL pointer or a zero-length +array results in a solid line. Odd array sizes are not supported and +result in undefined behavior. + +

+ + + +
Note: + +

The dashes array does not work under Windows 95, 98, + or Me, since those operating systems do not support + complex line styles. + +

+ +

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 transformation matrix, so you should only +call these while the matrix is set to the identity matrix (the +default). + +

void fl_point(int x, int y)

+ +

Draw a single pixel at the given coordinates. + +

void fl_rectf(int x, int y, int w, int h) +
void fl_rectf(int x, int y, int w, int h)

+ +

Color a rectangle that exactly fills the given bounding box. + +

void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)

+ +

Color a rectangle with "exactly" the passed +r,g,b color. On screens with less than 24 bits of +color this is done by drawing a solid-colored block using fl_draw_image() so that +the correct color shade is produced. + +

void fl_rect(int x, int y, int w, int h) +
void fl_rect(int x, int y, int w, int h, Fl_Color c)

+ +

Draw a 1-pixel border inside this bounding box. + +

void fl_line(int x, int y, int x1, int y1) +
void fl_line(int x, int y, int x1, int y1, int x2, int y2)

+ +

Draw one or two lines between the given points. + +

void fl_loop(int x, int y, int x1, int y1, int x2, int y2) +
void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, +int y3)

+ +

Outline a 3 or 4-sided polygon with lines. + +

void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) +
void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int +x3, int y3)

+ +

Fill a 3 or 4-sided polygon. The polygon must be convex. + +

void fl_xyline(int x, int y, int x1) +
void fl_xyline(int x, int y, int x1, int y2) +
void fl_xyline(int x, int y, int x1, int y2, int x3)

+ +

Draw horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + +

void fl_yxline(int x, int y, int y1) +
void fl_yxline(int x, int y, int y1, int x2) +
void fl_yxline(int x, int y, int y1, int x2, int y3)

+ +

Draw vertical and horizontal lines. A vertical line is drawn +first, then a horizontal, then a vertical. + +

void fl_arc(int x, int y, int w, int h, double a1, double a2) +
void fl_pie(int x, int y, int w, int h, double a1, double a2)

+ +

Draw ellipse sections using integer coordinates. These +functions match the rather limited circle drawing code provided +by X and WIN32. The advantage over using fl_arc with floating point +coordinates is that they are faster because they often use the +hardware, and they draw much nicer small circles, since the +small sizes are often hard-coded bitmaps. + +

If a complete circle is drawn it will fit inside the passed bounding +box. The two angles are measured in degrees counterclockwise from +3'oclock and are the starting and ending angle of the arc, a2 +must be greater or equal to a1.

+ +

fl_arc() draws a series of lines to approximate the arc. +Notice that the integer version of fl_arc() has a different +number of arguments than the fl_arc() +function described later in this chapter.

+ +

fl_pie() draws a filled-in pie slice. This slice may +extend outside the line drawn by fl_arc; to avoid this +use w - 1 and h - 1.

+ +

void fl_scroll(int X, int Y, int W, int H, int dx, int dy, +void (*draw_area)(void*, int,int,int,int), void* data)

+ +

Scroll a rectangle and draw the newly exposed portions. The contents +of the rectangular area is first shifted by dx and +dy pixels. The callback is then called for every newly +exposed rectangular area, + +

Drawing Complex Shapes

+ +

The complex drawing functions let you draw arbitrary shapes +with 2-D linear transformations. The functionality matches that +found in the Adobe® PostScriptTM language. The +exact pixels that are filled are less defined than for the fast +drawing functions so that FLTK can take advantage of drawing +hardware. On both X and WIN32 the transformed vertices are +rounded to integers before drawing the line segments: this +severely limits the accuracy of these functions for complex +graphics, so use OpenGL when greater accuracy and/or performance +is required. + +

void fl_push_matrix() +
void fl_pop_matrix()

+ +

Save and restore the current transformation. The maximum +depth of the stack is 4. + +

void fl_scale(float x, float y) +
void fl_scale(float x) +
void fl_translate(float x, float y) +
void fl_rotate(float d) +
void fl_mult_matrix(float a, float b, float c, float d, float +x, float y)

+ +

Concatenate another transformation onto the current one. The rotation +angle is in degrees (not radians) and is counter-clockwise. + +

double fl_transform_x(double x, double y) +
double fl_transform_y(double x, double y) +
double fl_transform_dx(double x, double y) +
double fl_transform_dy(double x, double y) +
void fl_transformed_vertex(double xf, double yf)

+ +

Transform a coordinate or a distance trough the current transformation matrix. +After transforming a coordinate pair, it can be added to the vertex +list without any forther translations using fl_transformed_vertex. + +

void fl_begin_points() +
void fl_end_points()

+ +

Start and end drawing a list of points. Points are added to +the list with fl_vertex. + +

void fl_begin_line() +
void fl_end_line()

+ +

Start and end drawing lines. + +

void fl_begin_loop() +
void fl_end_loop()

+ +

Start and end drawing a closed sequence of lines. + +

void fl_begin_polygon() +
void fl_end_polygon()

+ +

Start and end drawing a convex filled polygon. + +

void fl_begin_complex_polygon() +
void fl_gap() +
void fl_end_complex_polygon()

+ +

Start and end drawing a complex filled polygon. This polygon +may be concave, may have holes in it, or may be several +disconnected pieces. Call fl_gap() to seperate loops of +the path. It is unnecessary but harmless to call +fl_gap() before the first vertex, after the last one, +or several times in a row. + +

+ + + +
Note: + +

For portability, you should only draw polygons that + appear the same whether "even/odd" or + "non-zero" winding rules are used to fill + them. Holes should be drawn in the opposite direction of + the outside loop. + +

+ +

fl_gap() should only be called between +fl_begin_complex_polygon() and +fl_end_complex_polygon(). To outline the polygon, use +fl_begin_loop() and replace each fl_gap() with +fl_end_loop();fl_begin_loop().

+ +

void fl_vertex(float x, float y)

+Add a single vertex to the current path. + +

void fl_curve(float x, float y, float x1, float y1, float x2, float +y2, float x3, float y3)

+ +

Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at x,y and x3,y3. + +

void fl_arc(float x, float y, float r, float start, float end)

+ +

Add a series of points to the current path on the arc of a +circle; you can get elliptical paths by using scale and rotate +before calling fl_arc(). x,y are the center of +the circle, and r is its radius. fl_arc() +takes start and end angles that are measured +in degrees counter-clockwise from 3 o'clock. If end is +less than start then it draws the arc in a clockwise +direction. + +

void fl_circle(float x, float y, float r)

+ +

fl_circle() is equivalent to fl_arc(...,0,360) but +may be faster. It must be the only thing in the path: if you +want a circle as part of a complex polygon you must use fl_arc(). + +

+ + + +
Note: + +

fl_circle() draws incorrectly if the + transformation is both rotated and non-square scaled. + +

+ +

Drawing Text

+ +

All text is drawn in the current font. +It is undefined whether this location or the characters are +modified by the current transformation. + +

void fl_draw(const char *, int x, int y) +
void fl_draw(const char *, int n, int x, int y)

+ +

Draw a nul-terminated string or an array of n characters +starting at the given location. Text is aligned to the left and to +the baseline of the font. To align to the bottom, subtract fl_descent() from +y. To align to the top, subtract fl_descent() and add fl_height(). +This version of fl_draw provides direct access to +the text drawing function of the underlying OS. It does not apply any +special handling to control characters. + +

void fl_draw(const char *, int x, int y, int w, int h, +Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1)

+ +

Fancy string drawing function which is used to draw all the +labels. The string is formatted and aligned inside the passed +box. Handles '\t' and '\n', expands all other control +characters to ^X, and aligns inside or against the edges of the +box described by x, y, w and h. See Fl_Widget::align() +for values for align. The value +FL_ALIGN_INSIDE is ignored, as this function always +prints inside the box. + +

If img is provided and is not NULL, the +image is drawn above or below the text as specified by the +align value. + +

The draw_symbols argument specifies whether or not +to look for symbol names starting with the "@" character. + +

The text length is limited to 1024 caracters per line. + +

void fl_measure(const char *, int &w, +int &h, int draw_symbols = 1)

+ +

Measure how wide and tall the string will be when printed by +the fl_draw(...align) function. If the incoming +w is non-zero it will wrap to that width. + +

int fl_height()

+ +

Recommended minimum line spacing for the current font. You +can also just use the value of size passed to fl_font(). + +

int fl_descent()

+ +

Recommended distance above the bottom of a +fl_height() tall box to draw the text at so it looks +centered vertically in that box. + +

float fl_width(const char*) +
float fl_width(const char*, int n) +
float fl_width(uchar)

+ +

Return the pixel width of a nul-terminated string, a sequence of n +characters, or a single character in the current font. + +

const char *fl_shortcut_label(ulong)

+ +

Unparse a shortcut value as used by Fl_Button +or Fl_Menu_Item +into a human-readable string like "Alt+N". This only +works if the shortcut is a character key or a numbered function +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. + +

Fonts

+ +

FLTK supports a set of standard fonts based on the Times, +Helvetica/Arial, Courier, and Symbol typefaces, as well as +custom fonts that your application may load. Each font is +accessed by an index into a font table. + +

Initially only the first 16 faces are filled in. There are +symbolic names for them: FL_HELVETICA, +FL_TIMES, FL_COURIER, and modifier values +FL_BOLD and FL_ITALIC which can be added to +these, and FL_SYMBOL and FL_ZAPF_DINGBATS. +Faces greater than 255 cannot be used in Fl_Widget +labels, since Fl_Widget stores the index as a byte.

+ +

void fl_font(int face, int size)

+ +

Set the current font, which is then used by the routines +described above. You may call this outside a draw context if +necessary to call fl_width(), but on X this will open +the display. + +

The font is identified by a face and a +size. The size of the font is measured in +pixels and not "points". Lines should be spaced +size pixels apart or more.

+ +

int fl_font() +
int fl_size()

+ +

Returns the face and size set by the most recent call to +fl_font(a,b). This can be used to save/restore the +font. + +

Character Encoding

+ +

FLTK 1 supports western character sets using the eight bit encoding +of the user-selected global code page. For MS Windows and X11, the code +page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1. +On Mac OS X, we assume MacRoman. + +

FLTK provides the functions fl_latin1_to_local, +fl_local_to_latin1, fl_mac_roman_to_local, and +fl_local_to_mac_roman to convert strings between both +encodings. These functions are only required if your source +code contains "C"-strings with international characters and +if this source will be compiled on multiple platforms. + +

Assuming that the following source code was written on MS Windows, +this example will output the correct label on OS X and X11 as well. +Without the conversion call, the label on OS X would read +Fahrvergn¸gen with a deformed umlaut u. +

+  btn = new Fl_Button(10, 10, 300, 25);
+  btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+
+ +

If your application uses characters that are not part of both +encodings, or it will be used in areas that commonly use different +code pages, yoou might consider upgrading to FLTK 2 which supports +UTF-8 encoding. + +

Drawing Overlays

+ +

These functions allow you to draw interactive selection rectangles +without using the overlay hardware. FLTK will XOR a single rectangle +outline over a window. + +

void fl_overlay_rect(int x, int y, int w, int h); +
void fl_overlay_clear();

+ +

fl_overlay_rect() draws a selection rectangle, erasing any +previous rectangle by XOR'ing it first. fl_overlay_clear() +will erase the rectangle without drawing a new one. + +

Using these functions is tricky. You should make a widget +with both a handle() and draw() method. +draw() should call fl_overlay_clear() before +doing anything else. Your handle() method should call +window()->make_current() and then +fl_overlay_rect() after FL_DRAG events, and +should call fl_overlay_clear() after a +FL_RELEASE event.

+ +

Drawing Images

+ +

To draw images, you can either do it directly from data in +your memory, or you can create a Fl_Image object. The advantage of +drawing directly is that it is more intuitive, and it is faster +if the image data changes more often than it is redrawn. The +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 much faster. + +

Direct Image Drawing

+ +

The behavior when drawing images when the current +transformation matrix is not the identity is not defined, so you +should only draw images when the matrix is set to the identity. + +

void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D += 3, int LD = 0) +
void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, +int D = 1, int LD = 0)

+ +

Draw an 8-bit per color RGB or luminance image. The pointer +points at the "r" data of the top-left pixel. Color +data must be in r,g,b order. X,Y are where to +put the top-left corner. W and H define the +size of the image. D is the delta to add to the pointer +between pixels, it may be any value greater or equal to +3, or it can be negative to flip the image +horizontally. LD is the delta to add to the pointer +between lines (if 0 is passed it uses W * D), and may +be larger than W * D to crop data, or negative to flip +the image vertically. + +

It is highly recommended that you put the following code before the +first show() of any window in your program to get rid +of the dithering if possible:

+ + + +

Gray scale (1-channel) images may be drawn. This is done if +abs(D) is less than 3, or by calling +fl_draw_image_mono(). Only one 8-bit sample is used for +each pixel, and on screens with different numbers of bits for +red, green, and blue only gray colors are used. Setting +D greater than 1 will let you display one channel of a +color image. + +

+ + + +
Note: + +

The X version does not support all possible visuals. + If FLTK cannot draw the image in the current visual it + will abort. FLTK supports any visual of 8 bits or less, + and all common TrueColor visuals up to 32 bits.

+ +
+ +

typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar +*) +
void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, +int H, int D = 3) +
void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, +int W, int H, int D = 1)

+ +

Call the passed function to provide each scan line of the +image. This lets you generate the image as it is being drawn, +or do arbitrary decompression of stored data, provided it can be +decompressed to individual scan lines easily. + +

The callback is called with the void * user data +pointer which can be used to point at a structure of information +about the image, and the x, y, and w +of the scan line desired from the image. 0,0 is the upper-left +corner of the image, not X,Y. A pointer to a +buffer to put the data into is passed. You must copy w +pixels from scanline y, starting at pixel x, +to this buffer.

+ +

Due to cropping, less than the whole image may be requested. +So x may be greater than zero, the first y may +be greater than zero, and w may be less than +W. The buffer is long enough to store the entire W +* D pixels, this is for convenience with some decompression +schemes where you must decompress the entire line at once: +decompress it into the buffer, and then if x is not +zero, copy the data over so the x'th pixel is at the +start of the buffer.

+ +

You can assume the y's will be consecutive, except +the first one may be greater than zero.

+ +

If D is 4 or more, you must fill in the unused bytes +with zero.

+ +

int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)

+ +

Draws XPM image data, with the top-left corner at the given position. +The image is dithered on 8-bit displays so you won't lose color space +for programs displaying both images and pixmaps. This function returns +zero if there was any error decoding the XPM data. + +

To use an XPM, do:

+ + + +

Transparent colors are replaced by the optional +Fl_Color argument. To draw with true transparency you must +use the Fl_Pixmap class. + +

int fl_measure_pixmap(char **data, int &w, int &h)

+ +

An XPM image contains the dimensions in its data. This +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. + +

Direct Image Reading

+ +

FLTK provides a single function for reading from the current +window or off-screen buffer into a RGB(A) image buffer.

+ +

uchar *fl_read_image(uchar *p, int +X, int Y, int W, int H, int alpha = 0);

+ +

Read a RGB(A) image from the current window or off-screen +buffer. The p argument points to a buffer that can hold +the image and must be at least W*H*3 bytes when reading +RGB images and W*H*4 bytes when reading RGBA images. If +NULL, fl_read_image() will create an array of +the proper size which can be freed using delete[].

+ +

The 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.

+ +

Image Classes

+ +

FLTK provides a base image class called Fl_Image which supports +creating, copying, and drawing images of various kinds, along +with some basic color operations. Images can be used as labels +for widgets using the image() and +deimage() +methods or drawn directly. + +

The Fl_Image class +does almost nothing by itself, but is instead supported by three +basic image types: + +

+ +

The Fl_Bitmap class encapsulates a mono-color bitmap image. +The draw() method draws the image using the current drawing +color. + +

The Fl_Pixmap class encapsulates a colormapped image. +The draw() method draws the image using the colors in the +file, and masks off any transparent colors automatically. + +

The Fl_RGB_Image class encapsulates a full-color +(or grayscale) image with 1 to 4 color components. Images with +an even number of components are assumed to contain an +alpha channel that is used for transparency. The transparency +provided by the draw() method is either a 24-bit +blend against the existing window contents or a "screen door" +transparency mask, depending on the platform and screen color depth. + +

char fl_can_do_alpha_blending()

+ +

fl_can_do_alpha_blending() will return 1, if your +platform supports true alpha blending for RGBA images, or 0, +if FLTK will use screen door transparency. + +

FLTK also provides several image classes based on the three +standard image types for common file formats: + +

+ +

Each of these image classes load a named file of the +corresponding format. The Fl_Shared_Image class +can be used to load any type of image file - the class examines +the file and constructs an image of the appropriate type. + +

Finally, FLTK provides a special image class called Fl_Tiled_Image to tile +another image object in the specified area. This class can be +used to tile a background image in a Fl_Group widget, +for example. + +

virtual void copy();
+virtual void copy(int w, int h);

+ +

The copy() method creates a copy of the image. The second form +specifies the new size of the image - the image is resized using the +nearest-neighbor algorithm. + +

void draw(int x, int y, int w, int h, int ox = 0, int oy = 0);

+ +

The draw() method draws the image object. +x,y,w,h indicates a destination rectangle. +ox,oy,w,h is a source rectangle. This source rectangle +is copied to the destination. The source rectangle may extend +outside the image, i.e. ox and oy may be +negative and w and h may be bigger than the +image, and this area is left unchanged. + +

void draw(int x, int y)

+ +

Draws the image with the upper-left corner at x,y. +This is the same as doing draw(x,y,img->w(),img->h(),0,0). + +

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. Fl_Double_Window uses offscreen rendering +to avoid flickering on systems that don't support +double-buffering natively. + +

Fl_Offscreen fl_create_offscreen(int w, int h)

+ +

Create an RGB offscreen buffer with w*h pixels. + +

void fl_delete_offscreen(Fl_Offscreen)

+ +

Delete a previously created offscreen buffer. All drawings are lost. + +

void fl_begin_offscreen(Fl_Offscreen)

+ +

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()

+ +

Quit sending drawing commands to this offscreen buffer. + +

void fl_copy_offscreen(int x, int y, +int w, int h, Fl_Offscreen osrc, int srcx, int srcy)

+ +

Copy a rectangular area of the size w*h from srcx, srcy in the offscreen +buffer into the current buffer at x, y. + +*/ -- cgit v1.2.3