Access an overlay as a LibGGI visual; load data into an overlay
Name
ggiOvl2Vis, ggiOvlLoadVis : Access an overlay as a LibGGI visual; load data into an overlay
Synopsis
#include <ggi/ovl.h> ggi_visual_t ggiOvl2Vis(ggiOvl_t ovl); int ggiOvlLoadVis(ggiOvl_t ovl, int x, int y, int w, int h);
Description
ggiOvl2Vis creates a LibGGI visual handle which may be used to draw in the object using basic LibGGI primitives, to manipulate the overlay's color pallette if it has one, gain directbuffer access to the overlay's data if such access is allowed, and many other fun and/or abusive things.
The created visual is not automatically attached to any of the extension libraries of the parent visual. There may be restrictions on which extensions it may be attached to. These restrictions will be fully enumerated in the ggiClone function which will be added to LibGGI during it's 3.0 release cycle.
Caveat: not all overlays were meant to be used as visuals. Depending on the nature of the overlay, and how useful/practical converting it to a visual is, you may find that the resulting visual performs slowly, or that certain LibGGI primitives fail with an error code, or even that ggiOvl2Vis fails entirely in the first place. Consider using the more lightweight function ggiOvl2Buf(3).
In a similar manner to ggiOpen(3), arguments to the back-end target may be passed via additional parameters.
The function ggiOvlLoadVis is a rudimentary function for loading an image into an overlay from an area of the visual to which the overlay belongs. Only normal color data (not alpha/Z data) may be loaded in this fashion, and no interpolation or scaling is done. This function is not guaranteed to be particularly fast, but will process color space conversion as appropriate, and will be more universally available than ggiOvl2Vis or ggiOvl2Buf(3). The parameters x,:p:y and w, h represent coordinates in pixels of a rectangle in the visual from which to load the data.
Return value
ggiOvl2Vis returns a ggi_visual_t handle, or NULL if an error occured. ggiOvlLoadVis returns 0 (GGI_OK) on success or a negative error code on failure.