imencdec(3x)


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>
   libAfterImage/ASImageBevel

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

       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;

   libAfterImage/ASImageDecoder

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

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

   libAfterImage/asimage/quality

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

       #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

   libAfterImage/asimage/ASImageOutput

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

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

SEE ALSO

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

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;

   libAfterImage/asimage/start_image_decoding()

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
   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()
   libAfterImage/asimage/set_decoder_bevel_geom()

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.
   libAfterImage/asimage/set_decoder_shift()

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.
   libAfterImage/asimage/set_decoder_back_color()

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.
   libAfterImage/asimage/stop_image_decoding()

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()
   libAfterImage/asimage/start_image_output()

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.
   libAfterImage/asimage/set_image_output_back_color()

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.
   libAfterImage/asimage/stop_image_output()

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.





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.