ggiOvlCreate

Name

ggiOvlCreateSprite, ggiOvlCreateWindow, ggiOvlCreateVideo, ggiOvlCreate, ggiOvlCreateInGroup -- Allocate and activate a video overlay resource on the fly.

Synopsis

#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);

Description

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.

Return value

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.

Examples

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;
}

See Also

ggiOvlAdd(3ggi),