defines main structures and function for image manipulation.

 libAfterImage  provides powerful functionality to load,  store 
and  transform  images. It allows for smaller memory utilization by
utilizing run-length encoding of the image data. There could be
different levels of compression selected, allowing to choose best
speed/memory ratio.

Structures :
          ASImage 
          ASImageManager 
          ASImageBevel 
          ASImageDecoder 
          ASImageOutput 
          ASImageLayer 
          ASGradient 

Functions :
         asimage_init(), asimage_start(), create_asimage(),
         clone_asimage(), destroy_asimage()

  ImageManager Reference counting and managing :
         create_image_manager(), destroy_image_manager(),
         store_asimage(), fetch_asimage(), query_asimage(),
         dup_asimage(), release_asimage(),
         release_asimage_by_name(), forget_asimage(),
         safe_asimage_destroy()

  Gradients helper functions :
         flip_gradient(), destroy_asgradient()

  Layers helper functions :
         init_image_layers(), create_image_layers(),
         destroy_image_layers()

  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>

identifies what output format should be used for storing the transformation result. Also identifies what data is currently stored in alt member of  ASImage structure.

is the main structure to hold image data.

Images are stored internally split into ARGB channels, each split
into scanline. Actuall data is stored using ASStorage container. Inside
 ASImage  data structure we only  store  IDs pointing to data in ASStorage
ASStorage implements reference counting, data compression, 
automatic memory defragmentation and other nice things.

 asimage_init()
 asimage_start()
 create_asimage()
 destroy_asimage()

effectively limits size of the allowed images to be loaded from files. That is needed to be able to filter out corrupt files.

Limit on  bevel outline to be drawn around the image.

Number of search paths to be used while loading images from files.

#define MAX_IMPORT_IMAGE_SIZE   8000
#define MAX_BEVEL_OUTLINE       100
#define MAX_SEARCH_PATHS        8      /* prudently limiting ourselfs */

contains pallette allowing us to map double values in vector image data into actuall ARGB values.

specifies parameters of the image superimposition.

 libAfterImage  allows for simultaneous superimposition (overlaying) of
arbitrary number of images. To facilitate this  ASImageLayer  structure
has been created in order to specify parameters of each image
participating in overlaying operation. Images need not to be exact
same size. For each image its position on destination is specified
via dst_x and dst_y data members. Each image maybe tiled and clipped
to fit into rectangle specified by clip_x, clip_y, clip_width,
clip_height ( in image coordinates - not destination ). If image is
missing, then area specified by dst_x, dst_y, clip_width, clip_height
will be filled with solid_color.
Entire image will be tinted using  tint  parameter prior to overlaying.
Bevel specified by  bevel  member will be drawn over image prior to
overlaying. Specific  overlay  method has to be specified.
merge_scanlines method is pointer to a function,
that accepts 2 ASScanlines as arguments and performs overlaying of
first one with the second one.
There are 15 different merge_scanline methods implemented in
 libAfterImage , including alpha-blending, tinting, averaging,
HSV and HSL  colorspace  operations, etc.

 ASImageLayer  s could be organized into chains using next pointers.
Since there could be a need to rearrange layers and maybe bypass some
layers - we need to provide for flexibility, while at the same time
allowing for simplicity of arrays. As the result next pointers could
be used to link together continuous arrays of layer, like so :
array1: [layer1(next==NULL)][layer2(next!=NULL)]
         ____________________________|
         V
array2: [layer3(next==NULL)][layer4(next==NULL)][layer5(next!=NULL)]
         ________________________________________________|
         V
array3: [layer6(next==NULL)][layer7(next==layer7)]
                               ^______|

While iterating throught such a  list  we check for two conditions -
exceeding count of layers and layer pointing to self. When any of
that is met - we stopping iteration.

merge_layers()
 blender .h

Combination of this flags defines the way  gradient  is rendered.

when  set it will cause  gradient 's direction to be rotated by 45 degrees

will cause  gradient direction to be rotated by 90 degrees. When combined with GRADIENT_TYPE_DIAG - rotates  gradient direction by 135 degrees.

This are named combinations of above flags to define type of  gradient .

normal left-to-right  gradient .

diagonal top-left to bottom-right.

vertical top to bottom  gradient .

diagonal bottom-left to top-right.

describes how  gradient is to be drawn.

 libAfterImage  includes functionality to  draw  multipoint gradients in
4 different directions left->right, top->bottom and diagonal
lefttop->rightbottom and bottomleft->topright. Each  gradient  described
by type, number of colors (or anchor points), ARGB values for each
 color  and offsets of each point from the beginning of  gradient  in
fractions of entire length. There should be at least 2 anchor points.
very first point should have offset of 0. and last point should have
offset of 1. Gradients are drawn in ARGB  colorspace , so it is possible
to have semitransparent gradients.

