LibGGIBuf Functions
===================


The following functions still need to be documented: `ggiBufAdd2Group`,  `ggiBufUntie`, `ggiBufStrip`, `ggiBufDestroyBuffer`



Initialize LibGGIBuf extension
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufInit ggiBufExit

Synopsis
--------

::

  #include <ggi/buf.h>

  int ggiBufInit(void);

  int ggiBufExit(void);


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

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

`ggiBufExit` uninitializes the library (after being initialized by
`ggiBufInit`) and automatically cleans up if necessary.  This should
be called after an application is finished with the library.  If any
LibBuf functions are called after the library has been uninitialized,
the results will be undefined.

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


Return Value
------------

`ggiBufInit` returns `0` for OK, otherwise an error code.

`ggiBufExit` returns:

`0`
	after successfully cleaning up,

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

`<0`
	error, especially if more `ggiBufExit` calls have been done
	than `ggiBufInit` calls.


See Also
--------


:man:`ggiBufAttach(3)`



Enable the LibGGIBuf API on a LibGGI visual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufAttach ggiBufDetach

Synopsis
--------

::

  #include <ggi/buf.h>

  int ggiBufAttach(ggi_visual_t vis, ggiGA_resource_list *reqlist);

  int ggiBufDetach(ggi_visual_t vis);


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


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


`ggiBufDetach` cleans up all state associated with using the LibGGIBuf
API on the visual :p:`vis`.  The visual is stripped of any active
buffers.  Note, however, that the buffers are not themselves currently
guaranteed to be destroyed and may still exist as objects, consuming
resources.  Behavior of these objects is at this point undefined.
They should be destroyed before calling `ggiBufDetach`.



Return Value
------------



Both functions return `0` for OK, otherwise an error code.


Examples
--------

Activate LibBuf such that the `ggiBufCreate*` functions work::

  ggiGA_resource_list reslist;
  reslist = NULL;
  ggiBufInit();
  ggiBufAttach(vis, &reslist);

  /* Do some libbuf stuff */

  ggiBufDetach(vis);
  ggiBufExit();



Allocate and activate an auxillary buffer resource on the fly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufCreateBuffer ggiBufCreateZ ggiBufCreateAlpha


Synopsis
--------

::

  #include <ggi/buf.h>

  ggiBuf_t ggiBufCreateBuffer(ggi_visual_t vis, 
			      enum ggiGA_resource_type fulltype,
			      struct ggiGA_resource_props *props,
			      enum ggiBuf_flags flags, ggiBuf_t forthis);

  ggiBuf_t ggiBufCreateZ(ggi_visual_t vis, ggiBuf_t forthis,
		         enum ggiGA_storage_type stype,
		         ggi_graphtype gt, enum ggiBuf_flags flags);

  ggiBuf_t ggiBufCreateAlpha(ggi_visual_t vis, ggiBuf_t forthis,
			     enum ggiGA_storage_type stype,
		             ggi_graphtype gt, enum ggiBuf_flags flags);


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


`ggiBufCreateZ` allocates and creates a Z buffer suitable for use with
the buffer referenced by :p:`forthis`.  If :p:`forthis` is ``NULL``, a Z
buffer for the main framebuffer of :p:`vis` is created.  The parameter
:p:`stype` designates the type of storage which the Z buffer is to
use, for example, `GA_STORAGE_SWAP` will get normal system memory, and
`GA_STORAGE_VRAM` will get video board memory.  `GA_STORAGE_DONTCARE` will
pick the preferred storage type for the visual automatically.  See the
storage type definitions in the LibGAlloc documentation for full a
list of values and their meanings for this field.


