====== Creating a Preamble ======
----
A cel's preamble contains information that tells the cel engine how to interpret the data it finds in the cel source data. The preamble tells whether the cel is coded or uncoded, how many bits are devoted to each cel pixel, how many columns and rows of pixels there are in the cel, and (if the cel is extracted from existing data) what offsets to use when extracting data. The preamble also contains information about how the cel data should be processed, such as how an 8-bit uncoded cel should be unfolded, whether to disable VH swapping or not, and other processing considerations.
If the cel is packed, its preamble is one word long. If the cel is unpacked, its preamble is two words long. The second word contains information necessary for handling the unpacked pixels-necessary because unpacked cel data can be extracted from an existing image source such as the frame buffer.
===== The First Preamble Word =====
A cel's first preamble word contains control bits for the source data as shown in Table 7.
Table 6: The values in the first preamble word.
---------------------------------------------------------
Bit # |Value Name |Parameter Controlled
---------------------------------------------------------
3128 |xxxxxxx |Reserved for future use. Set to
| |0.
---------------------------------------------------------
2724 |SKIPX |A value from 0 to 15 that asks
| |the cel engine to skip that
| |number of pixels at the
| |beginning of each row.
---------------------------------------------------------
2316 |xxxxxxx |Reserved for future use. Set to
| |0.
---------------------------------------------------------
156 |VCNT |The number of rows in this cel
| |minus one.
---------------------------------------------------------
5 |xxxxxxx |Reserved for future use. Set to
| |0.
---------------------------------------------------------
4 |UNCODED |If 1, the cel is uncoded. If 0,
| |the cel is coded.
---------------------------------------------------------
3 |REP8 |Controls bit replication in an
| |uncoded 8-bpp cel. If 1, missing
| |low-order bits are replicated
| |from the high-order bits. If 0,
| |missing low-order bits are set
| |to 0.
---------------------------------------------------------
20 |BPP |A value that sets the bits used
| |per pixel in the cel source
| |data. 1=1, 2=2, 3=4, 4=6, 5=8,
| |and 6=16. 0 and 7 are reserved
| |values.
---------------------------------------------------------
==== The SKIPX Value ====
The ''%%SKIPX%%'' value set by bits 27, 26, 25, and 24 sets the number of pixels the cel engine will skip at the beginning of each row. For example, a ''%%SKIPX%%'' value of five tells the cel engine to skip projecting the first five pixels of each cel row, which effectively deletes the first five columns of the cel.
This value is used mainly for fine-tuning an offset when an unpacked cel is extracted as a subrectangle of existing source data. The ''%%WOFFSET%%'' value in the second preamble word provides the coarse offset (by words in RAM), and the ''%%SKIPX%%'' value provides the fine offset (by pixels within a word). Using ''%%SKIPX%%'' and ''%%WOFFSET%%'' together is described in more detail in [[documentation:development:opera:pf25:ppgfldr:ggsfldr:gpgfldr:5gpgf|Creating a Preamble for Extracted Data]].
==== The VCNT Value ====
The ''%%VCNT%%'' value ''%%%%''describes the vertical count of the cel: the number of pixel rows it contains //minus 1.// For example, a cel with 68 rows has a ''%%VCNT%%'' value of 67; a cel with 1 row has a ''%%VCNT%%'' value of 0. A cel cannot use ''%%VCNT%%'' to specify a row count of 0.
The ''%%VCNT%%'' must use the row count minus 1 because the ''%%VCNT%%'' bits are loaded into a hardware register that the cel engine decrements until ''%%VCNT%%'' goes from 0000000000 to 1111111111, at which point the cel engine stops projecting cel rows. Although you might be tempted to think that a ''%%VCNT%%'' value of 1111111111 is the same as specifying 0 rows, it is not. A ''%%VCNT%%'' value of 1111111111 specifies a 1024-row cel.
**Note:** For LRFORM cels, VCNT specifies pairs of rows of cel data (doubling the height of an LRFORM cel).
==== The UNCODED Bit ====
If bit 4 is set, it indicates that the cel is an uncoded cel. When set to 0, the cel is a coded cel. The cel engine interprets the incoming pixel values accordingly, processing coded cel pixels through the PLUT, and passing uncoded cel pixels around the PLUT and directly to the pixel processor. This bit is only useful for 8- and 16-bit cels.
==== The REP8 Bit ====
Bit 3 applies to the ''%%REP8%%'' bit only 8-bit uncoded cels. An uncoded cel needs to pass 5 bits of red, 5 bits of green, and 5 bits of blue value into the pixel processor. The 8-bit uncoded cel has only 3 bits to devote to red, 3 bits to green, and 2 bits to blue. ''%%REP8%%'' tells the cel engine how to fill in the missing low-order bits for each value before it sends the pixel to the pixel processor.
If ''%%REP8%%'' is set to 1, bits 4 and 3 of the red value are duplicated and used (consecutively) to fill in the missing bits 1 and 0 of the red value. Bits 4 and 3 of the green value are also duplicated and used to fill in the missing bits 1 and 0 of the green value. For the blue value, which is missing bits 2, 1, and 0, blue bit 4 is duplicated and used to fill in blue bits 2 and 0; and blue bit 3 is duplicated and used to fill in blue bit 1. (See Figure 4, the Unfolding 8-bit uncoded pixels into a 15-bit color value, in [[:documentation:development:opera:pf25:ppgfldr:ggsfldr:gpgfldr:3gpg#xref38473|Understanding the Cel Engine and SPORT]].)
==== The BPP Value ====
The ''%%BPP%%'' value specifies how many bits are devoted to each of the cel's pixels (//after// unpacking, if it is a packed cel). A value of
* 1 specifies 1 bpp
* 2 specifies 2 bpp
* 3 specifies 4 bpp
* 4 specifies 6 bpp
* 5 specifies 8 bpp
* 6 specifies 16 bpp
The values 0 and 7 are reserved for future use.
The cel engine uses the bpp value to interpret the bits streaming in from the data unpacker (or directly from the source data if the cel is an unpacked cel). The bits devoted to each pixel determine, how many registers are used in the PLUT for coded cels. For example, a 1-bpp coded cel uses only two PLUT registers for its pixels, while an 8-bpp coded cel uses all 32 PLUT registers.
===== The Second Preamble Word =====
Unpacked cels require a second preamble word, which contains the control bits shown in Table 8. If you provide a second preamble word for a packed cel, the cel engine ignores any of the second word's values and interprets the carefully constructed data you placed there as garbage imagery (unless you set ''%%CCBPRE%%'').
Table 7: The values in the second preamble word.
---------------------------------------------------------
Bit # |Value Name |Parameter Controlled
---------------------------------------------------------
31-24 |WOFFSET(8) |The word offset value for 1-, 2-,
| |4-, or G- bpp cels. This value is
| |the number minus two of cel data
| |words from one row of pixels to the
| |beginning of the next row of pixels.
| |Set 23-16 to zero.
---------------------------------------------------------
2516 |WOFFSET(10) |The word offset value for 8- or
| |16-bpp cels. This value is the
| |number of cel data words from one
| |row of pixels to the next row of
| |pixels minus 2.
---------------------------------------------------------
15 |xxxxxxx |Reserved for future use. Set to 0.
---------------------------------------------------------
14 |NOSWAP |When set to 1, this value disables
| |the SWAPHV bit of the cel engine
| |control word, which ensures that the
| |VH bits of a pixel are not be
| |swapped, destroying an uncoded
| |pixel's integrity. When set to 0, VH
| |bits can be swapped if SWAPHV is
| |set.
---------------------------------------------------------
1312 |UNCLSB |Set the value of the incoming
| |uncoded pixel's blue least
| |significant bit. 00=set it to 0;
| |01=copy the blue LSB (bit 0) of the
| |incoming pixel; 10=copy the blue MSB
| |(bit 4) of the incoming pixel;
| |11=copy the green LSB (bit 5) of the
| |incoming pixel.
---------------------------------------------------------
11 |LRFORM |When set to 1, this value specifies
| |that a 16-bit unpacked cel's pixels
| |are stored in left/right memory
| |format (just like the frame buffer
| |layout). When set to 0, it specifies
| |linear memory format. (This value
| |applies only to 16-bit unpacked
| |cels.)
---------------------------------------------------------
100 |TLHPCNT |This value sets the number of pixels
| |in each row of the cel source data
| |minus 1.
---------------------------------------------------------
==== The WOFFSET Value ====
The ''%%WOFFSET%%'' value is defines a subrectangle of source data from within existing source data such as the frame buffer or another unpacked source data file. This value indicates how many words of pixel data exist from the beginning of one cel row to the beginning of the next cel row, in other words, how many words wide the original source data is. The cel engine knows how many pixels to read in each row of the subrectangle (indicated by the ''%%HPCNT%%'' and ''%%SKIPX%%'' values); it skips all pixels between the spot where it finishes reading subrectangle pixels and the address of the word that begins the next row of pixels.
For example, if you want to define an unpacked subrectangle that uses 5 words to store each row of pixels. The subrectangle comes from cel source data that uses 12 words to store each row of pixels. You need a word offset of 12 words to ensure that each row of the subrectangle starts on the same column of the mother cel.
The second preamble word contains two possible ''%%WOFFSET%%'' values. The number of bits per pixel determines which value is used:
* WOFFSET(8), which is used for 1-, 2-, 4-, or 6-bpp cels.
* WOFFSET(10), which is used for 8- or 16-bpp cels.
The two values use overlapping bit sets, so you can only use one or the other ''%%WOFFSET%%'' value. Whichever one you use, the integer stored there is the word offset //minus 2,// which is necessary to accommodate the pipelining architecture of the cel engine.
''%%WOFFSET%%'' works together with the CCB's pointer to cel source data and the ''%%SKIPX%%'', ''%%VCNT%%'', and ''%%HPCNT%%'' preamble values to define a subrectangle (see [[documentation:development:opera:pf25:ppgfldr:ggsfldr:gpgfldr:5gpgf|Creating a Preamble for Extracted Data]]).
==== The NOSWAP Bit ====
The cel engine can, if the cel engine control word so specifies, swap the V and H bits of a pixel before projecting it. If you are projecting a 16-bpp uncoded cel, it may be important to you that bits 0 and 15 //not// be swapped to ensure the pixel data's integrity. If so, setting the ''%%NOSWAP%%'' bit to 1 guarantees that the cel engine will not swap the bits even if the cel engine control word is set to swap them. Setting ''%%NOSWAP%%'' to 0 allows (but does not set) V and H swapping.
==== The UNCLSB Value ====
When an uncoded pixel bypasses the data decoder and is fed into the pixel processor, it may have used bit 0 (normally the least-significant blue bit) to store a V or H value, which is read and passed on to the projector. If so, you may wish to set bit 0 to a predetermined blue value before the pixel goes to the pixel processor. ''%%UNCLSB%%'' determines what that blue value will be.
If ''%%UNCLSB%%'' is set to 00, then bit 0 is set to 0, effectively removing the blue resolution that the lower bit provides. If ''%%UNCLSB%%'' is set to 01, bit 0 retains its current value, a useful setting if bit 0 has never been used to hold a V or H value. If ''%%UNCLSB%%'' is set to 10, bit 0 is set to the value contained in bit 4 of the pixel (the most-significant blue bit). And if ''%%UNCLSB%%'' is set to 11, bit 0 is set to the value contained in bit 5 of the pixel (which copies the least-significant green bit).
The ''%%UNCLSB%%'' value overrides any setting in the ''%%PDCLSB%%'' value of the cel engine control word (see [[documentation:development:opera:pf25:ppgfldr:ggsfldr:gpgfldr:5gpgk|The PDCLSB Value]] for more information), which also sets bit 0 of a pixel coming out of the data decoder. Because ''%%UNCLSB%%'' appears anytime a second preamble word is used, unpacked cels are controlled by ''%%UNCLSB%%'', while packed cels (which do not have a second preamble word) are controlled by ''%%PDCLSB%%''.
==== The LRFORM Bit ====
The ''%%LRFORM%%'' bit only affects 16-bit unpacked cels, which is the required format if you are creating cel source data from an image stored within a bitmap. Pixels in a bitmap are stored in VRAM using left/right format; that is, pixels from row pairs are interleaved with each other. For example, pixel 0 of row 0 is stored in the first half of a VRAM word, pixel 0 of row 1 is stored in the second half of the same word. In the next word, pixel 1 of row 0 is stored with pixel 1 of row 1. The left/right format allows the display generator to speedily perform interpolation and other pixel operations.
If you use 16-bit uncoded cel source data stored in left/right format (in other words, you pick up an image from the frame buffer or another bitmap), you must set the ''%%LRFORM%%'' bit to 1 so the cel engine can process the pixels correctly. If ''%%LRFORM%%'' is set to 0, the cel engine assumes that the source data is stored in normal format (pixels are not interleaved within rows, they are stored consecutively, one after the other, within a single row before the pixels within the next row are stored).
The ''%%LRFORM%%'' bit has no effect on any cels other than 16-bit unpacked cels because all other types of cels are stored in normal format.
Setting ''%%LRFORM%%'' causes two rows of cel data to be processed simultaneously effectively doubling the value specified by ''%%VCNT%%''.
==== The TLHPCNT Value ====
The ''%%TLHPCNT%%'' value contains the number of pixels in each row of unpacked cel source data minus 1. Because this is a single value, it means that an unpacked cel must always be rectangular (although some of its pixels can be transparent so that it does not have to appear rectangular).
The ''%%TLHPCNT%%'' value, like the ''%%VCNT%%'' value of the first preamble word, is the actual count minus 1 because it is used in a register that decrements until the value goes from 00000000000 to 11111111111. A value of 0 means there's one pixel in each row. A value of -1 (11111111111) means that there are 2,048 pixels in each row.