Provided by: libafterimage-dev_2.2.12-2_amd64 
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 <sasha at aftercode dot net>
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, upto 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 upto 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 memebr 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 memebr 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.