The parameter :p:`gt` chooses the bit depth of the buffer and
specifies whether the buffer contains greyscale or RGB data, as per a
normal LibGGI graphtype.  The parameter :p:`flags` can contain
contains any combination of the following flags: `BUF_DISPOSE`,
`BUF_PUTGET`, `BUF_BLEND_ALT`, `BUF_CMP_GT`, `BUF_CMP_LT` (or
alternatively `BUF_CMP_GTE`, `BUF_CMP_LTE`), `BUF_CMP_SIGNED`.  The
meaning of these flags is described in the documentation for
:man:`ggiBufSetGCFlags(3)`.  The value ``BUF_DISPOSE <<
BUF_TOGGLE_SHIFT`` may also be used to ensure that these flags may be
turned on or off with `ggiBufSetGCFlags`.  Otherwise, you may be
restricted to only operating in the modes represented by their
presence`nonpresence.



`ggiBufCreateAlpha` allocates and creates a Alpha side-buffer suitable
for use with the buffer referenced by :p:`forthis`.  If :p:`forthis`
is ``NULL``, an Alpha buffer for the main framebuffer of :p:`vis` is
created.  The parameter :p:`stype` designates the type of storage
which the Alpha buffer is to use, for example, `GA_STORAGE_SWAP` will
get normal system memory, and `GA_STORAGE_VRAM` will get video board
memory.  `GA_STORAGE_DONTCARE` will pick the preferred storage type
for the visual automatically.  See the storage type definitions in the
LibGAlloc documentation for full a list of values and their meanings
for this field.


The parameter :p:`gt` chooses the bit depth of the buffer and
specifies whether the buffer contains greyscale or RGB data, as per a
normal LibGGI graphtype.  The parameter :p:`flags` can contain any
combination of the following flag values: `BUF_DISPOSE`, `BUF_PUTGET`,
`BUF_BLEND_ALT`, `BUF_BLEND_SRC_PREMULT`, `BUF_BLEND_DST_PREMULT`,
`BUF_BLEND_OVER` (`BUF_BLEND_SRC_OVER`), `BUF_BLEND_UNDER`
(`BUF_BLEND_DST_OVER`), `BUF_BLEND_SRC_IN`, `BUF_BLEND_DST_IN`,
`BUF_BLEND_SRC_OUT`, `BUF_BLEND_DST_OUT`, `BUF_BLEND_TOP`
(`BUF_BLEND_SRC_TOP`), `BUF_BLEND_BOTTOM` (`BUF_BLEND_DST_TOP`),
`BUF_BLEND_XOR`, `BUF_BLEND_PLUS`, `BUF_BLEND_POSTDIV`.  The meaning
of these flags is described in the documentation for
:man:`ggiBufSetGCFlags(3)`.


These flags, except for `BUF_BLEND_ALT`, `BUF_PUTGET`,
`BUF_BLEND_SRC_PREMULT` and `BUF_BLEND_DST_PREMULT`, may also be
shifted left by `BUF_TOGGLE_SHIFT` bits to ensure that they may be
turned on or off with `ggiBufSetGCFlags`, though certain combinations
of flags do ensure this implicitly where it makes sense.


Note that hardware acceleration for alpha side-buffers is rare, and
unless you want to use blends that are not usually found implemented
in hardware, what you probably really want is to negotiate an alpha
channel-buffer along with the video mode.  :man:`ggiBufCladVis(3)` 
will activate such channel-buffers implicitly.


.. note::

  This doesn't seem to exist anymore, but `ggiBufCreateBuffer` needs
  description

  `ggiBufCreateSwatch` allocates and creates a swatch buffer 
  suitable for use with the buffer referenced by :p:`forthis`.  
  A swatch is a dimensionless area full of pixels in the same pixel 
  format as the buffer it was created for.  If the parameter 
  :p:`forthis` is NULL, a Swatch buffer for the main framebuffer 
  of :p:`vis` is created.  The parameter :p:`stype` 
  designates the type of storage which the swatch buffer is to use, for 
  example, GA_STORAGE_SWAP will get normal system memory, and GA_STORAGE_VRAM 
  will get video board memory.    GA_STORAGE_DONTCARE will pick the preferred 
  storage type for the visual automatically.    See the storage type 
  definitions in the LibGAlloc documentation for full a list of values and 
  their meanings for this field.



Return Value
------------

For all three functions a `ggiBuf_t` object handle will be returned if
the buffer was successfully allocated and activated.  On error, ``NULL``
will be returned.


Examples
--------

Activate an emulated 8-bit Z buffer for the main framebuffer::

  zbuf = ggiBufCreateZ(vis, NULL, GA_STORAGE_SWAP, 
		       GT_CONSTRUCT(8, GT_GRAYSCALE, 8), GT_CMP_LTE);
  if(zbuf == NULL) {
        /* We cannot get a Z */
  }
  else {
        ggiCladVis(vis, 1, &amp;zbuf); /* Turn it on */
  }


See Also
--------

:man:`ggiBufClad(3)`, :man:`ggiBufCladVis(3)`


Add a request for an ancillary buffer to a LibGAlloc request list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufAdd

Synopsis
--------

::

  #include <ggi/buf.h>

  int ggiBufAdd(ggi_visual_t vis, 
	        ggiGA_resource_list *reqlist,
	        enum ggiGA_resource_type subtype,
	        struct ggiGA_resource_props *props,
	        enum ggiBuf_flags flags,
	        ggiGA_resource_handle tothis,
	        ggiGA_resource_handle *handle);


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


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

The parameter :p:`reqlist` refers to a LibGAlloc request list, and a
handle to the newly added request is returned in the parameter
:p:`handle`.

`ggiBufAdd` attaches a request for an ancilary buffer defined
by the properties in :p:`props`.  The parameter :p:`subtype`
designates the type of ancillary buffer desired.  See the LibGAlloc 
documentation for a list of buffer types and the meanings of the properties 
structure.  The parameter :p:`flags` is placed in the `.flags`
member of an auto-generated carb resource.  This function is provided 
for advanced users who are familiar with LibGAlloc.


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

`ggiBufAdd` returns `0` on success, or a negative value if an error
occurred.




Activate an ancillary buffer resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufTie ggiBufClad ggiBufCladVis

Synopsis
--------

::

  #include <ggi/buf.h>

  ggiBuf_t ggiBufTie(ggi_visual_t vis, ggiGA_resource_handle handle_tank,
		     int narg, void *args);

  int ggiBufClad(ggiBuf_t buf, int numbufs, ggiBuf_t *bufs, ggiBuf_t *res);

  int ggiBufCladVis(ggi_visual_t vis, int numbufs, ggiBuf_t *bufs);


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

`ggiBufTie` creates a ggiBuf_t object from an approved LibGAlloc
resource handle.  For normal use, :p:`narg` will be 0 and :p:`args`
will be NULL.  If the :p:`narg` parameter is not 0 and the :p:`args`
parameter is not NULL, the :p:`args` parameter should be passed a char
** pointer to a list of strings which are used as arguments to set up
additional resources not managed by LibBuf/LibGAlloc/LibGGI.  These
arguments may be specific to the visual, or to the type of resource,
or both.


The following pertains only to users performing their own memory
management: If the :p:`narg` parameter is not zero but the :p:`args`
parameter is NULL, the ggiBuf_t created will refer to the :p:`narg`'th
instance in a resource where the qty feild > 1.  If the converse (the
:p:`narg` parameter is zero but the :p:`args` parameter contains a
non-NULL value, then :p:`args` is assumed to point to a size_t
containing an offset at which the ggiBuf_t object should manage data.
In this case, on return that size_t will contain the offset that was
actually used, if different from that which was requested.


`ggiBufClad` will combine the :p:`nbuf` buffers who's handles are
stored in the array pointed to by the parameter :p:`bufs` into a
single *clad buffer*, returned in the parameter :p:`res`.  A clad
buffer is one which consists of a stack of layered buffers containing
different aspects of data with a common geometry, e.g. pixel data in
one layer, Z coordinates in another, and Alpha weights in a third.
Clad buffers may not be accessed via the methods documented in the
`ggiBufGetValue` manpage, nor may they be used as arguments to the
`ggiBufSetGCForeground`/`ggiBufGetGCForeground` functions.  Clad
buffers are mainly for internal use by other libraries (e.g. through
functions like ggiBuf2BltSource), but as they may have potential use
to experienced LibGGI programmers, they are provided as part of the
formal API.


`ggiBufCladVis` causes :p:`nbuf` ancillary buffers who's handles are
stored in the array pointed to by the parameter :p:`bufs` to be used
by the visual :p:`vis` to provide additional channels, e.g. alpha or
Z.  After a visual has been clad, any drawing operations performed on
the visual are subject to the effects of these ancilary buffers.  The
behavior of calling `ggiBufCladVis` on a visual which has already been
clad is currently undefined.


In addition, `ggiBufCladVis` also activates any special purpose
channels which aready exist in the visual's pixel format.  If it is
desired to access these channels using a ggiBuf_t object (which is
usually the case) then the caller may provide additional ``NULL``
values in the array :p:`bufs`, and ggiBuf_t objects will be created
and pointers to them will be returned therein.


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

`ggiBufTie` returns a newly allocated ggiBuf_t object, or ``NULL`` on
failure.  `ggiBufClad` and `ggiBufCladVis` return zero on success or a
negative value on failure.


Example
-------

Create a clad visual and draw one box under another::

  ggiGASet(vis, reqlist, &reslist);  /* get resources from LibGAlloc */
  res_z = ggiGAHandle(vis, reslist, reqlist, res_z); /* Get approved handle */
  zbuf = ggiBufTie(res_z, 0, NULL);
  ggiCladVis(vis, 1, &zbuf);
  ggiGCSetForeground(vis, white);
  ggiBufSetGCForeground(zbuf, 20);
  ggiDrawBox(vis, 40, 10, 50, 50);
  ggiGCSetForeground(vis, green);
  ggiBufSetGCForeground(zbuf, 200);
  ggiDrawBox(vis, 50, 20, 50, 50);



LibGGIBuf Access to GAlloc resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufGetMotorHandle ggiBufGetTankHandle ggiBufGetCarbHandle ggiBufClearMotorProperties ggiBufClearCarbProperties ggiBufClearTankProperties

Synopsis
--------

::

  #include <ggi/buf.h>

  ggiGA_resource_handle ggiBufGetMotorHandle(ggiBuf_t buf);

  ggiGA_resource_handle ggiBufGetTankHandle(ggiBuf_t buf);

  ggiGA_resource_handle ggiBufGetCarbHandle(ggiBuf_t buf);


  int ggiBufClearMotorProperties(struct ggiGA_resource_props *prop);
  
  int ggiBufClearCarbProperties(struct ggiGA_resource_props *prop);
  
  int ggiBufClearTankProperties(struct ggiGA_resource_props *prop);

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

TODO


Set or get the foreground, background default values and flags of a buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufSetGCForeground ggiBufSetGCBackground ggiBufSetGCFlags ggiBufGetGCForeground ggiBufGetGCBackground ggiBufGetGCFlags

Synopsis
--------

::

  #include <ggi/buf.h>

  int ggiBufSetGCForeground(ggiBuf_t buf, ggi_bufval val);

  int ggiBufSetGCBackground(ggiBuf_t buf, ggi_bufval val);

  int ggiBufSetGCFlags(ggiBuf_t buf, enum ggiBuf_flags flags);

  int ggiBufGetGCForeground(ggiBuf_t buf, ggi_bufval *val);

  int ggiBufGetGCBackground(ggiBuf_t buf, ggi_bufval *val);

  int ggiBufGetGCFlags(ggiBuf_t buf, enum ggiBuf_flags *flags);

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

`ggiBufSetGCForeground` and `ggiBufGetGCForeground` set and read,
respectively, the current value used as a default for the channel
(Alpha, Z, etc.) represented by the buffer buf when data is sent to a
compound buffer or clad visual to which buf belongs, when such data
has no corresponding channel.  This value applies to all pixels drawn
in the foreground color in two-color operations, or otherwise to all
pixels.


`ggiBufSetGCBackground` and `ggiBufGetGCBackground` set and read,
respectively, the current value used as a default when the buffer is
cleared with ggiBufClear.  This value is also used in the same way
that the foreground value is used when a two-color operation like text
drawing is performed, but applies only to pixels drawn in the
background color.


`ggiBufSetGCFlags` and `ggiBufGetGCFlags` set and read, respectively,
flags which define the default behavior of the buffer.


The following flag values are defined for both Alpha and Z buffers:


`BUF_DISPOSE`
    Designates that the resultant alpha or Z value is not to overwrite
    the destination alpha or Z value, and is instead thrown away.

`BUF_PUTGET`
    Designates that the channel is valid as both source and
    destination when a command is invoked which causes data from the
    buffer to be written back to itself at another position.  In other
    words, on a clad visual, when this flag is not set, the copybox
    operation will use the buffer's foreground value for the source
    value, whereas, when it is set, the values in the buffer at the
    source location will be used.  (This also works for crossblt, when
    the clad visual is used as the source visual.)  Note that this
    also affects LibGGI get/put operations when used on a clad visual
    that contains alpha or Z in-pixel channels, however, using it as
    such must only be done when it is known that the channels are
    in-pixel, because otherwise it has no affect on get/put
    operations.


The following flag values are defined for Z buffers:


`BUF_CMP_GT`, `BUF_CMP_LT`, `BUF_CMP_EQ`, `BUF_CMP_GTE`, `BUF_CMP_LTE`
    These flags determine the comparison type (greater than, less
    than, greater than or equal, and less than or equal, respectively)
    used when deciding which of two Z values is considered to be
    *over* the other.  `BUF_CMP_LTE` is the default comparison
    (assuming it is available), meaning that if the source Z value is
    less than or equal to the destination Z value, the pixel in
    question will be drawn.


The following flags are defined for Alpha buffers and determine the
type of blend performed:

`BUF_BLEND_OVER` or BUF_BLEND_SRC_OVER`
    Values are blended using the following rule expressed with normalized 
    Alpha values::
    
      D = As * S + (1 - As) * D * Ad;
      A = As + (1 - As) * Ad

