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.

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.

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.

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.

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