Drawing Images
[Drawing Functions]


Typedefs

typedef const uchar *(* fltk::DrawImageCallback )(void *data, int x, int y, int w, uchar *buffer)

Enumerations

enum  fltk::PixelType {
  fltk::MASK, fltk::MONO, fltk::BGR, fltk::RGB,
  fltk::RGBA, fltk::ABGR, fltk::ARGB, fltk::BGRA,
  fltk::RGBM, fltk::MBGR, fltk::MRGB, fltk::BGRM
}

Functions

int fltk::depth (PixelType t)
void fltk::drawimage (DrawImageCallback, void *, PixelType, const Rectangle &, int delta)
void fltk::drawimage (DrawImageCallback, void *, PixelType, const Rectangle &)
void fltk::drawimage (const uchar *, PixelType, const Rectangle &, int delta, int ldelta)
void fltk::drawimage (const uchar *, PixelType, const Rectangle &, int delta)
void fltk::drawimage (const uchar *, PixelType, const Rectangle &)
uchar * fltk::readimage (uchar *p, PixelType, const Rectangle &, int delta, int ldelta)
uchar * fltk::readimage (uchar *p, PixelType, const Rectangle &, int delta)
uchar * fltk::readimage (uchar *p, PixelType, const Rectangle &)

Detailed Description

If you plan to draw the same image many times, you may want an fltk::Image subclass and call draw() on it. The advantage of using such an object is that the image data is stored already-translated to whatever form the display needs (and on X at least it is stored in the same memory space as the server), so drawing it is much faster. (Also currently alpha transparency is broken on X and Windows unless you use an Image).

The advantage of using these calls verses fltk::Image is that it is a lot easier to write the program. It also is the fastest way if you are only going to draw the image once (for instance a video image that is changing, or the output of your painting program that you want the user to change).

Currently the image is only affected by the integer portion of the current transformation. This may change in future versions!

The X version does not support some visuals and will abort() if this is called on them. Currently only TrueColor, the rare DirectColor, and PseudoColor of less or equal to 8 bits are supported. It is recommended that you put fltk::visual(fltk::RGB) at the start of your program to indicate that you want TrueColor, all known X servers unsupported by FLTK in their default mode provide a working full-color mode.

Typedef Documentation

DrawImageCallback
 

Type of function passed to drawimage(). It must return a pointer to a horizontal row of w pixels, starting with the pixel at x and y (relative to the top-left corner of the image, not to the coordinate space drawimage() is called in). These pixels must be in the format described by type passed to drawimage() and must be the delta apart passed to drawimage().

data is the same as the argument passed to drawimage(). This can be used to point at a structure of information about the image.

The passed buffer contains room for at least the number of pixels specified by the width passed to drawimage(). You can use this as temporary storage to construct a row of the image, and return a pointer to it (or offset x into it if desired).

Due to cropping, less than the whole image may be requested. So the callback may get an x greater than zero, the first y passed to it may be greater than zero, and x+w may be less than the width of the image. The passed buffer is long enough to store the entire w * delta bytes, this is for convienence with some decompression schemes where you must decompress the entire line at once: decompress it into the buffer, and then if x is not zero, shift the data over so the x'th pixel is at the start of the buffer.

Enumeration Type Documentation

enum PixelType
 

Enumeration describing how colors are stored in an array of bytes that is a pixel. This is used as an argument for fltk::drawimage(), fltk::readimage(), and fltk::Symbol::readimage().

The types are described by the order the bytes are in memory. Thus RGB means R is stored at a byte with an address of one less than where G is stored. Warning: some Windows and X software describes the pixels backwards from this. I use this standard because it works for arrays of data larger than bytes.

The Mask types are not supported except on OS/X, they render the same as the premultiplied versions on other platforms. This may be fixed in the future.

Enumeration values:
MASK  1 byte: 0xff = fltk::getcolor(), 0 = transparent
MONO  1 byte: 0xff = fltk::getbgcolor(), 0 = fltk::getcolor() ("inverted" so that a b&w image looks correct in black color)
BGR  often used by Windows software
RGB  normal method of storing 3-channel color
RGBA  normal method of storing 4-channel color, array of fltk::Color on a big-endian machine
ABGR  array of fltk::Color on a little-endian machine
ARGB  some Windows software on a big-endian machine
BGRA  often used by Windows software
RGBM  RGBA but not premultiplied (M stands for "mask").
MBGR  ABGR but not premultiplied.
MRGB  ARGB but not premultiplied.
BGRM  BRGA but not premultiplied.

