imencdec(1)              AfterStep X11 window manager              imencdec(1)



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>

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

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

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

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

SEE ALSO
       start_image_output()
       set_image_output_back_color()
       toggle_image_output_direction()
       stop_image_output()

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

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

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.

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.

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.

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

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.

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.

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.



3rd Berkeley Distribution      AfterStep v.2.2.9                   imencdec(1)
