ggiBufTie, ggiBufClad, ggiBufCladVis : Activate an ancillary buffer resource
#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);
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.
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.
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);