Set the display priority of an overlay within its group
Name
ggiOvlHide, ggiOvlIsHidden, ggiOvlShow, ggiOvlSetPriority, ggiOvlGetPriority : Set the display priority of an overlay within its group
Synopsis
#include <ggi/ovl.h> int ggiOvlHide(ggiOvl_t ovl); int ggiOvlIsHidden(ggiOvl_t ovl); int ggiOvlShow(ggiOvl_t ovl); int ggiOvlSetPriority(ggiOvl_t ovl, uint32_t slot, int swap); int ggiOvlGetPriority(ggiOvl_t ovl, uint32_t *slot);
Description
ggiOvlHide turns off display of a graphics overlay so it cannot be seen. ggiOvlShow will cause the overlay to be turned on such that, as long as it is not obscured by another overlay or positioned, sized, colored, or filtered in such a way that makes it effectively invisible, it will be visible to the user. ggiOvlIsHidden returns a positive value if an overlay has the potential to be seen, or a value of zero if the overlay has been turned off with ggiOvlHide. That is to say, ggiOvlIsHidden will not return a positive value if the overlay has been activated with ggiOvlShow but is obscured by another overlay, or is for some other reason not visible to the user.
ggiOvlSetPriority and ggiOvlGetPriority sets or gets the priority slot of an overlay which is a member of a group, e.g. a sprite engine. An overlay in a higher priority slot will appear to be in front of overlays in lower priority slots. Overlays with negative priorities are hidden from view. The parameter swap, if set to 1, will cause the overlay which currently occupies that priority slot to exchange priorities with the overlay ovl, or if swap is set to 0, if there is an overlay currently residing in the requested slot, it will be moved to a slot with a negative number thus causing it to be hidden. Values other than one or zero for the parameter swap are reserved for future use.
For ggiOvlSetPriority, the special slot value of 'OVL_SLOT_FIND' will look for an unoccupied slot in the priority group, starting at the highest priority, and if found, will put ovl in that slot. Otherwise, the ovl will be left in its current slot and ggiOvlSetPriority fails.
Return value
Except for ggiOvlIsHidden, the return value for which is described above, all functions return zero on success or a negative value on failure.