Inherits fltk::Symbol.

Inherited by fltk::rgbImage, fltk::SharedImage, fltk::xbmImage, and fltk::xpmImage.

Public Member Functions
void	_draw (const Rectangle &) const
void	_measure (int &W, int &H) const
uchar *	buffer ()
const uchar *	buffer () const
void	buffer_changed ()
int	buffer_depth () const
int	buffer_height () const
int	buffer_linedelta () const
PixelType	buffer_pixeltype () const
int	buffer_width () const
int	depth () const
void	destroy ()
void	draw (const Rectangle &from, const Rectangle &to) const
void	draw (int x, int y) const
void	draw (const Rectangle &r) const
void	draw_diced (const Rectangle &R)
virtual bool	fetch ()
void	fetch_if_needed () const
bool	fills_rectangle () const
int	height () const
	Image (const uchar *d, PixelType p, int w, int h)
	Image (int w, int h, const char *name=0)
	Image (const char *name=0)
	Image (const uchar *d, PixelType p, int w, int h, int linedelta)
	Image (PixelType p, int w, int h, const char *name=0)
void	label (Widget *o)
uchar *	linebuffer (int y)
unsigned long	mem_used () const
PixelType	pixeltype () const
void	refetch ()
void	setimage (const uchar *d, PixelType p, int w, int h)
void	setimage (const uchar *d, PixelType p, int w, int h, int linedelta)
void	setpixels (const uchar *d, int y)
void	setpixels (const uchar *d, const Rectangle &, int linedelta)
void	setpixels (const uchar *d, const Rectangle &r)
void	setpixeltype (PixelType)
void	setsize (int w, int h)
int	width () const
	~Image ()
Static Public Member Functions
static unsigned long	total_mem_used ()

Detailed Description

A rectangular buffer of pixels that can be efficiently drawn on the screen. The draw() functions will copy (or "over" composite if there is alpha in the pixeltype()) onto the output, transformed by the current transform.

NOTE: If you already have a set of pixels sitting in your own memory, drawimage() can draw it and is much easier to use. You should use this class only if you will be drawing the same image multiple times, with no changes to the pixels.

The buffer is created and filled in by setting the type of pixels with setpixeltype(), the size with setsize(), and then calling buffer() (note that setpixels() calls buffer() for you). The initial buffer is filled with undefined contents.

The best way to put data into the buffer is to make one or more calls to setpixels(), to replace rectangular regions.

You can directly address the buffer() to read and write the pixels. The size of the buffer is in buffer_width() and buffer_height() (this may be much larger than width() and height()) and the distance between lines is in buffer_linedelta(). If you change any pixels you should call buffer_changed() before the next draw().

Due to operating system limitations, buffer() is usually not an array of pixeltype() pixels. Instead setpixels() converts pixels into a type the operating system can use. The type of pixels in the buffer is retured by buffer_pixeltype(). This is really inconvienent, so you can also call the method force_ARGB32_on(). This will cause buffer_pixeltype() to return ARGB32, so you can assume this at compile time. The implementation of Image may be less efficient (actually the overhead is zero on Windows and close to zero on most other systems)

If buffer() has not been called, draw() will call the fetch() virtual method. It should call setpixeltype(), setsize() and setpixels(). This is used to defer reading image files or decompressing data until needed. fetch() will also restore the buffer contents to the original values if you have written to the buffer. If fetch() does not allocate a buffer, draw() will draw a solid rectangle in the current color.

Because Image is a subclass of Symbol, it may be used as a Widget::image() or as the box() in a Style. If you give it a name it can be drawn with "@name;" in a label. If resized, the Symbol _draw() method will use the inset() call to decide on edge thicknesses and will dice the image up into 9 individually-scaled pieces, which is very useful for GUI buttons and background images (this is similar to how Flash draws buttons).

There are a number of subclasses such as jpgImage and pngImage that display compressed image data, either from in-memory data buffers or from files.

Constructor & Destructor Documentation

Image::Image ( const char * name = 0 ) [inline]

The default constructor sets pixeltype() to RGB32 (0x00rrggbb) and width() and height() to 12. This means that 12x12 square with the current color will be drawn if not able to draw anything else.

The optional name is passed to the Symbol constructor and allows the image to be drawn by putting "@name;" into a label.

Image::Image	(	int	w,
		int	h,
		const char *	name = `0`
	)		`[inline]`

Does setsize(w,h). This causes the width() and height() to return the passed values. No buffer is allocated, call buffer() to do that. The pixeltype() is set to RGB32 (0x00rrggbb).

Image::Image	(	PixelType	p,
		int	w,
		int	h,
		const char *	name = `0`
	)		`[inline]`

