--- name: "imencdec" section: "3x" platform: "linux" package: "libafterimage-dev" version: "2.2.12-18" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/imencdec" --- # imencdec(3x) encoding/decoding ASImage data from/to usable data structures libAfterImage/imencdec.h ## NAME **imencdec** - encoding/decoding ASImage data from/to usable data structures libAfterImage/imencdec.h ## NAMEimencdec defines main structures and function for image storing, extraction and conversion to/from usable formats. ## DESCRIPTION this header defines structures and functions to be used by outside applications for reading and writing into ASImages. ASImage pixel data maybe stored in sevral different formats, and should not be accessed directly, but only through encoder/decoder facility. ## SEE ALSO Structures :\ ASImageBevel\ ASImageDecoder\ ASImageOutput Functions :\ Encoding :\ asimage\_add\_line(), asimage\_add\_line\_mono(),\ asimage\_print\_line(), get\_asimage\_chanmask(),\ move\_asimage\_channel(), copy\_asimage\_channel(),\ copy\_asimage\_lines() Decoding\ start\_image\_decoding(), stop\_image\_decoding(),\ asimage\_decode\_line (), set\_decoder\_shift(),\ set\_decoder\_back\_color() Output :\ start\_image\_output(), set\_image\_output\_back\_color(),\ toggle\_image\_output\_direction(), stop\_image\_output() Other libAfterImage modules :\ ascmap.h asfont.h asimage.h asvisual.h blender.h export.h\ import.h transform.h ximage.h ## AUTHOR Sasha Vasko \ libAfterImage/ASImageBevel ## NAMEASImageBevel describes bevel to be drawn around the image. ## DESCRIPTION Bevel is used to create 3D effect while drawing buttons, or any other image that needs to be framed. Bevel is drawn using 2 primary colors: one for top and left sides - hi color, and another for bottom and right sides - low color. There are additionally 3 auxiliary colors: hihi is used for the edge of top-left corner, hilo is used for the edge of top-right and bottom-left corners, and lolo is used for the edge of bottom-right corner. Colors are specified as ARGB and contain alpha component, thus allowing for semitransparent bevels. Bevel consists of outline and inline. Outline is drawn outside of the image boundaries and its size adds to image size as the result. Alpha component of the outline is constant. Inline is drawn on top of the image and its alpha component is fading towards the center of the image, thus creating illusion of smooth disappearing edge. ## SOURCE typedef struct ASImageBevel { #define BEVEL\_SOLID\_INLINE (0x01\<\<0)\ ASFlagType type ; /\* reserved for future use \*/ /\* primary bevel colors \*/\ ARGB32 hi\_color ; /\* top and left side color \*/\ ARGB32 lo\_color ; /\* bottom and right side color \*/ /\* these will be placed in the corners \*/\ ARGB32 hihi\_color ; /\* color of the top-left corner \*/\ ARGB32 hilo\_color ; /\* color of the top-right and \ \* bottom-left corners \*/\ ARGB32 lolo\_color ; /\* color of the bottom-right corner \*/ /\* outlines define size of the line drawn around the image \*/\ unsigned short left\_outline ; \ unsigned short top\_outline ;\ unsigned short right\_outline ; \ unsigned short bottom\_outline ;\ /\* inlines define size of the semitransparent line drawn \ \* inside the image \*/\ unsigned short left\_inline ;\ unsigned short top\_inline ;\ unsigned short right\_inline ;\ unsigned short bottom\_inline ; }ASImageBevel; libAfterImage/ASImageDecoder ## NAMEASImageDecoder describes the status of reading any particular ASImage, as well as providing detail on how it should be done. ## DESCRIPTION ASImageDecoder works as an abstraction layer and as the way to automate several operations. Most of the transformations in libAfterImage are performed as operations on ASScanline data structure, that holds all or some of the channels of single image scanline. In order to automate data extraction from ASImage into ASScanline ASImageDecoder has been designed. It has following features : 1) All missing scanlines, or channels of scanlines will be filled with supplied back\_color 2) It is possible to leave out some channels of the image, extracting only subset of channels. It is done by setting only needed flags in filter member. 3) It is possible to extract sub-image of the image by setting offset\_x and offset\_y to top-left corner of sub-image, out\_width - to width of the sub-image and calling decode\_image\_scanline method as many times as height of the sub-image. 4) It is possible to apply bevel to extracted sub-image, by setting bevel member to specific ASImageBevel structure. Extracted Scanlines will be stored in buffer and it will be updated after each call to decode\_image\_scanline(). ## SOURCE /\* low level driver (what data to use - native, XImage or ARGB): \*/ typedef void (\*decode\_asscanline\_func)( struct ASImageDecoder \*imdec, \ unsigned int skip, int y ); /\* high level driver (bevel or not bevel): \*/ typedef void (\*decode\_image\_scanline\_func)\ (struct ASImageDecoder \*imdec); typedef struct ASImageDecoder {\ struct ASVisual \*asv;\ struct ASImage \*im ;\ ASFlagType filter; /\* flags that mask set of \ \* channels to be extracted \ \* from the image \*/ ARGB32 back\_color; /\* we fill missing scanlines \ \* with this default - black\*/\ unsigned int offset\_x, /\* left margin on source image \ \* before which we skip everything \*/\ out\_width; /\* actual length of the output \ \* scanline \*/\ unsigned int offset\_y, /\* top margin \*/\ out\_height;\ ASImageBevel \*bevel; /\* bevel to wrap everything \ \* around with \*/ /\* offsets of the drawn bevel baseline on resulting image : \*/\ int bevel\_left, bevel\_top, \ bevel\_right, bevel\_bottom ; /\* scanline buffer containing current scanline \*/\ struct ASScanline buffer; /\* matches the out\_width \*/ /\* internal data : \*/\ unsigned short bevel\_h\_addon, bevel\_v\_addon ;\ int next\_line ; struct ASScanline \*xim\_buffer; /\* matches the size of the \ \* original XImage \*/ decode\_asscanline\_func decode\_asscanline ;\ decode\_image\_scanline\_func decode\_image\_scanline ; }ASImageDecoder; libAfterImage/asimage/quality ## FUNCTION Defines level of output quality/speed ratio ## NAMEASIMAGE\_QUALITY\_POOR there will be no dithering and interpolation used while transforming ASIMAGE\_QUALITY\_FAST there will be no dithering and used while transforming but interpolation will be used. ASIMAGE\_QUALITY\_GOOD simplified dithering is performed in addition to interpolation. ASIMAGE\_QUALITY\_TOP full dithering and interpolation. ASIMAGE\_QUALITY\_DEFAULT requests current default setting - typically same as ASIMAGE\_QUALITY\_GOOD. MAX\_GRADIENT\_DITHER\_LINES defines number of lines to use for dithering, while rendering gradients, in order to create smooth effect. Higher number will slow things down, but will create better gradients. ## SOURCE \#define ASIMAGE\_QUALITY\_POOR 0 #define ASIMAGE\_QUALITY\_FAST 1 #define ASIMAGE\_QUALITY\_GOOD 2 #define ASIMAGE\_QUALITY\_TOP 3 #define ASIMAGE\_QUALITY\_DEFAULT -1 \#define MAX\_GRADIENT\_DITHER\_LINES ASIMAGE\_QUALITY\_TOP+1 libAfterImage/asimage/ASImageOutput ## NAMEASImageOutput describes the output state of the transformation result. It is used to transparently write results into ASImage or XImage with different levels of quality. ## DESCRIPTION libAfterImage allows for transformation result to be stored in both ASImage ( useful for long term storage and subsequent processing ) and XImage ( useful for transfer of the result onto the X Server). At the same time there are 4 different quality levels of output implemented. They differ in the way special technics, like error diffusion and interpolation are applyed, and allow for fine grained selection of quality/speed ratio. ASIMAGE\_QUALITY\_GOOD should be good enough for most applications. The following additional output features are implemented : 1) Filling of the missing channels with supplied values. 2) Error diffusion to improve quality while converting from internal\ 24\.8 format to 8 bit format. 3) Tiling of the output. If tiling\_step is greater then 0, then each\ scanlines will be copied into lines found tiling\_step one from\ another, up to the edge of the image. 4) Reverse order of output. Output image will be mirrored along y\ axis if bottom\_to\_top is set to True. ## NOTES The output\_image\_scanline method should be called for each scanline to be stored. Convenience functions listed below should be used to safely alter state of the output instead of direct manipulation of the data members. (makes you pity you don't write in C++ doesn't it ?) Also There is a trick in the way how output\_image\_scanline handles empty scanlines while writing ASImage. If back\_color of empty scanline matches back\_color of ASImageOutput - then particular line is erased! If back\_colors are same - then particular line of ASImage gets filled with the back\_color of ASScanline. First approach is useful when resulting image will be used in subsequent call to merge\_layers - in such case knowing back\_color of image is good enough and we don't need to store lines with the same color. In case where ASImage will be converted into Pixmap/XImage - second approach is preferable, since that conversion does not take into consideration image's back color - we may want to change it in the future. ## SEE ALSO start\_image\_output() set\_image\_output\_back\_color() toggle\_image\_output\_direction() stop\_image\_output() ## SOURCE typedef void (\*encode\_image\_scanline\_func)( struct ASImageOutput \*imout,\ struct ASScanline \*to\_store ); typedef void (\*output\_image\_scanline\_func)( struct ASImageOutput \*,\ struct ASScanline \*, int ); typedef struct ASImageOutput {\ struct ASVisual \*asv;\ struct ASImage \*im ;\ ASAltImFormats out\_format ;\ CARD32 chan\_fill\[4\];\ int buffer\_shift; /\* -1 means - buffer is empty,\ \* 0 - no shift,\ \* 8 - use 8 bit precision \*/\ int next\_line ; /\* next scanline to be written \*/\ unsigned int tiling\_step; /\* each line written will be \ \* repeated with this step until \ \* we exceed image size \*/\ unsigned int tiling\_range; /\* Limits region in which we need \ \* to tile. If set to 0 then image \ \* height is used \*/\ int bottom\_to\_top; /\* -1 if we should output in\ \* bottom to top order, \ \* +1 otherwise\*/ int quality ; /\* see above \*/ output\_image\_scanline\_func\ output\_image\_scanline ; /\* high level interface - division,\ \* error diffusion as well \ \* as encoding \*/\ encode\_image\_scanline\_func\ encode\_image\_scanline ; /\* low level interface - \ \* encoding only \*/ /\* internal data members : \*/\ struct ASScanline buffer\[2\], \*used, \*available; }ASImageOutput; libAfterImage/asimage/start\_image\_decoding() ## NAMEstart\_image\_decoding() \- allocates and initializes decoder structure. ## SYNOPSIS ASImageDecoder \*start\_image\_decoding( ASVisual \*asv,ASImage \*im,\ ASFlagType filter,\ int offset\_x, int offset\_y,\ unsigned int out\_width,\ unsigned int out\_height,\ ASImageBevel \*bevel ); ## INPUTS - asv \- pointer to valid ASVisual structure ( needed mostly to see if we are in BGR mode or not ); - im \- ASImage we are going to decode; - filter \- bitmask where set bits mark channels that has to be decoded. - offset\_x \- left margin inside im, from which we should start reading pixel data, effectively clipping source image. - offset\_y \- top margin inside im, from which we should start reading scanlines, effectively clipping source image. Note that when edge of the image is reached, subsequent requests for scanlines will wrap around to the top of the image, and not offset\_y. - out\_width- width of the scanline needed. If it is larger then source image - then image data will be tiled in it. If it is smaller - then image data will be clipped. - out\_height \- height of the output drawable. -1 means that same as image height. if out\_height is greater then image height, then image will be tiled. - bevel \- NULL or pointer to valid ASImageBevel structure if decoded data should be overlayed with bevel at the time of decoding. ## RETURN VALUE start\_image\_decoding() returns pointer to newly allocated ASImageDecoder structure on success, NULL on failure. ## DESCRIPTION Normal process of reading image data from ASImage consists of 3 steps : 1) start decoding by calling start\_image\_decoding. 2) call decode\_image\_scanline() method of returned structure, for each scanline up to desired height of the target image. Decoded data will be returned in buffer member of the ASImageDecoder structure. 3) finish decoding and deallocated all the used memory by calling stop\_image\_decoding() libAfterImage/asimage/set\_decoder\_bevel\_geom() ## NAMEset\_decoder\_bevel\_geom() \- changes default placement of the bevel on decoded image. ## SYNOPSIS void set\_decoder\_bevel\_geom( ASImageDecoder \*imdec, int x, int y,\ unsigned int width, unsigned int height ); ## INPUTS - imdec \- pointer to pointer to structure, previously created by start\_image\_decoding. - x,y \- left top position of the inner border of the Bevel outline as related to the origin of subimage being decoded. - width, - height \- widtha and height of the inner border of the bevel outline. ## DESCRIPTION For example if you only need to render small part of the button, that is being rendered from transparency image. NOTE This call modifies bevel\_h\_addon and bevel\_v\_addon of ASImageDecoder structure. libAfterImage/asimage/set\_decoder\_shift() ## NAMEset\_decoder\_shift() \- changes the shift value of decoder - 8 or 0. ## SYNOPSIS void set\_decoder\_shift( ASImageDecoder \*imdec, int shift ); ## INPUTS - imdec \- pointer to pointer to structure, previously created by start\_image\_decoding. - shift \- new value to be used as the shift while decoding image. valid values are 8 and 0. ## DESCRIPTION This function should be used instead of directly modifyeing value of shift member of ASImageDecoder structure. libAfterImage/asimage/set\_decoder\_back\_color() ## NAMEset\_decoder\_back\_color() \- changes the back color to be used while decoding the image. ## SYNOPSIS void set\_decoder\_back\_color( ASImageDecoder \*imdec, ARGB32 back\_color ); ## INPUTS - imdec \- pointer to pointer to structure, previously created by start\_image\_decoding. - back\_color \- ARGB32 color value to be used as the background color to fill empty spaces in decoded ASImage. ## DESCRIPTION This function should be used instead of directly modifyeing value of back\_color member of ASImageDecoder structure. libAfterImage/asimage/stop\_image\_decoding() ## NAMEstop\_image\_decoding() \- finishes decoding, frees all allocated memory. ## SYNOPSIS void stop\_image\_decoding( ASImageDecoder \*\*pimdec ); ## INPUTS - pimdec \- pointer to pointer to structure, previously created by start\_image\_decoding. ## RETURN VALUE pimdec - pointer to ASImageDecoder will be reset to NULL. ## SEE ALSO start\_image\_decoding() libAfterImage/asimage/start\_image\_output() ## NAMEstart\_image\_output() \- initializes output structure ## SYNOPSIS ASImageOutput \*start\_image\_output ( struct ASVisual \*asv,\ ASImage \*im,\ ASAltImFormats format,\ int shift, int quality ); ## INPUTS - asv \- pointer to valid ASVisual structure - im \- destination ASImage - format \- indicates that output should be written into alternative format, such as supplied XImage, ARGB32 array etc. - shift \- precision of scanline data. Supported values are 0 - no precision, and 8 - 24.8 precision. Value of that argument defines by how much scanline data is shifted rightwards. - quality \- what algorithms should be used while writing data out, i.e. full error diffusion, fast error diffusion, no error diffusion. ## DESCRIPTION start\_image\_output() creates and initializes new ASImageOutput structure based on supplied parameters. Created structure can be subsequently used to write scanlines into destination image. It is effectively hiding differences of XImage and ASImage and other available output formats. outpt\_image\_scanline() method of the structure can be used to write out single scanline. Each written scanlines moves internal pointer to the next image line, and possibly writes several scanlines at once if tiling\_step member is not 0. libAfterImage/asimage/set\_image\_output\_back\_color() ## NAMEset\_image\_output\_back\_color() \- changes background color of output ## SYNOPSIS void set\_image\_output\_back\_color ( ASImageOutput \*imout,\ ARGB32 back\_color ); ## INPUTS - imout \- ASImageOutput structure, previously created with start\_image\_output(); - back\_color \- new background color value in ARGB format. This color will be used to fill empty parts of outgoing scanlines. libAfterImage/asimage/toggle\_image\_output\_direction() ## NAMEtoggle\_image\_output\_direction() \- reverses vertical direction of output ## SYNOPSIS void toggle\_image\_output\_direction( ASImageOutput \*imout ); ## INPUTS - imout \- ASImageOutput structure, previously created with start\_image\_output(); ## DESCRIPTION reverses vertical direction output. If previously scanlines has been written from top to bottom, for example, after this function is called they will be written in opposite direction. Current line does not change, unless it points to the very first or the very last image line. In this last case it will be moved to the opposing end of the image. libAfterImage/asimage/stop\_image\_output() ## NAMEstop\_image\_output() \- finishes output, frees all the allocated memory. ## SYNOPSIS void stop\_image\_output( ASImageOutput \*\*pimout ); ## INPUTS - pimout \- pointer to pointer to ASImageOutput structure, previously created with call to start\_image\_output(). ## RETURN VALUE pimout - pointer to ASImageOutput will be reset to NULL. ## DESCRIPTION Completes image output process. Flushes all the internal buffers. Deallocates all the allocated memory. Resets pointer to NULL to avoid dereferencing invalid pointers.