make_gradient()

This are flags that define rotation angle.

defines rotation of 90 degrees counterclockwise.

defines rotation of 180 degrees counterclockwise. combined they define rotation of 270 degrees counterclockwise.

We use 32 bit ARGB values to define how tinting should be done.
The formula for tinting particular channel data goes like that:
tinted_data = (image_data * tint)/128
So  if   tint  channel  value  is greater then 127 - same channel will be
brighter in destination image;  if  it is lower then 127 - same channel
will be darker in destination image. Tint channel  value  of 127
( or 0x7F hex ) does not change anything.
Alpha channel is tinted as well, allowing for creation of
semitransparent images. Calculations are performed in 24.8 format -
with 8 bit precision. Result is saturated to avoid overflow, and
precision is carried over to next pixel ( error diffusion ), when con
verting 24.8 to 8 bit format.

special  value that disables tinting

also disables tinting.

Defines the level of compression to attempt on  ASImage  scanlines.

defined as 0 - disables compression.

defined as 100 - highest compression level. Anything in between 0 and 100 will cause only part of the scanline to be compressed. This is obsolete. Now all images are compressed  if possible.

frees datamembers of the supplied  ASImage structure, and initializes it to all 0.

void asimage_init (ASImage * im, Bool free_resources);

im

- pointer to valid  ASImage structure

free_resources

-  if True will  make function attempt to  free all non-NULL pointers.

destroys XImage and mask XImage kept from previous conversions to/from X Pixmap.

void flush_asimage_cache (ASImage * im );

im

- pointer to valid  ASImage structure

Allocates memory needed to  store scanline of the image of supplied size. Assigns all the data members valid values. Makes sure that  ASImage structure is ready to  store image data.

void asimage_start (ASImage * im, unsigned int width,
                                  unsigned int height,
                                  unsigned int compression);

im

- pointer to valid  ASImage structure

width

- width of the image

height

- height of the image

compression

- level of compression to perform on image data. compression has to be in range of 0-100 with 100 signifying highest level of compression.

In order to resize  ASImage  structure after asimage_start() has been
called, asimage_init() must be invoked to  free  all the memory, and
then asimage_start() has to be called with new dimensions.

Performs memory allocation for the new  ASImage structure, as well as initialization of allocated structure based on supplied parameters.

 ASImage  *create_asimage( unsigned int width,
                         unsigned int height,
                         unsigned int compression);

width

- desired image width

height

- desired image height

compression

- compression level in new ASImage( see asimage_start() for more ).

Pointer to newly allocated and initialized  ASImage  structure on
Success. NULL in case of any kind of error - that should never happen.

 ASImage  *clone_asimage(ASImage *src, ASFlagType filter );

src

- original  ASImage .

filter

- bitmask of channels to be copied from one image to another.

New  ASImage , as a  copy  of original image.

Creates exact  clone  of the original  ASImage , with same compression,
back_color and rest of the attributes. Only  ASImage  data will be
carried over. Any attached alternative forms of images (XImages, etc.)
will not be copied. Any channel with unset bit in filter will not be
copied. Image name,  ASImageManager  and ref_count will not be copied -
use store_asimage() afterwards and  make  sure you use different name,
to avoid clashes with original image.

frees all the memory allocated for specified  ASImage .

void destroy_asimage(  ASImage  **im );

im

- pointer to valid  ASImage structure.

If there was XImage attached to it - it will be deallocated as well.

asview.c:  ASView .5

will replace  ASImage 's data using data from another  ASImage

Bool asimage_replace (ASImage *im,  ASImage  *from);

im

- pointer to valid  ASImage structure.

from

- pointer to  ASImage from which to take the data.

this function updates image without reallocating structure itself, which 
means that all pointers to it will still be valid. If that function 
succeeds - [from]  ASImage  will become unusable and should be deallocated 
using free() call.

This function replaces contents of the vector member of  ASImage structure with new double precision data.

set_asimage_vector(  ASImage  *im, register double *vector );

im

- pointer to valid  ASImage structure.

vector

- scientific data to attach to the image.

Data must have size of width*height ahere width and height are size of 
the  ASImage .

This function replaces contents of the vector member of  ASImage structure with new double precision data, generated from native  ARGB32 image contents. Color palette is generated by indexing  color values using max_colors, dither and opaque_threshold parameters.

 ASVectorPalette * vectorize_asimage(  ASImage  *im, 
                                    unsigned int max_colors, 
                                    unsigned int dither,  
                                    int opaque_threshold );

im

- pointer to valid  ASImage structure.

max_colors

- maximum size of the  colormap .

dither

- number of bits to strip off the  color data ( 0...7 )

opaque_threshold

- alpha channel threshold at which pixel should be treated as opaque

