1Name 2 3 ARB_compressed_texture_pixel_storage 4 5Name Strings 6 7 GL_ARB_compressed_texture_pixel_storage 8 9Contact 10 11 Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com) 12 13Contributors 14 15 Bruce Merry, ARM 16 Daniel Koch, TransGaming 17 Jeff Bolz, NVIDIA 18 Pat Brown, NVIDIA 19 Patrick Doane, Blizzard 20 21Notice 22 23 Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. Approved by the ARB on 2011/06/20. 39 Approved by the Khronos Promoters on 2011/07/29. 40 41Version 42 43 Last Modified Date: April 26, 2011 44 Revision: 8 45 46Number 47 48 ARB Extension #110 49 50Dependencies 51 52 OpenGL 1.2 is required. 53 54 This extension is written against The OpenGL 4.1 (Compatibility Profile) 55 specification. 56 57Overview 58 59 This extension expands the functionality of the PixelStore modes 60 to allow UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, UNPACK_SKIP_PIXELS, 61 UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES to affect the operation of 62 CompressedTexImage*D and CompressedTexSubImage*D. Similarly, it 63 also allows PACK_ROW_LENGTH, PACK_SKIP_ROWS, PACK_SKIP_PIXELS, 64 PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES to affect the operation of 65 GetCompressedTexImage*D. This allows data to be transferred 66 to or from a specified sub-rectangle of a larger compressed image. 67 68 This extension is designed primarily to support compressed image 69 formats with fixed-size blocks. To use this new mechanism, an 70 application should program new parameters UNPACK_COMPRESSED_BLOCK_ 71 {WIDTH,HEIGHT,DEPTH,SIZE} to indicate the number of texels in each 72 dimension of the fixed-size block as well as the number of bytes 73 consumed by each block. These parameters, in addition to the 74 existing PixelStore parameters, are used to identify a collection 75 of bytes in client memory or a buffer object's data store to use 76 as compressed texture data. This operation is unlikely to have 77 the desired results if the client programs a block size inconsistent 78 with the underlying compressed image format, or if the compressed 79 image format has variable-sized blocks. 80 81New Procedures and Functions 82 83 None 84 85New Tokens 86 87 Accepted by the <pname> parameter of PixelStore[fi], GetBooleanv, 88 GetIntegerv, GetInteger64v, GetFloatv, and GetDoublev: 89 90 UNPACK_COMPRESSED_BLOCK_WIDTH 0x9127 91 UNPACK_COMPRESSED_BLOCK_HEIGHT 0x9128 92 UNPACK_COMPRESSED_BLOCK_DEPTH 0x9129 93 UNPACK_COMPRESSED_BLOCK_SIZE 0x912A 94 PACK_COMPRESSED_BLOCK_WIDTH 0x912B 95 PACK_COMPRESSED_BLOCK_HEIGHT 0x912C 96 PACK_COMPRESSED_BLOCK_DEPTH 0x912D 97 PACK_COMPRESSED_BLOCK_SIZE 0x912E 98 99Changes to Section 3.7.4 (Pixel Storage Modes and Pixel Buffer Objects), 100page 229 101 102 Replace the section in the first paragraph, page 229 that states: 103 104 "Pixel storage modes affect the operation of TexImage*D, TexSubImage*D, 105 DrawPixels, and ReadPixels (as well as other commands; see sections 3.6.2 106 and 3.8) when one of these commands is issued." 107 108 With the following: 109 110 "Pixel storage modes affect the operation of TexImage*D, TexSubImage*D, 111 CompressedTexImage*D, CompressedTexSubImage*d, DrawPixels, and ReadPixels 112 (as well as other commands; see sections 3.6.2 and 3.8) when one of these 113 commands is issued." 114 115 Modify Table 3.1 description to: 116 117 "Table 3.1: PixelStore parameters pertaining to one or more of 118 DrawPixels, ColorTable, ColorSubTable, ConvolutionFilter1D, 119 ConvolutionFilter2D, SeparableFilter2D, PolygonStipple, TexImage1D, 120 TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D, 121 CompressedTexImage1D, CompressedTexImage2D, CompressedTexImage3D, 122 CompressedTexSubImage1D, CompressedTexSubImage2D and 123 CompressedTexSubImage3D." 124 125 Add to Table 3.1 contents with the following new entries: 126 127 Parameter Name Type Initial Value Valid Range 128 ------------------------------------------------------------------------- 129 UNPACK_COMPRESSED_BLOCK_WIDTH integer 0 [0,inf) 130 UNPACK_COMPRESSED_BLOCK_HEIGHT integer 0 [0,inf) 131 UNPACK_COMPRESSED_BLOCK_DEPTH integer 0 [0,inf) 132 UNPACK_COMPRESSED_BLOCK_SIZE integer 0 [0,inf) 133 134Changes to Section 3.9.5 (Compressed Texture Images), page 297 135 136 In the paragraph that starts "For all other compressed internal 137 formats..." remove the following sentence: 138 139 "All pixel storage and pixel transfer modes are ignored when decoding a 140 compressed texture image." 141 142 Add a new paragraph which states: 143 144 "If the compressed data are arranged into fixed-size blocks of texels the 145 pixel storage modes can be used to select a sub-rectangle from a larger 146 containing rectangle. These pixel storage modes operate in the same 147 way as they do for TexImage*D and as described in section 3.7.4. By 148 default the pixel storage modes UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, 149 UNPACK_SKIP_PIXELS, UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES are 150 ignored for compressed images. To enable UNPACK_SKIP_PIXELS and 151 UNPACK_ROW_LENGTH both UNPACK_COMPRESSED_BLOCK_SIZE and 152 UNPACK_COMPRESSED_BLOCK_WIDTH must be non-zero. To also enable 153 UNPACK_SKIP_ROWS and UNPACK_IMAGE_HEIGHT, UNPACK_COMPRESSED_BLOCK_HEIGHT 154 must be non-zero. And to also enable UNPACK_SKIP_IMAGES, 155 UNPACK_COMPRESSED_BLOCK_DEPTH must be non-zero. Use 156 UNPACK_COMPRESSED_BLOCK_WIDTH to specify the block width in pixels, 157 UNPACK_COMPRESSED_BLOCK_HEIGHT to specify the block height in pixels, 158 UNPACK_COMPRESSED_BLOCK_DEPTH to specify the block depth in pixels and 159 UNPACK_COMPRESSED_BLOCK_SIZE to specify the block size in bytes. All 160 parameters need to be consistent with the compressed format to produce 161 the desired results. 162 163 When selecting a sub-rectangle from a compressed image: 164 165 * the UNPACK_SKIP_PIXELS parameter must be a multiple of the 166 UNPACK_COMPRESSED_BLOCK_WIDTH parameter; 167 * the UNPACK_SKIP_ROWS parameter must be a multiple of the 168 UNPACK_COMPRESSED_BLOCK_HEIGHT parameter for CompressedTexImage2D 169 and CompressedTexImage3D; 170 * the UNPACK_SKIP_IMAGES parameter must be a multiple of the 171 UNPACK_COMPRESSED_BLOCK_DEPTH parameter for CompressedTexImage3D. 172 173 The error INVALID_OPERATION will be generated if any of the previous 174 conditions are violated. 175 176 For CompressedTexImage1D the <imageSize> parameter must be equal to: 177 UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) 178 For CompressedTexImage2D the <imageSize> parameter must be equal to: 179 UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT) 180 For CompressedTexImage3D the <imageSize> parameter must be equal to: 181 UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT) * ceil(<depth> / UNPACK_COMPRESSED_BLOCK_DEPTH) 182 183 The error INVALID_VALUE will be generated if <imageSize> does not match 184 this requirement when pixel storage modes are active. 185 186 Based on the definition of Unpacking from Section 3.7.4 for uncompressed 187 images, unpacking compressed images can be defined where: 188 189 * "n", the number of elements in a group, is 1 190 * "s", the size of an element, is UNPACK_COMPRESSED_BLOCK_SIZE 191 * "l", the number of groups in a row, is ceil(UNPACK_ROW_LENGTH / 192 UNPACK_COMPRESSED_BLOCK_WIDTH), where UNPACK_ROW_LENGTH is positive 193 otherwise it's ceil(<length> / UNPACK_COMPRESSED_BLOCK_WIDTH) 194 * "a", the value of UNPACK_ALIGNMENT is ignored and 195 * "k=nl" as is defined for uncompressed images. 196 197 Before obtaining the first compressed image block from memory, the <data> 198 pointer is advanced by (UNPACK_SKIP_PIXELS / 199 UNPACK_COMPRESSED_BLOCK_WIDTH) * "n" + (UNPACK_SKIP_ROWS / 200 UNPACK_COMPRESSED_BLOCK_HEIGHT) * "k" elements. Then ceil(<width> / 201 UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained from contiguous blocks 202 in memory (without advancing the pointer), after which the pointer is 203 advanced by "k" elements. ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT) 204 sets of ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained 205 this way. For three-dimensional compressed images the pointer is advanced 206 by (UNPACK_SKIP_IMAGES / UNPACK_COMPRESSED_BLOCK_DEPTH) times the number 207 of elements in one two-dimensional image before obtaining the first group 208 from memory. Then after <height> rows are obtained the pointer skips over 209 the remaining ceil(UNPACK_IMAGE_HEIGHT / UNPACK_COMPRESSED_BLOCK_HEIGHT) 210 rows, if UNPACK_IMAGE_HEIGHT is positive before starting the next two- 211 dimensional image." 212 213Changes to Section 4.3.2 (Reading Pixels), page 380 214 215 Modify Table 4.7, page 382, description to: 216 217 "Table 4.7: PixelStore parameters pertaining to ReadPixels, 218 GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram, 219 GetMinmax, GetPolygonStipple, GetTexImage, and GetCompressedTexImage." 220 221 Add to Table 4.7 contents with the following new entries: 222 223 Parameter Name Type Initial Value Valid Range 224 ------------------------------------------------------------------------- 225 PACK_COMPRESSED_BLOCK_WIDTH integer 0 [0,inf) 226 PACK_COMPRESSED_BLOCK_HEIGHT integer 0 [0,inf) 227 PACK_COMPRESSED_BLOCK_DEPTH integer 0 [0,inf) 228 PACK_COMPRESSED_BLOCK_SIZE integer 0 [0,inf) 229 230Changes to Section 6.1.4 (Texture Queries), page 446 231 232 In the paragraph that talks about GetCompressedTexImage remove the 233 following sentence: 234 235 "All pixel storage and pixel transfer modes are ignored when returning a 236 compressed texture image." 237 238 Add a new paragraph at this point with the following contents: 239 240 "By default the pixel storage modes PACK_ROW_LENGTH, PACK_SKIP_ROWS, 241 PACK_SKIP_PIXELS, PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are ignored for 242 compressed images. To enable PACK_SKIP_PIXELS and PACK_ROW_LENGTH both 243 PACK_COMPRESSED_BLOCK_SIZE and PACK_COMPRESSED_BLOCK_WIDTH must be non- 244 zero. To also enable PACK_SKIP_ROWS and PACK_IMAGE_HEIGHT, 245 PACK_COMPRESSED_BLOCK_HEIGHT must be non-zero. And to also enable 246 PACK_SKIP_IMAGES, PACK_COMPRESSED_BLOCK_DEPTH must be non-zero. All 247 parameters need to be consistent with the compressed format to produce 248 the desired results. When the pixel storage modes are active, the 249 correspondence of texels to memory locations is as defined for 250 CompressedTexImage3D in section 3.9.5." 251 252Additions to the AGL/GLX/WGL Specifications 253 254 None 255 256Errors 257 258 None 259 260New State 261 262 (Table 6.37, Pixels) add the following: 263 264 Get Value Type Get Command Initial Value Description Section 265 ------------- ---- ----------- ------------- ----------- ------- 266 UNPACK_COMPRESSED_BLOCK_WIDTH Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_WIDTH 3.7.4 267 UNPACK_COMPRESSED_BLOCK_HEIGHT Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_HEIGHT 3.7.4 268 UNPACK_COMPRESSED_BLOCK_DEPTH Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_DEPTH 3.7.4 269 UNPACK_COMPRESSED_BLOCK_SIZE Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_SIZE 3.7.4 270 PACK_COMPRESSED_BLOCK_WIDTH Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_WIDTH 4.3.2 271 PACK_COMPRESSED_BLOCK_HEIGHT Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_HEIGHT 4.3.2 272 PACK_COMPRESSED_BLOCK_DEPTH Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_DEPTH 4.3.2 273 PACK_COMPRESSED_BLOCK_SIZE Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_SIZE 4.3.2 274 275New Implementation Dependent State 276 277 None 278 279Issues 280 281 1) How do indirect rendering implementations deal with this? They don't 282 know what compressed format is used. 283 284 RESOLVED: By specifying the BLOCK sizes in the PixelStore parameters 285 the client side implementation has enough information to transfer the 286 minimal amount of data to satisfy the API request without needing 287 detailed knowledge of the compression format. So from the client 288 to server data transfer point of view, it's still just a memcpy of 289 the client data without interpretation based on the compression 290 format. 291 292 2) Do we enforce that the block size parameters match those of the format 293 being manipulated? 294 295 RESOLVED: No. They are only used for this memcpy operation. The 296 issue is that PixelStore is client state, while the actual format of 297 the texture is server state that may not even be knowable by the 298 client. If the user indicates that he is dealing in 8x2 64-bit blocks, 299 the client may not be able to figure out that it doesn't accurately 300 describe the actual format (e.g., DXT1 using 4x4 64-bit blocks). 301 302 However, we don't really care. These parameters are used (along with 303 the API call parameters) to indicate a collection of bytes to read. 304 The client extracts those bytes and transfers them to the server for 305 further processing. If the byte count isn't consistent with the 306 width/height/internalformat parameters, the server complains. If the 307 byte count is consistent, the server just accepts the data extracted 308 by the client as-is. 309 310 For example, let's say we specified a 16x16 DXT1 image. That would 311 have the server looking for a 4x4 array of blocks (128B total). If 312 the user said the blocks were 8x2 and 64-bit, the client would 313 transmit a 2x8 array of blocks (still 128B). We'd get no error. 314 However, if the image were 12x12, the server would want a 3x3 array 315 of blocks, while the client would want to transmit a 2x6 array of 316 blocks because the rightmost "8x2" blocks are partial and would be 317 padded out as though the image were 16x12. In that case, the byte 318 counts wouldn't be consistent. 319 320 3) Do we need to specify what happens with a hypothetical variable-size 321 block format? 322 323 RESOLVED: These new "block size" parameters are used to collect 324 scattered bytes from user memory into a single block of "sub image" 325 memory, and they don't care what the format is. 326 327 4) Do these new parameters affect TexImage* calls with compressed internal 328 formats? 329 330 RESOLVED: No, they only affect CompressedTexImage*, 331 CompressedTexSubImage* and GetCompressedTexImage* APIs, where the 332 texels specified or queried are specified or returned in compressed 333 form. In desktop OpenGL, it is possible to specify or query texels for 334 textures with compressed internal formats using APIs like TexImage*, 335 using non-compressed <format> and <type> arguments. In these cases, 336 previously existing PixelStore parameters already applied to the 337 specified image. 338 339 5) Should {UN}PACK_ROW_LENGTH and {UN}PACK_IMAGE_HEIGHT be required to be 340 in multiples of the block size? 341 342 RESOLVED: It's not necessary since the rounding in the specified 343 compressed image unpacking will round up to the next block size and 344 produce a valid result. 345 346Revision History 347 348 Rev. Date Author Changes 349 ---- -------- -------- ----------------------------------------------- 350 8 04/26/11 pdaniell Fix language which specifies what parameters 351 need to be non-zero for {UN}PACK_IMAGE_HEIGHT 352 to be used. 353 354 7 04/21/11 pdaniell Add final enum values. 355 356 6 12/15/10 pdaniell Resolve issues 2 and 5. 357 358 5 11/29/10 pdaniell Fix typo. 359 360 4 11/10/10 pdaniell Fixes based on feedback from Bruce and Pat in 361 bug 7016. 362 363 3 11/05/10 pdaniell Resolve issue (2). 364 365 2 11/04/10 pdaniell Fixed typos and feedback from bug 6998. 366 Moved edits from Core to Compatibility profile. 367 Further clarifications from internal review. 368 369 1 10/19/10 pdaniell Initial version. 370