ggiGA_resource_type : Types of resources
#include <ggi/ga_types.h> enum ggiGA_resource_type
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.
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.
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.)
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.
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.
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.
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.