pointer to the  ASVectorPalette  structure that could be used for 
reverse conversion from double values to  ARGB32 . 

alt.vector member of the supplied  ASImage  will be replaced and will 
contain WIDTHxHEIGHT double values representing generated scientific 
data.

 create  ASImage management and reference counting object.

 ASImageManager  *create_image_manager(  ASImageManager  *reusable_memory,
                                      double gamma, ... );

reusable_memory

- optional pointer to a block of memory to be used to  store  ASImageManager object.

double

gamma -  value of gamma correction to be used while loading images from files.

...

- NULL terminated  list of up to 8 PATH strings to  list locations at which images could be found.

Creates  ASImageManager  object in memory and initializes it with
requested gamma  value  and PATH  list . This Object will contain a hash
table referencing all the loaded images. When such object is used while
loading images from the file - gamma and PATH values will be used, so
that all the loaded and referenced images will have same parameters.
File name will be used as the image name, and  if  same file is attempted
to be loaded again - instead reference will be incremented, and
previously loaded image will be retyrned. All the images stored in
 ASImageManager 's table will contain a back pointer to it, and they must
be deallocated only by calling release_asimage(). destroy_asimage() will
refuse to deallocate such an image.

 destroy management obejct.

void destroy_image_manager( struct  ASImageManager  *imman, 
                               Bool reusable );

imman

- pointer to  ASImageManager object to be deallocated

reusable

-  if True, then memory that holds object itself will not be deallocated. Usefull when object is created on stack.

Destroys all the referenced images, PATH values and  if  reusable is False,
also deallocates object's memory.

 add  ASImage to the reference.

Bool store_asimage(  ASImageManager * imageman,  ASImage  *im, 
                       const char *name );

imageman

- pointer to valid  ASImageManager object.

im

- pointer to the image to be stored.

name

- unique name of the image.

Adds specifyed image to the  ASImageManager 's  list  of referenced images.
Stored  ASImage  could be deallocated only by release_asimage(), or when
 ASImageManager  object itself is destroyed.

 relocate  ASImage into a different image manager.

void     relocate_asimage(  ASImageManager * to_imageman,  ASImage  *im );

to_imageman

- pointer to valid  ASImageManager object.

im

- pointer to the image to be stored.

Moves image from one  ASImageManager 's  list  of referenced images into 
another  ASImageManager . Reference count will be kept the same.

 ASImage  *fetch_asimage(  ASImageManager * imageman, const char *name );
 ASImage  *query_asimage(  ASImageManager * imageman, const char *name );

imageman

- pointer to valid  ASImageManager object.

name

- unique name of the image.

Looks for image with the name in  ASImageManager 's  list  and  if  found,
returns pointer to it. Note that query_asimage() does not increment 
reference count, while fetch_asimage() does. Therefore  if  fetch_asimage()
is used - release_asimage() should be called , when image is no longer 
in use.

increment reference count of stored  ASImage .

 ASImage  *dup_asimage(  ASImage * im );

im

- pointer to already referenced image.

decrement reference count for given  ASImage .

decrement reference count for  ASImage identifyed by its name.

int release_asimage(  ASImage  *im );
int release_asimage_by_name(  ASImageManager  *imman, char *name );

im

- pointer to already referenced image.

imageman

- pointer to valid  ASImageManager object.

name

- unique name of the image.

Decrements reference count on the  ASImage  object and destroys it  if 
reference count is below zero.

remove  ASImage from  ASImageManager 's hash by pointer.

remove  ASImage from  ASImageManager 's hash by its name.

void     forget_asimage(  ASImage  *im );
void  forget_asimage_name(  ASImageManager  *imman, const char *name );

im

pointer to already referenced image.

imageman

pointer to valid  ASImageManager object.

name

unique name of the image.

either  release or  destroy  asimage , checking  if it is attached to  ASImageManager .

int      safe_asimage_destroy(  ASImage  *im );

im

pointer to and  ASImage structure.

prints  list of images referenced in given  ASImageManager structure.

-  destroy  ASGradient structure, deallocating all associated memory

- initialize  set of  ASImageLayer structures.

void init_image_layers( register  ASImageLayer  *l, int count );

l

- pointer to valid  ASImageLayer structure.

count

- number of elements to initialize.

Initializes array on  ASImageLayer  structures to sensible defaults.
Basically - all zeros and merge_scanlines == alphablend_scanlines.

- allocate and initialize  set of  ASImageLayer 's.

 ASImageLayer  *create_image_layers( int count );

count

- number of  ASImageLayer structures in allocated array.

Pointer to newly allocated and initialized array of  ASImageLayer 
structures on Success. NULL in case of any kind of error - that
should never happen.

Performs memory allocation for the new array of  ASImageLayer 
structures, as well as initialization of allocated structure to
sensible defaults - merge_func will be  set  to alphablend_scanlines.

