LibGGIBlt Functions
===================

Almost everything is there except ggiBltSetCoordBase and
ggiBltGetCoordBase.


Extension management
~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltInit ggiBltExit ggiBltAttach ggiBltDetach

Synopsis
--------

::

  #include <ggi/blt.h>
  
  int ggiBltInit(void);
  
  int ggiBltExit(void);

  int ggiBltAttach(ggi_visual_t vis, ggiGA_resource_list *reqlist);
  
  int ggiBltDetach(ggi_visual_t vis);


Description
-----------

`ggiBltInit` initializes the library. This function must be called
before using other LibGGIBlt functions; otherwise the results will be
undefined.

`ggiBltExit` uninitializes the library (after being initialized by
`ggiBltInit`) and automatically cleanup if necessary.  This should be
called after an application is finished with the library.  If any
LibGGIBlt functions are called after the library has been
uninitialized, the results will be undefined.

`ggiBltInit` allows multiple invocations.  A reference count is
maintained, and to completely uninitialize the library, `ggiBltExit`
must be called as many times as `ggiBltInit` has been called
beforehand.


`ggiBltAttach` extends a visual such that the LibBlt API may be used
on the visual handle.  This function must be called before using other
LibGGIBlt functions on the visual handle.  The parameter reslist is a
pointer to a LibGAlloc resource list kept by the application, and such
an object must exist and be passed here in order to use the
simple-form `ggiBltCreate*` functions.

`ggiBltDetach` cleans up all state associated with using the LibGGIBlt
API on this visual.


Return value
------------


`ggiBltInit`, `ggiBltAttach` and `ggiBltDetach` return `0` for OK,
otherwise an error code.


`ggiBltExit` returns:

`0`
	after successfully cleaning up,

`>0`
	the number of 'open' `ggiBltInit` calls, if there has been
	more than one call to `ggiBltInit`.  As `ggiBltInit` and
	`ggiBltExit` must be used in properly nested pairs, e.g. the
	first `ggiBltExit` after two `ggiBltInit`\ s will return 1.

`<0` 
	error, especially if more `ggiBltExit` calls have been done
	than `ggiBltInit` calls.

Example
-------

Activate LibGGIBlt such that the ggiBltCreate* functions work::

  ggiGA_resource_list reslist;
  reslist = NULL;
  ggiBltInit();
  ggiBltAttach(vis, &reslist);

  /* Do some libblt stuff */

  ggiBltDetach(vis);
  ggiBltExit();




Allocate and activate a blit on-the-fly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltCreate ggiBltDestroy

Synopsis
--------

::

  #include <ggi/blt.h>

  ggiBlt_t ggiBltCreate(ggi_visual_t vis, enum ggiGA_storage_type stype,
		        int numrows, enum ggi_ll_rop rop, 
		        enum ggiBlt_flags flags);

  int ggiBltDestroy(ggiBlt_t *blt);

Description
-----------


`ggiBltCreate` allocates and creates a *blit*.  LibGGIBlt's definition,
of a *blit* is a set of operations that can be prepared, stored, and then 
set in motion later -- `ggiBltCreate` does not create a data buffer to contain
pixel data which will be used during these operations.  For that, see 
`ggiBltCreateBob`.  Think of a *blit* instead as a sort of *display list*,
or if you are unfamiliar with that term, a virtual *command FIFO* : LibGGIBlt
stores precompiled data and instructions representing blitting operations
in a ggiBlt_t.


The parameter :p:`stype` designates the type of storage which the blit
will use to store precompiled operations, for example,
``GA_STORAGE_SWAP`` will get normal system memory, and
``GA_STORAGE_TRANSFER | GA_STORAGE_RAM`` will get AGP RAM, DMA-capable
RAM, or an otherwise shared application/target-driver area, and thus
will transfer the commands it contains to the target in the most
efficient manner possible.  ``GA_STORAGE_DONTCARE`` will pick the most
preferred available storage type for the blit.  See the storage type
definitions in the LibGAlloc documentation for a full list of values
and their meanings for this field.


The parameter :p:`numrows` determines how many operations can be
stored in the blit.  These operations may be loaded with the various
`ggiBltPut*` functions, and may be dispatched to the target via the
`ggiBltGo` function.

