ascompose.html

Generated from ascompose.c with ROBODoc v3.2.3 on Tue Jan 15 15:07:58 2002

## libAfterImage/ascompose

NAME

     ascompose is a tool to compose image(s) and display/save it based on
     supplied XML input file.

SYNOPSIS

     ascompose -f file|-s string [-o file] [-t type] [-V]"
     ascompose -f file|-s string [-o file] [-t type] [-V]"
     ascompose -f file|-s string [-o file] [-t type] [-V] [-n]"
     ascompose -f file|-s string [-o file] [-t type] [-V] [-r]"
     ascompose [-h]
     ascompose [-v]

DESCRIPTION

     ascompose reads supplied XML data, and manipulates image accordingly.
     It could transform images from files of any supported file format,
     draw gradients, render antialiased texturized text, perform
     superimposition of arbitrary number of images, and save images into
     files of any of supported output file formats.

     At any point, the result of any operation could be assigned a name,
     and later on referenced under this name.

     At any point during the script processing, result of any operation
     could be saved into a file of any supported file types.

     Internal image format is 32bit ARGB with 8bit per channel.

     Last image referenced, will be displayed in X window, unless -n option
     is specified. If -r option is specified, then this image will be
     displayed in root window of X display, effectively setting a background
     for a desktop. If -o option is specified, this image will also be
     saved into the file or requested type.

     ascompose can be compiled to not reference X Window System, thus
     allowing it to be used on web servers and any other place. It does not
     even require X libraries in that case.

     Supported file types for input are :
     XPM   - via internal code, or libXpm library.
     JPEG  - via libJpeg library.
     PNG   - via libPNG library.
     XCF   - via internal code. For now XCF support is not complete as it
             does not merge layers.
     PPM/PNM - via internal code.
     BMP, ICO, CUR - via internal code.
     GIF   - via libungif library.
     TIFF  - via libtiff library (including alpha channel support).
     see libAfterImage/ASImageFileTypes for more.

     Supported file types for output :
     XPM   - via internal code, or libXpm library.
     JPEG  - via libJpeg library.
     PNG   - via libPNG library.
     GIF   - via libungif library.
     TIFF  - via libtiff library (including alpha channel support).

OPTIONS

        -h --help          display help and exit.
        -f --file file     an XML file to use as input.
        -s --string string an XML string to use as input.
        -n --no-display    don't display the last referenced image.
        -r --root-window   draw last referenced image image on root window.
        -o --output file   output last referenced image in to a file.
                           You should use -t to specify what file type to
                           use. Filenames are meaningless when it comes to
                           determining what file type to use.
        -t --type type     type of file to output to.
        -v --version       display version and exit.
        -V --verbose       increase verbosity. To increase verbosity level
                           use several of these, like: ascompose -V -V -V.
        -D --debug         maximum verbosity - show everything and
                           debug messages.

PORTABILITY

     ascompose could be used both with and without X window system. It has
     been tested on most UNIX flavors on both 32 and 64 bit architecture.
     It has also been tested under CYGWIN environment on Windows 95/NT/2000

USES

     libAfterImage         all the image manipulation routines.
     libAfterBase          Optionally. Misc data handling such as hash
                           tables and console io. Must be used when compiled
                           without X Window support.
     libJPEG               JPEG image format support.
     libPNG                PNG image format support.
     libungif              GIF image format support.
     libTIFF               TIFF image format support.

AUTHOR

     Ethan Fisher          <allanon at crystaltokyo dot com>
     Sasha Vasko           <sasha at aftercode dot net>
     Eric Kowalski         <eric at beancrock dot net>

## libAfterImage/ascompose/sample

EXAMPLE

     Here is the default script that gets executed by ascompose, if no
     parameters are given :

SOURCE

        static char* default_doc_str = "\
        <composite op=hue>\
          <composite op=add>\
            <scale width=512 height=384><img src=rose512.jpg/></scale>\
            <tile width=512 height=384><img src=back.xpm/></tile>\
          </composite>\
          <tile width=512 height=384><img src=fore.xpm/></tile>\
        </composite>\
        ";

## libAfterImage/ascompose/tags