-  destroy  set of  ASImageLayer structures.

void destroy_image_layers( register  ASImageLayer  *l,
                           int count,
                           Bool reusable );

l

- pointer to pointer to valid array of  ASImageLayer structures.

count

- number of structures in array.

reusable

-  if True - then array itself will not be deallocates - which is usable when it was allocated on stack.

frees all the memory allocated for specified array of  ASImageLayer  s.
If there was  ASImage  and/or  ASImageBevel  attached to it - it will be
deallocated as well.

size_t asimage_add_line (  ASImage  * im, ColorPart  color ,
                          CARD32 * data, unsigned int y);

im

- pointer to valid  ASImage structure

color

-  color channel's number

data

- raw channel data of 32 bits per pixel - only lowest 8 bits gets encoded.

y

- image row starting with 0

asimage_add_line() return size of the encoded channel scanline in
bytes. On failure it will return 0.

Encodes raw data of the single channel into  ASImage  channel scanline.
based on compression level selected for this  ASImage  all or part of
the scanline will be RLE encoded.

size_t asimage_add_line_mono (  ASImage  * im, ColorPart  color ,
                               CARD8  value , unsigned int y);

im

- pointer to valid  ASImage structure

color

-  color channel's number

value

-  value for the channel

y

- image row starting with 0

asimage_add_line_mono() return size of the encoded channel scanline
in bytes. On failure it will return 0.

encodes  ASImage  channel scanline to have same  color  components
 value  in every pixel. Useful for vertical gradients for example.

ASFlagType get_asimage_chanmask(  ASImage  *im);

im

- valid  ASImage object.

goes throu all the scanlines of the  ASImage  and toggles bits 
representing those components that have at least some data.

void move_asimage_channel(  ASImage  *dst, int channel_dst,
                            ASImage  *src, int channel_src );

dst

-  ASImage which will have its channel substituted;

channel_dst

- what channel to  move data to;

src

-  ASImage which will donate its channel to dst;

channel_src

- what source image channel to  move data from.

MOves channel data from one  ASImage  to another, while discarding
what was already in destination's channel.

Source image (donor) will loose its channel data, as it will be
moved to destination  ASImage . Also there is a condition that both
images must be of the same width - otherwise function returns
without doing anything. If height is different - the minimum of
two will be used.

void copy_asimage_channel(  ASImage  *dst, int channel_dst,
                            ASImage  *src, int channel_src );

dst

-  ASImage which will have its channel substituted;

channel_dst

- what channel to  copy data to;

src

-  ASImage which will donate its channel to dst;

channel_src

- what source image channel to  copy data from.

Same as move_asimage_channel() but makes  copy  of channel's data
instead of simply moving it from one image to another.

void copy_asimage_lines(  ASImage  *dst, unsigned int offset_dst,
                          ASImage  *src, unsigned int offset_src,
                         unsigned int nlines, ASFlagType filter );

dst

-  ASImage which will have its channel substituted;

offset_dst

- scanline in destination image to  copy to;

src

-  ASImage which will donate its channel to dst;

offset_src

- scanline in source image to  copy data from;

nlines

- number of scanlines to be copied;

filter

- specifies what channels should be copied.

Makes  copy  of scanline data for continuos  set  of scanlines, affecting
only those channels marked in filter.
NOTE
Images must be of the same width.

This are flags that define what should be printed by
asimage_print_line():
    VRB_LINE_SUMMARY    -  print  only summary for each scanline
    VRB_LINE_CONTENT    -  print  summary and data for each scanline
    VRB_CTRL_EXPLAIN    -  print  summary, data and control codes for each
                          scanline

    unsigned int asimage_print_line (  ASImage  * im, ColorPart  color ,
                                      unsigned int y,
                                      unsigned long verbosity);

im

- pointer to valid  ASImage structure

color

-  color channel's number

y

- image row starting with 0

verbosity

- verbosity level - any combination of flags is allowed

amount of memory used by this particular channel of specified
scanline.

asimage_print_line() prints data stored in specified image scanline
channel. That may include simple summary of how much memory is used,
actual visible data, and/or RLE control codes. That helps to see
how effectively data is encoded.

Useful mostly for debugging purposes.

- translate image into a  list of rectangles.

XRectangle* 
    get_asimage_channel_rects(  ASImage  *src, int channel, 
                               unsigned int threshold, 
                               unsigned int *rects_count_ret ); 

src

-  ASImage which will donate its channel to dst;

channel

- what source image channel to  copy data from;

threshold

- threshold to compare channel values against;

rects_count_ret

- returns count of generated rectangles.

This function will translate contents of selected channel 
(usualy alpha) into a  list  of rectangles, ecompasing regions 
with values above the threshold. This is usefull to generate shape
of the window to be used with X Shape extention.