Allocate and activate a blit on-the-fly
Name
ggiBltCreate, ggiBltDestroy : Allocate and activate a blit on-the-fly
Synopsis
#include <ggi/blt.h> ggiBlt_t ggiBltCreate(ggi_visual_t vis, ggiGA_storage_type stype, int numrows, enum ggi_ll_rop rop, enum ggiBlt_flags flags); int ggiBltDestroy(ggiBlt_t *blt);
Description
ggiBltCreate allocates and creates a blit. LibGGIBlt's definition, of a blit is a set of operations that can be prepared, stored, and then set in motion later -- ggiBltCreate does not create a data buffer to contain pixel data which will be used during these operations. For that, see ggiBltCreateBob(3). Think of a blit instead as a sort of display list, or if you are unfamiliar with that term, a virtual command FIFO : LibGGIBlt stores precompiled data and instructions representing blitting operations in a ggiBlt_t.
The parameter stype designates the type of storage which the blit will use to store precompiled operations, for example, 'GA_STORAGE_SWAP' will get normal system memory, and 'GA_STORAGE_TRANSFER | GA_STORAGE_RAM' will get AGP RAM, DMA-capable RAM, or an otherwise shared application/target-driver area, and thus will transfer the commands it contains to the target in the most efficient manner possible. 'GA_STORAGE_DONTCARE' will pick the most preferred available storage type for the blit. See the storage type definitions in the LibGAlloc documentation for a full list of values and their meanings for this field.
The parameter numrows determines how many operations can be stored in the blit. These operations may be loaded with the various ggiBltPut* functions, and may be dispatched to the target via the ggiBltGo(3) function.
The parameter rop demands that a certain set of raster operations be supported by the blit (this term rop is used loosely in LibGGIBlt to cover various operations like color keying and alpha blends in addition to traditional boolean raster operations.) See the LibGAlloc documentation for a full list of values and their meanings for this field.
The parameter flags determines some behavioral charactersistics of the blit when operations or graphics context are altered. It may contain any of the following flags:
- 'BLT_FLAGS_STICKY_CLIP'
The current value of the clipping rectangle is stored in the precompiled command, and when sent to target, the results will be clipped with the values which were in effect when the command was loaded into the blit. Otherwise, the clip values used are those currently in effect on the visual when the command is sent to the target.
- 'BLT_FLAGS_STICKY_FGBG'
The current value of the foreground and background drawing colors are stored in the precompiled command, and when sent to target, any monochrome/bichrome drawing operations will be rendered with the values which were in effect when the command was loaded into the blit. Otherwise, the colors used are those currently in effect on the visual when the command is sent to the target.
- 'BLT_FLAGS_STICKY_BLEND'
The current chosen default alpha blending formula (or nonpresence thereof) is stored in the precompiled command, and when sent to target, any alpha operations will use the blending formula which was in effect when the command was loaded into the blit. Otherwise, the blend used is that currently in effect on the visual when the command is sent to the target, even if the given visual was clad (using LibGGIBuf's ggiBufCladVis(3)) after creation of the blit.
The function ggiBltDestroy releases all resources related to the given blit and sets the proferred pointer to 'NULL'.
Return value
ggiBltCreate will return a ggiBlt_t object handle if the blit was successfully allocated and activated, or on error, NULL.
ggiBltDestroy returns 0 (GGI_OK) on success, or a negative error code on failure.
Examples
Create a 50-operation blit with a few boolean rops available:
blt = ggiBltCreate(vis, GA_STORAGE_SWAP, ROP_NOR | ROP_XOR | ROP_AND, 0, 0); if (blt == NULL) { /* We cannot get this blt */ }