<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY email         "esr@thyrsus.com">
]>
<refentry id='gifcompose.1'>
<refentryinfo><date>2 May 2012</date></refentryinfo>
<refmeta>
<refentrytitle>gifcompose</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GIFLIB</refmiscinfo>
<refmiscinfo class="manual">GIFLIB Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>gifcompose</refname>
<refpurpose>image-composition minilanguage for GIFs</refpurpose>
</refnamediv>

<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>gifcompose</command>
      <arg choice='opt'>-v</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>

<para>The gifcompose program uses the GIFLIB utility tools to support
a minilanguage for describing GIF pasteup sequences.</para>

</refsect1>
<refsect1><title>Specification Syntax</title>

<para>The gifcompose tool takes a series of text lines on stdin and
interprets them as commands to do pasteup operations. The commands
are:</para>

<variablelist>
<varlistentry>
<term><command>gif &lt;name&gt;</command></term>
<listitem>
<para>Paste in &lt;name&gt;.gif</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>raw &lt;name&gt; &lt;width&gt; &lt;height&gt;</command></term>
<listitem>
<para>Paste in the given raw-format file (no suffix supplied).  Raw format
is a stream of 8-bit indices into the EGA color map.  Accordingly, the
width and height must be specified, and the source must be exactly
width times height bytes long.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>rgb &lt;name&gt; &lt;width&gt; &lt;height&gt;</command></term>
<listitem>
<para>Paste in the given RGB-format file (no suffix supplied).  Raw format
is a stream of 24-bit color values.  Accordingly, the width and height
must be specified, and the source must be exactly 3 times width times
height bytes long.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>text &lt;text&gt; [foreground &lt;index&gt;] [color &lt;r&gt; &lt;g&gt; &lt;b&gt;]</command></term>
<listitem>
<para>Copy 8x8 monospace font, with transparent background and index 1 as
foreground.  If the text string contains whitespaces, they must be
escaped or the string must be quoted (shell conventions).</para>
<para>The optional suffix `foreground &lt;n&gt;' sets the foreground
color index.</para>
<para>The optional suffix `color &lt;r&gt; &lt;g&gt; &lt;b&gt;' sets
the RGB color to be used for the foreground index.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Each generator operation may be followed by any combination of the
following suffixes:</para>

<variablelist>
<varlistentry>
<term><command>at &lt;x&gt; &lt;y&gt;</command></term>
<listitem>
<para>Place the image at the given (upper-left-hand-corner) coordinates
in the pasted-up result.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>clip &lt;name&gt; &lt;top-x&gt; &lt;top-y&gt; &lt;bottom-x&gt; &lt;bottom-y&gt;</command></term>
<listitem>
<para>Clip image using the given rectange, paste it onto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>xflip</command></term>
<listitem>
<para>Flip the image around the X axis before placing it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>yflip</command></term>
<listitem>
<para>Flip the image around the Y axis before placing it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>left</command></term>
<listitem>
<para>Rotate the image 90 degrees counterclockwise before placing it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>right</command></term>
<listitem>
<para>Rotate the image 90 degrees clockwise before placing it.</para>
</listitem>
</varlistentry>

</variablelist>

<variablelist>
<varlistentry>
<term><command>screen size &lt;x-size&gt; &lt;y-size&gt;</command></term>
<listitem>
<para>Set the global screen size of the final image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>screen position &lt;x&gt; &lt;y&gt;</command></term>
<listitem>
<para>Set the global screen position of the final image.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Comments or comment lines may be preceded with `#' and will be
ignored.</para>

</refsect1>
<refsect1><title>Options</title>

<variablelist>
<varlistentry>
<term>-v</term>
<listitem>
<para>Emit a report on each composition action to stderr as it happens.</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>
<refsect1><title>Bugs</title>

<para>The suffix sequence `left left' sometimes mysteriously fails to
work, probably due to some restriction in <ulink
url="gifflip.html">gifflip</ulink>.</para>

<para>No support for resizing or odd-angle rotations yet.</para>

<para>The `color' suffix of text is a no-op, because the present version of
<ulink url="gifovly.html">gifovly</ulink> throws away color tables.</para>

<para>Error checking is rudimentary.</para>

</refsect1>
<refsect1><title>Author</title>

<para>Eric S. Raymond <email>&email;</email></para>

</refsect1>
</refentry>
