FLTK 1.4.4: Fl_Shared_Image Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Shared_Image Class Reference

This class supports caching, loading, and drawing of image files. More...

`#include <Fl_Shared_Image.H>`

Inheritance diagram for Fl_Shared_Image:

## Public Member Functions
Fl_Shared_Image * | as_shared_image () FL_OVERRIDE
| Returns whether an image is an Fl_Shared_Image or not.
void | color_average (Fl_Color c, float i) FL_OVERRIDE
| Averages the colors in the image with the provided FLTK color value.
Fl_Image * | copy ()
| Increments the reference counter and returns a pointer to itself.
Fl_Image * | copy () const
Fl_Image * | copy (int W, int H) const FL_OVERRIDE
| Return a shared image of this image with the requested size.
void | desaturate () FL_OVERRIDE
| Convert the image to gray scale.
void | draw (int X, int Y)
void | draw (int X, int Y, int W, int H, int cx=0, int cy=0) FL_OVERRIDE
| Draw this image to the current graphics context.
const Fl_Image * | image () const
| Returns a pointer to the internal Fl_Image object.
const char * | name ()
| Returns the filename of the shared image.
int | original ()
| Returns whether this is an original image.
int | refcount ()
| Returns the number of references of this shared image.
void | release () FL_OVERRIDE
| Releases and possibly destroys (if refcount <= 0) a shared image.
virtual void | reload ()
| Reloads the shared image from disk.
void | uncache () FL_OVERRIDE
| Remove the cached device specific image data.
Public Member Functions inherited from Fl_Image
Fl_Image * | copy () const
| Creates a copy of the image in the same size.
int | count () const
| Returns the number of data values associated with the image.
int | d () const
| Returns the image depth.
const char *const * | data () const
| Returns a pointer to the current image data array.
int | data_h () const
| Returns the height of the image data.
int | data_w () const
| Returns the width of the image data.
void | draw (int X, int Y)
| Draws the image to the current drawing surface.
int | fail () const
| Returns a value that is not 0 if there is currently no image available.
| Fl_Image (int W, int H, int D)
| The constructor creates an empty image with the specified width, height, and depth.
int | h () const
| Returns the current image drawing height in FLTK units.
void | inactive ()
| The inactive() method calls color_average(FL_BACKGROUND_COLOR, 0.33f) to produce an image that appears grayed out.
virtual void | label (Fl_Menu_Item *m)
| This method is an obsolete way to set the image attribute of a menu item.
virtual void | label (Fl_Widget *w)
| This method is an obsolete way to set the image attribute of a widget or menu item.
int | ld () const
| Returns the current line data size in bytes.
virtual void | scale (int width, int height, int proportional=1, int can_expand=0)
| Sets the drawing size of the image.
int | w () const
| Returns the current image drawing width in FLTK units.
virtual | ~Fl_Image ()
| The destructor is a virtual method that frees all memory used by the image.

## Static Public Member Functions
static void | add_handler (Fl_Shared_Handler f)
| Adds a shared image handler, which is basically a test function for adding new image formats.
static Fl_Shared_Image * | find (const char *name, int W=0, int H=0)
| Finds a shared image from its name and size specifications.
static Fl_Shared_Image * | get (const char *name, int W=0, int H=0)
| Find or load an image that can be shared by multiple widgets.
static Fl_Shared_Image * | get (Fl_RGB_Image *rgb, int own_it=1)
| Builds a shared image from a pre-existing Fl_RGB_Image.
static Fl_Shared_Image ** | images ()
| Returns the Fl_Shared_Image* array.
static int | num_images ()
| Number of shared images in their various cached sizes.
static void | remove_handler (Fl_Shared_Handler f)
| Removes a shared image handler.
Static Public Member Functions inherited from Fl_Image
static Fl_Labeltype | define_FL_IMAGE_LABEL ()
static Fl_RGB_Scaling | RGB_scaling ()
| Returns the currently used RGB image scaling method.
static void | RGB_scaling (Fl_RGB_Scaling)
| Sets the RGB image scaling method used for copy(int, int).
static Fl_RGB_Scaling | scaling_algorithm ()
| Gets what algorithm is used when resizing a source image to draw it.
static void | scaling_algorithm (Fl_RGB_Scaling algorithm)
| Sets what algorithm is used when resizing a source image to draw it.

