#include <ggi/ovl.h>
ggiOvl_t ggiOvlCreateSprite
(ggi_visual_t vis
int width
int height
ggiGA_resource_type subtype
enum ggiOvlFlags flags);
ggiOvl_t ggiOvlCreateVideo
(ggi_visual_t vis
int width
int height
ggiGA_resource_type subtype
enum ggiOvlFlags flags);
ggiOvl_t ggiOvlCreate
(ggi_visual_t vis
struct ggiGA_resource_props *prop_motor
struct ggiGA_resource_props *prop_carb
struct ggiGA_resource_props *prop_tank
ggiGA_resource_type type);
ggiOvl_t ggiOvlCreateInGroup
(ggi_visual_t vis
ggiOvl_tgrop_leader
struct ggiGA_resource_props *prop_tank);
ggiOvlCreateSprite allocates and creates a Sprite object for use on the given visual. The parameter subtype allows choosing a particular type of sprite: GA_RT_SPRITE_POINTER will find hardware mouse cursors, GA_RT_SPRITE_CURSOR will find hardware text cursors, and GA_RT_SPRITE_SPRITE will find a true sprite, if one exists, before trying one of the former two resources. The value zero, or the value GA_RT_SPRITE_DONTCARE, will get any sprite available regardless of it's type. For resources of subtype GA_RT_SPRITE_POINTER, the flag value OVL_FLAGS_AUTOTRACK designate that the target has the ability to automatically move the mouse cursor based on user input, transparent the LibGII input handler. Some targets, in fact, must always do so, and in those cases ggiOvlCreateSprite will fail unless the flag value OVL_FLAGS_AUTOTRACK is set.
ggiOvlCreateVideo allocates and creates a video overlay area for use on the given visual. The video overlay may or may not require the use of video card RAM, depending on the display subsystem. The parameter subtype allows choosing a particular type of video overlay. Currently there is only one type implemented, GA_RT_VIDEO_MOTION. The value zero, or the value GA_RT_VIDEO_DONTCARE will get any video overlay available regardless of its type, which is of dubious usefulness since video overlay windows vary widely in their application.
ggiOvlCreateWindow allocates and creates a viewport or other area which provides hardware translation of pixel format or pixel layout. The parameter subtype allows choosing a particular type of window: GA_RT_WINDOW_YUV will find overlays which allow you to store pixels in a certain screen area in untranslated YUV colorspace, yet still display them normally to the user; GA_RT_WINDOW_MMU will create a memory translation overlay, which allows you to access a sub-area of the framebuffer as if it were its own framebuffer, with memory layout translated by the display subsystem (think of this as a directbuffer for display-sub.) The value zero, or the value GA_RT_WINDOW_DONTCARE, will get any overlay window available regardless of its type, which is of dubious usefulness since overlay windows vary widely in their application.
In the above three functions, the width and height parameters request a minimum visual size of the object. This size is given in the current default units, see ggiOvlSetCoordBase.
ggiOvlCreate and ggiOvlCreateInGroup are provided for advanced users. The three parameters props_motor, props_carb, and props_tank represent LibGAlloc properties structures, and are documented in the LibGAlloc documentation. The parameter type selects the type of the resource. ggiOvlCreateInGroup allows the creation of new members of groups of resources that share something, e.g. a set of sprites which share a priority engine. The parameter group_leader can actually be any ggiOvl_t which is also in that group.
For all five functions a ggiOvl_t object handle will be returned if the overlay was successfully allocated and activated. On error, NULL will be returned.
Example 1. Activate a mouse cursor.
cursor = ggiOvlCreateSprite(vis, 64, 64, GA_RT_SPRITE_POINTER, OVL_FLAGS_AUTOTRACK); if(cursor == NULL) { cursor = ggiOvlCreateSprite(vis, 64, 64, GA_RT_SPRITE_POINTER, 0); if (cursor == NULL) autotrack = 0; else { /* Cannot get a mouse cursor. */ } } else { autotrack = 1; }