XmHTML Programmers Manual: XmImageInfo Structure
Author: Koen D'Hondt

### Name

> XmImageInfo structure - XmHTML External Image definition.

### Description

> The XmImageInfo structure forms the core of the image support offered by a XmHTML Widget. The information contained within this structure allow a XmHTML Widget to correctly create and display the image represented by this structure.

### Structures

    	typedef struct _XmImageInfo{
    	    /* regular image fields */
    	    String url;                  /* original location of image        */
    	    unsigned char *data;         /* raw image data.                   */
    	    unsigned char *clip;         /* raw clipmask data. XYBitmap format*/
    	    Dimension width;             /* used image width, in pixels       */
    	    Dimension height;            /* used image height, in pixels      */
    	    Dimension *reds;             /* red image pixels                  */
    	    Dimension *greens;           /* green image pixels                */
    	    Dimension *blues;            /* blue image pixels                 */
    	    int bg;                      /* transparent pixel index           */
    	    unsigned int ncolors;        /* Used number of colors             */
    	    unsigned int options;        /* configuration options             */

    	    /* image classification fields and original data */
    	    unsigned char type;          /* image type                        */
    	    unsigned char depth;         /* image bits per pixel              */
    	    unsigned char colorspace;    /* image colorspace                  */
    	    unsigned char transparency;  /* image transparency type           */
    	    Dimension swidth;            /* original image width              */
    	    Dimension sheight;           /* original image height             */
    	    unsigned int scolors;        /* original number of colors         */

    	    /* Alpha Channel Section */
    	    unsigned char *alpha;        /* alpha channel data                */
    	    float fg_gamma;              /* image gamma                       */

    	    /* Additional animation data */
    	    int x;                       /* frame x-position                  */
    	    int y;                       /* frame y-position                  */
    	    int loop_count;              /* animation loop count              */
    	    unsigned char dispose;       /* image disposal method             */
    	    int timeout;                 /* frame refreshment in milliseconds */
    	    int nframes;                 /* no of animation frames remaining  */
    	    struct _XmImageInfo *frame;  /* ptr to next animation frame       */

    	    XtPointer user_data;         /* room for user data                */
    	}XmImageInfo, *XmImageInfoStruct;

> As one can see, there are four different sections to this structure.

> #### Regular Image Data Section

> Specifies all the data required by a XmHTML Widget to create and display an image.

> - url
>   Specifies the name of the image;
> - data
>   Specifies the actual image data. This is a stream of bytes in which each byte represents an index in the image's colormap. Each value must lie in the range 0-255 inclusive;
> - clip
>   Specifies possible image clipmask data. This is a stream of bytes in XYBitmap format. A XmHTML Widget will use this data to create a clipping bitmap which will cause the displayed image to be transparent;
> - width, height
>   Specifies the dimensions of the image. The size of the image data is taken as the product of these two numbers;
> - reds, greens, blues
>   Specifies the colormap used by the image. These arrays contain respectively the red, green and blue components that make up a color. Each value must lie in the range 0-255 inclusive. Each byte in the actual image data represents an index into each of these arrays;
> - ncolors
>   Specifies the number of entries for each of the red, green and blue color arrays with a maximum value of 256;
> - bg
>   Specifies the transparent pixel index. Each byte in the image data that has this value is considered as being transparent. A value of -1 specifies that the image is not transparent;
> - ncolors
>   image configuration options. See below.

> #### Alpha Channel Section

> An Alpha Channel is a (complex) method to achieve transparency at pixel level. It is a series of values used to compute partial pixel transparency. These values range from 0 (fully transparent) to 255 (fully opaque). All intermediate values specify a certain amount of transparency for each pixel in the image.

> - alpha
>   Specifies alpha channel data. The size of this array must be equal to the size of the image data;
> - fg_gamma
>   Specifies the foreground gamma correction. It is used in combination with the display gamma value to correct the brightness for each color.

> #### Animation Section

> Specifies additional data a XmHTML Widget will use to create and display an animation. An animation consists of a number of frames which are all displayed in sequence. The size of the first frame in an animation defines the logical screen area: each subsequent frame will be positioned relative to and in this area. Frames of which the dimensions exceed the logical screen area and frames of which portions fall outside the logical screen area will be automatically clipped.

> - x,y
>   Specify the position of the current frame with respect to the dimensions of the logical screen;
> - loop_count
>   Specifies the number of times an animation should be repeated. A value of zero specifies infinite repetition;
> - dispose
>   The disposal method that is to be used for this frame. Possible values are: XmIMAGE_DISPOSE_NONE (do nothing, overlays the previous frame with the current frame), XmIMAGE_DISPOSE_BY_BACKGROUND (Restore to background setting, the area used by the previous frame is restored to current background color or image) and XmIMAGE_DISPOSE_BY_PREVIOUS (restore to previous, the area used by the previous frame is restored to what was there prior to rendering the previous frame).
> - timeout
>   Specifies the number of milliseconds that is to be waited before the next frame is displayed;
> - nframes
>   Specifies the total number of frames in an animation;
> - frame
>   Specifies the next frame;

> #### Image Classification Section

> This section contains data that is unused by a XmHTML Widget but is provided for your convenience. It provides additional information about the image.

