ggiBufAdd

Name

ggiBufAdd, ggiBufAddZ, ggiBufAddAlpha, ggiBufAddSwatch -- Add a request for an ancillary buffer to a LibGAlloc request list.

Synopsis

#include <ggi/buf.h>

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

int ggiBufAddZ(ggi_visual_t vis, ggiGA_resource_list *reqlist, enum ggiGA_storage_type sneed, ggi_graphtype gt, enum ggiBuf_flags flags, ggiGA_resource_handle tothis, ggiGA_resource_handle *handle);

int ggiBufAddAlpha(ggi_visual_t vis, ggiGA_resource_list *reqlist, enum ggiGA_storage_type sneed, ggi_graphtype gt, enum ggiBuf_flags flags, ggiGA_resource_handle tothis, ggiGA_resource_handle *handle);

int ggiBufAddSwatch(ggi_visual_t vis, ggiGA_resource_list *reqlist, enum ggiGA_storage_type sneed, size_t numpixels, ggiGA_resource_handle tothis, ggiGA_resource_handle *handle);

Description

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

In all three functions, the parameter reqlist refers to a LibGAlloc request list, and a handle to the newly added request is returned in the parameter handle.

ggiBufAdd attaches a request for an ancilarry buffer defined by the properties in props. The parameter 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 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.

ggiBufAddZ attaches a request for a Z buffer suitable for use with the resource referenced by tothis. The parameter sneed designates the type of storage which the Z buffer is to use; see the storage type definitions in the LibGAlloc documentation for full a list of values and their meanings for this field.

The parameter 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 flags can contain 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 ggiBufSetGCFlags. The value BUF_DISPOSE << BUF_TOGGLE_SHIFT may also be used to ensure that this flags may be turned on or off with ggiBufSetGCFlags. Otherwise, the returned resource may be restricted to only operating in the modes represented by their presence/nonpresence.

ggiBufAddAlpha attaches a request for an Alpha side-buffer suitable for use with the resource referenced by tothis. The parameter sneed designates the type of storage which the Z buffer is to use; see the storage type definitions in the LibGAlloc documentation for full a list of values and their meanings for this field.

The parameter 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 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 ggiBufSetGCFlags. 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 what you probably really want is to negotiate an alpha channel-buffer along with the video mode. ggiBufCladVis will activate such channel-buffers implicitly.

ggiBufAddSwatch attaches a request for a swatch buffer suitable for use with the resource referenced by tothis. A swatch is a dimensionless area full of pixels in the same pixel format as the buffer it was created for; the numpixels parameter specifies how many pixels are needed. The parameter sneed designates the type of storage which the Z buffer is to use; see the storage type definitions in the LibGAlloc documentation for full a list of values and their meanings for this field.

Return value

All four functions return 0 on success, or a negative value if an error occurred.

Examples

Example 1. Add a request for a mode with a Z buffer

ggiGA_resource_list reqlist = NULL;
ggiGA_resource_handle mode_h, z_h;

ggiGAAddSimpleMode(vis, reqlist, 640, 480, 1, GT_AUTO, &mode_h);
ggiBufAddZ(vis, reqlist, GA_STORAGE_SWAP, 8, 0, mode_h, &z_h);

See Also

, ggiBufCreateZ(3ggi)