TAGS

     Here is the list and description of possible XML tags to use in the
     script :
        img       - load image from the file.
        recall    - recall previously loaded/generated image by its name.
        text      - render text string into new image.
        save      - save an image into the file.
        bevel     - draw solid bevel frame around the image.
        gradient  - render multipoint gradient.
        mirror    - create mirror copy of an image.
        blur      - perform gaussian blur on an image.
        rotate    - rotate/flip image in 90 degree increments.
        scale     - scale an image to arbitrary size.
        crop      - crop an image to arbitrary size.
        tile      - tile an image to arbitrary size.
        hsv       - adjust Hue, Saturation and Value of an image.
        pad       - pad image with solid color from either or all sides.
        solid     - generate new image of requested size, filled with solid
                  color.
        composite - superimpose arbitrary number of images using one of 15
                  available methods.

     Each tag generates new image as the result of the transformation -
     existing images are never modified and could be reused as many times
     as needed. See below for description of each tag.

     Whenever numerical values are involved, the basic math ops (add,
     subtract, multiply, divide), unary minus, and parentheses are
     supported.
     Operator precedence is NOT supported.  Percentages are allowed, and
     apply to the "size" parameter of this function.

     Each tag is only allowed to return ONE image.

## libAfterImage/ascompose/tags/img

NAME

     img - load image from the file.

SYNOPSIS

     <img id="new_img_id" src=filename/>

ATTRIBUTES

     id     Optional.  Image will be given this name for future reference.
     src    Required.  The filename (NOT URL) of the image file to load.

NOTES

     The special image src "xroot:" will import the background image
     of the root X window, if any.  No attempt will be made to offset this
     image to fit the location of the resulting window, if one is displayed.

## libAfterImage/ascompose/tags/recall

NAME

     recall - recall previously generated and named image by its id.

SYNOPSIS

     <recall id="new_id" srcid="image_id">

ATTRIBUTES

     id       Optional.  Image will be given this name for future reference.
     srcid    Required.  An image ID defined with the "id" parameter for
              any previously created image.

## libAfterImage/ascompose/tags/text

NAME

     text - render text string into new image, using specific font, size
            and texture.

SYNOPSIS

     <text id="new_id" font="font" point="size" fgcolor="color"
           bgcolor="color" fgimage="image_id" bgimage="image_id"
           spacing="points">My Text Here</text>

ATTRIBUTES

     id       Optional.  Image will be given this name for future reference.
     font     Optional.  Default is "fixed".  Font to use for text.
     point    Optional.  Default is 12.  Size of text in points.
     fgcolor  Optional.  No default.  The text will be drawn in this color.
     bgcolor  Optional.  No default.  The area behind the text will be drawn
              in this color.
     fgimage  Optional.  No default.  The text will be textured by this image.
     bgimage  Optional.  No default.  The area behind the text will be filled
              with this image.
     spacing  Optional.  Default 0.  Extra pixels to place between each glyph.

NOTES

     <text> without bgcolor, fgcolor, fgimage, or bgimage will NOT
     produce visible output by itself.  See EXAMPLES below.

## libAfterImage/ascompose/tags/save

NAME

     save - write generated/loaded image into the file of one of the
            supported types

SYNOPSIS

     <save id="new_id" dst="filename" format="format" compress="value"
           opacity="value" replace="0|1" delay="mlsecs">

ATTRIBUTES

     id       Optional.  Image will be given this name for future reference.
     dst      Required.  Name of file image will be saved to.
     format   Optional.  Ouput format of saved image.  Defaults to the
              extension of the "dst" parameter.  Valid values are the
              standard AS image file formats: xpm, jpg, png, gif, tiff.
     compress Optional.  Compression level if supported by output file
              format. Valid values are in range of 0 - 100 and any of
              "deflate", "jpeg", "ojpeg", "packbits" for TIFF files.
              Note that JPEG and GIF will produce images with deteriorated
              quality when compress is greater then 0. For JPEG default is
              25, for PNG default is 6 and for GIF it is 0.
     opacity  Optional. Level below which pixel is considered to be
              transparent, while saving image as XPM or GIF. Valid values
              are in range 0-255. Default is 127.
     replace  Optional. Causes ascompose to delete file if the file with the
              same name already exists. Valid values are 0 and 1. Default
              is 1 - files are deleted before being saved. Disable this to
              get multimage animated gifs.
     delay    Optional. Delay to be stored in GIF image. This could be used
              to create animated gifs. Note that you have to set replace="0"
              and then write several images into the GIF file with the same
              name.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/bevel

NAME

     bevel - draws solid bevel frame around the image.

SYNOPSIS

     <bevel id="new_id" colors="color1 color2"
            border="left top right bottom">

ATTRIBUTES

     id       Optional.  Image will be given this name for future reference.
     colors   Optional.  Whitespace-separated list of colors.  Exactly two
              colors are required.  Default is "#ffdddddd #ff555555".  The
              first color is the color of the upper and left edges, and the
              second is the color of the lower and right edges.
     borders  Optional.  Whitespace-separated list of integer values.
              Default is "10 10 10 10".  The values represent the offsets
              toward the center of the image of each border: left, top,
              right, bottom.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/gradient

NAME

     gradient - render multipoint gradient.