`BUF_BLEND_UNDER` or `BUF_BLEND_DST_OVER`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = Ad * D + (1 - Ad) * S * As;
      A = Ad + (1 - Ad) * As

`BUF_BLEND_SRC_IN`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = As * S * Ad;
      A = As * Ad


`BUF_BLEND_DST_IN`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = Ad * D * As;
      A = Ad * As

`BUF_BLEND_SRC_OUT`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = As * S * (1 - Ad);
      A = As * (1 - Ad)

`BUF_BLEND_DST_OUT`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = Ad * D * (1 - As);
      A = Ad * (1 - As)

`BUF_BLEND_TOP` or `BUF_BLEND_SRC_TOP`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = As * S * Ad + (1 - As) * D * Ad;
      A = As * Ad + (1 - As) * Ad

`BUF_BLEND_BOTTOM` or `BUF_BLEND_DST_TOP`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = Ad * D * As + (1 - Ad) * S * As;
      A = Ad * As + (1 - Ad) * As

`BUF_BLEND_XOR`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = As * S * (1-Ad) + (1-As) * D * Ad;
      A = As * (1-Ad) + (1-As) * Ad

`BUF_BLEND_PLUS`
    Values are blended using the following rule expressed with normalized 
    Alpha values::

      D = As * S + Ad * D;
      A = As * Ad

