00001 #ifndef IMENCDEC_HEADER_FILE_INCLUDED 00002 #define IMENCDEC_HEADER_FILE_INCLUDED 00003 00004 #include "asvisual.h" 00005 #include "blender.h" 00006 #include "scanline.h" 00007 /*#define TRACK_ASIMAGES*/ 00008 #ifdef __cplusplus 00009 extern "C" { 00010 #endif 00011 00012 /****h* libAfterImage/imencdec.h 00013 * NAME 00014 * imencdec defines main structures and function for image storing, 00015 * extraction and conversion to/from usable formats. 00016 * DESCRIPTION 00017 * this header defines structures and functions to be used by outside 00018 * applications for reading and writing into ASImages. ASImage pixel 00019 * data maybe stored in sevral different formats, and should not be 00020 * accessed directly, but only through encoder/decoder facility. 00021 * 00022 * SEE ALSO 00023 * Structures : 00024 * ASImageBevel 00025 * ASImageDecoder 00026 * ASImageOutput 00027 * 00028 * Functions : 00029 * Encoding : 00030 * asimage_add_line(), asimage_add_line_mono(), 00031 * asimage_print_line(), get_asimage_chanmask(), 00032 * move_asimage_channel(), copy_asimage_channel(), 00033 * copy_asimage_lines() 00034 * 00035 * Decoding 00036 * start_image_decoding(), stop_image_decoding(), 00037 * asimage_decode_line (), set_decoder_shift(), 00038 * set_decoder_back_color() 00039 * 00040 * Output : 00041 * start_image_output(), set_image_output_back_color(), 00042 * toggle_image_output_direction(), stop_image_output() 00043 * 00044 * Other libAfterImage modules : 00045 * ascmap.h asfont.h asimage.h asvisual.h blender.h export.h 00046 * import.h transform.h ximage.h 00047 * AUTHOR 00048 * Sasha Vasko <sasha at aftercode dot net> 00049 ******/ 00050 00051 struct ASVisual; 00052 struct ASImage; 00053 00054 /****s* libAfterImage/ASImageBevel 00055 * NAME 00056 * ASImageBevel describes bevel to be drawn around the image. 00057 * DESCRIPTION 00058 * Bevel is used to create 3D effect while drawing buttons, or any other 00059 * image that needs to be framed. Bevel is drawn using 2 primary colors: 00060 * one for top and left sides - hi color, and another for bottom and 00061 * right sides - low color. There are additionally 3 auxiliary colors: 00062 * hihi is used for the edge of top-left corner, hilo is used for the 00063 * edge of top-right and bottom-left corners, and lolo is used for the 00064 * edge of bottom-right corner. Colors are specified as ARGB and contain 00065 * alpha component, thus allowing for semitransparent bevels. 00066 * 00067 * Bevel consists of outline and inline. Outline is drawn outside of the 00068 * image boundaries and its size adds to image size as the result. Alpha 00069 * component of the outline is constant. Inline is drawn on top of the 00070 * image and its alpha component is fading towards the center of the 00071 * image, thus creating illusion of smooth disappearing edge. 00072 * SOURCE 00073 */ 00074 00075 typedef struct ASImageBevel 00076 { 00077 #define BEVEL_SOLID_INLINE (0x01<<0) 00078 ASFlagType type ; /* reserved for future use */ 00079 00080 /* primary bevel colors */ 00081 ARGB32 hi_color ; /* top and left side color */ 00082 ARGB32 lo_color ; /* bottom and right side color */ 00083 00084 /* these will be placed in the corners */ 00085 ARGB32 hihi_color ; /* color of the top-left corner */ 00086 ARGB32 hilo_color ; /* color of the top-right and 00087 * bottom-left corners */ 00088 ARGB32 lolo_color ; /* color of the bottom-right corner */ 00089 00090 /* outlines define size of the line drawn around the image */ 00091 unsigned short left_outline ; 00092 unsigned short top_outline ; 00093 unsigned short right_outline ; 00094 unsigned short bottom_outline ; 00095 /* inlines define size of the semitransparent line drawn 00096 * inside the image */ 00097 unsigned short left_inline ; 00098 unsigned short top_inline ; 00099 unsigned short right_inline ; 00100 unsigned short bottom_inline ; 00101 }ASImageBevel; 00102 /*******/ 00103 00104 /****s* libAfterImage/ASImageDecoder 00105 * NAME 00106 * ASImageDecoder describes the status of reading any particular ASImage, 00107 * as well as providing detail on how it should be done. 00108 * DESCRIPTION 00109 * ASImageDecoder works as an abstraction layer and as the way to 00110 * automate several operations. Most of the transformations in 00111 * libAfterImage are performed as operations on ASScanline data 00112 * structure, that holds all or some of the channels of single image 00113 * scanline. In order to automate data extraction from ASImage into 00114 * ASScanline ASImageDecoder has been designed. 00115 * 00116 * It has following features : 00117 * 1) All missing scanlines, or channels of scanlines will be filled with 00118 * supplied back_color 00119 * 2) It is possible to leave out some channels of the image, extracting 00120 * only subset of channels. It is done by setting only needed flags in 00121 * filter member. 00122 * 3) It is possible to extract sub-image of the image by setting offset_x 00123 * and offset_y to top-left corner of sub-image, out_width - to width of 00124 * the sub-image and calling decode_image_scanline method as many times 00125 * as height of the sub-image. 00126 * 4) It is possible to apply bevel to extracted sub-image, by setting 00127 * bevel member to specific ASImageBevel structure. 00128 * 00129 * Extracted Scanlines will be stored in buffer and it will be updated 00130 * after each call to decode_image_scanline(). 00131 * SOURCE 00132 */ 00133 00134 /* low level driver (what data to use - native, XImage or ARGB): */ 00135 typedef void (*decode_asscanline_func)( struct ASImageDecoder *imdec, 00136 unsigned int skip, int y ); 00137 /* high level driver (bevel or not bevel): */ 00138 typedef void (*decode_image_scanline_func) 00139 (struct ASImageDecoder *imdec); 00140 00141 typedef struct ASImageDecoder 00142 { 00143 struct ASVisual *asv; 00144 struct ASImage *im ; 00145 ASFlagType filter; /* flags that mask set of 00146 * channels to be extracted 00147 * from the image */ 00148 00149 ARGB32 back_color; /* we fill missing scanlines 00150 * with this default - black*/ 00151 unsigned int offset_x, /* left margin on source image 00152 * before which we skip everything */ 00153 out_width; /* actual length of the output 00154 * scanline */ 00155 unsigned int offset_y, /* top margin */ 00156 out_height; 00157 ASImageBevel *bevel; /* bevel to wrap everything 00158 * around with */ 00159 00160 /* offsets of the drawn bevel baseline on resulting image : */ 00161 int bevel_left, bevel_top, 00162 bevel_right, bevel_bottom ; 00163 00164 /* scanline buffer containing current scanline */ 00165 struct ASScanline buffer; /* matches the out_width */ 00166 00167 /* internal data : */ 00168 unsigned short bevel_h_addon, bevel_v_addon ; 00169 int next_line ; 00170 00171 struct ASScanline *xim_buffer; /* matches the size of the 00172 * original XImage */ 00173 00174 decode_asscanline_func decode_asscanline ; 00175 decode_image_scanline_func decode_image_scanline ; 00176 }ASImageDecoder; 00177 /********/ 00178 00179 /****d* libAfterImage/asimage/quality 00180 * FUNCTION 00181 * Defines level of output quality/speed ratio 00182 * NAME 00183 * ASIMAGE_QUALITY_POOR there will be no dithering and interpolation used 00184 * while transforming 00185 * NAME 00186 * ASIMAGE_QUALITY_FAST there will be no dithering and used while 00187 * transforming but interpolation will be used. 00188 * NAME 00189 * ASIMAGE_QUALITY_GOOD simplified dithering is performed in addition to 00190 * interpolation. 00191 * NAME 00192 * ASIMAGE_QUALITY_TOP full dithering and interpolation. 00193 * NAME 00194 * ASIMAGE_QUALITY_DEFAULT requests current default setting - typically 00195 * same as ASIMAGE_QUALITY_GOOD. 00196 * NAME 00197 * MAX_GRADIENT_DITHER_LINES defines number of lines to use for dithering, 00198 * while rendering gradients, in order to create smooth effect. Higher 00199 * number will slow things down, but will create better gradients. 00200 * SOURCE 00201 */ 00202 #define ASIMAGE_QUALITY_POOR 0 00203 #define ASIMAGE_QUALITY_FAST 1 00204 #define ASIMAGE_QUALITY_GOOD 2 00205 #define ASIMAGE_QUALITY_TOP 3 00206 #define ASIMAGE_QUALITY_DEFAULT -1 00207 00208 #define MAX_GRADIENT_DITHER_LINES ASIMAGE_QUALITY_TOP+1 00209 /*******/ 00210 00211 00212 /****s* libAfterImage/asimage/ASImageOutput 00213 * NAME 00214 * ASImageOutput describes the output state of the transformation result. 00215 * It is used to transparently write results into ASImage or XImage with 00216 * different levels of quality. 00217 * DESCRIPTION 00218 * libAfterImage allows for transformation result to be stored in both 00219 * ASImage ( useful for long term storage and subsequent processing ) 00220 * and XImage ( useful for transfer of the result onto the X Server). 00221 * At the same time there are 4 different quality levels of output 00222 * implemented. They differ in the way special technics, like error 00223 * diffusion and interpolation are applyed, and allow for fine grained 00224 * selection of quality/speed ratio. ASIMAGE_QUALITY_GOOD should be good 00225 * enough for most applications. 00226 * The following additional output features are implemented : 00227 * 1) Filling of the missing channels with supplied values. 00228 * 2) Error diffusion to improve quality while converting from internal 00229 * 24.8 format to 8 bit format. 00230 * 3) Tiling of the output. If tiling_step is greater then 0, then each 00231 * scanlines will be copied into lines found tiling_step one from 00232 * another, upto the edge of the image. 00233 * 4) Reverse order of output. Output image will be mirrored along y 00234 * axis if bottom_to_top is set to True. 00235 * NOTES 00236 * The output_image_scanline method should be called for each scanline 00237 * to be stored. Convenience functions listed below should be used to 00238 * safely alter state of the output instead of direct manipulation of 00239 * the data members. (makes you pity you don't write in C++ doesn't it ?) 00240 * 00241 * Also There is a trick in the way how output_image_scanline handles 00242 * empty scanlines while writing ASImage. If back_color of empty scanline 00243 * matches back_color of ASImageOutput - then particular line is erased! 00244 * If back_colors are same - then particular line of ASImage gets filled 00245 * with the back_color of ASScanline. First approach is usefull when 00246 * resulting image will be used in subsequent call to merge_layers - in 00247 * such case knowing back_color of image is good enough and we don't need 00248 * to store lines with the same color. In case where ASImage will be 00249 * converted into Pixmap/XImage - second approach is preferable, since 00250 * that conversion does not take into consideration image's back color - 00251 * we may want to change it in the future. 00252 * 00253 * SEE ALSO 00254 * start_image_output() 00255 * set_image_output_back_color() 00256 * toggle_image_output_direction() 00257 * stop_image_output() 00258 * SOURCE 00259 */ 00260 typedef void (*encode_image_scanline_func)( struct ASImageOutput *imout, 00261 struct ASScanline *to_store ); 00262 typedef void (*output_image_scanline_func)( struct ASImageOutput *, 00263 struct ASScanline *, int ); 00264 00265 typedef struct ASImageOutput 00266 { 00267 struct ASVisual *asv; 00268 struct ASImage *im ; 00269 ASAltImFormats out_format ; 00270 CARD32 chan_fill[4]; 00271 int buffer_shift; /* -1 means - buffer is empty, 00272 * 0 - no shift, 00273 * 8 - use 8 bit precision */ 00274 int next_line ; /* next scanline to be written */ 00275 unsigned int tiling_step; /* each line written will be 00276 * repeated with this step until 00277 * we exceed image size */ 00278 unsigned int tiling_range; /* Limits region in which we need 00279 * to tile. If set to 0 then image 00280 * height is used */ 00281 int bottom_to_top; /* -1 if we should output in 00282 * bottom to top order, 00283 * +1 otherwise*/ 00284 00285 int quality ; /* see above */ 00286 00287 output_image_scanline_func 00288 output_image_scanline ; /* high level interface - division, 00289 * error diffusion as well 00290 * as encoding */ 00291 encode_image_scanline_func 00292 encode_image_scanline ; /* low level interface - 00293 * encoding only */ 00294 00295 /* internal data members : */ 00296 struct ASScanline buffer[2], *used, *available; 00297 }ASImageOutput; 00298 /********/ 00299 /****f* libAfterImage/asimage/start_image_decoding() 00300 * NAME 00301 * start_image_decoding() - allocates and initializes decoder structure. 00302 * SYNOPSIS 00303 * ASImageDecoder *start_image_decoding( ASVisual *asv,ASImage *im, 00304 * ASFlagType filter, 00305 * int offset_x, int offset_y, 00306 * unsigned int out_width, 00307 * unsigned int out_height, 00308 * ASImageBevel *bevel ); 00309 * INPUTS 00310 * asv - pointer to valid ASVisual structure ( needed mostly 00311 * to see if we are in BGR mode or not ); 00312 * im - ASImage we are going to decode; 00313 * filter - bitmask where set bits mark channels that has to be 00314 * decoded. 00315 * offset_x - left margin inside im, from which we should start 00316 * reading pixel data, effectively clipping source image. 00317 * offset_y - top margin inside im, from which we should start 00318 * reading scanlines, effectively clipping source image. 00319 * Note that when edge of the image is reached, 00320 * subsequent requests for scanlines will wrap around to 00321 * the top of the image, and not offset_y. 00322 * out_width- width of the scanline needed. If it is larger then 00323 * source image - then image data will be tiled in it. 00324 * If it is smaller - then image data will be clipped. 00325 * out_height - height of the output drawable. -1 means that same as 00326 * image height. if out_height is greater then image height, 00327 * then image will be tiled. 00328 * bevel - NULL or pointer to valid ASImageBevel structure if 00329 * decoded data should be overlayed with bevel at the 00330 * time of decoding. 00331 * RETURN VALUE 00332 * start_image_decoding() returns pointer to newly allocated 00333 * ASImageDecoder structure on success, NULL on failure. 00334 * DESCRIPTION 00335 * Normal process of reading image data from ASImage consists of 00336 * 3 steps : 00337 * 1) start decoding by calling start_image_decoding. 00338 * 2) call decode_image_scanline() method of returned structure, for 00339 * each scanline upto desired height of the target image. Decoded data 00340 * will be returned in buffer member of the ASImageDecoder structure. 00341 * 3) finish decoding and deallocated all the used memory by calling 00342 * stop_image_decoding() 00343 *********/ 00344 /****f* libAfterImage/asimage/set_decoder_bevel_geom() 00345 * NAME 00346 * set_decoder_bevel_geom() - changes default placement of the bevel on 00347 * decoded image. 00348 * SYNOPSIS 00349 * void set_decoder_bevel_geom( ASImageDecoder *imdec, int x, int y, 00350 * unsigned int width, unsigned int height ); 00351 * INPUTS 00352 * imdec - pointer to pointer to structure, previously created 00353 * by start_image_decoding. 00354 * x,y - left top position of the inner border of the Bevel outline 00355 * as related to the origin of subimage being decoded. 00356 * width, 00357 * height - widtha and height of the inner border of the bevel outline. 00358 * DESCRIPTION 00359 * For example if you only need to render small part of the button, that 00360 * is being rendered from transparency image. 00361 * NOTE 00362 * This call modifies bevel_h_addon and bevel_v_addon of 00363 * ASImageDecoder structure. 00364 *******/ 00365 /****f* libAfterImage/asimage/set_decoder_shift() 00366 * NAME 00367 * set_decoder_shift() - changes the shift value of decoder - 8 or 0. 00368 * SYNOPSIS 00369 * void set_decoder_shift( ASImageDecoder *imdec, int shift ); 00370 * INPUTS 00371 * imdec - pointer to pointer to structure, previously created 00372 * by start_image_decoding. 00373 * shift - new value to be used as the shift while decoding image. 00374 * valid values are 8 and 0. 00375 * DESCRIPTION 00376 * This function should be used instead of directly modifyeing value of 00377 * shift memebr of ASImageDecoder structure. 00378 *******/ 00379 /****f* libAfterImage/asimage/set_decoder_back_color() 00380 * NAME 00381 * set_decoder_back_color() - changes the back color to be used while 00382 * decoding the image. 00383 * SYNOPSIS 00384 * void set_decoder_back_color( ASImageDecoder *imdec, ARGB32 back_color ); 00385 * INPUTS 00386 * imdec - pointer to pointer to structure, previously created 00387 * by start_image_decoding. 00388 * back_color - ARGB32 color value to be used as the background color to 00389 * fill empty spaces in decoded ASImage. 00390 * DESCRIPTION 00391 * This function should be used instead of directly modifyeing value of 00392 * back_color memebr of ASImageDecoder structure. 00393 *******/ 00394 /****f* libAfterImage/asimage/stop_image_decoding() 00395 * NAME 00396 * stop_image_decoding() - finishes decoding, frees all allocated 00397 * memory. 00398 * SYNOPSIS 00399 * void stop_image_decoding( ASImageDecoder **pimdec ); 00400 * INPUTS 00401 * pimdec - pointer to pointer to structure, previously created 00402 * by start_image_decoding. 00403 * RETURN VALUE 00404 * pimdec - pointer to ASImageDecoder will be reset to NULL. 00405 * SEE ALSO 00406 * start_image_decoding() 00407 *******/ 00408 00409 ASImageDecoder *start_image_decoding( struct ASVisual *asv, struct ASImage *im, 00410 ASFlagType filter, 00411 int offset_x, int offset_y, 00412 unsigned int out_width, 00413 unsigned int out_height, 00414 ASImageBevel *bevel ); 00415 void set_decoder_bevel_geom( ASImageDecoder *imdec, int x, int y, 00416 unsigned int width, unsigned int height ); 00417 void set_decoder_shift( ASImageDecoder *imdec, int shift ); 00418 void set_decoder_back_color( ASImageDecoder *imdec, ARGB32 back_color ); 00419 void stop_image_decoding( ASImageDecoder **pimdec ); 00420 00421 /****f* libAfterImage/asimage/start_image_output() 00422 * NAME 00423 * start_image_output() - initializes output structure 00424 * SYNOPSIS 00425 * ASImageOutput *start_image_output ( struct ASVisual *asv, 00426 * ASImage *im, 00427 * ASAltImFormats format, 00428 * int shift, int quality ); 00429 * INPUTS 00430 * asv - pointer to valid ASVisual structure 00431 * im - destination ASImage 00432 * format - indicates that output should be written into alternative 00433 * format, such as supplied XImage, ARGB32 array etc. 00434 * shift - precision of scanline data. Supported values are 0 - no 00435 * precision, and 8 - 24.8 precision. Value of that argument 00436 * defines by how much scanline data is shifted rightwards. 00437 * quality - what algorithms should be used while writing data out, i.e. 00438 * full error diffusion, fast error diffusion, no error 00439 * diffusion. 00440 * DESCRIPTION 00441 * start_image_output() creates and initializes new ASImageOutput 00442 * structure based on supplied parameters. Created structure can be 00443 * subsequently used to write scanlines into destination image. 00444 * It is effectively hiding differences of XImage and ASImage and other 00445 * available output formats. 00446 * outpt_image_scanline() method of the structure can be used to write 00447 * out single scanline. Each written scanlines moves internal pointer to 00448 * the next image line, and possibly writes several scanlines at once if 00449 * tiling_step member is not 0. 00450 **********/ 00451 /****f* libAfterImage/asimage/set_image_output_back_color() 00452 * NAME 00453 * set_image_output_back_color() - changes background color of output 00454 * SYNOPSIS 00455 * void set_image_output_back_color ( ASImageOutput *imout, 00456 * ARGB32 back_color ); 00457 * INPUTS 00458 * imout - ASImageOutput structure, previously created with 00459 * start_image_output(); 00460 * back_color - new background color value in ARGB format. This color 00461 * will be used to fill empty parts of outgoing scanlines. 00462 *********/ 00463 /****f* libAfterImage/asimage/toggle_image_output_direction() 00464 * NAME 00465 * toggle_image_output_direction() - reverses vertical direction of output 00466 * SYNOPSIS 00467 * void toggle_image_output_direction( ASImageOutput *imout ); 00468 * INPUTS 00469 * imout - ASImageOutput structure, previously created with 00470 * start_image_output(); 00471 * DESCRIPTION 00472 * reverses vertical direction output. If previously scanlines has 00473 * been written from top to bottom, for example, after this function is 00474 * called they will be written in opposite direction. Current line does 00475 * not change, unless it points to the very first or the very last 00476 * image line. In this last case it will be moved to the opposing end of 00477 * the image. 00478 *********/ 00479 /****f* libAfterImage/asimage/stop_image_output() 00480 * NAME 00481 * stop_image_output() - finishes output, frees all the allocated memory. 00482 * SYNOPSIS 00483 * void stop_image_output( ASImageOutput **pimout ); 00484 * INPUTS 00485 * pimout - pointer to pointer to ASImageOutput structure, 00486 * previously created with call to start_image_output(). 00487 * RETURN VALUE 00488 * pimout - pointer to ASImageOutput will be reset to NULL. 00489 * DESCRIPTION 00490 * Completes image output process. Flushes all the internal buffers. 00491 * Deallocates all the allocated memory. Resets pointer to NULL to 00492 * avoid dereferencing invalid pointers. 00493 *********/ 00494 ASImageOutput *start_image_output( struct ASVisual *asv, ASImage *im, ASAltImFormats format, int shift, int quality ); 00495 void set_image_output_back_color( ASImageOutput *imout, ARGB32 back_color ); 00496 void toggle_image_output_direction( ASImageOutput *imout ); 00497 void stop_image_output( ASImageOutput **pimout ); 00498 00499 #ifdef __cplusplus 00500 } 00501 #endif 00502 00503 #endif
1.5.1