FLTK 1.4.4: Fl_Image_Surface Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Image_Surface Class Reference

Directs all graphics requests to an Fl_Image. More...

`#include <Fl_Image_Surface.H>`

Inheritance diagram for Fl_Image_Surface:

## Public Member Functions
| Fl_Image_Surface (int w, int h, int high_res=0, Fl_Offscreen off=0)
| Constructor with optional high resolution.
Fl_Shared_Image * | highres_image ()
| Returns a possibly high resolution image made of all drawings sent to the Fl_Image_Surface object.
Fl_RGB_Image * | image ()
| Returns a depth-3 image made of all drawings sent to the Fl_Image_Surface object.
bool | is_current () FL_OVERRIDE
| Is this surface the current drawing surface?
void | mask (const Fl_RGB_Image *)
| Defines a mask applied to drawings made after use of this function.
Fl_Offscreen | offscreen ()
| Returns the Fl_Offscreen object associated to the image surface.
void | origin (int *x, int *y) FL_OVERRIDE
| Computes the coordinates of the current origin of graphics functions.
void | origin (int x, int y) FL_OVERRIDE
| Sets the position of the origin of graphics in the drawable part of the drawing surface.
int | printable_rect (int *w, int *h) FL_OVERRIDE
| Computes the width and height of the drawable area of the drawing surface.
void | rescale ()
| Adapts the Fl_Image_Surface object to the new value of the GUI scale factor.
void | set_current () FL_OVERRIDE
| Make this surface the current drawing surface.
| ~Fl_Image_Surface ()
| The destructor.
Public Member Functions inherited from Fl_Widget_Surface
void | draw (Fl_Widget *widget, int delta_x=0, int delta_y=0)
| Draws the widget on the drawing surface.
void | draw_decorated_window (Fl_Window *win, int x_offset=0, int y_offset=0)
| Draws a window with its title bar and frame if any.
void | print_window_part (Fl_Window *win, int x, int y, int w, int h, int delta_x=0, int delta_y=0)
| Draws a rectangular part of an on-screen window.
Public Member Functions inherited from Fl_Surface_Device
Fl_Graphics_Driver * | driver ()
| Returns the graphics driver of this drawing surface.
virtual | ~Fl_Surface_Device ()
| The destructor.

## Protected Member Functions
void | translate (int x, int y) FL_OVERRIDE
| Translates the current graphics origin accounting for the current rotation.
void | untranslate () FL_OVERRIDE
| Undoes the effect of a previous translate() call.
Protected Member Functions inherited from Fl_Widget_Surface
| Fl_Widget_Surface (Fl_Graphics_Driver *d)
| The constructor.
Protected Member Functions inherited from Fl_Surface_Device
void | driver (Fl_Graphics_Driver *graphics_driver)
| Sets the graphics driver of this drawing surface.
virtual void | end_current ()
| FLTK calls this each time a surface ceases to be the current drawing surface.
| Fl_Surface_Device (Fl_Graphics_Driver *graphics_driver)
| Constructor that sets the graphics driver to use for the created surface.

## Friends
class | Fl_Graphics_Driver

## Additional Inherited Members
Static Public Member Functions inherited from Fl_Surface_Device
static Fl_Surface_Device * | pop_current ()
| Removes the top element from the current drawing surface stack, and makes the new top element current.
static void | push_current (Fl_Surface_Device *new_current)
| Pushes `new_current` on top of the stack of current drawing surfaces, and makes it current.
static Fl_Surface_Device * | surface ()
| The current drawing surface.
Protected Attributes inherited from Fl_Widget_Surface
int | x_offset
| horizontal offset to the origin of graphics coordinates
int | y_offset
| vertical offset to the origin of graphics coordinates

## Detailed Description

Directs all graphics requests to an Fl_Image.

After creation of an Fl_Image_Surface object, make it the current drawing surface calling Fl_Surface_Device::push_current(), and all subsequent graphics requests will be recorded in the image. It's possible to draw widgets (using Fl_Image_Surface::draw()) or to use any of the Drawing functions or the Color & Font functions. Finally, call image() on the object to obtain a newly allocated Fl_RGB_Image object. Fl_Gl_Window objects can be drawn in the image as well.

Usage example:

