| 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. |