The FL_IMAGE Structure (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Supported image types, Previous: The Basic Image Support API, 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: Supported image types, Previous: The Basic Image Support API, Up: Part VI Images [Contents][Index]