ggiOvlAdd

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 enum 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 enum ggiGA_resource_type type 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. Currently support for these functions is sporadic; it will be completed in a later stage of LibOvl's development.

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. 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_AUTOs 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 paremeter type. The last four parameters are used to return handles to the resulting resources as they appear in the list.

ggiOvlAdd2Group is used to add a request for a graphics overlay resource based on a previously added resource. 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

Example 1. 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