defines main structures and function for image storing, extraction and conversion to/from usable formats.

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.

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

Sasha Vasko <sasha at aftercode dot net>

describes  bevel to be drawn around the image.

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.

describes the status of reading any particular  ASImage , as well as providing detail on how it should be done.

 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().

Defines level of output quality/speed ratio

there will be no dithering and interpolation used while transforming

there will be no dithering and used while transforming but interpolation will be used.

simplified dithering is performed in addition to interpolation.

full dithering and interpolation.

requests current default setting - typically same as ASIMAGE_QUALITY_GOOD.

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.

describes the output state of the transformation result. It is used to transparently write results into  ASImage or XImage with different levels of quality.

 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.

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 usefull 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.

start_image_output()
set_image_output_back_color()
toggle_image_output_direction()
stop_image_output()

- allocates and initializes decoder structure.

 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  );

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.

start_image_decoding() returns pointer to newly allocated
 ASImageDecoder  structure on success, NULL on failure.

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()

- changes default placement of the  bevel on decoded image.

void set_decoder_bevel_geom(  ASImageDecoder  *imdec, int x, int y,
                             unsigned int width, unsigned int height );

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.

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.

- changes the shift  value of decoder - 8 or 0.

void set_decoder_shift(  ASImageDecoder  *imdec, int shift );

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.

This function should be used instead of directly modifyeing  value  of
shift memebr of  ASImageDecoder  structure.

- changes the back  color to be used while decoding the image.

void set_decoder_back_color(  ASImageDecoder  *imdec,  ARGB32  back_color );

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 .

This function should be used instead of directly modifyeing  value  of
back_color memebr of  ASImageDecoder  structure.

- finishes decoding, frees all allocated memory.

void stop_image_decoding(  ASImageDecoder  **pimdec );

pimdec

- pointer to pointer to structure, previously created by start_image_decoding.

pimdec  - pointer to  ASImageDecoder  will be reset to NULL.

start_image_decoding()

- initializes output structure

 ASImageOutput  *start_image_output ( struct  ASVisual  *asv,
                                     ASImage  *im,
                                     ASAltImFormats  format,
                                    int shift, int quality );

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.

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.

- changes  background  color of output

void set_image_output_back_color (  ASImageOutput  *imout,
                                    ARGB32  back_color );

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.

- reverses vertical direction of output

void toggle_image_output_direction(  ASImageOutput  *imout );

imout

-  ASImageOutput structure, previously created with start_image_output();

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.

- finishes output, frees all the allocated memory.

void stop_image_output(  ASImageOutput  **pimout );

pimout

- pointer to pointer to  ASImageOutput structure, previously created with call to start_image_output().

pimout      - pointer to  ASImageOutput  will be reset to NULL.

Completes image output process. Flushes all the internal buffers.
Deallocates all the allocated memory. Resets pointer to NULL to
avoid dereferencing invalid pointers.