1imencdec(1) AfterStep X11 window manager imencdec(1)
2
6 imencdec - encoding/decoding ASImage data from/to usable data struc‐
7 tures libAfterImage/imencdec.h
8
10 defines main structures and function for image storing, extraction and
11 conversion to/from usable formats.
12
15 this header defines structures and functions to be used by outside
16 applications for reading and writing into ASImages. ASImage pixel
17 data maybe stored in sevral different formats, and should not be
18 accessed directly, but only through encoder/decoder facility.
19
21 Structures :
22 ASImageBevel
23 ASImageDecoder
24 ASImageOutput
25 Functions :
27 Encoding :
28 asimage_add_line(), asimage_add_line_mono(),
29 asimage_print_line(), get_asimage_chanmask(),
30 move_asimage_channel(), copy_asimage_channel(),
31 copy_asimage_lines()
32 Decoding
34 start_image_decoding(), stop_image_decoding(),
35 asimage_decode_line (), set_decoder_shift(),
36 set_decoder_back_color()
37 Output :
39 start_image_output(), set_image_output_back_color(),
40 toggle_image_output_direction(), stop_image_output()
41 Other libAfterImage modules :
43 ascmap.h asfont.h asimage.h asvisual.h blender.h export.h
44 import.h transform.h ximage.h
45
47 Sasha Vasko <sasha at aftercode dot net>
48
50 describes bevel to be drawn around the image.
51
54 Bevel is used to create 3D effect while drawing buttons, or any other
55 image that needs to be framed. Bevel is drawn using 2 primary colors:
56 one for top and left sides - hi color, and another for bottom and
57 right sides - low color. There are additionally 3 auxiliary colors:
58 hihi is used for the edge of top-left corner, hilo is used for the
59 edge of top-right and bottom-left corners, and lolo is used for the
60 edge of bottom-right corner. Colors are specified as ARGB and contain
61 alpha component, thus allowing for semitransparent bevels.
62 Bevel consists of outline and inline. Outline is drawn outside of the
64 image boundaries and its size adds to image size as the result. Alpha
65 component of the outline is constant. Inline is drawn on top of the
66 image and its alpha component is fading towards the center of the
67 image, thus creating illusion of smooth disappearing edge.
68
70 Source :
71 typedef struct ASImageBevel
72 {
73 #define BEVEL_SOLID_INLINE (0x01<<0)
74 ASFlagType type ; /* reserved for future use */
75 /* primary bevel colors */
77 ARGB32 hi_color ; /* top and left side color */
78 ARGB32 lo_color ; /* bottom and right side color */
79 /* these will be placed in the corners */
81 ARGB32 hihi_color ; /* color of the top-left corner */
82 ARGB32 hilo_color ; /* color of the top-right and
83 * bottom-left corners */
84 ARGB32 lolo_color ; /* color of the bottom-right corner */
85 /* outlines define size of the line drawn around the image */
87 unsigned short left_outline ;
88 unsigned short top_outline ;
89 unsigned short right_outline ;
90 unsigned short bottom_outline ;
91 /* inlines define size of the semitransparent line drawn
92 * inside the image */
93 unsigned short left_inline ;
94 unsigned short top_inline ;
95 unsigned short right_inline ;
96 unsigned short bottom_inline ;
97 }ASImageBevel;
98
100 describes the status of reading any particular ASImage, as well as pro‐
101 viding detail on how it should be done.
102
105 ASImageDecoder works as an abstraction layer and as the way to
106 automate several operations. Most of the transformations in
107 libAfterImage are performed as operations on ASScanline data
108 structure, that holds all or some of the channels of single image
109 scanline. In order to automate data extraction from ASImage into
110 ASScanline ASImageDecoder has been designed.
111 It has following features :
113 1) All missing scanlines, or channels of scanlines will be filled with
114 supplied back_color
115 2) It is possible to leave out some channels of the image, extracting
116 only subset of channels. It is done by setting only needed flags in
117 filter member.
118 3) It is possible to extract sub-image of the image by setting offset_x
119 and offset_y to top-left corner of sub-image, out_width - to width of
120 the sub-image and calling decode_image_scanline method as many times
121 as height of the sub-image.
122 4) It is possible to apply bevel to extracted sub-image, by setting
123 bevel member to specific ASImageBevel structure.
124 Extracted Scanlines will be stored in buffer and it will be updated
126 after each call to decode_image_scanline().
127
129 Source :
130 /* low level driver (what data to use - native, XImage or ARGB): */
131 typedef void (*decode_asscanline_func)( struct ASImageDecoder *imdec,
132 unsigned int skip, int y );
133 /* high level driver (bevel or not bevel): */
134 typedef void (*decode_image_scanline_func)
135 (struct ASImageDecoder *imdec);
136 typedef struct ASImageDecoder
138 {
139 ASVisual *asv;
140 ASImage *im ;
141 ASFlagType filter; /* flags that mask set of
142 * channels to be extracted
143 * from the image */
144 ARGB32 back_color; /* we fill missing scanlines
146 * with this default - black*/
147 unsigned int offset_x, /* left margin on source image
148 * before which we skip everything */
149 out_width; /* actual length of the output
150 * scanline */
151 unsigned int offset_y, /* top margin */
152 out_height;
153 ASImageBevel *bevel; /* bevel to wrap everything
154 * around with */
155 /* offsets of the drawn bevel baseline on resulting image : */
157 int bevel_left, bevel_top,
158 bevel_right, bevel_bottom ;
159 /* scanline buffer containing current scanline */
161 ASScanline buffer; /* matches the out_width */
162 /* internal data : */
164 unsigned short bevel_h_addon, bevel_v_addon ;
165 int next_line ;
166 ASScanline *xim_buffer; /* matches the size of the
168 * original XImage */
169 decode_asscanline_func decode_asscanline ;
171 decode_image_scanline_func decode_image_scanline ;
172 }ASImageDecoder;
173
175 Defines level of output quality/speed ratio
176
178 there will be no dithering and interpolation used while transforming
179 ASIMAGE_QUALITY_FAST there will be no dithering and used while trans‐
180 forming but interpolation will be used. ASIMAGE_QUALITY_GOOD simpli‐
181 fied dithering is performed in addition to interpolation. ASIM‐
182 AGE_QUALITY_TOP full dithering and interpolation. ASIMAGE_QUAL‐
183 ITY_DEFAULT requests current default setting - typically same as ASIM‐
184 AGE_QUALITY_GOOD. MAX_GRADIENT_DITHER_LINES defines number of lines to
185 use for dithering, while rendering gradients, in order to create smooth
186 effect. Higher number will slow things down, but will create better
187 gradients.
188
191 Source :
192 #define ASIMAGE_QUALITY_POOR 0
193 #define ASIMAGE_QUALITY_FAST 1
194 #define ASIMAGE_QUALITY_GOOD 2
195 #define ASIMAGE_QUALITY_TOP 3
196 #define ASIMAGE_QUALITY_DEFAULT -1
197 #define MAX_GRADIENT_DITHER_LINES ASIMAGE_QUALITY_TOP+1
199
201 describes the output state of the transformation result. It is used to
202 transparently write results into ASImage or XImage with different lev‐
203 els of quality.
204
207 libAfterImage allows for transformation result to be stored in both
208 ASImage ( useful for long term storage and subsequent processing )
209 and XImage ( useful for transfer of the result onto the X Server).
210 At the same time there are 4 different quality levels of output
211 implemented. They differ in the way special technics, like error
212 diffusion and interpolation are applyed, and allow for fine grained
213 selection of quality/speed ratio. ASIMAGE_QUALITY_GOOD should be good
214 enough for most applications.
215 The following additional output features are implemented :
216 1) Filling of the missing channels with supplied values.
217 2) Error diffusion to improve quality while converting from internal
218 24.8 format to 8 bit format.
219 3) Tiling of the output. If tiling_step is greater then 0, then each
220 scanlines will be copied into lines found tiling_step one from
221 another, upto the edge of the image.
222 4) Reverse order of output. Output image will be mirrored along y
223 axis if bottom_to_top is set to True.
224
226 The output_image_scanline method should be called for each scanline
227 to be stored. Convenience functions listed below should be used to
228 safely alter state of the output instead of direct manipulation of
229 the data members. (makes you pity you don't write in C++ doesn't it ?)
230 Also There is a trick in the way how output_image_scanline handles
232 empty scanlines while writing ASImage. If back_color of empty scanline
233 matches back_color of ASImageOutput - then particular line is erased!
234 If back_colors are same - then particular line of ASImage gets filled
235 with the back_color of ASScanline. First approach is usefull when
236 resulting image will be used in subsequent call to merge_layers - in
237 such case knowing back_color of image is good enough and we don't need
238 to store lines with the same color. In case where ASImage will be
239 converted into Pixmap/XImage - second approach is preferable, since
240 that conversion does not take into consideration image's back color -
241 we may want to change it in the future.
242
244 start_image_output()
245 set_image_output_back_color()
246 toggle_image_output_direction()
247 stop_image_output()
248
250 Source :
251 typedef void (*encode_image_scanline_func)( struct ASImageOutput *imout,
252 ASScanline *to_store );
253 typedef void (*output_image_scanline_func)( struct ASImageOutput *,
254 ASScanline *, int );
255 typedef struct ASImageOutput
257 {
258 ASVisual *asv;
259 ASImage *im ;
260 ASAltImFormats out_format ;
261 CARD32 chan_fill[4];
262 int buffer_shift; /* -1 means - buffer is empty,
263 * 0 - no shift,
264 * 8 - use 8 bit precision */
265 int next_line ; /* next scanline to be written */
266 unsigned int tiling_step; /* each line written will be
267 * repeated with this step until
268 * we exceed image size */
269 unsigned int tiling_range; /* Limits region in which we need
270 * to tile. If set to 0 then image
271 * height is used */
272 int bottom_to_top; /* -1 if we should output in
273 * bottom to top order,
274 * +1 otherwise*/
275 int quality ; /* see above */
277 output_image_scanline_func
279 output_image_scanline ; /* high level interface - division,
280 * error diffusion as well
281 * as encoding */
282 encode_image_scanline_func
283 encode_image_scanline ; /* low level interface -
284 * encoding only */
285 /* internal data members : */
287 ASScanline buffer[2], *used, *available;
288 }ASImageOutput;
289
291 - allocates and initializes decoder structure.
292
295 ASImageDecoder *start_image_decoding( ASVisual *asv,ASImage *im,
296 ASFlagType filter,
297 int offset_x, int offset_y,
298 unsigned int out_width,
299 unsigned int out_height,
300 ASImageBevel *bevel );
301
303 asv - pointer to valid ASVisual structure ( needed mostly to see if
304 we are in BGR mode or not );
305 im - ASImage we are going to decode;
307 filter - bitmask where set bits mark channels that has to be decoded.
309 offset_x
311 - left margin inside im, from which we should start reading
312 pixel data, effectively clipping source image.
313 offset_y
315 - top margin inside im, from which we should start reading scan‐
316 lines, effectively clipping source image. Note that when edge of
317 the image is reached, subsequent requests for scanlines will
318 wrap around to the top of the image, and not offset_y.
319 out_width-
321 width of the scanline needed. If it is larger then source image
322 - then image data will be tiled in it. If it is smaller - then
323 image data will be clipped.
324 out_height
326 - height of the output drawable. -1 means that same as image
327 height. if out_height is greater then image height, then image
328 will be tiled.
329 bevel - NULL or pointer to valid ASImageBevel structure if decoded
331 data should be overlayed with bevel at the time of decoding.
332
335 start_image_decoding() returns pointer to newly allocated
336 ASImageDecoder structure on success, NULL on failure.
337
339 Normal process of reading image data from ASImage consists of
340 3 steps :
341 1) start decoding by calling start_image_decoding.
342 2) call decode_image_scanline() method of returned structure, for
343 each scanline upto desired height of the target image. Decoded data
344 will be returned in buffer member of the ASImageDecoder structure.
345 3) finish decoding and deallocated all the used memory by calling
346 stop_image_decoding()
347
349 - changes default placement of the bevel on decoded image.
350
353 void set_decoder_bevel_geom( ASImageDecoder *imdec, int x, int y,
354 unsigned int width, unsigned int height );
355
357 imdec - pointer to pointer to structure, previously created by
358 start_image_decoding.
359 x,y - left top position of the inner border of the Bevel outline as
361 related to the origin of subimage being decoded.
362 width,
364 height - widtha and height of the inner border of the bevel outline.
367
370 For example if you only need to render small part of the button, that
371 is being rendered from transparency image.
372 NOTE
373 This call modifies bevel_h_addon and bevel_v_addon of
374 ASImageDecoder structure.
375
377 - changes the shift value of decoder - 8 or 0.
378
381 void set_decoder_shift( ASImageDecoder *imdec, int shift );
382
384 imdec - pointer to pointer to structure, previously created by
385 start_image_decoding.
386 shift - new value to be used as the shift while decoding image. valid
388 values are 8 and 0.
389
392 This function should be used instead of directly modifyeing value of
393 shift memebr of ASImageDecoder structure.
394
396 - changes the back color to be used while decoding the image.
397
400 void set_decoder_back_color( ASImageDecoder *imdec, ARGB32 back_color );
401
403 imdec - pointer to pointer to structure, previously created by
404 start_image_decoding.
405 back_color
407 - ARGB32 color value to be used as the background color to fill
408 empty spaces in decoded ASImage.
409
412 This function should be used instead of directly modifyeing value of
413 back_color memebr of ASImageDecoder structure.
414
416 - finishes decoding, frees all allocated memory.
417
420 void stop_image_decoding( ASImageDecoder **pimdec );
421
423 pimdec - pointer to pointer to structure, previously created by
424 start_image_decoding.
425
428 pimdec - pointer to ASImageDecoder will be reset to NULL.
429
431 start_image_decoding()
432
434 - initializes output structure
435
438 ASImageOutput *start_image_output ( struct ASVisual *asv,
439 ASImage *im,
440 ASAltImFormats format,
441 int shift, int quality );
442
444 asv - pointer to valid ASVisual structure
445 im - destination ASImage
447 format - indicates that output should be written into alternative for‐
449 mat, such as supplied XImage, ARGB32 array etc.
450 shift - precision of scanline data. Supported values are 0 - no preci‐
452 sion, and 8 - 24.8 precision. Value of that argument defines by
453 how much scanline data is shifted rightwards.
454 quality
456 - what algorithms should be used while writing data out, i.e.
457 full error diffusion, fast error diffusion, no error diffusion.
458
461 start_image_output() creates and initializes new ASImageOutput
462 structure based on supplied parameters. Created structure can be
463 subsequently used to write scanlines into destination image.
464 It is effectively hiding differences of XImage and ASImage and other
465 available output formats.
466 outpt_image_scanline() method of the structure can be used to write
467 out single scanline. Each written scanlines moves internal pointer to
468 the next image line, and possibly writes several scanlines at once if
469 tiling_step member is not 0.
470
472 - changes background color of output
473
476 void set_image_output_back_color ( ASImageOutput *imout,
477 ARGB32 back_color );
478
480 imout - ASImageOutput structure, previously created with
481 start_image_output();
482 back_color
484 - new background color value in ARGB format. This color will be
485 used to fill empty parts of outgoing scanlines. libAfterIm‐
486 age/asimage/toggle_image_output_direction()
487
489 - reverses vertical direction of output
490
493 void toggle_image_output_direction( ASImageOutput *imout );
494
496 imout - ASImageOutput structure, previously created with
497 start_image_output();
498
501 reverses vertical direction output. If previously scanlines has
502 been written from top to bottom, for example, after this function is
503 called they will be written in opposite direction. Current line does
504 not change, unless it points to the very first or the very last
505 image line. In this last case it will be moved to the opposing end of
506 the image.
507
509 - finishes output, frees all the allocated memory.
510
513 void stop_image_output( ASImageOutput **pimout );
514
516 pimout - pointer to pointer to ASImageOutput structure, previously cre‐
517 ated with call to start_image_output().
518
521 pimout - pointer to ASImageOutput will be reset to NULL.
522
524 Completes image output process. Flushes all the internal buffers.
525 Deallocates all the allocated memory. Resets pointer to NULL to
526 avoid dereferencing invalid pointers.
5273rd Berkeley Distribution AfterStep v.2.2.6 imencdec(1)