> - type
>   Specifies the original format of the image. See XmHTMLImageGetType for a list of possible values;
> - depth
>   Specifies the number of bits per pixel. It indicates how many bits are used to store a single color, and hints to the maximum number of colors the image can have.
> - colorspace
>   Specifies the original colorspace used by this image. Possible values are: XmIMAGE_COLORSPACE_GRAYSCALE (only shades of gray, all components in a shade have the same value), XmIMAGE_COLORSPACE_INDEXED (original image refers to a predefined colormap) and XmIMAGE_COLORSPACE_RGB (the original image data is in rgb format);
> - transparency
>   Specifies the type of transparency that is to be employed for this image. Possible values are: XmIMAGE_NONE (the image is fully opaque), XmIMAGE_TRANSPARENCY_BG (the image achieves transparency by substituting the current background setting) and XmIMAGE_TRANSPARENCY_ALPHA(the image achieves transparency by using an alpha channel. This is currently only used by PNG images with an alpha channel or a tRNS chunk).
> - swidth, sheight
>   Specify the original image dimensions. These values can differ from the width and height fields if the image has been scaled;
> - scolors
>   Specifies the original number of colors in the image. This value is smaller than the ncolors field if the image has been quantized, and it can be larger than, equal to or less than the ncolors field if the image has been dithered; It's value is rather meaningless for the XmIMAGE_COLORSPACE_RGB colorspace.

> The last field in the structure (the user_data field) is unused by a XmHTML Widget and can be used to store any data one might want to associate with this image (when this image is being loaded progressively for example, this field can be used to store administration data).

### Options

> There are several options that influence the behaviour of the XmImageInfo structure. These options affect the actual image creation, the way the actual image should be created, if and when this structure should be destroyed and how this should be done. Each option sets a specific bit and multiple options can be OR'd together.

> The available options are listed below. When the description reads "Set By Default" it indicates an option that is set when a XmImageInfo structure was obtained using the XmHTMLImageDefaultProc convenience function.

> `#define XmIMAGE_DELAYED (1<<1)`
>   Indicates the image is delayed, e.i. it will be provided at a later stage. When a XmHTML Widget encounters this bit, it will display a default image instead of the actual image (the actual image data is unknown at this point). Once the final image data is available, this bit should be unset and one should use either the XmHTMLImageUpdate or XmHTMLImageReplace convenience function to instruct a XmHTML Widget to create the actual image;

> `#define XmIMAGE_DEFERRED_FREE (1<<2)`
>   Indicates XmHTML may free this structure when a new document is loaded.
>   Set By default;

> `#define XmIMAGE_IMMEDIATE_FREE (1<<3)`
>   Indicates XmHTML may free this structure when XmHTML no longer needs it;

> `#define XmIMAGE_RGB_SINGLE (1<<4)`
>   Indicates that the reds, greens and blues fields are allocated in a single memory area instead of three seperate memory arrays.
>   Set By Default;

> `#define XmIMAGE_ALLOW_SCALE (1<<5)`
>   Indicates that a XmHTML Widget is allowed to scale an image. This option has been made available after carefull consideration: the HTML 3.2 standard specifically forbids scaling of images if the width and height arguments of the `<IMG>` tag do not match the actual image dimensions. However, it is common use to specify incorrect dimensions to scale the image and hence one can choose to adhere to the standard or allow this common misbehaviour.
>   WARNING: not setting this bit will prevent an image to be scaled.
>   Set By Default;

> `#define XmIMAGE_FRAME_IGNORE (1<<6)`
>   Use with animations: set this bit when a frame falls outside the logical screen area. No pixmap is created but the timeout for the frame is kept.

> `#define XmIMAGE_CLIPMASK (1<<7)`
>   This bit should be set a XmImageInfo structure contains clipmask data. XmHTML uses this info to create a clipping bitmap. Changing this bit from set to unset will lead to a memory leak while changing it from unset to set without providing a clipmask yourself will cause an error to happen. You can set this bit when you are providing your own clipmask (to provide non-rectangular images for example), PROVIDED you fill the "clip" field with valid bitmap data;

> `#define XmIMAGE_SHARED_DATA (1<<8)`
>   This bit should be set when images share data. XmHTML sets this bit when the image in question is an internal image, e.i., one for which the image data may never be freed. Be carefull setting this bit yourself, since it prevents XmHTML from freeing the image data present in the XmImageInfo structure. It can easily lead to memory leaks when an image is not an internal image.

> `#define XmIMAGE_PROGRESSIVE (1<<9)`
>   Setting this bit will enable XmHTML progressive image loading. The present XmHTML Beta (1.1.0 as of this writing) contains a number of provisions to enable progressive image loading, but the interface is not yet fully defined.

> `#define XmIMAGE_DELAYED_CREATION (1<<10)`
>   Set this bit for images with an alpha channel present. Alpha channel processing merges the current background with the original image data using the alpha channel data to compose the actual on-screen image. When this bit is set, the XmImageInfo structure may not be freed as long as the current document is alive: to properly compose the actual image, both information on the current background and the on-screen position is required.

### See Also

> XmHTML(3X), XmHTMLImageDefaultProc(3X), XmHTMLImageFreeImageInfo(3X), XmImageCreate(3X), XmImageCreateFromInfo(3X), XmImageDestroy(3X), XmImage(3X)

XmHTML, October 7, 1997