Carb resource properties

Name

ggiGA_carb_props : Carb resource properties

#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 coefficient. 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 coefficient 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_TESSELATE', 'LL_ROP_XWRAP', and 'LL_ROP_YWRAP' values are used for pattern fills. They apply only to the source, or operand1. 'LL_ROP_TESSELATE' 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(3) 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(3), 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(3).

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