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