Types of resources
Name
ggiGA_resource_type : Types of resources
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(3) operation has been used on the visual, it is recommended that calls to ggiGetMode(3) and ggiSetMode(3) and its variants be reworked to use the LibGAlloc method for setting modes. More on that later.
The function ggiGAAddMode(3) can be used to add a framebuffer resource to the request list. You can use ggiGAGetGGIMode(3) and ggiGAGetGGIDB(3) 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 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.
Advanced list structures with tags
Additionally to what has been said about the tag field in ggiGA_resource_state(3), it is possible to nest tag groups with the so called tag heads.
Tag heads are virtual resources and only exist in libgalloc's target's static resource list (AKA feature description list). They are therefore only relevant for libgalloc target developers. Tag heads bind two tag groups together in a form of ring list.
For motor/carb tag groups, there are situations where you have a set of resources A nad a set of resources B, and you are only allowed to use resources that are either in A or in B, but you cannot allocate resources from both A and B at the same time.
Tag heads are also used for tank tag groups to determine which resources are allowed to share the same storage space with which other resources, when you have a situation where A and B can share the same storage as C, but A cannot share storage with B:
+-------+ | C | | +---+ | | | A | | | +---+ | | | B | | | +---+ | +-------+
But this is not OK:
+-----------+ | C | | +-------+ | | | B | | | | +---+ | | | | | A | | | | | +---+ | | | +-------+ | +-----------+
Then we represent the situation with a tank tag group where C and a tag head are in the first level, and from the taghead starts a lower level tag group that contains A and B.
The tag group form a reduced grouping expression where the first level tag group and all odd numbered levels are conjuncts and the second level tag group and all even are disjuncts. That is the above is:
C ^ (A v B)
Where ^ means that the operands can coexist (or share, in the case of tanks) and v means, that the operands cannot coexist (or share, in the case of tanks).