`BUF_BLEND_ALT`
    This nifty feature allows you to choose a second blend to be used
    in when both alpha and Z are in use, which will be used when the Z
    value of the source is determined to be *behind* that of the
    destination.  To choose the second blend, shift any of the below
    BUF_BLEND* flags (with the exception of `BUF_BLEND_*_PREMULT`)
    left by `BUF_ALTBLEND_SHIFT` bits.  In order to use this feature,
    this flag must have been set on both the Z and the Alpha buffer
    when they were first created.  This flag should not be shifted by
    `BUF_ALTBLEND_SHIFT`, as it obviously applies to both blends.

`BUF_BLEND_SRC_PREMULT`
    Values in the source are premultiplied by their Alpha.  This flag
    should not be shifted by `BUF_ALTBLEND_SHIFT`, as it applies to both
    the primary and secondary blend.


`BUF_BLEND_DST_PREMULT`
    Values in the destination are premultiplied by their Alpha.  This
    flag should not be shifted by `BUF_ALTBLEND_SHIFT`, as it applies to
    both the primary and secondary blend.

`BUF_BLEND_POSTDIV`
    The values obtained from the above formulas are divided by the
    resultant Alpha. This is generally desired for OVER/UNDER/XOR/PLUS
    blends, and generally not desired for the IN/OUT blends.

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

