Supported image types (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Creating Images, Previous: The FL_IMAGE Structure, Up: Part VI Images [Contents][Index]

### 37.3 Supported image types

Forms Library supports all common and not-so-common image types. For example, the supported images range from the simple 1 bit bitmap to full 24 bit RGB images. 12 bit gray scale images (common in medical imaging) are also supported.

The supported image types are denoted using the following constants, all of them (except `FL_IMAGE_FLEX`) using a different bit, so they can be bitwise ORed together:

    FL_IMAGE_MONO,    /* 1 bit bitmaps */
    FL_IMAGE_GRAY,    /* gray-scale image (8 bit) */
    FL_IMAGE_GRAY16,  /* gray-scale image (9 to 16 bit) */
    FL_IMAGE_CI,      /* generic color index image */
    FL_IMAGE_RGB,     /* 24 bit RGB(A) image */
    FL_IMAGE_PACKED,  /* 24 bit RGB(A) image. Packed storage */
    FL_IMAGE_FLEX,    /* All of the above */

For the 24 bit variety another 8 bit (`image->alpha` and the top-most byte of the packed integer) is available for the application, perhaps storing the alpha values into it. The Forms Library does not modify or reference this extra byte.

Mono (b&w) images are stored as a colormap image with a lut of length 2.

The `FL_IMAGE_FLEX` type is mainly for the reading and loading routines to indicate the types they are capable of handling. For example, if you’re coding an output routine, you use `FL_IMAGE_FLEX` to indicate that the output routine can take any type the image. Otherwise the driver will convert the image type before handing the image over to the actual output routine.

In displaying an image of type `FL_IMAGE_GRAY16`, window leveling, a technique to visualize specific ranges of the data, is employed. Basically, you specify a window level (`level`) and a window width (`wwidth`) and the display function will map all pixels that fall within `level-width/2` and `level+width/2` linearly to the whole dynamic range of the intensities the hardware is capable of displaying. For example, if the display device can only display 256 shades of gray, `level-width/2` is mapped to 0 and `level+width/2` is mapped to 255, and pixels values between `level-width/2` and `level+width/2` are linearly mapped to values between 0 and 255. Pixel values that fall below `level-width/2` are mapped to zero and those that larger than `level+width/2` are mapped to 255.

Use the following routine to set the window level

    int flimage_windowlevel(FL_IMAGE *im, int level, int wwidth);

The function returns 1 if window level parameters are modified, otherwise 0 is returned. Setting `wwidth` to zero disables window leveling. Note that if `im` points to a multiple image, window level parameters are changed for all images.

To obtain the image type name in string format, e.g., for reporting purposes, use the following routine

    const char *flimage_type_name(int type);

To convert between different types of images, the following routine is available

    int flimage_convert(FL_IMAGE *image, int newtype, int ncolors);

The parameter `newtype` should be one of the supported image types mentioned earlier in this section. Parameter `ncolors` is meaningful only if `newtype` is `FL_IMAGE_CI`. In this case, it specifies the number of colors to generate, most likely from a color quantization process. If the conversion is successful a non-negative integer is returned, otherwise a negative integaer. Depending on which quantization function is used, the number of quantized colors may not be more than 256.

To keep information loss to a minimum, `flimage_convert()` may elect to keep the original image in memory even if the conversion is successful. For example, converting a full color image (24 bit) into a 8 bit image and then converting back can lose much information of the image if the converting function does not keep the original image.

What this means is that the following sequence gets back the original image

    /* the current image is RGB. Now we reduce the full color
       image to 8 bit color index image. The conversion routine
       will keep the 24 bit color. */

    flimage_convert(image, FL_IMAGE_CI, 256);

    /* Now convert back to RGB for image processing. The con-
       version routine will notice that the input image was
       originally converted from a 24bit image. Instead of
       doing the conversion, it simply retrieves the saved
       image and returns. */

    flimage_convert(image, FL_IMAGE_RGB, 0);

This behavior might not always be what the application wants. To override it, you can set `image->force_convert` to 1 before calling the conversion routine. Upon function return the flag is reset to zero.

Next: Creating Images, Previous: The FL_IMAGE Structure, Up: Part VI Images [Contents][Index]