## Protected Member Functions
void | add ()
| Adds a shared image to the image pool.
Fl_Shared_Image * | copy_ (int W, int H) const
| Create a resized copy of the image and wrap it into the share image class.
| Fl_Shared_Image ()
| Creates an empty shared image.
| Fl_Shared_Image (const char *n, Fl_Image *img=0)
| Creates a shared image from its filename and its corresponding Fl_Image* img.
void | update ()
| Update the dimensions of the shared images.
virtual | ~Fl_Shared_Image ()
| The destructor frees all memory and server resources that are used by the image.
Protected Member Functions inherited from Fl_Image
void | d (int D)
| Sets the current image depth.
void | data (const char *const *p, int c)
| Sets the current data pointer and count of pointers in the array.
void | draw_empty (int X, int Y)
| The protected method draw_empty() draws a box with an X in it.
int | draw_scaled (int X, int Y, int W, int H)
| Draw the image to the current drawing surface rescaled to a given width and height.
void | h (int H)
| Sets the height of the image data.
void | ld (int LD)
| Sets the current line data size in bytes.
void | w (int W)
| Sets the width of the image data.

## Static Protected Member Functions
static int | compare (Fl_Shared_Image **i0, Fl_Shared_Image **i1)
| Compares two shared images.
Static Protected Member Functions inherited from Fl_Image
static void | labeltype (const Fl_Label *lo, int lx, int ly, int lw, int lh, Fl_Align la)
static void | measure (const Fl_Label *lo, int &lw, int &lh)

## Protected Attributes
int | alloc_image_
Fl_Image * | image_
const char * | name_
int | original_
int | refcount_

## Static Protected Attributes
static int | alloc_handlers_ = 0
static int | alloc_images_ = 0
static Fl_Shared_Handler * | handlers_ = 0
static Fl_Shared_Image ** | images_ = 0
static int | num_handlers_ = 0
static int | num_images_ = 0

## Friends
class | Fl_Graphics_Driver
class | Fl_JPEG_Image
class | Fl_PNG_Image
class | Fl_SVG_Image

## Additional Inherited Members
Static Public Attributes inherited from Fl_Image
static const int | ERR_FILE_ACCESS = -2
static const int | ERR_FORMAT = -3
static const int | ERR_MEMORY_ACCESS = -4
static const int | ERR_NO_IMAGE = -1
static bool | register_images_done = false
| True after fl_register_images() was called, false before.

## Detailed Description

This class supports caching, loading, and drawing of image files.

Most applications will also want to link against the fltk_images library and call the fl_register_images() function to support standard image formats such as BMP, GIF, JPEG, PNG, and SVG (unless the library was built with the option removing SVG support).

Images can be requested (loaded) with Fl_Shared_Image::get(), find(), and some other methods. All images are cached in an internal list of shared images and should be released when they are no longer needed. A refcount is used to determine if a released image is to be destroyed with delete.

See also
  fl_register_image()
  Fl_Shared_Image::get()
  Fl_Shared_Image::find()
  Fl_Shared_Image::release()

## Constructor & Destructor Documentation

## ◆ Fl_Shared_Image() [1/2]

Fl_Shared_Image::Fl_Shared_Image | ( |  | ) |
| protected

Creates an empty shared image.

The constructors create a new shared image record in the image cache.

The constructors are protected and cannot be used directly from a program. Use the get() method instead.

## ◆ Fl_Shared_Image() [2/2]

Fl_Shared_Image::Fl_Shared_Image | ( | const char * | n,
|  | Fl_Image * | img = 0 )
| protected

Creates a shared image from its filename and its corresponding Fl_Image* img.

The constructors create a new shared image record in the image cache.

The constructors are protected and cannot be used directly from a program. Use the get() method instead.

Parameters

  [in] | n | filename or pool name of the image, must be unique among shared images
  [in] | img | the image that is made available using the name

## ◆ ~Fl_Shared_Image()

Fl_Shared_Image::~Fl_Shared_Image | ( |  | ) |
| protectedvirtual

The destructor frees all memory and server resources that are used by the image.

The destructor is protected and cannot be used directly from a program. Use the Fl_Shared_Image::release() method instead.

## Member Function Documentation

## ◆ add()

void Fl_Shared_Image::add | ( |  | ) |
| protected

Adds a shared image to the image pool.

This protected method adds an image to the pool, an ordered list of shared images. The pool is searched for a matching image whenever one is requested, for instance with Fl_Shared_Image::get() or Fl_Shared_Image::find().

This method does not increase or decrease reference counts!

## ◆ add_handler()

void Fl_Shared_Image::add_handler | ( | Fl_Shared_Handler | f | ) |
| static

Adds a shared image handler, which is basically a test function for adding new image formats.

This function will be called when an Fl_Shared_Image is to be loaded (for instance with Fl_Shared_Image::get()) and the image type is not known to FLTK.

All registered image handlers will be called in the order of registration. You should always call fl_register_images() before adding your own handlers - unless you need to override a known image file type which should be rare.

See also
  Fl_Shared_Handler for more information of the function you need to define.

## ◆ as_shared_image()

