1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>XmHTML Programmers Manual: XmImageInfo Structure</TITLE>
<META HTTP-EQUIV="Keywords" CONTENT="XmHTML, HTML, Motif, Widget, eXode, XntHelp, Linux">
<META HTTP-EQUIV="Reply-to" CONTENT="ripley@xs4all.nl">
<META HTTP-EQUIV="Description"
CONTENT = "XmImageInfo structre - XmHTML External Image definition.">
<META NAME="Author" CONTENT="Koen D'Hondt">
<META NAME="Copyright" content="1995-1997 by Ripley Software Development">
<META NAME="Source" content="$Source$">
<META NAME="Revision" content="$Revision$">
<META NAME="Font" content="helvetica">
<link rev="made" href="mailto:ripley@xs4all.nl">
<link rel="home" href="http://www.xs4all.nl/~ripley">
<link rel="previous" href="HTML.html">
<link rel="next" href="XmImage.html">
<link rel="up" href="../man.html">
<link rel="copyright" href="copyrights.html">
</HEAD>
<BODY BGCOLOR="#FFFFFF" text="#000000">
<h3><font face="helvetica,arial">Name</font></h3>
<blockquote>
XmImageInfo structure - XmHTML External Image definition.
</blockquote>
<h3><font face="helvetica,arial">Description</font></h3>
<blockquote>
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.
</blockquote>
<h3><font face="helvetica,arial">Structures</font></h3>
<pre>
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;
</pre>
<blockquote>
As one can see, there are four different sections to this structure.
<p>
<h4><font face="helvetica,arial">Regular Image Data Section</font></h4>
Specifies all the data required by a XmHTML Widget to create and
display an image.
<p>
<ul>
<li>url<br>
Specifies the name of the image;
<li>data<br>
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;
<li>clip<br>
Specifies possible image clipmask data.
This is a stream of bytes in XYBitmap format. A XmHTML Widget
will use this data to create a <i>clipping</i> bitmap which will
cause the displayed image to be transparent;
<li>width, height<br>
Specifies the dimensions of the image. The size
of the image data is taken as the product of these two numbers;
<li>reds, greens, blues<br>
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;
<li>ncolors<br>
Specifies the number of entries for each of the
red, green and blue color arrays with a maximum value of 256;
<li>bg<br>
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;
<li>ncolors<br>
image configuration options. See below.
</ul>
<h4><font face="helvetica,arial">Alpha Channel Section</font></h4>
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.
<p>
<ul>
<li>alpha<br>
Specifies alpha channel data. The size of this
array must be equal to the size of the image data;
<li>fg_gamma<br>
Specifies the foreground gamma correction.
It is used in combination with the display gamma value to correct
the brightness for each color.
</ul>
<h4><font face="helvetica,arial">Animation Section</font></h4>
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 <b>first</b>
frame in an animation defines the <i>logical screen area</i>: 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.
<p>
<ul>
<li>x,y<br>
Specify the position of the current frame
with respect to the dimensions of the logical screen;
<li>loop_count<br>
Specifies the number of times an animation
should be repeated. A value of zero specifies infinite repetition;
<li>dispose<br>
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).
<li>timeout<br>
Specifies the number of milliseconds that is
to be waited before the next frame is displayed;
<li>nframes<br>
Specifies the total number of frames in an
animation;
<li>frame<br>
Specifies the next frame;
</ul>
<h4><font face="helvetica,arial">Image Classification Section</font></h4>
This section contains data that is unused by a XmHTML Widget but
is provided for your convenience. It provides additional information
about the image.
<p>
<ul>
<li>type<br>
Specifies the original format of the image.
See XmHTMLImageGetType for a list of possible values;
<li>depth<br>
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.
<li>colorspace<br>
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);
<li>transparency<br>
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).
<li>swidth, sheight<br>
Specify the original image dimensions. These
values can differ from the width and height fields if the image
has been scaled;
<li>scolors<br>
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.
</ul>
<p>
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).
</blockquote>
<h3><font face="helvetica,arial">Options</font></h3>
<blockquote>
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.
<p>
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.
<p>
<dl>
<dt><tt>#define XmIMAGE_DELAYED (1<<1)</tt>
<dd>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;
<p>
<dt><tt>#define XmIMAGE_DEFERRED_FREE (1<<2)</tt>
<dd>Indicates XmHTML may free this structure when a new document is
loaded.<br>
Set By default;
<p>
<dt><tt>#define XmIMAGE_IMMEDIATE_FREE (1<<3)</tt>
<dd>Indicates XmHTML may free this structure when XmHTML no longer needs
it;
<p>
<dt><tt>#define XmIMAGE_RGB_SINGLE (1<<4)</tt>
<dd>Indicates that the reds, greens and blues fields are allocated in a
single memory area instead of three seperate memory arrays.<br>
Set By Default;
<p>
<dt><tt>#define XmIMAGE_ALLOW_SCALE (1<<5)</tt>
<dd>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 <tt><IMG></tt> 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.<br>
<b>WARNING:</b> not setting this bit will prevent an image to be
scaled.<br>
Set By Default;
<p>
<dt><tt>#define XmIMAGE_FRAME_IGNORE (1<<6)</tt>
<dd>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.
<p>
<dt><tt>#define XmIMAGE_CLIPMASK (1<<7)</tt>
<dd>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 <b>without</b> providing a clipmask yourself <b>will</b>
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;
<p>
<dt><tt>#define XmIMAGE_SHARED_DATA (1<<8)</tt>
<dd>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.
<p>
<dt><tt>#define XmIMAGE_PROGRESSIVE (1<<9)</tt>
<dd>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.
<p>
<dt><tt>#define XmIMAGE_DELAYED_CREATION (1<<10)</tt>
<dd>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 <b>not be freed</b>
as long as the current document is alive: to properly compose the
actual image, both information on the current background <b>and</b>
the on-screen position is required.
</dl>
</blockquote>
<h3><font face="helvetica,arial">See Also</font></h3>
<blockquote>
XmHTML(3X), XmHTMLImageDefaultProc(3X), XmHTMLImageFreeImageInfo(3X),
XmImageCreate(3X), XmImageCreateFromInfo(3X), XmImageDestroy(3X),
XmImage(3X)
</blockquote>
<hr noshade size="2" width="25%">
<i><font size="-1">
XmHTML, October 7, 1997
</font></i>
</body>
</html>
|
