Image Class Reference

Inherits Symbol.

Inherited by rgbImage, SharedImage, xbmImage, and xpmImage.

List of all members.

Public Member Functions

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

Static Public Member Functions

unsigned long total_mem_used ()

Detailed Description

A rectangular buffer of pixels that the program can write (and read?) and 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.

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), or if you can efficiently use the linebuffer() and setpixels() functions to write your image to the buffer as you generate it. Otherwise you will have no efficiency advantages over drawimage() and it may actually perform worse.

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.

There is no destructor due to C++'s lame insistence that it be called on static objects. An fltk program may contain many static instances and this destruction is a waste of time on program exit, plus work must be done to avoid losing the display connection before the destruction. If you do want to destroy an Image, you must call destroy() before doing so.

Constructor & Destructor Documentation

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

The default constructor sets the width() and height() to -1, which indicates that setsize() has not been called. This allows measurement to be deferred until fetch() or _measure() is called. The pixeltype() is set to RGB32 (0x00rrggbb).

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

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

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 that the Image. If you are able to figure out the type you can read and write the pixels directly.

The non-const version will sync any previous drawing with the display, on the assumption that you are about to write to the 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.

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

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.

bool Image::fills_rectangle (   )  const [virtual]
 

Returns true if the pixeltype does not support alpha.

Reimplemented from 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 types of pixels that can be 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(d,Rectangle(w,h),linedelta);
except, if possible, d 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 (currently OS/X only).

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

Same as setpixels(data,Rectangle(0,y,width(),1)), sets the 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::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::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:
Sun Jan 7 00:55:17 2007. FLTK ©2006 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.