Fl_Shared_Image * Fl_Shared_Image::as_shared_image | ( |  | ) |
| inlinevirtual

Returns whether an image is an Fl_Shared_Image or not.

This virtual method returns a pointer to an Fl_Shared_Image if this object is an instance of Fl_Shared_Image or NULL if not. This can be used to detect if a given Fl_Image object is a shared image, i.e. derived from Fl_Shared_Image.

Since
  1.4.0

Reimplemented from Fl_Image.

## ◆ color_average()

void Fl_Shared_Image::color_average | ( | Fl_Color | c,
|  | float | i )
| virtual

Averages the colors in the image with the provided FLTK color value.

This method changes the pixel data of this specific image.

Note
  It does not change any of the resized copies of this image, nor does it necessarily apply the color changes if this image is resized later.

Parameters

  [in] | c | blend with this color
  [in] | i | blend fraction

See also
  Fl_Image::color_average(Fl_Color c, float i)

Reimplemented from Fl_Image.

## ◆ compare()

int Fl_Shared_Image::compare | ( | Fl_Shared_Image ** | i0,
|  | Fl_Shared_Image ** | i1 )
| staticprotected

Compares two shared images.

The order of comparison is:

1. Image name, usually the filename used to load it
2. Image width
3. Image height

Binary search in a sorted array works only if we search for the same parameters that were also used for sorting. No special cases are possible here.

Fl_Shared_Image::find() requires a search for an element with a matching name and the original_ flags set. This is not implemented via binary search, but by a simple run of the array inside Fl_Shared_Image::find().

Parameters

  [in] | i0,i1 | image pointer pointer for sorting

Returns
  Whether the images match or their relative sort order (see text).

Return values

  0 | the images match
  <0 | Image `i0` is less than image `i1`
  >0 | Image `i0` is greater than image `i1`

## ◆ copy() [1/2]

Fl_Image * Fl_Shared_Image::copy | ( |  | ) |

Increments the reference counter and returns a pointer to itself.

When the image is no longer used, call Fl_Shared_Image::release().

To get a copy of the image data, call this->image()->copy() instead.

Returns
  pointer to an Fl_Shared_Image that can be safely cast

## ◆ copy() [2/2]

Fl_Image * Fl_Shared_Image::copy | ( | int | W,
|  | int | H ) const
| virtual

Return a shared image of this image with the requested size.

This is the same as calling Fl_Shared_Image::get(this->name(), W, H).

If a shared image of the desired size already exists in the shared image pool, the existing image is returned and no copy is made. But the reference counter is incremented. When the image is no longer used, call Fl_Shared_Image::release().

To get a copy of the image data, call this->image()->copy(W, H) instead.

Parameters

  [in] | W,H | size of requested image

Returns
  pointer to an Fl_Shared_Image that can be safely cast, or NULL if the image can't be found and can't be created.

Reimplemented from Fl_Image.

## ◆ copy_()

Fl_Shared_Image * Fl_Shared_Image::copy_ | ( | int | W,
|  | int | H ) const
| protected

Create a resized copy of the image and wrap it into the share image class.

