.\" t
.\" @(#)imencdec.3		03/24/2024
.TH imencdec 3x "AfterStep v.2.2.12" "Mar 24 2024" "AfterStep X11 window manager"
.UC
.SH NAME
\fBimencdec\fP\ \- encoding/decoding ASImage data from/to usable data structures
libAfterImage/imencdec\&.h
.SH NAMEimencdec
defines main structures and function for image storing, extraction and conversion to/from usable formats\&.

.SH DESCRIPTION
.fi
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\&.
.fi

.SH SEE ALSO
.fi
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
.fi

.SH AUTHOR
.fi
Sasha Vasko <sasha at aftercode dot net>
.fi
libAfterImage/ASImageBevel
.SH NAMEASImageBevel
describes bevel to be drawn around the image\&.

.SH DESCRIPTION
.fi
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\&.
.fi

.SH SOURCE
.in +4n

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

.in
libAfterImage/ASImageDecoder
.SH NAMEASImageDecoder
describes the status of reading any particular ASImage, as well as providing detail on how it should be done\&.

.SH DESCRIPTION
.fi
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()\&.
.fi

.SH SOURCE
.in +4n

.fi
/* 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;
.fi

.in
libAfterImage/asimage/quality
.SH FUNCTION
.fi
Defines level of output quality/speed ratio
.fi

.SH 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\&.

.SH SOURCE
.in +4n

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

.in
libAfterImage/asimage/ASImageOutput
.SH 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\&.

.SH DESCRIPTION
.fi
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, up to 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\&.
.fi

.SH NOTES
.fi
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\&.
.fi

.SH SEE ALSO
.fi
start_image_output()
set_image_output_back_color()
toggle_image_output_direction()
stop_image_output()
.fi

.SH SOURCE
.in +4n

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

.in
libAfterImage/asimage/start_image_decoding()
.SH NAMEstart_image_decoding()
\- allocates and initializes decoder structure\&.

.SH SYNOPSIS
.fi
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 );
.fi

.SH INPUTS
.IP "asv"
\- pointer to valid ASVisual structure ( needed mostly to see if we are in BGR mode or not );
.IP "im"
\- ASImage we are going to decode;
.IP "filter"
\- bitmask where set bits mark channels that has to be decoded\&.
.IP "offset_x"
\- left margin inside im, from which we should start reading pixel data, effectively clipping source image\&.
.IP "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\&.
.IP "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\&.
.IP "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\&.
.IP "bevel"
\- NULL or pointer to valid ASImageBevel structure if decoded data should be overlayed with bevel at the time of decoding\&.

.SH RETURN VALUE
.fi
start_image_decoding() returns pointer to newly allocated
ASImageDecoder structure on success, NULL on failure\&.
.fi

.SH DESCRIPTION
.fi
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 up to 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()
.fi
libAfterImage/asimage/set_decoder_bevel_geom()
.SH NAMEset_decoder_bevel_geom()
\- changes default placement of the bevel on decoded image\&.

.SH SYNOPSIS
.fi
void set_decoder_bevel_geom( ASImageDecoder *imdec, int x, int y,
                             unsigned int width, unsigned int height );
.fi

.SH INPUTS
.IP "imdec"
\- pointer to pointer to structure, previously created by start_image_decoding\&.
.IP "x,y"
\- left top position of the inner border of the Bevel outline as related to the origin of subimage being decoded\&.
.IP "width,"

.IP "height"
\- widtha and height of the inner border of the bevel outline\&.

.SH DESCRIPTION
.fi
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\&.
.fi
libAfterImage/asimage/set_decoder_shift()
.SH NAMEset_decoder_shift()
\- changes the shift value of decoder \- 8 or 0\&.

.SH SYNOPSIS
.fi
void set_decoder_shift( ASImageDecoder *imdec, int shift );
.fi

.SH INPUTS
.IP "imdec"
\- pointer to pointer to structure, previously created by start_image_decoding\&.
.IP "shift"
\- new value to be used as the shift while decoding image\&. valid values are 8 and 0\&.

.SH DESCRIPTION
.fi
This function should be used instead of directly modifyeing value of
shift member of ASImageDecoder structure\&.
.fi
libAfterImage/asimage/set_decoder_back_color()
.SH NAMEset_decoder_back_color()
\- changes the back color to be used while decoding the image\&.

.SH SYNOPSIS
.fi
void set_decoder_back_color( ASImageDecoder *imdec, ARGB32 back_color );
.fi

.SH INPUTS
.IP "imdec"
\- pointer to pointer to structure, previously created by start_image_decoding\&.
.IP "back_color"
\- ARGB32 color value to be used as the background color to fill empty spaces in decoded ASImage\&.

.SH DESCRIPTION
.fi
This function should be used instead of directly modifyeing value of
back_color member of ASImageDecoder structure\&.
.fi
libAfterImage/asimage/stop_image_decoding()
.SH NAMEstop_image_decoding()
\- finishes decoding, frees all allocated memory\&.

.SH SYNOPSIS
.fi
void stop_image_decoding( ASImageDecoder **pimdec );
.fi

.SH INPUTS
.IP "pimdec"
\- pointer to pointer to structure, previously created by start_image_decoding\&.

.SH RETURN VALUE
.fi
pimdec  \- pointer to ASImageDecoder will be reset to NULL\&.
.fi

.SH SEE ALSO
.fi
start_image_decoding()
.fi
libAfterImage/asimage/start_image_output()
.SH NAMEstart_image_output()
\- initializes output structure

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

.SH INPUTS
.IP "asv"
\- pointer to valid ASVisual structure
.IP "im"
\- destination ASImage
.IP "format"
\- indicates that output should be written into alternative format, such as supplied XImage, ARGB32 array etc\&.
.IP "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\&.
.IP "quality"
\- what algorithms should be used while writing data out, i\&.e\&. full error diffusion, fast error diffusion, no error diffusion\&.

.SH DESCRIPTION
.fi
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\&.
.fi
libAfterImage/asimage/set_image_output_back_color()
.SH NAMEset_image_output_back_color()
\- changes background color of output

.SH SYNOPSIS
.fi
void set_image_output_back_color ( ASImageOutput *imout,
                                   ARGB32 back_color );
.fi

.SH INPUTS
.IP "imout"
\- ASImageOutput structure, previously created with start_image_output();
.IP "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()
.SH NAMEtoggle_image_output_direction()
\- reverses vertical direction of output

.SH SYNOPSIS
.fi
void toggle_image_output_direction( ASImageOutput *imout );
.fi

.SH INPUTS
.IP "imout"
\- ASImageOutput structure, previously created with start_image_output();

.SH DESCRIPTION
.fi
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\&.
.fi
libAfterImage/asimage/stop_image_output()
.SH NAMEstop_image_output()
\- finishes output, frees all the allocated memory\&.

.SH SYNOPSIS
.fi
void stop_image_output( ASImageOutput **pimout );
.fi

.SH INPUTS
.IP "pimout"
\- pointer to pointer to ASImageOutput structure, previously created with call to start_image_output()\&.

.SH RETURN VALUE
.fi
pimout      \- pointer to ASImageOutput will be reset to NULL\&.
.fi

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