fltk::Image Class Reference

Inherits fltk::Symbol.

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

List of all members.


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.


Public Member Functions

void _draw (const Rectangle &) const
void _measure (int &W, int &H) const
const uchar * buffer () const
uchar * buffer ()
void buffer_changed ()
int buffer_depth () const
int buffer_height () const
int buffer_linedelta () const
PixelType buffer_pixeltype () const
int buffer_width () const
void clear_forceARGB32 ()
int depth () const
void destroy ()
void draw (const Rectangle &from, const Rectangle &to) const
void draw (const Rectangle &r) const
void draw (int x, int y) const
virtual bool fetch ()
void fetch_if_needed () const
bool fills_rectangle () const
bool forceARGB32 () const
int h () const
int height () const
 Image (const uchar *d, PixelType p, int w, int h, int linedelta)
 Image (const uchar *d, PixelType p, int w, int h)
 Image (PixelType p, int w, int h, const char *name=0)
 Image (int w, int h, const char *name=0)
 Image (const char *name=0)
void label (Widget *o)
uchar * linebuffer (int y)
void make_current ()
unsigned long mem_used () const
PixelType pixeltype () const
void refetch ()
void set_forceARGB32 ()
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 &r)
void setpixels (const uchar *d, const Rectangle &, int linedelta)
void setpixeltype (PixelType)
void setsize (int w, int h)
int w () const
int width () const
 ~Image ()

Static Public Member Functions

static unsigned long total_mem_used ()


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

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.

int Image::depth  )  const [inline]
 

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

int Image::width  )  const [inline]
 

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

int Image::height  )  const [inline]
 

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

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.

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 *  data,
const Rectangle r
[inline]
 

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

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

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

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.

void Image::setimage const uchar *  d,
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::setimage const uchar *  d,
PixelType  p,
int  w,
int  h
[inline]
 

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

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.

const uchar * Image::buffer  )  const
 

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

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_depth  )  const
 

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

int Image::buffer_width  )  const
 

Return the width in pixels of buffer().

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

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.

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

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.

bool Image::fills_rectangle  )  const [virtual]
 

Returns true if the pixeltype does not support alpha.

Reimplemented from fltk::Symbol.

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;
  }

void Image::fetch_if_needed  )  const
 

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

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.

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.

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.

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


Fri Apr 2 15:19:54 2010. FLTK ©2007 Bill Spitzak and others.
Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.