Unpacking

Data are taken from host memory as a sequence of signed or unsigned bytes (GL data types byte and ubyte), signed or unsigned short integers (GL data types short and ushort), signed or unsigned integers (GL data types int and uint), or floating point values (GL data type float). These elements are grouped into sets of one, two, three, or four values, depending on the format, to form groups. Table 3.5 summarizes the format of groups obtained from memory; it also indicates those formats that yield indices and those that yield components.

  
Table 3.5: DrawPixels  and ReadPixels  formats. The second column gives a description of and the number and order of elements in a group.

By default the values of each GL data type are interpreted as they would be specified in the language of the client's GL binding. If UNPACK_SWAP_BYTES is enabled, however, then the values are interpreted with the bit orderings modified as per Table 3.6. The modified bit orderings are defined only if the GL data type ubyte has eight bits, and then for each specific GL data type only if that type is represented with 8, 16, or 32 bits.

  
Table 3.6: Bit ordering modification of elements when UNPACK_SWAP_BYTES is enabled. These reorderings are defined only when GL data type ubyte has 8 bits, and then only for GL data types with 8, 16, or 32 bits. Bit 0 is the least significant.

The groups in memory are treated as being arranged in a rectangle. This rectangle consists of a series of rows, with the first element of the first group of the first row pointed to by the pointer passed to DrawPixels . If the value of UNPACK_ROW_LENGTH is not positive, then the number of groups in a row is width; otherwise the number of groups is UNPACK_ROW_LENGTH. If p indicates the location in memory of the first element of the first row, then the first element of the Nth row is indicated by

where N is the row number (counting from zero) and k is defined as

where n is the number of elements in a group, l is the number of groups in the row, a is the value of UNPACK_ALIGNMENT, and s is the size, in units of GL ubytes, of an element. If the number of bits per element is not 1, 2, 4, or 8 times the number of bits in a GL ubyte, then k = nl for all values of a.

There is a mechanism for selecting a sub-rectangle of groups from a larger containing rectangle. This mechanism relies on three integer parameters: UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, and UNPACK_SKIP_PIXELS. Before obtaining the first group from memory, the pointer supplied to DrawPixels  is effectively advanced by elements. Then width groups are obtained from contiguous elements in memory (without advancing the pointer), after which the pointer is advanced by k elements. height sets of width groups of values are obtained this way. See Figure 3.8.

  
Figure 3.8: Selecting a subimage from an image. The indicated parameter names are prefixed by UNPACK_ for DrawPixels  and by PACK_ for ReadPixels .

Calling DrawPixels  with a type of BITMAP is a special case in which the data are a series of GL ubyte values. Each ubyte value specifies 8 1-bit elements with its 8 least-significant bits. The 8 single-bit elements are ordered from most significant to least significant if the value of UNPACK_LSB_FIRST is FALSE; otherwise, the ordering is from least significant to most significant. The values of bits other than the 8 least significant in each ubyte are not significant.

The first element of the first row is the first bit (as defined above) of the ubyte pointed to by the pointer passed to DrawPixels . The first element of the second row is the first bit (again as defined above) of the ubyte at location p+k, where k is computed as

There is a mechanism for selecting a sub-rectangle of elements from a BITMAP image as well. Before obtaining the first element from memory, the pointer supplied to DrawPixels  is effectively advanced by ubytes. Then UNPACK_SKIP_PIXELS 1-bit elements are ignored, and the subsequent width 1-bit elements are obtained, without advancing the ubyte pointer, after which the pointer is advanced by k ubytes. height sets of width elements are obtained this way.