[ prev :: next :: up ] libggiovl-current (3)

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,
              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,
                    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 :p:`handle` returns a handle to the newly added request.

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 291); backlink

Unknown interpreted text role "p".

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 :p:`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 parameter :p:`type`. The last four parameters are used to return handles to the resulting resources as they appear in the resource list reqlist.

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 296); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 296); backlink

Unknown interpreted text role "p".

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 :p:`handle_carb` refers to a carb resource in the list, for example, one returned in the :p:`handle_carb` parameter to ggiOvlAdd, and is used to find the group to which the new resource is to be joined. The :p:`prop_tank` and :p:`prop_tank_cap` parameters work as decribed for ggiOvlAdd.

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 309); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 309); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 309); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 309); backlink

Unknown interpreted text role "p".

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

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 319); backlink

Unknown interpreted text role "p".

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

:man:`ggiOvlCreate(3)`, :man:`ggiOvlAdd(3)`

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 355); backlink

Unknown interpreted text role "man".

System Message: ERROR/3 (../lowlevel/libovl/doc/libggiovl.txt, line 355); backlink

Unknown interpreted text role "man".
 
[ prev :: next :: up ] libggiovl-current (3)
2006/11/09 16:51:07