Resource lists

Name

ggiGA_resource_list, ggiGA_resource_handle : Resource lists

Synopsis

#include <ggi/galloc.h>

typedef struct ggiGA_resource *ggiGA_resource_list;

typedef struct ggiGA_resource *ggiGA_resource_handle;

Description

LibGAlloc is more a "protocol" than anything else. If that is the case, then the resource, LibGAlloc's fundamental unit, is the packet header. All of LibGAlloc's internal operations use linked lists of resources which are handled with the opaque types ggiGA_resource_list and ggiGA_resource_handle. The types are opaque because inside is linked list control structure, and some other LibGAlloc accounting information. Since it is opaque, access to the values inside is forbidden, except for the items for which API functions are provided to access, which mainly alter the type and the state of the resource. Values that may be assigned to the type and the state parameters are defined in ggi/ga_types.h.

LibGAlloc's API is designed such that many extensions will not need to manipulate resources directly. Instead a lot of resources will be manipulated solely with the properties structure described elsewhere. However, some features will exceed the properties structure, and in addition to, or instead of, the properties structure, a resource can have a private data structure which can be loaded with the ggiGASetPriv, ggiGAGetPriv functions. Those are functions only to be used by extension authors, however, because using a private structure implies that you will be placing special support in a LibGAlloc helper library or target that will handle the data on the other side of LibGAlloc's information flow. LibGAlloc will faithfully copy and free the contents of the private data, but it does not understand them. An important consequence of this fact is that no nested data structures are allowed in a private data area.

The Request List

Before we go on to describe the resource state, time should be taken to understand how a linked list of resources, which we refer to as the request list, is used to allocate feature resources. In the below discussion we should think of LibGAlloc as a foreign tourist on an international airplane flight, who is trying to buy as many cigarettes as he can from some of the other passengers, but has to pay in the currency accepted in their country. Not every resource uses just bytes of video RAM; They all have their own form of currency. For the purpose of this discussion though, we will ignore what kind of currency is being used, and instead we will talk about a resource just using an amount of space, and having sizes that say how much space the resource uses.

When a request list is processed, the list is taken in order, and space for each resource is budgeted until one of the resources does not fit. If a resource does not fit, the list is discarded immediately and an error is returned to the user with a flag set in the offending resource. The application may then try to modify the list and check again if it will fit, for as many times as it takes to get every item on the list approved by LibGAlloc.

If a resource is submitted on the list that has a size set to 'GGI_AUTO', then that resource will be made as large as possible, and may consume all the available space, so that any more resources that need space will be failed. This would make it very tedious to get a feature to be an optimal size because the application would have to submit the request with 'GGI_AUTO', find out what size the resource was budgeted at, and then reduce the size until everything fit. This would result in the application needing to do a lot of the work LibGAlloc is supposed to take off of our hands, so we have built in a way to get around this problem.

First, there is a way which you can put a resource into the list multiple times with different values. This allows you to put a request for, say a '640x480x8' video mode at the top of the list, and then request all of your features, and the put a request for 'GGI_AUTOxGGI_AUTOxGT_AUTO' at the end of the list. That would guarantee you to get '640x480x8' at least, and then if there was space left over after the features had been allocated, the video mode would be upsized. The section on tag groups describes this process in more detail.

Second, a resource can be flagged such that it is a resource cap. A resource cap immediately follows a resource of the same type, and any size in the cap resource must be set higher than the same value in the resource before it, or to 'GGI_AUTO'. It is known that these two resources refer to the same instance of a feature, and so the amount of space allocated for it will be at least the amount of space requested by the first resource, but at most the amount requested by the resource cap.

Finally, there are some resources that have meaning only when associated with another resource. Resources can be either be a regular resource or a resource which refers to a regular resource. All resources that refer to a regular resource must immediately follow the regular resource (or its cap if it has one) in the list. Each group of resource, resource cap and referring resources and their caps can be called a compound resource. These are described in more detail later.