Send and retrieve a LibGAlloc request list to/from a visual

Name

ggiGAGet, ggiGACheck, ggiGASet, ggiGAHandle : Send and retrieve a LibGAlloc request list to/from a visual

Synopsis

#include <ggi/galloc.h>

int ggiGACheck(ggi_visual_t vis, ggiGA_resource_list request,
               ggiGA_resource_list *result);

int ggiGASet(ggi_visual_t vis, ggiGA_resource_list request,
             ggiGA_resource_list *result);

#define ggiGAGet(vis, result) ggiGACheck(vis, NULL, result);

ggiGA_resource_handle ggiGAHandle(ggiGA_resource_list reslist,
                                  ggiGA_resource_list reqlist,
                                  ggiGA_resource_handle reqhandle);

Description

These functions allow a LibGAlloc request list to be gotten, verified, and actuated. The first three functions take the visual being manipulated as the first argument vis.

ggiGACheck will ask the visual if it can support all the resources listed in request. If not 'NULL', result will be pointed to a new list filled with descriptions of the resources and whether they can or cannot be allocated. If result was already pointing at a list (make sure to initialize it!) that list will be gracefully emptied. As a special case, if result points to request, the results will be placed into the given list without changing any handle values in the list.

In ggiGACheck's result list, properties of the resources may have been adjusted according to LibGAlloc's rules for request list processing and automatic sizing: in a successful resource, only 'GGI_AUTO's and values in resources with caps will have been adjusted. In a failed resource, other values are adjusted. However, the properties of resources that have been flagged immutable will not be altered.

In the event that the list contains a resource request which cannot be honored, that resource is marked as a failure and any resources after it (excepting their own cap, if they have one) may or may not have been checked, and their properties are not altered. However, you are guaranteed even in the presence of a failure that a list consisting of all the requests before the first failure in the list would succeed if passed to ggiGASet. (As long as there is at least one successful 'GA_RT_FRAME' resource in the list, and provided nothing is done to alter the visual in the meantime.)

ggiGASet will ggiGACheck a list, and, if there are no failures, it will allocate resources for any requests in the list. It will not initialize any of these resources, except for those directly relevant to the core LibGGI API (the main video mode and accelerator resources for the basic set of LibGGI drawing operations). Look to extensions supporting the given resource type to provide initialization and activation API functions for the given resource once it has been allocated, LibGAlloc does not do that.

In the event of a failure when it calls ggiGACheck, the returned results of ggiGASet differ subtly from those that would be returned by calling ggiGACheck directly. Mainly, ggiGASet does not honor immutable resources, and the resulting resources will no longer be marked as immutable and the properties therein may have been altered.

ggiGAGet will get a copy of the last request list successfully set. The list passed back will be identical to the one which would have been returned in the result parameter from the last successful call to ggiGASet.

As long as no modifications are made to either the request list or the result after a call to ggiGACheck or ggiGASet, or between a call to ggiSetMode(3) and ggiGAGet, a handle to a resource in result corresponding to a handle to the same resource in request may be obtained from result list using ggiGAHandle.

Return value

ggiGACheck returns GALLOC_OK (== 0) for success. GGI_ENOMEM may be returned if the system is out of memory, the return value GALLOC_ESPECIFY indicates that one of the requests failed due to incomplete information or there was no GA_RT_FRAME request in the list.

ggiGASet returns GALLOC_OK (== 0) for success. It should never fail except for running out of memory, in which case it returns GGI_ENOMEM. If it is passed a list that would not successfully verify with ggiGACheck, ggiGASet behaves exactly like ggiGACheck would with the exception of the handling of immutable resources.

ggiGAGet returns GALLOC_OK (== 0) for success or an error code on failure.

ggiGAHandle returns NULL if it could not find handle in reqlist matching handle, or if it could not find a resource corresponding to handle in reslist, or if fed any invalid parameters.

Examples

ggiGAGet/ggiGACheck/ggiGASet Example:

ggi_visual_t vis;
ggiGA_resource_list request, result;
ggiGA_resource_handle reqmode, resmode;
ggiInit();
vis = ggiOpen(NULL);
ggiGAAttach(vis);
ggiSetSimpleMode(vis, 640, 480, 640, 480, NULL);

/* Other features may be allocated */

ggiGAGet(vis, &request);
ggiGAAddSimpleMode(vis, &request, 640, 480, 
                   GGI_AUTO, GGI_AUTO, &reqmode);
if (ggiGACheck(vis, request, &result)) {
      print("Unknown error in check for more virt\n");
      autopsy(result);
}
else if (ggiGASet(vis, request, &result)) {
      print("Unexpected failure to allocate more virt\n");
      autopsy(result);
}
resmode = ggiGAHandle(reslist, reqlist, reqmode);
fprintf(stderr, "Requested mode was:");
ggiFPrintMode(stderr, ggiGAGetggiMode(reqmode));
fprintf(stderr, "\nResulting mode was:");
ggiFPrintMode(stderr, ggiGAGetggiMode(resmode));
fprintf(stderr, "\n");
ggiGADetach(vis);
ggiGAExit();
ggiExit();