SYNOPSIS

     <gradient id="new_id" angle="degrees" width="pixels" height="pixels"
               colors ="color1 color2 color3 [...]"
               offsets="fraction1 fraction2 fraction3 [...]"/>

ATTRIBUTES

     id       Optional.  Image will be given this name for future reference.
     refid    Optional.  An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "width"
              and "height" will be derived from the width and height of the
              refid image.
     width    Required.  The gradient will have this width.
     height   Required.  The gradient will have this height.
     colors   Required.  Whitespace-separated list of colors.  At least two
              colors are required.  Each color in this list will be visited
              in turn, at the intervals given by the offsets attribute.
     offsets  Optional.  Whitespace-separated list of floating point values
              ranging from 0.0 to 1.0.  The colors from the colors attribute
              are given these offsets, and the final gradient is rendered
              from the combination of the two.  If both colors and offsets
              are given but the number of colors and offsets do not match,
              the minimum of the two will be used, and the other will be
              truncated to match.  If offsets are not given, a smooth
              stepping from 0.0 to 1.0 will be used.
     angle    Optional.  Given in degrees.  Default is 0.  This is the
              direction of the gradient.  Currently the only supported
              values are 0, 45, 90, 135, 180, 225, 270, 315.  0 means left
              to right, 90 means top to bottom, etc.

## libAfterImage/ascompose/tags/mirror

NAME

     mirror - create new image as mirror copy of an old one.

SYNOPSIS

      <mirror id="new_id" dir="direction">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     dir      Required. Possible values are "vertical" and "horizontal".
              The image will be flipped over the x-axis if dir is vertical,
              and flipped over the y-axis if dir is horizontal.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/blur

NAME

     blur - perform a gaussian blurr on an image.

SYNOPSIS

     <blur id="new_id" horz="radius" vert="radius">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     horz     Optional. Horizontal radius of the blur in pixels.
     vert     Optional. Vertical radius of the blur in pixels.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/rotate

NAME

     rotate - rotate an image in 90 degree increments (flip).

SYNOPSIS

      <rotate id="new_id" angle="degrees">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     angle    Required.  Given in degrees.  Possible values are currently
              "90", "180", and "270".  Rotates the image through the given
              angle.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/scale

NAME

     scale - scale image to arbitrary size

SYNOPSIS

     <scale id="new_id" ref_id="other_imag" width="pixels" height="pixels">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     refid    Optional.  An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "width"
              and "height" will be derived from the width and height of the
              refid image.
     width    Required.  The image will be scaled to this width.
     height   Required.  The image will be scaled to this height.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/crop

NAME

     crop - crop image to arbitrary area within it.

SYNOPSIS

      <crop id="new_id" refid="other_image" srcx="pixels" srcy="pixels"
            width="pixels" height="pixels" tint="color">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     refid    Optional. An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "width"
              and "height" will be derived from the width and height of the
              refid image.
     srcx     Optional. Default is "0". Skip this many pixels from the left.
     srcy     Optional. Default is "0". Skip this many pixels from the top.
     width    Optional. Default is "100%".  Keep this many pixels wide.
     height   Optional. Default is "100%".  Keep this many pixels tall.
     tint     Optional. Additionally tint an image to specified color.
              Tinting can both lighten and darken an image. Tinting color
              0 or #7f7f7f7f yeilds no tinting. Tinting can be performed on
              any channel, including alpha channel.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/tile

NAME

     tile - tile an image to specified area.

SYNOPSIS

      <tile id="new_id" refid="other_image" width="pixels" height="pixels"
            x_origin="pixels" y_origin="pixels" tint="color">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     refid    Optional. An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "width"
              and "height" will be derived from the width and height of the
              refid image.
     width    Optional. Default is "100%". The image will be tiled to this
              width.
     height   Optional. Default is "100%". The image will be tiled to this
              height.
     x_origin Optional. Horizontal position on infinite surface, covered
              with tiles of the image, from which to cut out resulting
              image.
     y_origin Optional. Vertical position on infinite surface, covered
              with tiles of the image, from which to cut out resulting
              image.
     tint     Optional. Additionally tint an image to specified color.
              Tinting can both lighten and darken an image. Tinting color
              0 or #7f7f7f7f yields no tinting. Tinting can be performed
              on any channel, including alpha channel.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/hsv

NAME

     hsv - adjust Hue, Saturation and/or Value of an image and optionally
     tile an image to arbitrary area.

