blob: 6b8b5bfb0608a8585971abfe90b0172fe8a05e19 [file] [log] [blame]
Name
APPLE_row_bytes
Name Strings
GL_APPLE_row_bytes
Contributors
Andrew Barnes
John Rosasco
Contact
John Rosasco, Apple Computer (jdr 'at' apple.com)
Status
TBD
Version
Last Modified: October 17, 2006
Revision: #2
Number
372
Dependencies
OpenGL 1.1 is required.
Written based on the wording of the OpenGL 2.1 specification.
Overview
The APPLE_row_bytes extension was developed to relax the limitations
within GL regarding the packing and unpacking of pixel data from
arbitrary arrangements in memory.
Prior to this extension, similar, albeit more restrictive, functionality
existed in GL using pixel storage modes for unpacking, packing, and
alignment. The limitation of the existing mechanism lies primarily in how
packing or unpacking of data is specified with pixel atomicity rather than
basic machine units. To some extent, this pixel granularity can be
overcome using pixel storage modes GL_UNPACK_ALIGNMENT and
GL_PACK_ALIGNMENT. Both of these parameters are specified in basic
machine units but their range of possible values is restricted and even
then they do not allow for the packing and unpacking of pixel data in a
fully arbitrary manner.
Consider this simple example:
Consider a column of pixels in memory. The pixels are of GL_RGB
format and GL_UNSIGNED_BYTE type resulting in 3 bytes per pixel.
Now consider that this column of pixel data was arranged in memory
such that each row of the image (in this case each pixel) has two
bytes padding or space between them.
Each row of 1 pixel then has 5 bytes. An attempting to express this
memory arrangement with existing pixel storage semantics would
naturally start with a GL_UNPACK_ROW_LENGTH of 1 because there is
one pixel per row. However, no valid value of GL_UNPACK_ALIGNMENT,
1, 2, 4, or 8, will allow the proper row padding to express this
memory arrangement.
Glossary
Storage mode class - delineation of packing vs unpacking pixel storage
mode values.
Issues
What happens when row bytes pixel storage values are specified in
conjunction with row length or alignment values ?
Specifying non-zero row bytes packing or unpacking values will
override all values specified for both row length and alignment
of the same class. In other words, if GL_PACK_ROW_BYTES is
specified as non-zero, it overrides values of both
GL_PACK_ROW_LENGTH and GL_PACK_ALIGNMENT. The same scenario is
true of unpacking pixel storage parameters.
How do you switch between using row length and alignment values to row
bytes values ?
Set the row bytes value to zero for the same storage mode class
to use conventional row length and alignment semantics. Set
row bytes to non-zero to use APPLE_row_bytes semantics.
Does the semantics for packing need to match that of unpacking ?
(i.e. if you are unpacking with row bytes semantics do you need to pack with
row bytes ?)
No. Storage mode class semantics are independent.
If retrieving data from GL, such as in a ReadPixels() or
GetTexImage(), do the unpack settings have any effect ?
Yes. If the format and type of the data of a source or destination
for packing or unpacking is not known, as in the case of a
ReadPixels() call or a GetTexImage() call, the storage mode class
values for the unknown arrangement should be set to GL default
values. In the case cited above, the packing modes can be specified
but the unpacking modes should be set to default GL values.
What are the default values for GL_PACK_ROW_BYTES and GL_UNPACK_ROW_BYTES
?
Zero.
New Procedures and Functions
None.
Errors
None.
New Types
None.
New Tokens
Accepted by the <pname> parameter of PixelStorei and the <pname>
parameter of GetIntegerv:
PACK_ROW_BYTES_APPLE 0x8A15
UNPACK_ROW_BYTES_APPLE 0x8A16
New State
Get Value Get Command Type Value Attrib
--------- ----------- ---- ------- ------
PACK_ROW_BYTES_APPLE GetIntegerv Z+ 0 client_pixel_store
UNPACK_ROW_BYTES_APPLE GetIntegerv Z+ 0 client_pixel_store
Additions to table 3.1 of the 2.1 specification (PixelStore parameters (write)):
Parameter Name Type Initial Value Valid Range
UNPACK_ROW_BYTES_APPLE integer 0 [0, inf]
Additions to table 4.5 of the 2.1 specification (PixelStore parameters (read)):
Parameter Name Type Initial Value Valid Range
PACK_ROW_BYTES_APPLE integer 0 [0, inf]
Version History
#1 - Initial document.
#2 - Added state segment.