Add a request for a graphics overlay to a LibGAlloc request list

Name

ggiOvlAdd, ggiOvlAdd2Group : Add a request for a graphics overlay to a LibGAlloc request list

Synopsis

#include <ggi/ovl.h>

int ggiOvlAdd(ggiGA_resource_list *reqlist,
              struct ggiGA_resource_props *prop_motor,
              struct ggiGA_resource_props *prop_carb,
              struct ggiGA_resource_props *prop_tank,
              struct ggiGA_resource_props *prop_tank_cap,
              ggiGA_resource_type type,
              ggiGA_resource_handle *handle_motor,
              ggiGA_resource_handle *handle_carb,
              ggiGA_resource_handle *handle_tank,
              ggiGA_resource_handle *handle_tank_cap);

int ggiOvlAdd2Group(ggiGA_resource_list *reqlist,
                    struct ggiGA_resource_props *prop_tank,
                    struct ggiGA_resource_props *prop_tank_cap,
                    ggiGA_resource_handle handle_carb,
                    ggiGA_resource_handle *handle_tank,
                    ggiGA_resource_handle *handle_tank_cap);

Description

The ggiOvlAdd functions are LibOvl's interface to LibGAlloc. In both functions, the parameter reqlist refers to a LibGAlloc request list, and the parameter handle returns a handle to the newly added request.

ggiOvlAdd supplies a more convenient way to attach a request for a graphics overlay than doing so by hand with LibGAlloc functions. The parameters prop_motor and prop_tank are used to create a motor and tank resource, respectively, for the overlay. The parameter prop_tank_cap, if not 'NULL', creates a cap resource for the added tank, to prevent any 'GGI_AUTO's contained therein from absorbing excessive graphics resources. The parameter prop_carb creates a carb resource which is then attached as appropriate to the motor and to the tank, thus fully defining the resource. All resources are added with the resource type given in the parameter type. The last four parameters are used to return handles to the resulting resources as they appear in the resource list reqlist.

ggiOvlAdd2Group is used to add a request for a graphics overlay resource based on a previously added resource. This is most commonly used to allocate Z or alpha buffers for overlays which keep this data in a separate area. The parameter handle_carb refers to a carb resource in the list, for example, one returned in the handle_carb parameter to ggiOvlAdd, and is used to find the group to which the new resource is to be joined. The prop_tank and prop_tank_cap parameters work as decribed for ggiOvlAdd.

In comparing these functions to the ggiOvlCreate* function group, it is useful to note that the flags parameter of the ggiOvlCreate* functions simply alters the member .flags in the motor properties.

Return value

Both functions return 0 on success, or a negative value if an error occurred.

Examples

Add a request for two sprites in the same sprite engine:

ggiGA_resource_list reqlist = NULL;
struct ggiGA_resource_properties pm, pc, pt;
ggiGA_resource_handle m, c, t1, t2;

ggiOvlClearMotorProperties(&pm);
ggiOvlClearCarbProperties(&pc);
ggiOvlClearTankProperties(&pt);

pt.size.area.x = pt.size.area.y = 64;

ggiOvlAdd(vis, reqlist, 
        &pm, &pc, &pt, NULL, GA_RT_SPRITE_SPRITE, 
        &m,  &c,  &t1, NULL);
ggiOvlAdd2Group(vis, reqlist, &pt, NULL, c, &t2, NULL);

See Also