LibGAlloc resources
===================


Resource lists
~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_resource_list ggiGA_resource_handle

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.



Types of resources
~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_resource_type

Synopsis
--------

::

  #include <ggi/ga_types.h>

  enum ggiGA_resource_type

Description
-----------


The `ggiGA_resource_type` enumerated type indicates to LibGAlloc the
general type of feature that a resource represents.  It is used by
LibGAlloc targets to route the feature to callback code in the target
or in a helper library that is designed specifically to handle
resources of that type.  There are families of types and, subordinate
to those, individual subtypes. The family can be extracted by using
the macro `ggiGA_TYPE` to mask out subtype and other bits.  The
subtype can be determined with the macro `ggiGA_SUBTYPE`.  The macro
`ggiGA_FULLTYPE` gives both the type and the subtype together, a
commonly needed value.


Framebuffer Resources
"""""""""""""""""""""


Resources of type `GA_RT_TYPE_FRAME` are special, in that they
represent a main video mode.  LibGAlloc has its own operations for
setting and getting the video mode, which treat the video mode as just
one other type of feature.  Although LibGAlloc's API has been designed
to allow easy addition of LibGAlloc using extensions to existing code
by doing its best to accomodate when the regular `ggiSetMode`
operation has been used on the visual, it is recommended that calls to
`ggiGetMode` and `ggiSetMode` and its variants be reworked to use the
LibGAlloc method for setting modes.  More on that later.


The function `ggiGAAddMode` can be used to add a framebuffer resource
to the request list.  You can use `ggiGAGetGGIMode` and
`ggiGAGetGGIDB` to get a pointer to the ggi_mode and ggi_directbuffer
structures in the framebuffer resources, just remember if the resource
is destroyed that this pointer becomes invalid.  Also, resource
structures are treated differently when they are of this type, as
explained in the next section.


Anciliary Buffer Resources
""""""""""""""""""""""""""

Resources of type ``GA_RT_TYPE_BUFFER`` represent companion buffers
to other features.  There are many kinds.  A buffer is usually attached to
another resource with the ``GA_STATE_SEEABOVE`` state flag described
later in this chapter.  That is because anciliary buffers usually define
extra data for each pixel in a resource that contains pixel data, and
would be meaningless without a resource to be associated with.


Resource of sub-type ``GA_RT_BUFFER_ZBUFFER`` represent a 3D
Z-buffer. These are used to apply to each point on the screen a depth into
or out of the screen.  This data should be stored onboard the card because
it is a critical element in the mathematics that some graphics card
accelerators use when drawing 3D objects, however it is also possible
to emulate a Z buffer in normal RAM in some cases.


Resources of sub-type ``GA_RT_BUFFER_ABUFFER`` represent an Alpha
buffer.  Alpha values tell the graphics processor whether the pixel is
transparent, translucent, or opaque.  Usually Alpha values are stored
interleaved with the rest of the color data for a pixel, but this sub-type
exists to support implementations where the Alpha buffer is separate.


Resources of sub-type ``GA_RT_BUFFER_SBUFFER`` are Stencil, or Span,
buffers.  These are a popular software rendering technique that may
some day find itself with hardware assistance.


Resources of type ``GA_RT_BUFFER_SWATCH`` will result in the
allocation of onboard or offboard areas where you can draw in the same
pixel format as the main framebuffer.  The swatch is different than
simply allocating off-screen area by adjusting virtual resolution,
because on double and triple buffered displays (where the ggi_mode's
`frame` element is > 1), the virtual area exists once for each frame.
On-board swatch resources are kept only one per visual, and so they
are more efficient.  (And, unlike virtual area, they can also be
requested as off-board buffers.)


Resources of sub-types ``GA_RT_BUFFER_LSTEREO`` and
``GA_RT_BUFFER_RSTEREO`` represent data meant to be used to modify the
display data for the user's left and right eyes when using 3D viewing
devices.  (We put them in for Steffen, author of KGI, he knows more.)


Sprite Resources
""""""""""""""""

Sprites are small, and sometimes not so small, images that float on
top of the screen and can be moved around on the screen just by
changing a few hardware registers which define their screen position.
The contents of the image are contained either in registers or in the
video RAM.  The big advantage to sprites is that they remove the need
to worry about whether the image of the sprite will interfere with
other drawing operations being performed on the framebuffer. All
sprite like objects have a type of ``GA_RT_SPRITE``.


Resources of sub-type ``GA_RT_SPRITE_POINTER`` are sprites that are
specifically designed to make happen the little arrow that you move
around with your mouse.  They sometimes have features that other types
of sprites implemented on a card may not (like color transforms with
the image in back of it), and often lack features that generic sprites
have (like hardware collision detection).


