Preface Introduction Main index API Topic index API Glossary

ASImage

internal structures and methods used for image manipulation in libAfterImage

libAfterImage/asimage.h

NAME
asimage
defines main structures and function for image manipulation.

DESCRIPTION

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.

SEE ALSO

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

AUTHOR

Sasha Vasko <sasha at aftercode dot net>

libAfterImage/ASAltImFormats

NAME
ASAltImFormats
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.

SOURCE

typedef enum {
    ASA_ASImage = 0,
    ASA_XImage,
    ASA_MaskXImage,
    /* temporary XImages to be allocated from static pool of memory :*/
    ASA_ScratchXImage,  
    ASA_ScratchMaskXImage,
    
    ASA_ScratchXImageAndAlpha,

    ASA_ARGB32,
    ASA_Vector,       /* This cannot be used for transformation's result
                       * format */
    ASA_Formats
}ASAltImFormats;

libAfterImage/ASImage

NAME
ASImage
is the main structure to hold image data.

DESCRIPTION

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.

SEE ALSO

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

SOURCE


struct ASImageAlternative;
struct ASImageManager;

/* magic number identifying ASFont data structure */
#define MAGIC_ASIMAGE            0xA3A314AE

typedef struct ASImage
{

  unsigned long magic ;

  unsigned int width, height;       /* size of the image in pixels */

  /* arrays of storage ids of stored scanlines of particular channel: */
  ASStorageID *alpha,
              *red,
              *green,
              *blue;
  
  ASStorageID *channels[IC_NUM_CHANNELS]; 
                                    /* merely a shortcut so we can
                                     * somewhat simplify code in loops */

  ARGB32 back_color ;               /* background color of the image, so
                                     * we could discard everything that
                                     * matches it, and then restore it
                                     * back. */

  struct ASImageAlternative
  {  /* alternative forms of ASImage storage : */
    XImage *ximage ;                /* pointer to XImage created as the
                                     * result of transformations whenever
                                     * we request it to output into
                                     * XImage ( see to_xim parameter ) */
    XImage *mask_ximage ;           /* XImage of depth 1 that could be
                                     * used to store mask of the image */
    ARGB32 *argb32 ;                /* array of widthxheight ARGB32
                                     * values */
    double *vector ;                /* scientific data that should be used
                                     * in conjunction with
                                     * ASScientificPalette to produce
                                     * actuall ARGB data */
  }alt;

  struct ASImageManager *imageman;  /* if not null - then image could be
                                     * referenced by some other code */
  int                    ref_count ;/* this will tell us what us how many
                                     * times */

    
  char                  *name ;     /* readonly copy of image name 
                                     * this name is a hash value used to 
                                     * store image in the image-man's hash,
                                     * and gets freed automagically on image 
                                     * removal from hash */

#define ASIM_DATA_NOT_USEFUL    (0x01<<0)
#define ASIM_VECTOR_TOP2BOTTOM  (0x01<<1)
#define ASIM_XIMAGE_8BIT_MASK   (0x01<<2)
#define ASIM_NO_COMPRESSION     (0x01<<3) /* Do not use compression to 
                                           * save some computation time
                                           */
#define ASIM_ALPHA_IS_BITMAP    (0x01<<4) 
#define ASIM_RGB_IS_BITMAP      (0x01<<5) 
#define ASIM_XIMAGE_NOT_USEFUL  (0x01<<6)
#define ASIM_NAME_IS_FILENAME   (0x01<<7)

  ASFlagType             flags ;    /* combination of the above flags */
  
} ASImage;

libAfterImage/ASImageManager

NAME
ASImageManager
structure to be used to maintain list of loaded images for given set of search paths and gamma. Images are named and reference counted.

SOURCE

typedef struct ASImageManager
{
    ASHashTable  *image_hash ;
    /* misc stuff that may come handy : */
    char         *search_path[MAX_SEARCH_PATHS+1];
    double        gamma ;
}ASImageManager;

libAfterImage/LIMITS

NAME
MAX_IMPORT_IMAGE_SIZE
effectively limits size of the allowed images to be loaded from files. That is needed to be able to filter out corrupt files.
MAX_BEVEL_OUTLINE
Limit on bevel outline to be drawn around the image.
MAX_SEARCH_PATHS
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 */
```

libAfterImage/ASVectorPalette

NAME
ASVectorPalette
contains palette allowing us to map double values in vector image data into actuall ARGB values.

SOURCE

typedef struct ASVectorPalette
{
    unsigned int npoints ;
    double *points ;
    CARD16 *channels[IC_NUM_CHANNELS] ;   /* ARGB data for key points. */
    ARGB32  default_color;
}ASVectorPalette;

libAfterImage/asimage/ASImageLayer

NAME
ASImageLayer
specifies parameters of the image superimposition.

DESCRIPTION

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.

NOTES

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