Allocate and activate a blit source on-the-fly
Name
ggiBltCreateBob, ggiBltReuseBob, ggiBltDestroyBob : Allocate and activate a blit source on-the-fly
Synopsis
#include <ggi/blt.h> ggiBlt_source_t ggiBltCreateBob(ggi_visual_t vis, ggiBlt_t forthis, ggiGA_storage_type stype, int w, int h, int qty, ggi_graphtype gt); int ggiReuseBob(ggiBlt_source_t bob, ggiBlt_t forthis); int ggiBltDestroyBob(ggiBlt_source_t *blt);
Description
ggiBltCreateBob allocates and creates a pixel data buffer, also known as a BOB, for use as a source in blitting operations. The parameter forthis designates a blit for which the BOB is to be created.
The parameter stype designates the type of storage which the blit will use to store the pixel data, 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 data it contains to the target in the most efficient manner possible. 'GA_STORAGE_DONTCARE' will pick the most preferred available storage type for the pixel data. See the storage type definitions in the LibGAlloc documentation for a full list of values and their meanings for this field.
The parameters w and h specify the width and height in pixels of the BOB data. The parameter qty, if set > 1, requests multiple identical data areas be created, which can then be selected via the function ggiBltSetSourceIdx(3), and thus managed by the same ggiBlt_source_t object. The parameter gt chooses the bit-depth and color scheme of the BOB as per a normal ggi_graphtype.
ggiBltReUseBob checks to see if a BOB may be used with a blit for which it was not originally created. The parameter forthis designates an additional blit for which the BOB should be approved for use.
ggiBltDestroyBob releases all resources related to the given BOB and sets the proferred handle to 'NULL'.
Return value
ggiBltCreateBob will return a ggiBlt_source_t if the blit was successfully allocated and activated, with the src1 pointer inside the object set to point to a private LibGGIBlt data structure which must not be altered. On error, NULL will be returned.
ggiBltReuseBob will return 0 (GGI_OK) if the specified BOB is usable with the specified blit, or a negative error code on failure.
ggiBltDestroyBob returns 0 (GGI_OK) on success, or a negative error code on failure.
Examples
Create a 50x50 16bpp BOB for one blit and reuse it with a second blit:
bob = ggiBltCreateBob(vis, blt1, GA_STORAGE_DONTCARE, 50, 50, 1, GT_16BIT); if (ggiReuseBob(bob, blt2)) { /* This BOB is incompatible with blt2 */ }