This function is usually followed by a call to returned_image->add() to add the image to the pool, and this->refcounter_++` to make sure that the original shared image keeps a reference to the copy. Don't call this function if an image of the given size is already in the pool.

Parameters

  [in] | W,H | new image size

Returns
  a new shared image pointer that is not yet in the pool

## ◆ desaturate()

void Fl_Shared_Image::desaturate | ( |  | ) |
| virtual

Convert the image to gray scale.

This method changes the pixel data of this specific image.

Note
  It does not change any of the resized copies of this image, nor does it necessarily apply the color changes if this image is resized later.

See also
  Fl_Image::desaturate()

Reimplemented from Fl_Image.

## ◆ draw()

void Fl_Shared_Image::draw | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | int | cx = 0,
|  | int | cy = 0 )
| virtual

Draw this image to the current graphics context.

Parameters

  [in] | X,Y,W,H | draw at this position and size
  [in] | cx,cy | image origin

Reimplemented from Fl_Image.

## ◆ find()

Fl_Shared_Image * Fl_Shared_Image::find | ( | const char * | name,
|  | int | W = 0,
|  | int | H = 0 )
| static

Finds a shared image from its name and size specifications.

This uses a binary search in the image cache.

If the image `name` exists with the exact width `W` and height `H`, then it is returned.

If `W` == 0 and the image `name` exists with another size, then the original image with that `name` is returned.

In either case the refcount of the returned image is increased. The found image should be released with Fl_Shared_Image::release() when no longer needed.

An image is marked `original` if it was directly loaded from a file or from memory as opposed to copied and resized images.

This comparison is used in Fl_Shared_Image::find() to find an image that matches the requested one or to find the position where a new image should be entered into the sorted list of shared images.

It is used in two steps by Fl_Shared_Image::add():

1. search with exact width and height
2. if not found, search again with width = 0 (and height = 0)

The first step will only return a match if the image exists with the same width and height. The second step will match if there is an image marked `original` with the same name, regardless of width and height.

## ◆ get() [1/2]

Fl_Shared_Image * Fl_Shared_Image::get | ( | const char * | name,
|  | int | W = 0,
|  | int | H = 0 )
| static

Find or load an image that can be shared by multiple widgets.

If the image exists with the requested size, this image will be returned.

If the image exists, but only with another size, then a new copy with the requested size (width `W` and height `H`) will be created as a resized copy of the original image. The new image is added to the internal list of shared images.

If the image does not yet exist, then a new image of the proper dimension is created from the filename `name`. The original image from filename `name` is always added to the list of shared images in its original size. If the requested size differs, then the resized copy with width `W` and height `H` is also added to the list of shared images.

Note
  If the sizes differ, then two images are created as mentioned above. This is intentional so the original image is cached and preserved. If you request the same image with another size later, then the original image will be found, copied, resized, and returned.

Shared JPEG and PNG images can also be created from memory by using their named memory access constructor.

You should release() the image when you're done with it.

Parameters

  name | name of the image
  W,H | desired size

Returns
  the image at the requested size, or NULL if the image could not be found or generated

See also
  Fl_Shared_Image::find(const char *name, int W, int H)
  Fl_Shared_Image::release()
  Fl_JPEG_Image::Fl_JPEG_Image(const char *name, const unsigned char *data)
  Fl_PNG_Image::Fl_PNG_Image (const char *name_png, const unsigned char *buffer, int maxsize)

## ◆ get() [2/2]

Fl_Shared_Image * Fl_Shared_Image::get | ( | Fl_RGB_Image * | rgb,
|  | int | own_it = 1 )
| static

Builds a shared image from a pre-existing Fl_RGB_Image.

Parameters

  [in] | rgb | an Fl_RGB_Image used to build a new shared image.
  [in] | own_it | 1 if the shared image should delete `rgb` when it is itself deleted, 0 otherwise

Version
  1.3.4

## ◆ image()

const Fl_Image * Fl_Shared_Image::image | ( |  | ) | const
| inline

Returns a pointer to the internal Fl_Image object.

The output is a pointer to the `internal` image ('Fl_Image' or subclass) which can be used to inspect or copy the image.

Do not try to modify the image! You can copy the image though if you want or need to change any attributes, size etc. If all you need to do is to resize the image you should use Fl_Shared_Image::copy(int, int) instead.

Note
  The internal image (pointer) is protected for good reasons, e.g. to prevent access to the image so it can't be modified by user code. DO NOT cast away the 'const' attribute to modify the image.

User code should rarely need this method. Use with caution.

Returns
  const Fl_Image* image, the internal Fl_Image

Since
  1.4.0

## ◆ images()

Fl_Shared_Image ** Fl_Shared_Image::images | ( |  | ) |
| static

Returns the Fl_Shared_Image* array.

Returns
  a pointer to an array of shared image pointers, sorted by name and size

See also
  Fl_Shared_Image::num_images()

## ◆ num_images()

int Fl_Shared_Image::num_images | ( |  | ) |
| static

Number of shared images in their various cached sizes.

Returns
  number of entries in the array

See also
  Fl_Shared_Image::images()

## ◆ original()

int Fl_Shared_Image::original | ( |  | ) |
| inline

Returns whether this is an original image.

Images loaded from a file or from memory are marked `original` as opposed to images created as a copy of another image with different size (width or height).

Note
  This is useful for debugging (rarely used in user code).

Since
  FLTK 1.4.0

## ◆ refcount()

int Fl_Shared_Image::refcount | ( |  | ) |
| inline

Returns the number of references of this shared image.

When reference is below 1, the image is deleted.

## ◆ release()

void Fl_Shared_Image::release | ( |  | ) |
| virtual

Releases and possibly destroys (if refcount <= 0) a shared image.

In the latter case, it will reorganize the shared image array so that no hole will occur.

Reimplemented from Fl_Image.

## ◆ uncache()

void Fl_Shared_Image::uncache | ( |  | ) |
| virtual

Remove the cached device specific image data.

See also
  Fl_Image::uncache()

Reimplemented from Fl_Image.

## ◆ update()

void Fl_Shared_Image::update | ( |  | ) |
| protected

Update the dimensions of the shared images.

Internal method to synchronize shared image data with the actual image data.

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

- Fl_Shared_Image.H
- Fl_Shared_Image.cxx