Resources of sub-type ``GA_RT_SPRITE_CURSOR`` usually refer to the
blinking hardware cursor in VGA text mode, but there are also targets
that implement these for graphics modes as well, in which case they
are very similar to, if not the same as, the pointer sprites described
above.


Resources of sub-type ``GA_RT_SPRITE_SPRITE`` are all-purpose sprites.
They often come in sets in which certain sprites will appear to be
over or under other sprites when they overlap, and the sets sometimes
have hardware registers that keep track if any of the opaque pixels in
one sprite are occupying the same location as an opaque pixel in
another sprite.  Some graphics targets can have sprites up to the full
size of the screen.


Video related resources
"""""""""""""""""""""""

Resources of type ``GA_RT_VIDEO`` represent areas of the screen which
may be fed data from a TV tuner or hardware DVD/MPEG1/H.32x source.


Window Resources
""""""""""""""""

Resources of type ``GA_RT_WINDOW`` represent features that are meant
to aid or accelerate windowing systems.


Resources of sub-type ``GA_RT_WINDOW_YUV`` are YUV viewports, which
cause the pixel data in a certain region of the screen to be
interperated as YUV colorspace instead of RGB colorspace.  They are
useful for image processing programs like the GIMP.


Resources of sub-type ``GA_RT_WINDOW_MM`` are hardware address
translation windows which cause some of the IO space of the target to
refer to the contents of a region of the screen with the origin and stride
of the data being that of the window. If you understand modern CPUs, this
can be thought of as an MMU for rectangles in graphics memory.  If you've 
ever used the display-sub LibGGI target, then this would be a hardware 
accelerated display-sub with directbuffer.


