Extension management

Name

ggiOvlInit, ggiOvlExit, ggiOvlAttach, ggiOvlDetach : Extension management

Synopsis

#include <ggi/ovl.h>

int ggiOvlInit(void);

int ggiOvlExit(void);

int ggiOvlAttach(ggi_visual_t vis, ggiGA_resource_list *reqlist);

int ggiOvlDetach(ggi_visual_t vis);

Description

ggiOvlInit initializes the library. This function must be called before using other LibOvl functions; otherwise the results will be undefined.

ggiOvlExit uninitializes the library (after being initialized by ggiOvlInit) and automatically cleans up if necessary. This should be called after an application has finished using the library. If any LibOvl functions are called after the library has been uninitialized, the results will be undefined.

ggiOvlInit allows multiple invocations. A reference count is maintained, and to completely uninitialize the library, ggiOvlExit must be called as many times as ggiOvlInit has been called beforehand.

ggiOvlAttach extends a visual such that the LibOvl API may be used on the visual handle. This function must be called before using other LibOvl functions on the visual handle. The parameter reslist is a pointer to a LibGAlloc resource list kept by the application, and such an object must exist and be passed here in order to use the simple-form ggiOvlCreate* functions.

Note that not all LibGGI visuals support LibOvl, so checking the return code of ggiOvlAttach is important.

ggiOvlDetach cleans up all state associated with using the LibOvl API on this visual. The visual is stripped of any active LibOvl objects. Note, however, that the objects themselves are not currently guaranteed to be destroyed and may still exist, consuming resources. Behavior of these objects is at this point undefined. They should be destroyed before calling ggiOvlDetach.

Return value

ggiOvlInit, ggiOvlAttach and ggiOvlDetach return 0 for OK, otherwise an error code.

ggiOvlExit returns:

0

after successfully cleaning up,

>0

the number of 'open' ggiOvlInit calls, if there has been more than one call to ggiOvlInit. As ggiOvlInit and ggiOvlExit must be used in properly nested pairs, e.g. the first ggiOvlExit after two ggiOvlInits will return 1.

<0

error, especially if more ggiOvlExit calls have been done than ggiOvlInit calls.

Example

Activate LibOvl such that the ggiOvlCreate* functions work:

 ggiGA_resource_list reslist;

 reslist = NULL;
 if (!ggiOvlInit()) { 
     exit(EXIT_FAILURE);  /* can't start! */
 }
if (!ggiOvlAttach(vis, &reslist)) {
     ggiOvlExit();
     exit(EXIT_FAILURE);  /* can't attach OVL! */
}

 /* Do some libovl stuff */

 ggiOvlDetach(vis);
 ggiOvlExit();