FLTK 1.4.0: 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. More...

void	color_average (Fl_Color c, float i) FL_OVERRIDE
	Averages the colors in the image with the provided FLTK color value. More...

Fl_Image *	copy ()
	Increments the reference counter and returns a pointer to itself. More...

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

void	desaturate () FL_OVERRIDE
	Convert the image to gray scale. More...

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

const Fl_Image *	image () const
	Returns a pointer to the internal Fl_Image object. More...

const char *	name ()
	Returns the filename of the shared image.

int	original ()
	Returns whether this is an original image. More...

int	refcount ()
	Returns the number of references of this shared image. More...

void	release () FL_OVERRIDE
	Releases and possibly destroys (if refcount <= 0) a shared image. More...

virtual void	reload ()
	Reloads the shared image from disk.

void	uncache () FL_OVERRIDE
	Remove the cached device specific image data. More...

Public Member Functions inherited from Fl_Image
virtual class Fl_Shared_Image *	as_shared_image ()
	Returns whether an image is an Fl_Shared_Image or not. More...

virtual void	color_average (Fl_Color c, float i)
	The color_average() method averages the colors in the image with the provided FLTK color value. More...

Fl_Image *	copy () const
	Creates a copy of the image in the same size. More...

virtual Fl_Image *	copy (int W, int H) const
	Creates a resized copy of the image. More...

int	count () const
	Returns the number of data values associated with the image. More...

int	d () const
	Returns the image depth. More...

const char const	data () const
	Returns a pointer to the current image data array. More...

int	data_h () const
	Returns the height of the image data.

int	data_w () const
	Returns the width of the image data.

virtual void	desaturate ()
	The desaturate() method converts an image to grayscale. More...

void	draw (int X, int Y)
	Draws the image to the current drawing surface. More...

virtual void	draw (int X, int Y, int W, int H, int cx=0, int cy=0)
	Draws the image to the current drawing surface with a bounding box. More...

int	fail () const
	Returns a value that is not 0 if there is currently no image available. More...

	Fl_Image (int W, int H, int D)
	The constructor creates an empty image with the specified width, height, and depth. More...

int	h () const
	Returns the current image drawing height in FLTK units. More...

void	inactive ()
	The inactive() method calls color_average(FL_BACKGROUND_COLOR, 0.33f) to produce an image that appears grayed out. More...

virtual void	label (Fl_Menu_Item *m)
	This method is an obsolete way to set the image attribute of a menu item. More...

virtual void	label (Fl_Widget *w)
	This method is an obsolete way to set the image attribute of a widget or menu item. More...

int	ld () const
	Returns the current line data size in bytes. More...

virtual void	release ()
	Releases an Fl_Image - the same as '`delete` `this'`. More...

virtual void	scale (int width, int height, int proportional=1, int can_expand=0)
	Sets the drawing size of the image. More...

virtual void	uncache ()
	If the image has been cached for display, delete the cache data. More...

int	w () const
	Returns the current image drawing width in FLTK units. More...

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

static Fl_Shared_Image *	find (const char *name, int W=0, int H=0)
	Finds a shared image from its name and size specifications. More...

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

static Fl_Shared_Image *	get (Fl_RGB_Image *rgb, int own_it=1)
	Builds a shared image from a pre-existing Fl_RGB_Image. More...

static Fl_Shared_Image **	images ()
	Returns the Fl_Shared_Image* array. More...

static int	num_images ()
	Number of shared images in their various cached sizes. More...

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). More...

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

Protected Member Functions
void	add ()
	Adds a shared image to the image pool. More...

Fl_Shared_Image *	copy_ (int W, int H) const
	Create a resized copy of the image and wrap it into the share image class. More...

	Fl_Shared_Image ()
	Creates an empty shared image. More...

	Fl_Shared_Image (const char n, Fl_Image img=0)
	Creates a shared image from its filename and its corresponding Fl_Image* img. More...

void	update ()
	Update the dimensions of the shared images. More...

virtual	~Fl_Shared_Image ()
	The destructor frees all memory and server resources that are used by the image. More...

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

void	draw_empty (int X, int Y)
	The protected method draw_empty() draws a box with an X in it. More...

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

void	h (int H)
	Sets the height of the image data. More...

void	ld (int LD)
	Sets the current line data size in bytes. More...

void	w (int W)
	Sets the width of the image data. More...

Static Protected Member Functions
static int	compare (Fl_Shared_Image i0, Fl_Shared_Image i1)
	Compares two shared images. More...

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:

Image name, usually the filename used to load it
Image width
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, andthis->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():

search with exact width and height
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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Fl_Shared_Image() [1/2]

◆ Fl_Shared_Image() [2/2]

◆ ~Fl_Shared_Image()

Member Function Documentation

◆ add()

◆ add_handler()

◆ as_shared_image()

◆ color_average()

◆ compare()

◆ copy() [1/2]

◆ copy() [2/2]

◆ copy_()

◆ desaturate()

◆ draw()

◆ find()

◆ get() [1/2]

◆ get() [2/2]

◆ image()

◆ images()

◆ num_images()

◆ original()

◆ refcount()

◆ release()

◆ uncache()

◆ update()