All four functions `0` for OK or a negative value on failure.  In the
case of `ggiSetGCFlags`, failures usually mean that the display does
not support the desired blend or comparison.  You can avoid such
failures by insisting that the blend be available when the buffer is
created with `ggiBufAddAlpha`/`ggiBufCreateAlpha` or
`ggiBufAddZ`/`ggiBufCreateZ`.


Methods for raw access to buffer data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiBufClearBuffer ggiBufBuf2Mem ggiBufMem2Buf ggiBufBuf2Buf ggiBufConst2Buf ggiBufGetValue ggiBufPutValue

Synopsis
--------

::

  #include <ggi/buf.h>

  int ggiBufClearBuffer(ggiBuf_t buf);

  int ggiBufBuf2Mem(ggiBuf_t src, size_t xoffset, size_t yoffset, size_t stride,
                    void *membuf, size_t deststride,
                    size_t linewidth, size_t numlines);

  int ggiBufMem2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, size_t stride,
                    void *membuf, size_t srcstride,
                    size_t linewidth, size_t numlines);

  int ggiBufBuf2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, size_t stride,
                    ggiBuf_t src, size_t srcxoffset, size_t srcyoffset, 
		    size_t srcstride,
                    size_t linewidth, size_t numlines);

  int ggiBufConst2Buf(ggiBuf_t dest, size_t xoffset, size_t yoffset, 
		      size_t stride,
                      ggi_bufval val, size_t linewidth, size_t numlines);

  int ggiBufGetValue(ggiBuf_t buf, size_t xoffset, size_t yoffset,
                     size_t stride, ggi_bufval *val);

  int ggiBufPutValue(ggiBuf_t buf, size_t xoffset, size_t yoffset,
                     size_t stride, ggi_bufval val);


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


