Next: , Previous: , Up: Part VI Images   [Contents][Index]


37.2 The FL_IMAGE Structure

Before we go into more details on image support, some comments on the image structure are in order. The image structure contains the following basic fields that describe fully the image in question and how it should be displayed.

typedef unsigned char FL_PCTYPE;         /* primary color type */
#define FL_PCBITS     8                  /* primary color bits */
#define FL_PCMAX      ((1<<FL_PCBITS)-1) /* primary color max val */
typedef unsigned int  FL_PACKED;         /* packed RGB(A) type */

typedef struct flimage_ {
    int               type;
    int               w,
                      h;
    void            * app_data;
    void            * u_vdata;
    unsigned char  ** red;
    unsigned char  ** green;
    unsigned char  ** blue;
    unsigned char  ** alpha;
    unsigned short ** ci;
    unsigned short ** gray;
    FL_PACKED      ** packed;
    short           * red_lut;
    short           * green_lut;
    short           * blue_lut;
    short           * alpha_lut;
    int               map_len;
    int               colors;
    int               gray_maxval;
    int               app_background;
    int               wx,
                      wy;
    int               sx,
                      sy;
    int               sw,
                      sh;
    char            * comments;
    int              comments_len;
    void            * io_spec;
    int               spec_size;
    int               (*display) (struct flimage_ *, FL_WINDOW win);
    struct flimage_ * next;
    int               double_buffer;
    unsigned long     pixmap;
    /* more stuff omitted */
} FL_IMAGE;

The meaning of each field is as follows:

type

This field specifies the current image type and storage (1bit, 24bit etc. See next section for details). The image type also indicates implicitly which of the pixel fields should be used.

w,h

The width and height of the image.

app_data

A field that’s initialized at image creation. Its value can be set by the application prior to any existence of image. Once set, all images created thereafter will have the same value for this field. See Section later. The Forms Library does not modify or reference it once it’s initialized.

u_vdata

A field for use by the application. This field is always initialize to null. The Forms Library does not reference or modify it.

red, green, blue, alpha

This first three fields are the color components of a 24 bit image, each of which is a 2-dimensional array. The 2D array is arranged so the image runs from left to right and top to bottom. For example, the 3rd pixel on the 10th row is composed of the following RGB elements: (red[9][2],green[9][2],blue[9][2]). Note however, these fields are meaningful only if the image type is FL_IMAGE_RGB. Although it’s always allocated for a 24bit image, alpha is currently not used by the Forms Library

ci

The field are the pixel values for a color index image (image type FL_IMAGE_CI). The field is also a 2-dimensional array arranged in the same way as the fields red, green and blue, i.e., the image runs from left to right, top to bottom. For example, ci[3][9] should be used to obtain the 10th pixel on the 4th row. To obtain the RGB elements of a pixel, the pixel value should be used as an index into a lookup table specified by the fields red_lut, green_lut and blue_lut. Although ci can hold an unsigned short, only the lower FL_LUTBITS (12) bits are supported, i.e., the color index should not be bigger than 4095.

gray

This field, again a 2-dimensional array, holds the pixels of a gray image. The pixel values are interpreted as intensities in a linear fashion. Two types of gray images are supported, 8 bit (FL_IMAGE_GRAY) and 16 bit (FL_IMAGE_GRAY16). For 16 bit gray image, the actual depths of the image is indicated by member gray_maxval. For example, if gray_maxval is 4095, it is assumed that the actual pixel value ranges from 0 to 4095, i.e., the gray scale image is 12 bit. For 8 bit grayscale image, gray_maxval is not used. This means that the type FL_IMAGE_GRAY is always assumed to be 8 bit, the loading and creating routine should take care to properly scale data that are less than 8 bit.

gray_maxval

This field is meaningful only if the image type is FL_IMAGE_GRAY16. It specifies the actual dynamic range of the gray intensities. Its value should be set by the image loading routines if the gray image depth is more than 8 bits.

ci_maxval

This field by default is 256, indicating the maximum value of the color index.

packed

This field (a 2-dimensional array) holds a 24 bit/32 bit image in a packed format. Each element of the 2D array is an unsigned integer (for now) that holds the RGB, one byte each, in the lower 24 bits of the integer. The topmost byte is not used. The macro FL_PACK(r, g, b) should be used to pack the triplet (r, g, b) into a pixel and FL_UNPACK(p, r, g, b) should be used to unpack a pixel. To obtain individual primary colors, the macros FL_GETR(p), FL_GETG(p) and FL_GETB(p) are available.

Note that the use of the macros to pack and unpack are strongly recommended. It will isolate the application program from future changes of the primary color type (for example, 16-bit resolution for R,G and B).

red_lut, green_lut, blue_lut, alpha_lut

These are the lookup tables for a color index image. Each of the table is a 1D array of length image->map len. Although alpha lut is always allocated for a color index image, it’s currently not used by the Forms Library.

map_len

The length of the colormap (lookup table).

app_background

A packed RGB value indicating the preferred color to use for the background of an image (also known as transparent color). This field is initialized to an illegal value. Since there is no portable way to obtain the window background the application has to set this field if transparency is to be achieved. In future versions of image support, other means of doing transparency will be explored and implemented.

wx, wy

The window offset to use to display the image.

sx, sy, sw, sh

The subimage to display.

comments

This is typically set by the loading routines to convey some information about the image. The application is free to choose how to display the comment, which may have embedded newlines in it.

io_spec

This field is meant for the reading/writing routine to place format specific state information that otherwise needs to be static or global.

spec_size

This field should be set to the number of bytes io_spec contains.

display

A function you can use to display an image. The image loading routine sets this function.

next

This is a link to the next image. This is how flimage_load() chains multiple image together.

double_buffer

If true, the display function will double-buffer the image by using a pixmap. For typical image display it’s not necessary to enable double-buffering as it is very expensive (memory and speed). Double-buffering may be useful in image editing.

pixmap

The backbuffer pixmap if double-buffered.

Although it is generally not necessary for an application to access individual pixels, the need to do so may arise. In doing so, it is important to consult the image->type field before dereferencing any of the pixel field. That is, you should access image->ci only if you know that the image type is FL_IMAGE_CI or FL_IMAGE_MONO.


Next: , Previous: , Up: Part VI Images   [Contents][Index]