// this is the widget that you want to draw into an image
Fl_Widget *g = ...;
// create an Fl_Image_Surface object
Fl_Image_Surface *image_surface = new Fl_Image_Surface(g->w(), g->h());
// direct all further graphics requests to the image
Fl_Surface_Device::push_current(image_surface);
// draw a white background
fl_color(FL_WHITE);
fl_rectf(0, 0, g->w(), g->h());
// draw the g widget in the image
image_surface->draw(g);
// get the resulting image
Fl_RGB_Image* image = image_surface->image();
// direct graphics requests back to their previous destination
Fl_Surface_Device::pop_current();
// delete the image_surface object, but not the image itself
delete image_surface;
Fl_Image_Surface::Fl_Image_Surface
Fl_Image_Surface(int w, int h, int high_res=0, Fl_Offscreen off=0)
Constructor with optional high resolution.
Definition Fl_Image_Surface.cxx:38
Fl_Image_Surface::image
Fl_RGB_Image * image()
Returns a depth-3 image made of all drawings sent to the Fl_Image_Surface object.
Definition Fl_Image_Surface.cxx:151
Fl_RGB_Image
The Fl_RGB_Image class supports caching and drawing of full-color images with 1 to 4 channels of colo...
Definition Fl_Image.H:339
Fl_Surface_Device::pop_current
static Fl_Surface_Device * pop_current()
Removes the top element from the current drawing surface stack, and makes the new top element current...
Definition Fl_Device.cxx:154
Fl_Surface_Device::push_current
static void push_current(Fl_Surface_Device *new_current)
Pushes new_current on top of the stack of current drawing surfaces, and makes it current.
Definition Fl_Device.cxx:140
Fl_Widget_Surface::draw
void draw(Fl_Widget *widget, int delta_x=0, int delta_y=0)
Draws the widget on the drawing surface.
Definition Fl_Widget_Surface.cxx:43
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112
Fl_Widget::w
void w(int v)
Internal use only.
Definition Fl_Widget.H:154
Fl_Widget::h
void h(int v)
Internal use only.
Definition Fl_Widget.H:156
fl_color
Fl_Color fl_color()
Return the last fl_color() that was set.
Definition fl_draw.H:74
fl_rectf
void fl_rectf(int x, int y, int w, int h)
Color with current color a rectangle that exactly fills the given bounding box.
Definition fl_draw.H:339

## Constructor & Destructor Documentation

## ◆ Fl_Image_Surface()

Fl_Image_Surface::Fl_Image_Surface | ( | int | w,
|  | int | h,
|  | int | high_res = 0,
|  | Fl_Offscreen | off = 0 )

Constructor with optional high resolution.

Parameters

  w,h | Width and height of the resulting image. The value of the `high_res` parameter controls whether `w` and `h` are interpreted as pixels or FLTK units.
  high_res | If zero, the created image surface is sized at `w` x `h` pixels. If non-zero, the pixel size of the created image surface depends on the value of the display scale factor (see Fl::screen_scale(int)): the resulting image has the same number of pixels as an area of the display of size `w` x `h` expressed in FLTK units.
  off | If not null, the image surface is constructed around a pre-existing Fl_Offscreen. The caller is responsible for both construction and destruction of this Fl_Offscreen object. Is mostly intended for internal use by FLTK.

Version
  1.3.4 (1.3.3 without the `highres` parameter)

## Member Function Documentation

## ◆ highres_image()

Fl_Shared_Image * Fl_Image_Surface::highres_image | ( |  | ) |

Returns a possibly high resolution image made of all drawings sent to the Fl_Image_Surface object.

The Fl_Image_Surface object should have been constructed with Fl_Image_Surface(W, H, 1). The returned Fl_Shared_Image object is scaled to a size of WxH FLTK units and may have a pixel size larger than these values. The returned object should be deallocated with Fl_Shared_Image::release() after use.

Deprecated
  Use image() instead.

Version
  1.4 (1.3.4 for MacOS platform only)

## ◆ image()

Fl_RGB_Image * Fl_Image_Surface::image | ( |  | ) |

Returns a depth-3 image made of all drawings sent to the Fl_Image_Surface object.

The returned object contains its own copy of the RGB data; the caller is responsible for deleting it.

See also
  Fl_Image_Surface::mask(Fl_RGB_Image*)

## ◆ is_current()

bool Fl_Image_Surface::is_current | ( |  | ) |
| virtual

Is this surface the current drawing surface?

Reimplemented from Fl_Surface_Device.

## ◆ mask()

void Fl_Image_Surface::mask | ( | const Fl_RGB_Image * | mask | ) |

Defines a mask applied to drawings made after use of this function.

The mask is an Fl_RGB_Image made of a white scene drawn on a solid black background; the drawable part of the image surface is reduced to the white areas of the mask after this member function gets called. If necessary, the `mask` image is internally replaced by a copy resized to the surface's pixel size. Overall, the image returned by Fl_Image_Surface::image() contains all drawings made until the mask() method assigned a mask, at which point subsequent drawing operations to the image surface were passed through the white areas of the mask. On some platforms, shades of gray in the mask image control the blending of foreground and background pixels; mask pixels closer in color to white produce image pixels closer to the image surface pixel, those closer to black produce image pixels closer to what the image surface pixel was before the call to mask().

The mask is easily constructed using an Fl_Image_Surface object, drawing white areas on a black background there, and calling Fl_Image_Surface::image().

Parameters

  mask | A depth-3 image determining the drawable areas of the image surface. The `mask` object is not used after return from this member function.

Note
  - The image surface must not be the current drawing surface when this function gets called.
  - The mask can have any size but is best when it has the size of the image surface.
  - It's possible to use several masks in succession on the same image surface provided member function Fl_Image_Surface::image() is called between successive calls to Fl_Image_Surface::mask(const Fl_RGB_Image*).

Example of procedure to construct a masked image:

