1Name 2 3 APPLE_row_bytes 4 5Name Strings 6 7 GL_APPLE_row_bytes 8 9Contributors 10 11 Andrew Barnes 12 John Rosasco 13 14Contact 15 16 John Rosasco, Apple Computer (jdr 'at' apple.com) 17 18Status 19 20 TBD 21 22Version 23 24 Last Modified: October 17, 2006 25 Revision: #2 26 27Number 28 29 372 30 31Dependencies 32 33 OpenGL 1.1 is required. 34 35 Written based on the wording of the OpenGL 2.1 specification. 36 37Overview 38 39 The APPLE_row_bytes extension was developed to relax the limitations 40 within GL regarding the packing and unpacking of pixel data from 41 arbitrary arrangements in memory. 42 43 Prior to this extension, similar, albeit more restrictive, functionality 44 existed in GL using pixel storage modes for unpacking, packing, and 45 alignment. The limitation of the existing mechanism lies primarily in how 46 packing or unpacking of data is specified with pixel atomicity rather than 47 basic machine units. To some extent, this pixel granularity can be 48 overcome using pixel storage modes GL_UNPACK_ALIGNMENT and 49 GL_PACK_ALIGNMENT. Both of these parameters are specified in basic 50 machine units but their range of possible values is restricted and even 51 then they do not allow for the packing and unpacking of pixel data in a 52 fully arbitrary manner. 53 54 Consider this simple example: 55 56 Consider a column of pixels in memory. The pixels are of GL_RGB 57 format and GL_UNSIGNED_BYTE type resulting in 3 bytes per pixel. 58 Now consider that this column of pixel data was arranged in memory 59 such that each row of the image (in this case each pixel) has two 60 bytes padding or space between them. 61 62 Each row of 1 pixel then has 5 bytes. An attempting to express this 63 memory arrangement with existing pixel storage semantics would 64 naturally start with a GL_UNPACK_ROW_LENGTH of 1 because there is 65 one pixel per row. However, no valid value of GL_UNPACK_ALIGNMENT, 66 1, 2, 4, or 8, will allow the proper row padding to express this 67 memory arrangement. 68 69Glossary 70 71 Storage mode class - delineation of packing vs unpacking pixel storage 72 mode values. 73 74Issues 75 76 What happens when row bytes pixel storage values are specified in 77 conjunction with row length or alignment values ? 78 79 Specifying non-zero row bytes packing or unpacking values will 80 override all values specified for both row length and alignment 81 of the same class. In other words, if GL_PACK_ROW_BYTES is 82 specified as non-zero, it overrides values of both 83 GL_PACK_ROW_LENGTH and GL_PACK_ALIGNMENT. The same scenario is 84 true of unpacking pixel storage parameters. 85 86 How do you switch between using row length and alignment values to row 87 bytes values ? 88 89 Set the row bytes value to zero for the same storage mode class 90 to use conventional row length and alignment semantics. Set 91 row bytes to non-zero to use APPLE_row_bytes semantics. 92 93 Does the semantics for packing need to match that of unpacking ? 94 (i.e. if you are unpacking with row bytes semantics do you need to pack with 95 row bytes ?) 96 97 No. Storage mode class semantics are independent. 98 99 If retrieving data from GL, such as in a ReadPixels() or 100 GetTexImage(), do the unpack settings have any effect ? 101 102 Yes. If the format and type of the data of a source or destination 103 for packing or unpacking is not known, as in the case of a 104 ReadPixels() call or a GetTexImage() call, the storage mode class 105 values for the unknown arrangement should be set to GL default 106 values. In the case cited above, the packing modes can be specified 107 but the unpacking modes should be set to default GL values. 108 109 What are the default values for GL_PACK_ROW_BYTES and GL_UNPACK_ROW_BYTES 110 ? 111 Zero. 112 113 114New Procedures and Functions 115 116 None. 117 118 119Errors 120 121 None. 122 123 124New Types 125 126 None. 127 128 129New Tokens 130 131 Accepted by the <pname> parameter of PixelStorei and the <pname> 132 parameter of GetIntegerv: 133 134 PACK_ROW_BYTES_APPLE 0x8A15 135 UNPACK_ROW_BYTES_APPLE 0x8A16 136 137 138New State 139 140 Get Value Get Command Type Value Attrib 141 --------- ----------- ---- ------- ------ 142 PACK_ROW_BYTES_APPLE GetIntegerv Z+ 0 client_pixel_store 143 UNPACK_ROW_BYTES_APPLE GetIntegerv Z+ 0 client_pixel_store 144 145 146 147Additions to table 3.1 of the 2.1 specification (PixelStore parameters (write)): 148 149 Parameter Name Type Initial Value Valid Range 150 UNPACK_ROW_BYTES_APPLE integer 0 [0, inf] 151 152 153Additions to table 4.5 of the 2.1 specification (PixelStore parameters (read)): 154 155 Parameter Name Type Initial Value Valid Range 156 PACK_ROW_BYTES_APPLE integer 0 [0, inf] 157 158 159Version History 160 161#1 - Initial document. 162 163#2 - Added state segment. 164