SYNOPSIS

     <hsv id="new_id" refid="other_image"
          x_origin="pixels" y_origin="pixels" width="pixels" height="pixels"
          affected_hue="degrees|color" affected_radius="degrees"
          hue_offset="degrees" saturation_offset="value"
          value_offset="value">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     refid    Optional. An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "width"
              and "height" will be derived from the width and height of the
              refid image.
     width    Optional. Default is "100%". The image will be tiled to this
              width.
     height   Optional. Default is "100%". The image will be tiled to this
              height.
     x_origin Optional. Horizontal position on infinite surface, covered
              with tiles of the image, from which to cut out resulting
              image.
     y_origin Optional. Vertical position on infinite surface, covered
              with tiles of the image, from which to cut out resulting
              image.
     affected_hue    Optional. Limits effects to the renage of hues around
              this hue. If numeric value is specified - it is treated as
              degrees on 360 degree circle, with :
                  red = 0,
                  yellow = 60,
                  green = 120,
                  cyan = 180,
                  blue = 240,
                  magenta = 300.
              If colorname or value preceded with # is specified here - it
              will be treated as RGB color and converted into hue
              automagically.
     affected_radius
              Optional. Value in degrees to be used in order to
              calculate the range of affected hues. Range is determined by
              substracting and adding this value from/to affected_hue.
     hue_offset
              Optional. Value by which to adjust the hue.
     saturation_offset
              Optional. Value by which to adjust the saturation.
     value_offset
              Optional. Value by which to adjust the value.

NOTES

     One of the Offsets must be not 0, in order for operation to be
     performed.

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/pad

NAME

     pad - pad an image with solid color rectangles.

SYNOPSIS

     <pad id="new_id" refid="other_image" left="pixels" top="pixels"
          right="pixels" bottom="pixels" color="color">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     refid    Optional. An image ID defined with the "id" parameter for
              any previously created image.  If set, percentages in "pixel"
              pad values will be derived from the width and height of the
              refid image.
     left     Optional. Size to add to the left of the image.
     top      Optional. Size to add to the top of the image.
     right    Optional. Size to add to the right of the image.
     bottom   Optional. Size to add to the bottom of the image.
     color    Optional. Color value to fill added areas with. It could be
              transparent of course. Default is #FF000000 - totally black.

NOTES

     This tag applies to the first image contained within the tag.  Any
     further images will be discarded.

## libAfterImage/ascompose/tags/solid

NAME

     solid - generate image of specified size and fill it with solid color.

SYNOPSIS

     <solid id="new_id" color="color" width="pixels" height="pixels"/>

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     color    Optional.  Default is "#ffffffff".  An image will be created
              and filled with this color.
     width    Required.  The image will have this width.
     height   Required.  The image will have this height.

## libAfterImage/ascompose/tags/composite

NAME

     composite - superimpose arbitrary number of images on top of each
     other.

SYNOPSIS

     <composite id="new_id" op="op_desc"
                keep-transparency="0|1" merge="0|1">

ATTRIBUTES

     id       Optional. Image will be given this name for future reference.
     op       Optional. Default is "alphablend". The compositing operation.
              Valid values are the standard AS blending ops: add, alphablend,
              allanon, colorize, darken, diff, dissipate, hue, lighten,
              overlay, saturate, screen, sub, tint, value.
     merge    Optional. Default is "expand". Valid values are "clip" and
              "expand". Determines whether final image will be expanded to
              the maximum size of the layers, or clipped to the bottom
              layer.
     keep-transparency
              Optional. Default is "0". Valid values are "0" and "1". If
              set to "1", the transparency of the bottom layer will be
              kept for the final image.

NOTES

     All images surrounded by this tag will be composited with the given op.

     All tags surrounded by this tag will be given the following
     additional attributes in addition to their normal ones.  Under no
     circumstances is there a conflict with the normal child attributes.
     crefid   Optional. An image ID defined with the "id" parameter for
              any previously created image. If set, percentages in "x"
              and "y" will be derived from the width and height of the
              crefid image.
     x        Optional. Default is 0. Pixel coordinate of left edge.
     y        Optional. Default is 0. Pixel coordinate of top edge.
     clip_x   Optional. Default is 0. X Offset on infinite surface tiled
              with this image, from which to cut portion of an image to be
              used in composition.
     clip_y   Optional. Default is 0. Y Offset on infinite surface tiled
              with this image, from which to cut portion of an image to be
              used in composition.
     clip_width
              Optional. Default is image width. Tile image to this width
              prior to superimposition.
     clip_height
              Optional. Default is image height. Tile image to this height
              prior to superimposition.
     tile     Optional. Default is 0. If set will cause image to be tiled
              across entire composition, unless overridden by clip_width or
              clip_height.
     tint     Optional. Additionally tint an image to specified color.
              Tinting can both lighten and darken an image. Tinting color
              0 or #7f7f7f7f yields no tinting. Tinting can be performed
              on any channel, including alpha channel.

SEE ALSO

     libAfterImage