int W = …, H = …; // width and height of the image under construction
Fl_Image_Surface *surf = new Fl_Image_Surface(W, H, 1);
// first, construct the mask
Fl_Surface_Device::push_current(surf);
fl_color(FL_BLACK); // draw a black background
fl_rectf(0, 0, W, H);
fl_color(FL_WHITE); // next, draw in white what the mask should not filter out
fl_pie(0, 0, W, H, 0, 360); // here, an ellipse with axes lengths WxH
Fl_RGB_Image *mask = surf->image(); // get the mask
// second, draw the image background
fl_color(FL_YELLOW); // here, draw a yellow background
fl_rectf(0, 0, W, H);
// third, apply the mask
Fl_Surface_Device::pop_current();
surf->mask(mask);
delete mask; // the mask image can be safely deleted at this point
Fl_Surface_Device::push_current(surf);
// fourth, draw the image foreground, part of which will be filtered out by the mask
surf->draw(widget, 0, 0); // here the foreground is a drawn widget
// fifth, get the final result, masked_image, as a depth-3 Fl_RGB_Image
Fl_RGB_Image *masked_image = surf->image();
// Only the part of the foreground, here a drawn widget, that has not been
// filtered out by the mask, here the white ellipse, is in masked_image;
// the background, here solid yellow, shows up in the remaining areas of masked_image.
Fl_Surface_Device::pop_current();
delete surf;
Fl_Image_Surface::mask
void mask(const Fl_RGB_Image *)
Defines a mask applied to drawings made after use of this function.
Definition Fl_Image_Surface.cxx:260
fl_pie
void fl_pie(int x, int y, int w, int h, double a1, double a2)
Draw filled ellipse sections using integer coordinates.
Definition fl_draw.H:521

Since
  1.4.0

## ◆ offscreen()

Fl_Offscreen Fl_Image_Surface::offscreen | ( |  | ) |

Returns the Fl_Offscreen object associated to the image surface.

The returned Fl_Offscreen object is deleted when the Fl_Image_Surface object is deleted, unless the Fl_Image_Surface was constructed with non-null Fl_Offscreen argument.

## ◆ origin() [1/2]

void Fl_Image_Surface::origin | ( | int * | x,
|  | int * | y )
| virtual

Computes the coordinates of the current origin of graphics functions.

Parameters

  [out] | x,y | If non-null, *x and *y are set to the horizontal and vertical coordinates of the graphics origin.

Reimplemented from Fl_Widget_Surface.

## ◆ origin() [2/2]

void Fl_Image_Surface::origin | ( | int | x,
|  | int | y )
| virtual

Sets the position of the origin of graphics in the drawable part of the drawing surface.

Arguments should be expressed relatively to the result of a previous printable_rect() call. That is, printable_rect(&w, &h); origin(w/2, 0); sets the graphics origin at the top center of the drawable area. Successive origin() calls don't combine their effects. Origin() calls are not affected by rotate() calls (for classes derived from Fl_Paged_Device).

Parameters

  [in] | x,y | Horizontal and vertical positions in the drawing surface of the desired origin of graphics.

Reimplemented from Fl_Widget_Surface.

## ◆ printable_rect()

int Fl_Image_Surface::printable_rect | ( | int * | w,
|  | int * | h )
| virtual

Computes the width and height of the drawable area of the drawing surface.

Values are in the same unit as that used by FLTK drawing functions and are unchanged by calls to origin(). If the object is derived from class Fl_Paged_Device, values account for the user-selected paper type and print orientation and are changed by scale() calls.

Returns
  0 if OK, non-zero if any error

Reimplemented from Fl_Widget_Surface.

## ◆ rescale()

void Fl_Image_Surface::rescale | ( |  | ) |

Adapts the Fl_Image_Surface object to the new value of the GUI scale factor.

The Fl_Image_Surface object must not be the current drawing surface. This function is useful only for an object constructed with non-zero `high_res` parameter.

Version
  1.4

## ◆ set_current()

void Fl_Image_Surface::set_current | ( | void |  | ) |
| virtual

Make this surface the current drawing surface.

This surface will receive all future graphics requests.

Since FLTK 1.4.0 the preferred API to change the current drawing surface is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().

Note
  It is recommended to use this function only as follows :
  - The current drawing surface is the display;
  - make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object, calling set_current() on this object;
  - draw to that surface;
  - make the display current again with Fl_Display_Device::display_device()->set_current();
    don't do any other call to set_current() before this one.

Other scenarios of drawing surface changes should be performed via Fl_Surface_Device::push_current() and Fl_Surface_Device::pop_current().

Reimplemented from Fl_Surface_Device.

## ◆ translate()

void Fl_Image_Surface::translate | ( | int | x,
|  | int | y )
| protectedvirtual

Translates the current graphics origin accounting for the current rotation.

Each translate() call must be matched by an untranslate() call. Successive translate() calls add up their effects.

Reimplemented from Fl_Widget_Surface.

## ◆ untranslate()

void Fl_Image_Surface::untranslate | ( | void |  | ) |
| protectedvirtual

Undoes the effect of a previous translate() call.

Reimplemented from Fl_Widget_Surface.

The documentation for this class was generated from the following files:

- Fl_Image_Surface.H
- Fl_Image_Surface.cxx