The parameter :p:`rop` demands that a certain set of raster operations
be supported by the blit (this term *rop* is used loosely in LibGGIBlt
to cover various operations like color keying and alpha blends in
addition to traditional boolean raster operations.)  See the LibGAlloc
documentation for a full list of values and their meanings for this
feild.

The parameter :p:`flags` determines some behavioral charactersistics
of the blit when operations or graphics context are altered.  It may
contain any of the following flags:

``BLT_FLAGS_STICKY_CLIP``
    The current value of the clipping rectangle is stored in the
    precompiled command, and when sent to target, the results will be
    clipped with the values which were in effect when the command was
    loaded into the blit.  Otherwise, the clip values used are those
    currently in effect on the visual when the command is sent to the
    target.

``BLT_FLAGS_STICKY_FGBG``
    The current value of the foreground and background drawing colors
    are stored in the precompiled command, and when sent to target,
    any monochrome/bichrome drawing operations will be rendered with
    the values which were in effect when the command was loaded into
    the blit.  Otherwise, the colors used are those currently in
    effect on the visual when the command is sent to the target.

``BLT_FLAGS_STICKY_BLEND``
    The current chosen default alpha blending formula (or nonpresence
    thereof) is stored in the precompiled command, and when sent to
    target, any alpha operations will use the blending formula which
    was in effect when the command was loaded into the blit.
    Otherwise, the blend used is that currently in effect on the
    visual when the command is sent to the target, even if the given
    visual was clad (using LibGGIBuf's `ggiBufCladVis`) after creation
    of the blit.

The function `ggiBltDestroy` releases all resources related
to the given blit and sets the proferred pointer to ``NULL``.


Return value
------------

`ggiBltCreate` will return a `ggiBlt_t` object handle if the blit was 
successfully allocated and activated, or on error, `NULL`.  

`ggiBltDestroy` returns `0` (GGI_OK) on success, or a negative error
code on failure.

Examples
--------

Create a 50-operation blit with a few boolean rops available::

  blt = ggiBltCreate(vis, GA_STORAGE_SWAP, ROP_NOR | ROP_XOR | ROP_AND, 0, 0);
  if (blt == NULL) {
        /* We cannot get this blt */
    }

See Also
--------

:man:`ggiBltCreateBob(3)`


Allocate and activate a blit source on-the-fly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltCreateBob ggiBltReuseBob ggiBltDestroyBob

Synopsis
--------

::

  #include <ggi/blt.h>

  ggiBlt_source_t ggiBltCreateBob(ggi_visual_t vis, ggiBlt_t forthis,
				  enum ggiGA_storage_type stype, int w, int h,
				  int qty, ggi_graphtype gt);

  int ggiReuseBob(ggiBlt_source_t bob, ggiBlt_t forthis);

  int ggiBltDestroyBob(ggiBlt_source_t *blt);


Description
-----------

`ggiBltCreateBob` allocates and creates a pixel data buffer, also
known as a *BOB*, for use as a source in blitting operations.  The
parameter :p:`forthis` designates a blit for which the *BOB* is to be
created.

The parameter :p:`stype` designates the type of storage which the blit
will use to store the pixel data, for example, ``GA_STORAGE_SWAP``
will get normal system memory, and ``GA_STORAGE_TRANSFER |
GA_STORAGE_RAM`` will get AGP RAM, DMA-capable RAM, or an otherwise
shared application/target-driver area, and thus will transfer the data
it contains to the target in the most efficient manner possible.
``GA_STORAGE_DONTCARE`` will pick the most preferred available storage
type for the pixel data.  See the storage type definitions in the
LibGAlloc documentation for a full list of values and their meanings
for this field.

The parameters :p:`w` and :p:`h` specify the width and height in
pixels of the BOB data.  The parameter :p:`qty`, if set > 1, requests
multiple identical data areas be created, which can then be selected
via the function `ggiBltSetSourceIdx`, and thus managed by the same
`ggiBlt_source_t` object.  The parameter :p:`gt` chooses the bit-depth
and color scheme of the BOB as per a normal ggi_graphtype.


`ggiBltReUseBob` checks to see if a BOB may be used with a blit for
which it was not originally created.  The parameter :p:`forthis`
designates an additional blit for which the BOB should be approved for
use.

`ggiBltDestroyBob` releases all resources related to the given BOB and
sets the proferred handle to ``NULL``.


Return value
------------

`ggiBltCreateBob` will return a `ggiBlt_source_t` if the blit was 
successfully allocated and activated, with the `src1` pointer inside the 
object set to point to a private LibGGIBlt data structure which must not 
be altered.  On error, `NULL` will be returned.

`ggiBltReuseBob` will return `0` (GGI_OK) if the specified BOB is
usable with the specified blit, or a negative error code on failure.

`ggiBltDestroyBob` returns `0` (GGI_OK) on success, or a negative
error code on failure.

Examples
--------

Create a 50x50 16bpp BOB for one blit and reuse it with a second blit::

  bob = ggiBltCreateBob(vis, blt1, GA_STORAGE_DONTCARE, 50, 50, 1, GT_16BIT);
  if (ggiReuseBob(bob, blt2)) {
        /* This BOB is incompatible with blt2 */
  }

See Also
--------

:man:`ggiBltSetSourceIdx(3)`



Add a request for a blit and BOBs to a LibGAlloc request list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltAdd

Synopsis
--------

::

  #include <ggi/blt.h>

  int ggiBltAdd(ggiGA_resource_list *reqlist,
                struct ggiGA_resource_props **props,
                enum ggiGA_resource_type *types,
                int numresources,
                ggiGA_resource_handle **handles);

Description
-----------

The `ggiBltAdd` functions are LibGGIBlt's interface to LibGAlloc.
Currently support for these functions is sporadic; it will be
completed in a later stage of LibGGIBlt's development.

In all functions, the parameter :p:`reqlist` refers to a LibGAlloc
request list.

`ggiBltAdd` attaches a request for carb, motor, and tank resources
making up a blit and a set of BOBs to the designated request list,
manipulating the structure of the list as appropriate.

More docmentation on this function will follow as LibGGIBlt matures.
This function is provided for advanced users who are familiar with
LibGAlloc.


Return value
------------

The functions return `0` (GALLOC_OK) on success, or a negative error
code if an error occurred.

See Also
--------

:man:`ggiBltCreate(3)`, :man:`ggiBltCreateBob(3)`, :man:`ggiBltTie(3)`



(Un)wrap an approved LibGAlloc resource handle in blit or bob object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltTie ggiBltUnTie ggiBltTieBob ggiBltUnTieBob

Synopsis
--------

::

  #include <ggi/blt.h>

  ggiBlt_t ggiBltTie(ggiGA_resource_handle *handles, int numhandles);

  int ggiBltUntie(ggiBlt_t *blt);

  ggiBlt_t ggiBltTieBob(ggiGA_resource_handle *carb, 
		        ggiGA_resource_handle *tank);

  int ggiBltUntieBob(ggiBlt_source_t *bob);


Description
-----------

`ggiBltTie` creates a `ggiBlt_t` object from a set of approved
LibGAlloc resource handles, passed via the parameter :p:`handles` in
array form.  The parameter :p:`numhandles` designates the number of
handles in the array.


`ggiBltUnTie` destroys a `ggiBlt_t` object, but does not release
resources allocated via LibGAlloc.  To entirely release all resources,
use the function `ggiBltDestroy`.

`ggiBltTieBob` creates a `ggiBlt_source_t` object from a set of
approved LibGAlloc resource handles, passed via the parameters
:p:`carb` and :p:`tank`.  The structure returned contains a private
LibGGIBlt structure stored in the `src1` member, which must not be
altered.

`ggiBltUnTieBob` destroys a `ggiBlt_source_t` object, but does not
release resources allocated via LibGAlloc.  To entirely release all
resources, use the function `ggiBltDestroyBob`.


Return value
------------


`ggiBltTie` returns a newly allocated ggiBlt_t object.  

`ggiBltTieBob` returns a newly allocated ggiBlt_source_t object with a
private LibGGIBlt data structure stored in the `src1` member, which
must not be altered.

`ggiBltTie` and `ggiBltTieBob` return `NULL` on failure.

Functions `ggiBltUntie` and `ggiBltUntieBob` return `0` (GGI_OK) if
successful, or a negative error code on failure, and set the proferred
handle to ``NULL``.


See Also
--------

:man:`ggiBltCreate(3)`, :man:`ggiBltCreateBob(3)`, :man:`ggiBltAdd(3)`



Set or get the flags and ROP behavior of a BOB
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltSetBobBobFlags ggiBltGetBobBobFlags ggiBltSetBobRop ggiBltGetBobRop ggiBltSetBobKeyValue ggiBltGetBobKeyValue ggiBltSetBobKeyMask ggiBltGetBobKeyMask

Synopsis
--------

::

  #include <ggi/blt.h>

  int ggiBltSetBobRop(ggiBlt_source_t bob, enum ggi_ll_rop rop);

  int ggiBltGetBobRop(ggiBlt_source_t bob, enum ggi_ll_rop *rop);

  int ggiBltSetBobKeyValue(ggiBlt_source_t bob, ggi_pixel keyval);

  int ggiBltGetBobKeyValue(ggiBlt_source_t bob, ggi_pixel *keyval);

  int ggiBltSetBobKeyMask(ggiBlt_source_t bob, ggi_pixel keymask);

  int ggiBltGetBobKeyMask(ggiBlt_source_t bob, ggi_pixel *keymask);

  int ggiBltSetBobFlags(ggiBlt_source_t bob, enum ggiBlt_bob_flags flags);

  int ggiBltGetBobFlags(ggiBlt_source_t bob, enum ggiBlt_bob_flags *flags);


Description
-----------

`ggiBltSetBobFlags` and `ggiBltGetBobFlags` set and read,
respectively, the current special flags of a BOB.  Presently the only
flag value defined is ``BLT_BOBFLAGS_KEYNOT``, which alters the sense
of the destination color keying comparison (see below).

`ggiBltSetBobRop` and `ggiBltGetBobRop` set and read, respectively,
the current raster operation imparted to a blit operation when a BOB
is placed into a Blt with one of the `ggiBltPut*` functions.


`ggiBltSetBobKeyValue` and `ggiBltGetBobKeyValue` set and read,
respectively, the pixel value imparted as a destination *color key* to
a blit operation when a BOB is placed into a Blt with one of the
`ggiBltPut*` functions.  The blit only alters pixels in the
destination which previously contain this value, unless the key mask
(see below) is non-zero or the ``BLT_BOBFLAGS_KEYNOT`` bit is set, the
latter of which reverses the behavior, altering all pixels except
those that previously contain this value.


`ggiBltSetBobKeyMask` and `ggiBltGetBobKeyMask` set and read,
respectively, the pixel value imparted as a destination *color key mask*
to a blit operation when a BOB is placed into a Blt with one of the 
`ggiBltPut*` functions.  Bits set in this value are treated as 
*dont care* bits when compared to the *color key* set by
`ggiBltSetKeyValue`.


Once imparted through a `ggiBltPut*` function, calling these 
functions again on this BOB with a different value will not alter the 
respective property in the blit's precompiled operation, only the property 
to be imparted to future operations.


Return value
------------

All four function pairs `0` for OK or a negative value on failure.


Set or get the texture index of a BOB or other LibBlt data source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltSetSourceIdx ggiBltGetSourceIdx

Synopsis
--------

::

  #include <ggi/blt.h>

  int ggiBltSetSourceIdx(ggiBlt_source_t bob, int idx);

  int ggiBltGetSourceIdx(ggiBlt_source_t bob, int idx);


Description
-----------

`ggiBltSetSourceIdx` and `ggiBltGetSourceIdx` set and read,
respectively, the texture index of a BOB or other LibBlt data source,
which is imparted to a blit operation when a BOB is placed into a Blt
with one of the `ggiBltPut*` functions.  Data is taken from the
managed area with the given index when corresponding precompiled
operation is sent to the target.

Note: an alternate form is planned which will use a linear address
into the managed area, as well.

Once imparted through a `ggiBltPut*` function, calling these functions
again on this BOB with a different value will not alter the the blit's
precompiled operation, only the texture to be imparted to future
operations.


Return value
------------


All functions `0` for OK or a negative value on failure.



Index, dispatch, and monitor the operations in a blit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltSetIdx ggiBltGetIdx ggiBltGo ggiBltAt

Synopsis
--------

::

  #include <ggi/blt.h>

  int ggiBltSetIdx(ggiBlt_t blt, int idx);

  int ggiBltGetIdx(ggiBlt_t blt, int *idx);

  int ggiBltGo(ggiBlt_t blt, int start, int numrows);

  int ggiBltAt(ggiBlt_t blt);


Description
-----------

`ggiBltGo` sends precompiled commands contained in a blit to the
target for rendering.  Commands are sent starting at the command at
the row with index :p:`idx`, and proceeds for :p:`numrows` rows
(i.e. setting :p:`numrows` to 0 will result in no rows being sent.)
The function returns when the commands have all been dispatched, which
does not mean that they have been rendered to the screen.


`ggiBltAt` may be used in a threaded application to check the progress
of command dispatch while `ggiBltGo` is chewing on a blit.  It will
return the index of the row currently being dispatched, or the first
row which will not be dispatched after `ggiBltGo` has completed.  Note
again, that this does not guarantee that the associated rendering
commands have completed, only that they have been dispatched to the
target.

To force all rendering to be completed, use the LibGGI function
`ggiFlush`.

`ggiBltSetIdx` and `ggiBltGetIdx` set or retrieve, respectively, the
index of the row in the blit to which the next `ggiBltPut*` function
will store a precompiled command.


Return value
------------

Except for `ggiBltAt`, whose return value is described above, all
functions return zero (GGI_OK) or a negative error code on failure.



Load or alter precompiled commands in a blit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBltPutBatchop ggiBltPutBlit ggiBltPutReverseBlit ggiBltPutStretchBlit ggiBltPutZBlit ggiBltPutABlit ggiBltAlterBobIdx ggiBltAlterCoord ggiBltAlterBox ggiBltAlterStretchBox ggiBltAlterZ ggiBltAlterA

Synopsis
--------

::

  #include <ggi/blt.h>

  int ggiBltPutBatchop(ggiBlt_t into, batchop_t from, int numrows);

  int ggiBltPutBlit(ggiBlt_t blt, ggiBlt_source_t source,
		    long x, long y, int w, int h);

  int ggiBltPutReverseBlit(ggiBlt_t blt, ggiBlt_source_t dest,
			   long x, long y, int w, int h);

  int ggiBltPutStretchBlit(ggiBlt_t blt, ggiBlt_source_t source,
			   long x, long y, int sw, int sh, long dw, long dh);

  int ggiBltPutZBlit(ggiBlt_t blt, ggiBlt_source_t source,
		     long x, long y, int w, int h,
		     int ztl, int zbr);

  int ggiBltPutABlit(ggiBlt_t blt, ggiBlt_source_t source,
		     long x, long y, int w, int h,
		     int atl, int abr);

  int ggiBltAlterBobIdx(ggiBlt_t blt, int *bobidx, int numrows);

  int ggiBltAlterCoord(ggiBlt_t blt, long *x, long *y, int numrows);

  int ggiBltAlterBox(ggiBlt_t blt, long *x, long *y, int *w, int *h, 
		     int numrows);

  int ggiBltAlterStretchBox(ggiBlt_t blt, long *x, long *y, int *w, int *h, 
			    int numrows);

  int ggiBltAlterZ(ggiBlt_t blt, int *ztl, int *zbr, int numrows);

  int ggiBltAlterA(ggiBlt_t blt, int *atl, int *abr, int numrows);


Description
-----------


`ggiBltPutBatchop` loads values from a libmmutils batchop structure
into a blit.  It is for advanced users, and the exact standards for
user-defined batchops have not been specified yet.


The rest of the `ggiBltPut*` functions share some common parameters
and behaviors: all the commands load a request for a single blitting
operation into the blit designated by the parameter :p:`blt`.  The
operation is loaded at the row index of the blit, as set by
ggiBltSetIdx, and after the operation is added, the row index is
incremented automatically.  Properties such as the texture index,
color key values, and raster operation are copied from the BOB (or
other type of LibBlt source) designated by the parameter :p:`source`.
Use of the word "copied" in the last sentence is important, as
subsequently changing these values in the BOB will not change the
values stored in the precompiled command.


Except where otherwise noted, the parameters :p:`x` and :p:`y` refer
to a coordinate on the main visual represented (as standard in GGI
extensions) as an offset from the top left corner of the visual to
which the blit belongs, designating the top left corner of the
affected area on the visual, and are in the coordinate base units last
set with `ggiBltSetCoordbase`.  Contrarily, parameters :p:`w` and
:p:`h` represent the dimensions of the rendered object in the units of
the pixels or values as stored in the BOB's managed area, and will
correspond to pixels on the main visual.


The function `ggiBltPutBlit` fills the row with a command that
performs a standard, no-frills blit operation, and the function
ggiPutReverseBlit fills the row with a command that will take data
from the framebuffer rather than pushing data to the framebuffer.


`ggiBltPutStretchBlit` fills the row with a command that performs an
interpolated stretching or shrinking operation.  The parameters
:p:`sw` and :p:`sh` work the same as the parameters :p:`w` and :p:`h`
do in the other functions, but do not affect the size of the rendered
area on the visual.  The parameters :p:`dw` and :p:`dh` designate the
size of the rendered area on the visual, and are in the coordinate
base last set with `ggiBltSetCoordbase`.


The function `ggiBltPutZBlit` fills the row with a command that will
perform Z-clipping on a visual which has been clad via the LibBuf
function `ggiBufCladVis`.  The source Z depth is interpolated linearly
along both axis between the value :p:`ztl`, which represents the Z
depth at the top left corner of the affected area, and :p:`zbr`, which
represents the Z depth at the bottom right corner of the affected
area.


The function `ggiBltPutABlit` fills the row with a command that will
perform A blending on a visual which has been clad via the LibBuf
function `ggiBufCladVis`.  The source alpha blend factor is
interpolated linearly along both axis between the value :p:`atl`,
which represents the alpha at the top left corner of the affected
area, and :p:`abr`, which represents the alpha blend factor at the
bottom right corner of the affected area.


The `ggiBltAlter*` allow the coordinates, sizes, texture indexes,
Z-depths, and alpha blend factors placed into a precompiled commands
in the blit designated by :p:`blt` to be altered en-mass in a number
of consecutive rows (designated by the parameter :p:`numrows`).  If
the values being altered are not pertinant to a given row (e.g.
ggiBltAlterA is attempts to alter a row which does not contain a
command that performs alpha blending) they are silently ignored for
that row.


`ggiBltAlterBobIdx` alters the texture indexes which were imparted to
the precompiled command contained in each specified row by the BOB or
other LibBlt source which was originally used to create the command,
changing the indexes to the values stored in the array designated by
the parameter :p:`bobidx`.


`ggiBltAlterCoord` alters the x,y coordinates of the top left corner
of the affected area on the visual.  x coordinates are loaded from the
array designated by the parameter :p:`x`, and y coordinates are loaded
from the array designated by the parameter :p:`y`.  The values loaded
are interperated as described above, which means that they use
coordinate base units as set via the most recent call to
`ggiBltSetCoordBase`, not the coordinate base units which were in
effect when the precompiled command was originally added to the row.


`ggiBltAlterBox` functions the same as `ggiBltAlterCoord`, with the
additional parameters :p:`w` and :p:`h`, which designate arrays from
which to load new values for the width and height of the texture to be
copied, as described above.


`ggiBltAlterStretchBox` functions the same as `ggiBltAlterBox`, except
that the parameters :p:`sw` and :p:`sh` take the place of :p:`x` and
:p:`y`, and with the additional parameters :p:`dw` and :p:`dh`, which
designate arrays from which to load new values for the width and
height of the affected area on the visual, using the coordinate base
units as set via the most recent call to `ggiBltSetCoordBase`, not the
coordinate base units which were in effect when the precompiled
command was originally added to the row.


The function `ggiBltAlterA` alters top left and bottom right source Z
depths originally created by `ggiBltPutZBlit`, using the values stored
in the arrays designated by the parameters :p:`atl` and :p:`abr`,
respectively.


The function `ggiBltAlterA` alters top left and bottom right source
alpha values originally created by `ggiBltPutABlit`, using the values
stored in the arrays designated by the parameters :p:`ztl` and
:p:`zbr`, respectively.


Return value
------------

All functions return `0` (GGI_OK) for OK or a negative value on
failure.


Examples
--------

Make a bunch of objects dance around the screen::

  ggiBltSetIdx(blt, 0);

  for (i = 0; i < numobjects; i++) {
	ggiBltPutBlit(blt, bob, 0, 0, 25, 25);
	ggiBltSetSourceIdx(source, i);
  }
  x = malloc(sizeof(long) * numobjects);
  y = malloc(sizeof(long) * numobjects);
  i = 0;
  while (i++ < 3000) {
	GetNewCoordinates(i, x, y);
	ggiBltAlterCoord(blt, x, y, numobjects);
	ggiBltGo(blt, 0, numbjects);
	ggiFlush();
	usleep(100);
  }

