Allocate and activate an auxillary buffer resource on the fly

Name

ggiBufCreateBuffer, ggiBufCreateZ, ggiBufCreateAlpha : Allocate and activate an auxillary buffer resource on the fly

Synopsis

#include <ggi/buf.h>

ggiBuf_t ggiBufCreateBuffer(ggi_visual_t vis, 
                            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,
                       ggiGA_storage_type stype,
                       ggi_graphtype gt, enum ggiBuf_flags flags);

ggiBuf_t ggiBufCreateAlpha(ggi_visual_t vis, ggiBuf_t forthis,
                           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 forthis. If forthis is 'NULL', a Z buffer for the main framebuffer of vis is created. The parameter 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 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 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 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(3). 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 forthis. If forthis is 'NULL', an Alpha buffer for the main framebuffer of vis is created. The parameter 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 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(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(3), 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. 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 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 forthis is NULL, a Swatch buffer for the main framebuffer of vis is created. The parameter 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