Activate an ancillary buffer resource

Name

ggiBufTie, ggiBufClad, ggiBufCladVis : Activate an ancillary buffer resource

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, narg will be 0 and args will be NULL. If the narg parameter is not 0 and the args parameter is not NULL, the 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 narg parameter is not zero but the args parameter is NULL, the ggiBuf_t created will refer to the narg'th instance in a resource where the qty field > 1. If the converse (the narg parameter is zero but the args parameter contains a non-NULL value, then 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 nbuf buffers who's handles are stored in the array pointed to by the parameter bufs into a single clad buffer, returned in the parameter 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(3) manpage, nor may they be used as arguments to the ggiBufSetGCForeground(3)/ggiBufGetGCForeground(3) 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 nbuf ancillary buffers who's handles are stored in the array pointed to by the parameter bufs to be used by the visual 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 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);