Function Documentation

void drawimage (  const uchar *  pointer,
fltk::PixelType  type,
const Rectangle &  r
) 
 

Same except delta is set to the number of bytes used by type, and line_delta is set to r.w() times delta, indicating the rows are packed together one after another with no gap.

If you use fltk::RGB make sure your source data really is packed, if each row starts word-aligned then you must use the version where you pass the line_delta

void drawimage (  const uchar *  pointer,
fltk::PixelType  type,
const Rectangle &  r,
int  delta
) 
 

Same except line_delta is set to r.w() times delta, indicating the rows are packed together one after another with no gap.

If you use fltk::RGB make sure your source data really is packed, if each row starts word-aligned then you must use the version where you pass the line_delta

void drawimage (  const uchar *  pointer,
fltk::PixelType  type,
const Rectangle &  r,
int  delta,
int  line_delta
) 
 

Draw an image.

  • pointer points at the first byte of the top-left pixel.
  • type describes how to interpret the bytes of each pixel.
  • the image is put in the top-left corner of the rectangle, possibly clipped by the rectangle's bottom and right edge.
  • delta is how much to add to pointer to go 1 pixel to the right
  • line_delta is how much to add to pointer to go 1 pixel down

By setting line_delta to larger than delta*r.w() you can crop a picture out of a larger buffer. By setting delta to larger than the size of the pixel data you can skip extra bytes, such as alpha information you don't want, or draw one channel of an rgb image as a gray-scale iamge. By setting line_delta and/or delta negative you can get 90 degree rotations and mirror images of the data.

void drawimage (  DrawImageCallback  cb,
void *  data,
fltk::PixelType  type,
const Rectangle &  r
) 
 

Same except the delta is figured out from the type.

void drawimage (  DrawImageCallback  cb,
void *  data,
fltk::PixelType  type,
const Rectangle &  r,
int  delta
) 
 

Call the passed function to provide each scan line of the image. This lets you generate the image as it is being drawn, or do arbitrary decompression of stored data (provided it can be decompressed to individual scan lines easily).

callback is called with the void* data argument (this can be used to point at a structure of information about the image), the x, y, and number of pixels desired from the image, measured from the upper-left corner of the image. It is also given a buffer of at least w pixels that can be used as temporary storage, for instance to decompress a line read from a file. You can then return a pointer to this buffer, or to somewhere inside it.

The callback must return n pixels of the format described by type, delta apart from each other.

The xywh rectangle describes the area to draw. The callback is called with y values between y and y+h-1. Due to cropping not all pixels may be asked for. You can assumme y will be asked for in increasing order.

uchar * readimage (  uchar *  p,
PixelType  type,
const Rectangle &  r
) 
 

Reads a 2-D image off the current drawing destination. The resulting data can be passed to fltk::drawimage() or the 8-bit pixels examined or stored by your program.

The return value is either p or NULL if there is some problem (such as an inability to read from the current output surface, or if the rectangle is empty).

p points to the location to store the first byte of the upper-left pixel of the image.

type can be fltk::RGB or fltk::RGBA (possibly other types will be supported in the future).

rectangle indicates the position on the surface in the current transformation to read from and the width and height of the resulting image. What happens when the current transformation is rotated or scaled is undefined. If the rectangle extends outside the current drawing surface, or into areas obscured by overlapping windows, the result in those areas is undefined.

uchar * readimage (  uchar *  p,
PixelType  type,
const Rectangle &  r,
int  delta
) 
 

Same except delta is how much to add to a pointer into the buffer to go to the next pixel. This can be used to skip over extra data for each pixel, for instance to read RGB data into a 4-byte/pixel buffer. The skipped pixels are left with undefined values, do not assumme they are unchanged!

uchar * readimage (  uchar *  p,
PixelType  type,
const Rectangle &  rectangle,
int  delta,
int  linedelta
) 
 

p points to the location to store the first byte of the upper-left pixel of the image. The caller must allocate this, it cannot be NULL.

delta is how much to add to a pointer to advance from one pixel to the one to it's right. Any bytes skipped over are left with undefined values in them.

linedelta is how much to add to a pointer to advance from one pixel to the one below it. Any bytes skipped over are left with undefined values in them.

Negative values for delta and linedelta can be used to produce mirror images or 90 degree rotations of the data.

int depth (  PixelType  t  )  [inline]
 

Turn a PixelType into the number of bytes needed to hold a pixel.

Sun May 8 21:48:57 2005. FLTK ©2004 Bill Spitzak and others. See Main Page for details.