Allocate and activate a video overlay resource on the fly

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 ggiOvl_flags flags);

ggiOvl_t ggiOvlCreateWindow(ggi_visual_t vis,
                            int width, int height,
                            ggiGA_resource_type subtype,
                            enum ggiOvl_flags flags);

ggiOvl_t ggiOvlCreateVideo(ggi_visual_t vis,
                           int width, int height,
                           ggiGA_resource_type subtype,
                           enum ggiOvl_flags 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_t group_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, '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' designates that the target has the ability to automatically move the mouse cursor based on user input, transparently for 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. If it does, the RAM is set aside for use by this resource. 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 utility 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 pixels. If sub-pixel accuracy is desired at creation time, you should use ggiOvlCreate.

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

Activate a mouse cursor:

mouseptr = ggiOvlCreateSprite(vis, 64, 64, 
                              GA_RT_SPRITE_POINTER, OVL_FLAGS_AUTOTRACK);
if(mouseptr == NULL) {
      autotrack = 0;
      mouseptr = ggiOvlCreateSprite(vis, 64, 64, GA_RT_SPRITE_POINTER, 0);
      if (mouseptr == NULL) {
              /* Cannot get a mouse cursor. */
      }
}
else {
      autotrack = 1;
}