Miscellaneous Resources
"""""""""""""""""""""""

The type ``GA_RT_MISC`` is a catagory to file features that do not
belong to any family of features big enough to merit its own type.  
Hence, the name. :)


Resources of sub-type ``GA_RT_MISC_RAYPOS`` allow the querying and
lazy-polling of the raster position on displays that use cathode ray
tubes, or internally are structure similar to CRT displays. See
LibGGIMisc's `*RayPos` functions.


Resources of sub-type ``GA_RT_MISC_RAYTRIG_SET`` and
``GA_RT_MISC_RAYTRIG_PAL`` allow a way to tell the hardware to
automatically set a display attribute (like the frame displayed when
double-buffering, or the color pallete values) when the raster reaches
the end of the screen and begins the vertical retrace cycle.


Resources of sub-type ``GA_RT_MISC_SPLITLINE`` allow the screen data
to be wrapped into a cylinder which can be scrolled.  See the
LibGGIMisc :man:`ggiSetSplitline(3)` function documentation for more
information.


Resources of sub-type ``GA_RT_MISC_FONTCELL`` represent the data used
to display characters in a hardware text mode.  In these modes, the
frame contains one or two bytes per character, which are used as
indexes into a table of tiny graphics images of all the letters of the
alphabet and other characters elsewhere in the video RAM, or in a ROM.
These features allow you to read or modify the images of the
characters.


Variants: Motors, Tanks, and Carbs
----------------------------------

The flag ``GA_RT_MOTOR``, if set, indicates that the resource is a
*motor* resource; The flag ``GA_RT_CARB``, if set, indicates that the
resource is a *carb* resource; if neither flag is set, the resource is
a *tank* resource.


Motor resources represent the capabilities of the target to perform
the operations required to implement a feature, and usually occupy
little or no memory space.  For example,
(``GA_RT_MOTOR & GA_RT_SPRITE_SPRITE``)
would refer to the circuitry that places sprites on the screen, moves
them around, and performs prioritization and collision detection.


Tank resources represent the actual data manipulated by a motor
resource.  It is possible to associate multiple tanks with a motor,
and multiple motors with a tank.  Think of the tank as ammunition, and
the motor as a gun: as long as the bullets are the right type, they
can be used in any gun.


Carb resources are halfway between motors and tanks, both in meaning
and in fact.  A carb resource defines a mixing, blending, or other
operation which is performed on data from one or more tank resources
while it is on its way to the motor for positioning.  This can be a
software or hardware operation.  In order to attach a tank to a motor,
a carb resource is needed.


Motor, tank, and carb resources all use the resource properties
structure differently, and are called *resource variants*.  For more
detailed information, see the section on resource properties.



The Resource States
~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_resource_state

Synopsis
--------

::

  #include <ggi/ga_types.h>

  enum ggiGA_resource_state;


Description
-----------

The resource state is a variable that contains bitwise flags that
represent the status of a resource during negotiation. Some of these flags
are meant to be set only by the user, some of them are meant to be set
only by LibGAlloc, and some of them are bi-directional.  You can find out
which is which by masking with the values ``GA_STATE_REQUEST_MASK``
and ``GA_STATE_RESPONSE_MASK``.


The "failure" flag means the resource used too much space
---------------------------------------------------------

The ``RS_STATE_FAILED`` flag is set by LibGAlloc; it will also be
cleared by LibGAlloc, so there is no need to worry what state it is in
when you send a resource to LibGAlloc.  This flag indicates that this
resource is the point in the list where LibGAlloc decided that the feature
list did not fit.

LibGAlloc sets the "modified" flag if it makes a suggestion
-----------------------------------------------------------


The ``RS_STATE_MODIFIED`` flag is only set by LibGAlloc.  When it has
been set it means LibGAlloc has altered the valus of the sizes of the
resource.  This can be one of two cases -- if the resource contained
``GGI_AUTO`` sizes, then the ``GGI_AUTO``\ s have been replaced by
the largest sizes that would fit.  The other case, which you can tell by
the ``RS_STATE_FAILED`` flag returned by LibGAlloc, is that the
resource failed.  In this case, the sizes have been replaced with the
largest sizes that would suceed, whether or not they contained
``GGI_AUTO``.


The "nochange" flag tells LibGAlloc not to make suggestions
-----------------------------------------------------------


The ``RS_STATE_NOCHANGE`` flag is only set by the creator of a
resource. (In rare cases, this can be LibGAlloc.)  It is not altered after
the resource is created.  This flag tells Galloc not to suggest values for
the sizes of this resource if it fails during a ggiGACheck.  Normally, if 
a resource fails, LibGAlloc will set ``RS_STATE_MODIFIED`` flag, 
and replace the sizes in the object with smaller sizes that would succeed.  
This is like the optional suggestion parameter passed back by ggiCheckmode.
Note that this flag is only honored by `ggiGACheck`, and is ignored 
by ggiGASet, so, the values in the reslist returned from ggiGASet may have 
been altered regardless.


The "see above" flags designates a referring resource
-----------------------------------------------------

The ``RS_STATE_SEEABOVE`` flag is only set by the creator of a
resource. (In rare cases, this can be LibGAlloc.)  It is not altered after
the resource is created.  This flag designates the resource to be a
"referer resource" as described above.  Many of the properties fields in
this resource might be ignored in favor of the values in the first resource
in the current compound resource, (exactly which values are overridden
depends on the types of both resources.)


The "cap" flags designates a resource cap
-----------------------------------------

The ``RS_STATE_CAP`` flag is only set by the creator of a resource.
(In rare cases, this can be LibGAlloc.)  It is not altered after the
resource is created.  This flag designates the resource to be a "resource
cap" as described above.  The sizes in this resource must be greater than
the values in the resource before it in the list, (``GGI_AUTO``
should be considered infinity for this purpose.)  When budgeting space,
LibGAlloc will make the resource use at least as much space as the
resource before it, but no more than asked for by this resource.


The "noreset" flags designates an in-service feature
----------------------------------------------------

The ``RS_STATE_NORESET`` flag is only set by the creator of a
resource. (In rare cases, this can be LibGAlloc.)  It is not altered after
the resource is created.  This flag designates the resource to represent a
feature that is currently being used, and cannot be reallocated.  Any
feature anywhere in the request list which would force this resource to be
reallocated or use of it to be interrupted in any way will fail.


The "shared" flag designates a sharable resource
------------------------------------------------

The ``RS_STATE_SHARED`` flag is only set by LibGAlloc.  When it has
been set it means the resource properties structure can be/is shared.
Certain types of negotiations require a resource to appear multiple
times in the request list; sharing the properties structure is done in
these cases for efficiency and simplicity of internal code.

The "tag" field defines advanced list structure
-----------------------------------------------

Resources are considered to be in a *tag* group if the bits masked by
``GA_STATE_TAG_MASK`` are non-zero.  There are two types of tag
groups, one which has tanks in it, the other which has motors and
carbs; and they work a bit differently.


Tag groups containing tanks are processed as follows: each time a tank
resource of that tag group is encountered, it, and the resources
attached to it, are negotiated as they normally would be, but it is
assumed that they will be reusing the same storage areas that previous
resources in the tag group used (if more space is needed for this
resource than for any of the previous resources inthe tag group, a
larger area is requested).  The user is responsible at this point for
not trying to use the resources simultaneously, and for initializing
the storage areas after another resource has been using them.  Note
that ``GA_RT_FRAME`` resources are implicitly in a tag group with any
other ``GA_RT_FRAME`` resources.  Now, it is easy to see that the
process of *upsizing* a resource which was described earlier is
nothing more than requesting a second, bigger resource that shares the
same storage area, and simply not using the smaller resource.


In a tank tag group, compound resources interact with the tag group as
follows: any resources marked as *seeabovea* and in the same compound
must exist simultaneously with each other and so they do not share
storage area with each other even though they share the same tag; they
only share storage with resources in other compound resources.  Any
resources in the compound which are not marked as part of the tag
group cause allocation of new storage areas, even if they exist in
previous compounds in that tag group... so be sure to join your
seeaboves into the tag group, as well.


Note also that if you wish to upsize a resource and it's attached
seeaboves, e.g. Z-Buffers, they must appear in both the original
compound resource, and in the second *upsize* resource -- do not
assume that because you have requested a Z-buffer above in the list
that it is implicitly requested for other resources in the same tag
group; it is not.


Now, for tag groups containing motors and carbs, the handling is
slightly different.  Generally these consist of one or more motors and
a lot of carbs.  The carbs are attached to tank compound resources as
seeabove, and this is how the tank-carb-motor pipleine is glued
together.  If negotiation of a carb succeeds, it means that the tank
it is attached to has a valid path (the carb) through which its data
can be sent to any of the motors which are in the same tag group as
the carb.





LibGAlloc resource properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_resource_props ggiGA_storage_type ggiGA_mode

Synopsis
--------

::

  #include <ggi/ga_prop.h>

  #define GA_FLAG(props)	props->flags

  struct ggiGA_resource_props {

	enum ggiGA_storage_type storage_need;
	enum ggiGA_storage_type storage_ok;

	/* bits to control sharing by the user */
	enum ggiGA_storage_share storage_share;

	/* Meaning of qty and flags vary depending on type of resource. 
	   For the latter, see GA_FLAGS* defs in ga_types.h */
	uint16 qty;
	uint32 flags;

	/* On the way into a request, this is the desired size, 
	 * when returned back from gallocation, this is the
	 * maximum size.  Units for tanks are in pixels; Units for motors
	 * are in same units as snap grid (see GA_COORDBASE* values in .flags) 
	 */
	union {
		ggi_coord area;
		uint32 linear;
	} size;

	/* Possible variants */
	union {
		struct ggiGA_motor_props motor;
		struct ggiGA_carb_props carb;
		struct ggiGA_tank_props tank;
	} sub;
  };

  struct ggiGA_mode {
	ggi_mode mode;
	ggi_directbuffer db;
  };


Description
-----------

Most LibGalloc resources will contain a structure called the 
properties, which is set when the resource is added to a list
with `ggiGAAdd`, and a pointer to which can be retrieved with 
`ggiGAGetProperties`.

The properties structure contains commonly used parameters for the
negotiation of a resource.

Fields Common to Most Resources
-------------------------------

If a resource has a props structure, then it will probably use some
of the following members.  An additional union member, sub, contains
members specific to the three resource variants: *tank*, *motor*, and 
*carb* resources, and is described in the next three sections.

The `qty` member is a generic field for storing an integer attribute.
For example, a ``GA_RT_SPRITE_SPRITE`` motor resource would use this
field in negotiation of how many sprites it can display on the screen
simultaneuously.

The `flags` field is a generic variable for holding flags.  For example, 
most motor resources will use the the two flags ``GA_PIXEL_MODE`` or 
``GA_DOT_MODE`` to define what units the snap grid parameters are in
(see below).


The `size member` is used to define the size of the negotiated resource,
if it has one.  `GGI_AUTO` (0) is considered to mean automatically
find the maximum size possible for this resource.  The size member
can be accessed as size.x,size.y for two dimensional objects, or
size.linear for linear allocations. 


The Storage Type
----------------

The two members `storage_ok` and `storage_need` check the capability
to use certain types of data storage for the resource.  The meaning of
`storage_ok` and `storage_need` are described below; Let us look at
the values these fields may contain.  First, the special value
``GA_STORAGE_DONTCARE`` (which equals zero) means any type of storage
is acceptable.

The flag values ``GA_STORAGE_READ`` and ``GA_STORAGE_WRITE`` designate
that the storage is readable/writeable.  For convenience, the value
``GA_STORAGE_RW`` (equal to ``GA_STORAGE_READ | GA_STORAGE_WRITE``) is
also defined.  The flag value ``GA_STORAGE_DIRECT`` indicates that the
storage may be accessed as per normal system memory (even if it is
not.)  Unless it is set, special methods are needed to access the
storage.  The value ``GA_STORAGE_NORMAL`` (equal to ``GA_STORAGE_RW |
GA_STORAGE_DIRECT``) is provided for convenience as well.

The flag value ``GA_STORAGE_ONBOARD`` indicates that storage is
located on-board the graphics device, and does not need to be
transferred across the system bus in order to be used in a graphics
operation (however, on the down side, this means that actually loading
content into the storage from regular system memory will require the
data to be passed across the system bus.)  The value
``GA_STORAGE_VRAM`` (equal to ``GA_STORAGE_NORMAL | GA_STORAGE_ONBOARD``)
is more convenient to use.

The flag value ``GA_STORAGE_RAM`` indicates that the storage is normal
system memory which is stored permanently in RAM, that is, it will not
be swapped out to secondary storage.  The value ``GA_STORAGE_REALRAM``
(equal to ``GA_STORAGE_NORMAL`` | ``GA_STORAGE_RAM``) is more
convenient to use.

The flag value ``GA_STORAGE_SECONDARY`` indicates that the storage is
located on a physical medium which is slower than system RAM, usually
a disk drive.  Likewise, the flag value ``GA_STORAGE_TERTIARY``
indicates the storage is located on a medium which may have large
latency or very slow speed -- this usually indicates the storage is on
a network server which lacks service guarantees.

The flag value ``GA_STORAGE_TRANSFER`` indicates that the graphics
system is capable of using the storage without CPU assistance.  
For example, user-space DMA-capable buffers can be gotten using
the convenient value ``GA_STORAGE_DMA``, which is equal to 
``GA_STORAGE_REALRAM | GA_STORAGE_TRANSFER``.


The flag value ``GA_STORAGE_VIRT`` indicates that an automatic caching
system (transparent to the user) is in effect which makes slower
storage appear to be interchangable with faster storage.  For example,
the convenient value ``GA_STORAGE_SWAP`` represents virtual RAM which
may be stored in either real ram, or in *virtual memory* on a hard
drive.  Accordingly, ``GA_STORAGE_SWAP`` is equal to
``GA_STORAGE_REALRAM | GA_STORAGE_SECONDARY | GA_STORAGE_VIRT``.
Another convenience value ``GA_STORAGE_GART`` is provided and equals
``GA_STORAGE_REALRAM | GA_STORAGE_ONBOARD | GA_STORAGE_VIRT``.


The flag value ``GA_STORAGE_HOTPIPE`` indicates that read and write
operations to the storage do more than alter the contents of the
storage, and may in fact trigger graphics operations.


The `storage_need` and `storage_ok` members work together to provide a
flexible negotiation system. When a request is submitted to LibGAlloc
via ggiGASet, each bit flag position is checked in both positions, and
the following meanings apply depending on the values found:

``storage_ok = 0``, ``storage_need = 0``
    This type of storage is not acceptable.  The resource will fail if 
    it is only available with this type of storage.

``storage_ok = 0``, ``storage_need = 1``
    This type of storage is desirable, but is not entirely necessary.
    If this type of storage is not available, the resource will still
    succeed, but if it is available, LibGAlloc will try to allocate it
    before any other type of storage.

``storage_ok = 1``, ``storage_need = 0``
    This type of storage is undesirable, but is acceptable.  If this
    type of storage is the only kind available, the resource will
    still succeed, but if other storage is available, LibGAlloc will
    try to allocate it first.

``storage_ok = 1``, ``storage_need = 1``
    This type of storage is necessary.  The resource will fail unless
    it is available.


LibGAlloc also returns values in these fields.  The values in these
feilds will be always be altered by `ggiGASet`.  When `ggiGACheck`
is called the values will not be altered if the resource is flagged with 
``GA_STATE_NOCHANGE`` (see the section on resource state).  The meanings of 
the returned flags are as follows when a call to `ggiGACheck` or
`ggiGASet` fails:


``storage_ok = 0``, ``storage_need = 0``
    Any requests for this resource that have this bit set will fail.
    This type of storage is not compatible with this resource.

``storage_ok = 0``, ``storage_need = 1``
    Requests for this resource will be more likely to succeed if this
    bit is set to 1.

``storage_ok = 1``, ``storage_need = 0``
    Requests for this resource will be more likely to succeed if this
    bit is set to 0.

``storage_ok = 1``, ``storage_need = 1``
    Any requests for this resource will fail unless this bit is set.
    Storage of this type is the only kind compatible with this resource.


Note that downsizing the resource may help in the second and third
situation above depending on the available amounts of different types
of storage.  In this case, suggested sizes are supplied in the
returned resource.  In the first and fourth situations, altering
characteristics of the resource may change the values returned
entirely, by changing the types of storage that the resource is
compatible with.  Clues as to minimal alterations needed to make the
resource work with the originally requested storage type may have been
placed by LibGAlloc in various members of the returned resource.


When `ggiGASet` (or `ggiGACheck`) is successful, both members will
contain the same value, which will have bit flags set accordingly to
represent the type of storage which has actually been (or would be)
obtained and allocated for use by this resource.



See Also
--------

:man:`ggiGA_tank_props(3)`,
:man:`ggiGA_motor_props(3)`,
:man:`ggiGA_carb_props(3)`



Motor resource properties
~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_motor_props

::

  #include <ggi/ga_prop.h>

  struct ggiGA_motor_props {

	/* All units as per the GA_COORDBASE* bits set in 
	 * the common .flags member. 
	 */

	/* When positioned and sized on the screen, some features must 
	 * be positioned and sized on a snap grid.
	 */
	ggi_coord pos_snap;	/* Size of grid for positioning */
	ggi_coord size_snap;	/* Size of grid for sizing */
	ggi_coord grid_start;	/* Upper left of the snap grid */
	ggi_coord grid_size;	/* Size of the snap grid */

	/* For resources that support pixeldoubling/scaling or for 
	 * overlay windows that drive the DAC directly, these 
	 * define the available scaling factors.
	 */
	ggi_coord mul_min, mul_max;	/* dot double, triple, etc. */
	ggi_coord div_min, div_max;	/* Sub-dot resolution (scan windows) */

	/* Available raster operations e.g. XOR with current screen data. */
	uint32 rops;
  };

Description
-----------


A motor resource is a chipset feature that moves data (hence the
name).  As such, the properties used by motor resources all involve
limits and attributes concerning what capabilities the motor has to
move/position the data.  Motor properties area accessible through the
union member `sub.motor` in the resource properties structure.  The
common properties member `qty` will usually refer to the number of
simultaneous objects that can be positioned/moved by the motor.  The
common properties members `storage_ok` and `storage_need` are reserved
for future use.


The Snap Grid
-------------

Most motor resources allow you to position something on the screen,
but many have limitations about where on the screen you are able to
position that something.  The snap grid defines the rules for
positioning with a motor resource.  The `grid_start` and `grid_size`
members offer x,y coordinates within which the motor can position
things.

In addition, some motors can only place things on a grid (for example,
it might place things at 0,0 or 10,0 or 0,10 or 10,10 or 0,20 but not
at 3,5 or any other location whose coordinates are not divisible by
10.)  This is a lot like the *snap-to-grid* feature in many common
desktop publishing programs.


The `pos_snap` member defines x and y snap intervals, and if they are
set to values other than 1, attempting to position the resource at
coordinates off the snap grid will result in your coordinates being
rounded to the nearest grid snap point.  Likewise, there is a
`size_snap` member which tells you if the motor has similar
restrictions when it is resizing something.


Sub-Pixel Accuracy and Scaling
------------------------------

Many motor resources have a different resolution than the main
framebuffer, or the capability to scale things.  In some cases, the
motor is immune to the main framebuffer's double-scan and
pixel-doubling settings, and is able to position and size with
sub-pixel accuracy.  Even further, some motors use an entirely
different pixel clock which is gated into the CRTC when the raster
beam is traversing the object defined by the motor resource, so sub
dot accuracy is possible.  In addition, many resources support their
own pixel doubling or double-scan, allowing the motor to scale the
object.


The scaling factors possible are defined by four vectors contained in
the `mul_min`, `mul_max`, `div_min`, and `div_max` members.  The base
units that these members operate on are either known implicitly, or
are determined by flags.  The flag values ``GA_PIXEL_MODE`` and
``GA_DOT_MODE`` are provided for this purpose, and specify that the
scaling factors apply to pixels or dots, respectively.  It is
important to note that the snap grid described in the last section
uses units of ``1/div_max`` pixels or dots, as indicated by the
presence of these flag values.  Users will generally be sheilded from
this fact by an API using integer pixel coordinates or fixed-point
sub-pixel coordinates, but extension authors are advised to check
their units after negotiating a motor.


See Also
--------

:man:`ggiGA_resource_props(3)`





Tank resource properties
~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_tank_props

Synopsis
--------

::

  #include <ggi/ga_prop.h>

  struct ggiGA_tank_props {

	union {
		ggi_coord area;
		uint32 linear;
	} buf_snap;

	/* A vague description of the buffer pixel format */
	ggi_graphtype gt;

	/* Pointer to a *shared* detailed description of the pixel format */
	ggi_directbuffer *db;

	/* Pointers to access buffer data.
	   These are surrogates to the pointers in the shared *db */
	void *read, *write;
  };


Description
-----------

A tank resource represents data to be moved by a motor.  The tank
properties describe the layout this data is stored with.  They are
accessible under the union member `sub.tank`.  The common properties
member size refers to the size of the data stored in the tank; the
units are usually pixels, but it depends on the type of the resource.
The qty feild requests several of the same sized objects, or, if set
to ``GGI_AUTO`` (zero), will grab as many of the resources as will
fit.


Buffer Layout
-------------

A standard `ggi_graphtype` for the tank data is provided for in the
`gt` member.  Also, a pointer to a standard `ggi_directbuffer` structure
is provided for in the `db` member (this db structure is often shared
between many resources, and so should **not** be freed.)  Separate pointers
to access the data in the tank for read and write access are provided.
These are to be used instead of the read and write pointers in the
directbuffer structure.


Buffer Snap
-----------

Within the buffer space allocated for a tank, there may be a snap
grid (as described above for motors) or linear alignment restriction
on operations performed on the data, such that those operations can
only address data starting at certain locations in the buffer.  The
`buf_snap` member provides an embelishment of the db member's alignment
restrictions, and may be addressed as a vector 
(`sub.tank.buf_snap.area.x`, `sub.tank.buf_snap.area.y`), or as a 
linear quantity (`sub.tank.buf_snap.linear`).



See Also
--------

:man:`ggiGA_resource_props(3)`




Carb resource properties
~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGA_carb_props

::

  #include <ggi/ga_prop.h>

  struct ggiGA_carb_props {

	struct ggi_ll_math_gc can, must;
	void **block;
	int numblock;
  };



Description
-----------


A carb resource represents a translation, alteration, or mixing of 
data from tank(s) before a motor positions the data.  This kind of
resource is used to represent *raster operations*, special 
feature-specific pallette entries or look-up tables, and data
format (endian, depth) translations.  The carb-specific resource
properties are accessible under the union member sub.carb.  For
carb resources, the common properties members qty, size, and flags
have meanings that vary based on the type of the carb.  The carb
is used most commonly in LibBlt, so refer to that library's 
documentation for a description of how ``GA_RT_BOB`` carbs use these 
fields.

ROPs (raster operations)
------------------------

A 32-bit set of flags and bitmasks is defined in the enumerated type
`ggi_ll_rop`.  These represent the types of operations that can be
performed by a *ROP*.  For our purposes a ROP is an operation that
takes two tanks as *operands*, which are compared either bit-by-bit or
pixel-by-pixel, and some sort of result is produced by taking each
pair of bits (or pixels) as arguments to a function which produces one
bit (or pixel) of the result.  Since some hardware uses *unary* (or
*non-associative*) operators, there are cases where a certain ROP is
represented by two bits, one for each operand.


A note on notation: earlier hardware implementations of ROPs assume 
that the two tanks of data being operated on were a *source* tank, and 
the data which was to be replaced by the result of the operation.  
Later implementations allow operations between two tanks to be performed 
without the data to be replaced by the result being one of them.  As such, 
many of the symbols in the `ggi_ll_rop` type have two names; the
former being a ``*_SOURCE`` and ``*_DEST`` pair and the latter being an 
``*_OPERAND1``, ``*_OPERAND2`` pair.  These symbols are equivalent and are
merely to allow code clarity in either context.  When we refer to
a symbol in the below descriptions, we will omit the suffixes and
may be refer to a pair of bits by their common root e.g. ``LL_ROP_KEYVAL``
refers to the two bits ``LL_ROP_KEYVAL_SOURCE`` (a.k.a. ``LL_ROP_KEYVAL_OPERAND1``)
and ``LL_ROP_KEYVAL_DEST`` (a.k.a. ``LL_ROP_KEYVAL_OPERAND2``).


The least signifigant 16 bits of the `ggi_ll_rop` type are used to
supply one bit for each of the *boolean* ROPs.  These rops compare the
two operands bit-by-bit and the resulting value is a logical operation
between the two bit values.  There are 16 *truth tables* possible,
some of which have, in addition to a name like
``LL_ROP_TRUTHTABLE_0001``, a commonly used name like ``LL_ROP_NOR``.


The ``LL_ROP_KEVAL`` bits represent the ability to perform *keying*,
which is sometimes imprecisely referred to *comparing*.  To key is to
apply the ROP only when the data in one or the other operand matches,
or does not match, a specific value.  Further, the ``LL_ROP_KEYMASK``
bits designate the ability to exempt certain bits from the key
comparison, such that these bits are *don't care* bits.


The ``LL_ROP_COEFF`` bits represent the ability to scale the value of
each pixel by a constant coeeficient.  This is not multiplication
unless the tank is grayscale -- each of the color channels is
separately scaled, and may be adapted for gamma correction.  Further,
when the tank contains an Alpha channel, the coeeficient used is not a
constant, but rather the contents of the alpha channel in that pixel.
When used in this manner, the alternative ``LL_ROP_ALPHA`` symbol is
clearer to say.


The ``LL_ROP_THRESH`` bits represent the ability of the ROP to only be
performed when the pixel data is above (or below) a certain threshold
value.  This value represents the pixel's intensity as calculated by
weighting the values in each channel, not a simple integer value
derived from the whole pixel.  Further, when the tank contains a Z
channel, the comparison is assumed to be between Z values, rather than
by intensity.  When used in this manner, the alternative
``LL_ROP_DEPTH`` symbol is clearer to say.



The ``LL_ROP_ADD`` bit represents the ability to *add* the two pixels
together.  This is not always plain addition of the pixel's bit
values, it is addition of colors and uses a formula appropriate to the
tanks' color spaces.  Further the ``LL_ROP_KEY_CMP`` bit designates
the ability to *key* on the result of this *addition*.


The ``LL_ROP_TESSLATE``, ``LL_ROP_XWRAP``, and ``LL_ROP_YWRAP`` values
are used for *pattern fills*.  They apply only to the source, or
operand1.  ``LL_ROP_TESSLATE`` indicates that the ROP can take a
pattern inside a tank and repeat it many times to fill a larger region
with that pattern.  The others indicate that the pattern can be
*pinned*, such that the resulting fill begins at some offset inside
the pattern, rather than at the pattern's top left corner.


The ``LL_ROP_AUX`` bits indicate that this ROP feeds into another ROP
before being passed into the motor.  If ``LL_ROP_OPERAND1_AUX`` is
set, then the result from this rop becomes the first operand of
another ROP.  If ``LL_ROP_OPERAND2_AUX`` is set, then the result from
this rop becomes the second operand of another ROP.  IF both are set
(``LL_ROP_AUX``) this is a special case indicating a *side-by-side*
rop, which is most often used such that two tanks can be compared for
keying purposes, deciding whether or not to perform a different ROP on
a corresponding pixel in two other tanks.


As mentioned above, Z and Alpha operations are implicit when certain
ROP flags are set and the set of tanks being processed contain Z or
Alpha values.  There are two common ways in which Z and ALPHA
operations are performed.  In one mode, most common for Alpha and rare
for Z, the Z or Alpha data is contained in a channel alongside the
data for each color channel in the pixel itself.  In another mode,
most common for Z and rare for Alpha, the Z or Alpha data is kept in a
separate tank of the same geometry as the tank containing the color
data.  In the latter case ``LL_ROP_AUX bits`` are both set as
described in the last paragraph.


The ``LL_ROP_ALT`` bit is there to deal with unforseen or quirky ROPs that 
may need to be added to this API at a later date.  If it is set, assume
you know nothing about the meaning of the `ggi_ll_rop` value in question.
A `ggi_ll_rop` item with a value of ``LL_ROP_NOP`` does absolutely nothing.


Adjusters
---------


Adjusters represent the ability of a carb to adjust data between
various pixel formats.

The ``LL_ADJ_ENDIAN*`` bit flags represent the ability of the hardware
to compensate for differences between the endiannes (in 4, 8, 16, or
32 bit endian slices) of tanks.  The ``LL_ADJ_BACKASS_WORDS`` bit
represents the ability to reassemble the pixel with the bits in
reverse order, as a format that carries the bits backwards was
unfortunately popularized by an certain notorious operating system
whose name should not be spoken.


The ``LL_ADJ_UPSIZE`` and ``LL_ADJ_DOWNSIZE`` indicate an ability to
translate pixels between different bit-depths.


The ``LL_ADJ_USE_OWN_CLUT`` flag indicates that an internal CLUT
separate from CLUTs of the involved tanks is available for use.  The
``LL_ADJ_COLORSPACE`` flag indicates the ability to gamma correct or
adjust between colorspaces (YUV/RGB/CMYK).


Organization of the carb resource
---------------------------------

The carb properties members named `must` and `can` contain each a
`ggi_ll_rop` named `rop`, a `ggi_ll_adjuster` named `adj`, and a
`ggiGA_storage_type` named `tostorage`.  The former are described
above; the latter refer to the type of storage of the destination
resource, which the carb and the motor that owns it has been created
to send the data to.  This does **not** mean that normal
`storage_need` and `storage_ok` properties members in the carb
resource refer to the storage type of the source data (the source data
is a tank resource and has it's own `storage_ok`, `storage_need`
members).  Naturally, the values in the structure named must are
required for the request to succeed, and the ones in the structure
named can are just wishlist requests.  If the carb resource is not
flagged ``GA_STATE_NOCHANGE``, or is being returned by `ggiGASet`,
then the values returned in the structure named must are always
active, and cannot be disabled, while the ones returned in the
structure named can may be turned on or off through some mechanism
provided by a higher level extension target.


The `totype` carb properties member designates what types of resources
are valid candidates to receive the data from this carb (via its
motor).  This can be a specific type/subtype, or can be a whole
resource type family by using one of the ``GA_RT_*_DONTCARE`` values.
Usually, this value is a tank.  The `togt` carb properties member is
similar, it defines the valid graphics scheme/depth which are eligible
to receive data from this carb (via its motor), and can contain the
various auto/dontcare values accepted by `ggiSetMode`.


Several pointers (`block1`, `block2`, `block3`) are available and are
used to offer hints which allow extension targets to find resources
which are used to control the carb.  For ``GA_RT_BOB`` resources,
these are used to hand back addresses of *batchop blocks*.  Another
possible use is as a handoff for the addresses of internal
CLUT/ILUT/TLUT tables stored in VRAM.


See Also
--------

:man:`ggiGA_resource_props(3)`