`ggiBufPutValue` and `ggiBufGetValue` set or retrieve a single value
from the data inside a buffer.  The value is taken from or stored in
the parameter named :p:`val`, respectively.

`ggiBufConst2Buf` fills data locations inside the buffer with the
constant value given in the parameter :p:`mem`.  `ggiBufClear` fills
the entire buffer with the default background value of the buffer.

`ggiBufMem2Buf` and `ggiBufBuf2Mem` set or retrieve values from the
data inside the buffer.  The values are taken from or stored to the
memory area pointed to by the parameter named :p:`membuf`.  After each
line of data is transferred, :p:`memstride` *bytes* are skipped in the
memory area.

`ggiBuf2Buf` moves values from one buffer to another.

In all functions, the parameter :p:`src`, if present, designates the
buffer from which to take data and the parameter :p:`dest`, if
present, designates the buffer into which to store data.

In all functions, the parameter :p:`stride` (and :p:`srcstride`, if
present) represent the number of values between two consecutive
*lines* of the buffer.  However, if the value 0 is given, the default
stride stored in the `ggiBuf_t` is used.

In all functions, the :p:`xoffset`, :p:`yoffset` parameters (and
:p:`srcxoffset`, :p:`srcyoffset`, if present) give the number of
values from the start of the buffer to skip before beginning to access
the data.  The first data item accessed is the value at offset
:p:`yoffset` * :p:`stride` + :p:`xoffset` (or :p:`srcyoffset` *
:p:`srcstride` + :p:`srcyoffset`).

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

The functions return zero or a positive value on success, or a
negative value on failure.  The positive value will contain bitflags:
``BUF_ACCESSFUNC_UNNEEDED``, designates that there is no special
access method or non-trivial data layout involved in accessing the
data inside the buffer, and as such the user may proceed to access the
contents of the buffer directly through the pointers provided in the
object as if it were normal system RAM, provided `ggiFlush` has been
called to clear any pending drawing functions which may also be
accessing the data.  The positive value ``BUF_ACCESSFUNC_NOFLUSH``
means that it is not necessary to call `ggiFlush` before accessing the
data.

Helper macros
-------------

The following macros can be used if the buffer is 1D::

  #define ggiBufBuf2Mem1D(src, offset, dest, linewidth)           \
           ggiBufBuf2Mem(src, offset, 0, 0, dest, 0, linewidth, 0);

  #define ggiBufMem2Buf1D(dest, offset, membuf, linewidth)        \
          ggiBufMem2Buf(dest, offset, 0, 0, membuf, 0, linewidth, 0);

  #define ggiBufBuf2Buf1D(dest, offset, src, srcoffset, srcstride, linewidth)  \
	  ggiBufBuf2Buf(dest, offset, 0, 0, src, srcoffset, 0,    \
			0, srcstride, linewidth, 0);

  #define ggiBufConst2Buf1D(dest, offset, val, linewidth)         \
          ggiBufConst2Buf(dest, offset, 0, 0, val, linewidth, 0);

  #define ggiBufGetValue1D(buf, offset, val)      \
          ggiBufGetValue(buf, offset, 0, 0, val);

  #define ggiBufPutValue1D(buf, offset, val)      \
          ggiBufPutValue(buf, offset, 0, 0, val);