Does pixeltype(p) and setsize(w,h). No buffer is allocated, call buffer() to do that.

Image::Image	(	const uchar *	data,
		PixelType	p,
		int	w,
		int	h
	)		`[inline]`

Initializes the size and pixels by doing setimage(). Note that the pointer data may be used unchanged. If you want to force a copy you should use setpixels() instead.

Image::Image	(	const uchar *	data,
		PixelType	p,
		int	w,
		int	h,
		int	linedelta
	)		`[inline]`

Initializes the size and pixels by doing setimage(). Note that the pointer data may be used unchanged. If you want to force a copy you should use setpixels() instead.

Image::~Image ( )

The destructor calls destroy()

Member Function Documentation

void Image::_draw ( const Rectangle & r ) const [virtual]

Resizes the image to fit in the rectangle. This is the virtual method from the Symbol base class, so this is what is called if the image is used as a label or box type.

If the destination rectangle is not the same size, inset() is used to figure out the edge thicknesses. The image is then diced into 9 rectangles in a 3x3 grid by the insets, and each piece is scaled individually. This is very useful for scaling paintings of buttons. Note that if the insets are zero (the default) then the whole image is scaled as one piece. If you want, inset() can return different thicknesses depending on the size, producing very interesting scaling.

It is possible this will use drawflags(INACTIVE) to gray out the image in a system-specific way. NYI.

Implements fltk::Symbol.

Reimplemented in fltk::SharedImage.

void Image::_measure	(	int &	W,
		int &	H
	)		const `[virtual]`

Returns width() and height().

The default constructor sets an internal flag that indicates that fetch() must be called before the width() and height() are known. This is useful for subclasses that read a file and figure out both the size and pixels at the same time.

Reimplemented from fltk::Symbol.

const uchar * Image::buffer ( ) const

This just does a const-cast and calls the non-const version.

uchar * Image::buffer ( )

Creates (if necessary) and returns a pointer to the internal pixel buffer. This is probably going to be shared memory with the graphics system, it may have a different pixeltype, size, and linedelta than the Image. If you are able to figure out the type you can read and write the pixels directly.

void Image::buffer_changed ( ) [inline]

Call this if you modify the contents of buffer(). On some systems the memory is not actually shared with the window system, and this will cause draw() to copy the buffer to the system's memory. setpixels() calls this for you.

int Image::buffer_depth ( ) const

Returns the number of bytes per pixel stored in buffer(). This is the same as depth(buffer_pixeltype()).

int Image::buffer_height ( ) const

Return the height in pixels of buffer();

int Image::buffer_linedelta ( ) const

Return the distance between each row of pixels in buffer().

PixelType Image::buffer_pixeltype ( ) const

Return the type of pixels stored in buffer(). Likely to be ARGB32. On older (non-XRender) X system the types 1 and 2 indicate 1 and 2-byte data, but there is no api to figure out anything more about this data.

int Image::buffer_width ( ) const

Return the width in pixels of buffer().

int Image::depth ( ) const [inline]

Same as depth(pixeltype()), this returns how many bytes each pixel takes in the buffer sent to setpixels().

void Image::destroy ( )

Destroys the buffer() and any related system structures.

void Image::draw	(	int	x,
		int	y
	)		const

