ggiBltCreate, ggiBltDestroy : Allocate and activate a blit on-the-fly
#include <ggi/blt.h> ggiBlt_t ggiBltCreate(ggi_visual_t vis, enum ggiGA_storage_type stype, int numrows, enum ggi_ll_rop rop, enum ggiBlt_flags flags); int ggiBltDestroy(ggiBlt_t *blt);
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. 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 :p:`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 :p:`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 function.
The parameter :p:`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 feild.
The parameter :p:`flags` determines some behavioral charactersistics of the blit when operations or graphics context are altered. It may contain any of the following flags:
The function ggiBltDestroy releases all resources related to the given blit and sets the proferred pointer to NULL.
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.
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 */ }