Does measure() and then draw(Rectangle(0,0,w,h),Rectangle(x,y,w,h). Thus the top-left corner is placed at x,y and no scaling (other than due to the current transformation) is done.

void Image::draw	(	const Rectangle &	from,
		const Rectangle &	to
	)		const

Draws the subrectangle from of the image, transformed to fill the rectangle to (as transformed by the CTM). If the image has an alpha channel, an "over" operation is done.

Due to lame graphics systems, this is not fully operational on all systems: X11 without XRender extension: no transformations are done, the image is centered in the output area. X11 with XRender: rotations fill the bounding box of the destination rectangle, drawing extra triangular areas outside the source rectangle. Somewhat bad filtering when making images smaller. xbmImage does not transform. Windows: Only scaling, no rotations. Bad filtering. xbmImage does not do any transformations. OS/X: works well in all cases.

void fltk::Image::draw ( const Rectangle & r ) const [inline]

Draw the symbol in the Rectangley r. Depending on the actual symbol it may scale to fit this rectangle, or just draw in the upper-left corner, in most cases clipping to the rectangle if too big.

The most recent values sent to fltk::setcolor(), fltk::setbgcolor(), fltk::setdrawflags(), fltk::setfont(), etc, may be used by the symbol to change how it draws. The symbol should not change any of these values, if it needs to it should save and restore the original value (some fake built-in symbols will change these to affect the color used to draw the rest of a string of text).

Reimplemented from fltk::Symbol.

void Image::draw_diced ( const Rectangle & R )

Cubes an image and draws the 4 corners. It then expands the middle of the cube as far as needed, whilst only expanding the top and side edges horizontally/vertically as needed. With an image that has pixels set out as such: ABA CDC ABA The final image looks as follows, and is expanded to fit the required rectangle: AABBBBBAA AABBBBBAA CCDDDDDCC CCDDDDDCC CCDDDDDCC CCDDDDDCC CCDDDDDCC AABBBBBAA AABBBBBAA This function is mostly called from within FLTK's themes.

bool Image::fetch ( ) [virtual]

This is called by the draw() functions once after the Image is created or after refetch() has been called. This allows subclasses to defer reading files and calling setpixels() calls until the first draw() or measure(). This should return true if successful, false on any error (though fltk does not do anything useful with errors).

The base class does nothing and returns true, thus leaving the image unchanged.

Sample implementation:

  bool MyImage::fetch() {
    setsize(get_width(file), get_height(file));
    setpixeltype(my_pixeltype);
    for (int y=0; y<height(); y++) {
      uchar* buffer = linebuffer(y);
      get_line_of_pixels(file, buffer, y);
      setpixels(buffer, y);
    }
    return true;
  }

Reimplemented in fltk::SharedImage, fltk::gifImage, fltk::xpmFileImage, fltk::xbmImage, and fltk::xpmImage.

void Image::fetch_if_needed ( ) const

Call fetch() if it has not been called or if refetch() was called.

bool Image::fills_rectangle ( ) const [virtual]

Returns true if the pixeltype does not support alpha.

Reimplemented from fltk::Symbol.

int Image::height ( ) const [inline]

Return the height of the image in pixels. You can change this with setsize().

void Image::label ( Widget * o )

This is a 1.1 back-compatability function. It is the same as doing widget->image(this) and widget->label(0).

uchar * Image::linebuffer ( int y )

Return a pointer to a buffer that you can write up to width() pixels in pixeltype() to and then call setpixels(buffer,y) with. This can avoid doing any copying of the data if the internal format and pixeltype() are compatable, because it will return a pointer directly into the buffer and setpixels will detect this and do nothing.

unsigned long Image::mem_used ( ) const

Returns how much memory the image is using for buffer() and for any other structures it created. Returns zero if buffer() has not been called.

PixelType Image::pixeltype ( ) const [inline]

Return the type of pixels that are put into the image with setpixels(). You can change this with setpixeltype(). It is possible the internal data is in a different type, use buffer_pixeltype() to find out what that is.

void Image::refetch ( ) [inline]

Cause fetch() to be called again. This is useful for a file image if the file name or contents have changed.

void Image::setimage	(	const uchar *	d,
		PixelType	p,
		int	w,
		int	h
	)		`[inline]`

Figures out linedelta for you as w*depth(p).

void Image::setimage	(	const uchar *	source,
		PixelType	p,
		int	w,
		int	h,
		int	ld
	)

This is equivalent to:

  setsize(w, h);
  setpixeltype(p);
  setpixels(source, Rectangle(w,h), linedelta);

except, if possible, source is used as buffer() (throwing away the const!). This will happen if the pixeltype and linedelta are of types that it can handle unchanged and if the image memory does not need to be allocated by the system.

void Image::setpixels	(	const uchar *	buf,
		const Rectangle &	r,
		int	linedelta
	)

Replace the given rectangle of buffer() with the supplied data, which must be in the pixeltype(). linedelta is the distance between each row of pixels in data. The rectangle is assummed to fit inside the width() and height().

void Image::setpixels	(	const uchar *	buf,
		int	y
	)

Same as setpixels(data,Rectangle(0,y,width(),1)), sets one entire row of pixels.

void Image::setpixels	(	const uchar *	data,
		const Rectangle &	r
	)		`[inline]`

Figures out the linedelta for you as depth()*r.w().

void Image::setpixeltype ( PixelType p )

Change the stored pixeltype. If it is not compatable then destroy() is called.

void Image::setsize	(	int	w,
		int	h
	)

Change the size of the stored image. If it is not compatable with the current data size (generally if it is larger) then destroy() is called.

unsigned long Image::total_mem_used ( ) [inline, static]

Sum of all mem_used() calls to all Images. This is used by SharedImage to decide when to clear out cached images.

int Image::width ( ) const [inline]

Return the width of the image in pixels. You can change this with setsize().

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

fltk/Image.h
src/Image.cxx
src/osx/Image.cxx
src/win32/Image.cxx
src/x11/Image.cxx

fltk::Image Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation