1Name 2 3 EXT_packed_pixels 4 5Name Strings 6 7 GL_EXT_packed_pixels 8 9Version 10 11 $Date: 1997/09/22 23:23:58 $ $Revision: 1.21 $ 12 13Number 14 15 23 16 17Dependencies 18 19 EXT_abgr affects the definition of this extension 20 EXT_texture3D affects the definition of this extension 21 EXT_subtexture affects the definition of this extension 22 EXT_histogram affects the definition of this extension 23 EXT_convolution affects the definition of this extension 24 SGI_color_table affects the definition of this extension 25 SGIS_texture4D affects the definition of this extension 26 EXT_cmyka affects the definition of this extension 27 28Overview 29 30 This extension provides support for packed pixels in host memory. A 31 packed pixel is represented entirely by one unsigned byte, one 32 unsigned short, or one unsigned integer. The fields with the packed 33 pixel are not proper machine types, but the pixel as a whole is. Thus 34 the pixel storage modes, including PACK_SKIP_PIXELS, PACK_ROW_LENGTH, 35 PACK_SKIP_ROWS, PACK_IMAGE_HEIGHT_EXT, PACK_SKIP_IMAGES_EXT, 36 PACK_SWAP_BYTES, PACK_ALIGNMENT, and their unpacking counterparts all 37 work correctly with packed pixels. 38 39New Procedures and Functions 40 41 None 42 43New Tokens 44 45 Accepted by the <type> parameter of DrawPixels, ReadPixels, TexImage1D, 46 TexImage2D, GetTexImage, TexImage3DEXT, TexSubImage1DEXT, 47 TexSubImage2DEXT, TexSubImage3DEXT, GetHistogramEXT, GetMinmaxEXT, 48 ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT, 49 GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT, 50 GetSeparableFilterEXT, ColorTableSGI, GetColorTableSGI, TexImage4DSGIS, 51 and TexSubImage4DSGIS: 52 53 UNSIGNED_BYTE_3_3_2_EXT 0x8032 54 UNSIGNED_SHORT_4_4_4_4_EXT 0x8033 55 UNSIGNED_SHORT_5_5_5_1_EXT 0x8034 56 UNSIGNED_INT_8_8_8_8_EXT 0x8035 57 UNSIGNED_INT_10_10_10_2_EXT 0x8036 58 59Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 60 61 None 62 63Additions to Chapter 3 of the 1.0 Specification (Rasterization) 64 65 The five tokens defined by this extension are added to Table 3.4: 66 67 <type> Parameter Corresponding Special 68 Token Value GL Data Type Interpretation 69 ---------------- ------------- -------------- 70 UNSIGNED_BYTE ubyte No 71 BYTE byte No 72 UNSIGNED_SHORT ushort No 73 SHORT short No 74 UNSIGNED_INT uint No 75 INT int No 76 FLOAT float No 77 BITMAP ubyte Yes 78 UNSIGNED_BYTE_3_3_2_EXT ubyte Yes 79 UNSIGNED_SHORT_4_4_4_4_EXT ushort Yes 80 UNSIGNED_SHORT_5_5_5_1_EXT ushort Yes 81 UNSIGNED_INT_8_8_8_8_EXT uint Yes 82 UNSIGNED_INT_10_10_10_2_EXT uint Yes 83 84 Table 3.4: DrawPixels and ReadPixels <type> parameter values and the 85 corresponding GL data types. Refer to table 2.2 for definitions of 86 GL data types. Special interpretations are described near the end 87 of section 3.6.3. 88 89 [Section 3.6.3 of the GL Specification (Rasterization of Pixel 90 Rectangles) is rewritten as follows:] 91 92 3.6.3 Rasterization of Pixel Rectangles 93 94 The process of drawing pixels encoded in host memory is diagrammed in 95 Figure 3.7. We describe the stages of this process in the order in which 96 they occur. 97 98 Pixels are drawn using 99 100 void DrawPixels(sizei width, 101 sizei height, 102 enum format, 103 enum type, 104 void* data); 105 106 <format> is a symbolic constant indicating what the values in memory 107 represent. <width> and <height> are the width and height, respectively, 108 of the pixel rectangle to be drawn. <data> is a pointer to the data to 109 be drawn. These data are represented with one of seven GL data types, 110 specified by <type>. The correspondence between the thirteen <type> 111 token values and the GL data types they indicate is given in Table 3.4. 112 If the GL is in color index mode and <format> is not one of COLOR_INDEX, 113 STENCIL_INDEX, or DEPTH_COMPONENT, then the error INVALID_OPERATION 114 occurs. Some additional constraints on the combinations of <format> 115 and <type> values that are accepted are discussed below. 116 117 Unpacking 118 119 Data are taken from host memory as a sequence of signed or unsigned bytes 120 (GL data types byte and ubyte), signed or unsigned short integers (GL data 121 types short and ushort), signed or unsigned integers (GL data types int 122 and uint), or floating-point values (GL data type float). These elements 123 are grouped into sets of one, two, three, four, or five values, depending 124 on the <format>, to form a group. Table 3.5 summarizes the format of 125 groups obtained from memory. It also indicates those formats that yield 126 indices and those that yield components. 127 128 Target 129 Format Name Buffer Element Meaning and Order 130 ----------- ------ ------------------------- 131 COLOR_INDEX Color Color index 132 STENCIL_INDEX Stencil Stencil index 133 DEPTH_COMPONENT Depth Depth component 134 RED Color R component 135 GREEN Color G component 136 BLUE Color B component 137 ALPHA Color A component 138 RGB Color R, G, B components 139 RGBA Color R, G, B, A components 140 ABGR_EXT Color A, B, G, R components 141 CMYK_EXT Color Cyan, Magenta, Yellow, Black components 142 CMYKA_EXT Color Cyan, Magenta, Yellow, Black, A components 143 LUMINANCE Color Luminance component 144 LUMINANCE_ALPHA Color Luminance, A components 145 146 Table 3.5: DrawPixels and ReadPixels formats. The third column 147 gives a description of and the number and order of elements in a 148 group. 149 150 By default the values of each GL data type are interpreted as they would 151 be specified in the language of the client's GL binding. If 152 UNPACK_SWAP_BYTES is set to TRUE, however, then the values are 153 interpreted with the bit orderings modified as per the table below. The 154 modified bit orderings are defined only if the GL data type ubyte has 155 eight bits, and then for each specific GL data type only if that type 156 is represented with 8, 16, or 32 bits. 157 158 Element Default 159 Size Bit Ordering Modified Bit Ordering 160 ------- ------------ --------------------- 161 8-bit [7..0] [7..0] 162 16-bit [15..0] [7..0] [15..8] 163 32-bit [31..0] [7..0] [15..8] [23..16] [31..24] 164 165 Table: Bit ordering modification of elements when UNPACK_SWAP_BYTES 166 is TRUE. These reorderings are defined only when GL data type ubyte 167 has 8 bits, and then only for GL data types with 8, 16, or 32 bits. 168 169 The groups in memory are treated as being arranged in a rectangle. This 170 rectangle consists of a series of rows, with the first element of the 171 first group of the first row pointed to by the pointer passed to 172 DrawPixels. If the value of UNPACK_ROW_LENGTH is not positive, then the 173 number of groups in a row is <width>; otherwise the number of groups is 174 UNPACK_ROW_LENGTH. If the first element of the first row is at location 175 p in memory, then the location of the first element of the Nth row is 176 177 p + Nk 178 179 where N is the row number (counting from zero) and k is defined as 180 181 / nl s >= a 182 k = < 183 \ a/s * ceiling(snl/a) s < a 184 185 where n is the number of elements in a group, l is the number of groups 186 in a row, a is the value of UNPACK_ALIGNMENT, and s is the size, 187 in units of GL ubytes, of an element. If the number of bits per 188 element is not 1, 2, 4, or 8 times the number of bits in a GL ubyte, 189 then k = nl for all values of a. 190 191 There is a mechanism for selecting a sub-rectangle of groups from a 192 larger containing rectangle. This mechanism relies on three integer 193 parameters: UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, and UNPACK_SKIP_PIXELS. 194 Before obtaining the first group from memory, the pointer supplied to 195 DrawPixels is effectively advanced by 196 197 UNPACK_SKIP_PIXELS * n + UNPACK_SKIP_ROWS * k 198 199 elements. Then <width> groups are obtained from contiguous elements 200 in memory (without advancing the pointer), after which the pointer is 201 advanced by k elements. <height> sets of <width> groups of values are 202 obtained this way. See Figure 3.8. 203 204 Calling DrawPixels with a <type> of UNSIGNED_BYTE_3_3_2, 205 UNSIGNED_SHORT_4_4_4_4, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_INT_8_8_8_8, 206 or UNSIGNED_INT_10_10_10_2 is a special case in which all the elements 207 of each group are packed into a single unsigned byte, unsigned short, 208 or unsigned int, depending on the type. The number of elements per 209 packed pixel is fixed by the type, and must match the number of 210 elements per group indicated by the <format> parameter. (See the table 211 below.) The error INVALID_OPERATION is generated if a mismatch occurs. 212 213 GL Number 214 <type> Parameter Data of Matching 215 Token Name Type Elements Pixel Formats 216 ---------------- ---- -------- ------------- 217 218 UNSIGNED_BYTE_3_3_2_EXT ubyte 3 RGB 219 UNSIGNED_SHORT_4_4_4_4_EXT ushort 4 RGBA,ABGR_EXT,CMYK_EXT 220 UNSIGNED_SHORT_5_5_5_1_EXT ushort 4 RGBA,ABGR_EXT,CMYK_EXT 221 UNSIGNED_INT_8_8_8_8_EXT uint 4 RGBA,ABGR_EXT,CMYK_EXT 222 UNSIGNED_INT_10_10_10_2_EXT uint 4 RGBA,ABGR_EXT,CMYK_EXT 223 224 Bitfield locations of the first, second, third, and fourth elements 225 of each packed pixel type are illustrated in the diagrams below. Each 226 bitfield is interpreted as an unsigned integer value. If the base GL 227 type is supported with more than the minimum precision (e.g. a 9-bit 228 byte) the packed elements are right-justified in the pixel. 229 230 231 UNSIGNED_BYTE_3_3_2_EXT: 232 233 7 6 5 4 3 2 1 0 234 +-----------+-----------+-------+ 235 | | | | 236 +-----------+-----------+-------+ 237 238 first second third 239 element element element 240 241 242 UNSIGNED_SHORT_4_4_4_4_EXT: 243 244 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 245 +---------------+---------------+---------------+---------------+ 246 | | | | | 247 +---------------+---------------+---------------+---------------+ 248 249 first second third fourth 250 element element element element 251 252 253 UNSIGNED_SHORT_5_5_5_1_EXT: 254 255 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 256 +-------------------+-------------------+-------------------+---+ 257 | | | | | 258 +-------------------+-------------------+-------------------+---+ 259 260 first second third fourth 261 element element element element 262 263 264 UNSIGNED_INT_8_8_8_8_EXT: 265 266 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 267 +-----------------------+-----------------------+-----------------------+-----------------------+ 268 | | | | | 269 +-----------------------+-----------------------+-----------------------+-----------------------+ 270 271 first second third fourth 272 element element element element 273 274 275 UNSIGNED_INT_10_10_10_2_EXT: 276 277 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 278 +-----------------------------+-----------------------------+-----------------------------+-----+ 279 | | | | | 280 +-----------------------------+-----------------------------+-----------------------------+-----+ 281 282 first second third fourth 283 element element element element 284 285 286 The assignment of elements to fields in the packed pixel is as 287 described in the table below: 288 289 First Second Third Fourth 290 Format Element Element Element Element 291 ------ ------- ------- ------- ------- 292 RGB red green blue 293 RGBA red green blue alpha 294 ABGR_EXT alpha blue green red 295 CMYK_EXT cyan magenta yellow black 296 297 Byte swapping, if enabled, is performed before the elements are 298 extracted from each pixel. The above discussions of row length and 299 image extraction are valid for packed pixels, if "group" is substituted 300 for "element" and the number of elements per group is understood to 301 be one. 302 303 Calling DrawPixels with a <type> of BITMAP is a special case in which 304 the data are a series of GL ubyte values. Each ubyte value specifies 305 8 1-bit elements with its 8 least-significant bits. The 8 single-bit 306 elements are ordered from most significant to least significant if the 307 value of UNPACK_LSB_FIRST is FALSE; otherwise, the ordering is from 308 least significant to most significant. The values of bits other than 309 the 8 least significant in each ubyte are not significant. 310 311 The first element of the first row is the first bit (as defined above) 312 of the ubyte pointed to by the pointer passed to DrawPixels. The first 313 element of the second row is the first bit (again as defined above) of 314 the ubyte at location p+k, where k is computed as 315 316 k = a * ceiling(nl/8a) 317 318 There is a mechanism for selecting a sub-rectangle of elements from 319 a BITMAP image as well. Before obtaining the first element from memory, 320 the pointer supplied to DrawPixels is effectively advanced by 321 322 UNPACK_SKIP_ROWS * k 323 324 ubytes. Then UNPACK_SKIP_PIXELS 1-bit elements are ignored, and the 325 subsequent <width> 1-bit elements are obtained, without advancing the 326 ubyte pointer, after which the pointer is advanced by k ubytes. <height> 327 sets of <width> elements are obtained this way. 328 329 Conversion to floating-point 330 331 This step applies only to groups of components. It is not performed on 332 indices. Each element in a group is converted to a floating-point value 333 according to the appropriate formula in Table 2.4 (section 2.12). 334 Unsigned integer bitfields extracted from packed pixels are interpreted 335 using the formula 336 337 f = c / ((2**N)-1) 338 339 where c is the value of the bitfield (interpreted as an unsigned 340 integer), N is the number of bits in the bitfield, and the division is 341 performed in floating point. 342 343 [End of changes to Section 3.6.3] 344 345 If this extension is supported, all commands that accept pixel data 346 also accept packed pixel data. These commands are DrawPixels, 347 TexImage1D, TexImage2D, TexImage3DEXT, TexSubImage1DEXT, 348 TexSubImage2DEXT, TexSubImage3DEXT, ConvolutionFilter1DEXT, 349 ConvolutionFilter2DEXT, ConvolutionFilter3DEXT, SeparableFilter2DEXT, 350 SeparableFilter3DEXT, ColorTableSGI, TexImage4DSGIS, and 351 TexSubImage4DSGIS. 352 353Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations 354and the Framebuffer) 355 356 [Make the following changes to Section 4.3.2 (Reading Pixels):] 357 358 Final Conversion 359 360 For an index, if the <type> is not FLOAT, final conversion consists of 361 masking the index with the value given in Table 4.6; if the <type> is 362 FLOAT, then the integer index is converted to a GL float data value. 363 For a component, each component is first clamped to [0,1]. Then, 364 the appropriate conversion formula from Table 4.7 is applied to the 365 component. 366 367 <type> Parameter Index Mask 368 ---------------- ---------- 369 UNSIGNED_BYTE 2**8 - 1 370 BITMAP 1 371 BYTE 2**7 - 1 372 UNSIGNED_SHORT 2**16 - 1 373 SHORT 2**15 - 1 374 UNSIGNED_INT 2**32 - 1 375 INT 2**31 - 1 376 377 Table 4.6: Index masks used by ReadPixels. Floating point data 378 are not masked. 379 380 <type> GL Data Component 381 Parameter Type Conversion Formula 382 --------- ------- ------------------ 383 UNSIGNED_BYTE ubyte c = ((2**8)-1)*f 384 BYTE byte c = (((2**8)-1)*f-1)/2 385 UNSIGNED_SHORT ushort c = ((2**16)-1)*f 386 SHORT short c = (((2**16)-1)*f-1)/2 387 UNSIGNED_INT uint c = ((2**32)-1)*f 388 INT int c = (((2**32)-1)*f-1)/2 389 FLOAT float c = f 390 UNSIGNED_BYTE_3_3_2_EXT ubyte c = ((2**N)-1)*f 391 UNSIGNED_SHORT_4_4_4_4_EXT ushort c = ((2**N)-1)*f 392 UNSIGNED_SHORT_5_5_5_1_EXT ushort c = ((2**N)-1)*f 393 UNSIGNED_INT_8_8_8_8_EXT uint c = ((2**N)-1)*f 394 UNSIGNED_INT_10_10_10_2_EXT uint c = ((2**N)-1)*f 395 396 Table 4.7: Reversed component conversions - used when component data 397 are being returned to client memory. Color, normal, and depth 398 components are converted from the internal floating-point 399 representation (f) to a datum of the specified GL data type (c) using 400 the equations in this table. All arithmetic is done in the internal 401 floating point format. These conversions apply to component data 402 returned by GL query commands and to components of pixel data returned 403 to client memory. The equations remain the same even if the 404 implemented ranges of the GL data types are greater than the minimum 405 required ranges. (Refer to table 2.2.) Equations with N as the 406 exponent are performed for each bitfield of the packed data type, 407 with N set to the number of bits in the bitfield. 408 409 Placement in Client Memory 410 411 Groups of elements are placed in memory just as they are taken from memory 412 for DrawPixels. That is, the ith group of the jth row (corresponding to 413 the ith pixel in the jth row) is placed in memory must where the ith group 414 of the jth row would be taken from for DrawPixels. See Unpacking under 415 section 3.6.3. The only difference is that the storage mode parameters 416 whose names begin with PACK_ are used instead of those whose names begin 417 with UNPACK_. 418 419 [End of changes to Section 4.3.2] 420 421 If this extension is supported, all commands that return pixel data 422 also return packed pixel data. These commands are ReadPixels, 423 GetTexImage, GetHistogramEXT, GetMinmaxEXT, GetConvolutionFilterEXT, 424 GetSeparableFilterEXT, and GetColorTableSGI. 425 426Additions to Chapter 5 of the 1.0 Specification (Special Functions) 427 428 None 429 430Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 431 432 None 433 434Additions to the GLX Specification 435 436 None 437 438GLX Protocol 439 440 None 441 442Dependencies on EXT_abgr 443 444 If EXT_abgr is not implemented, then the references to ABGR_EXT in this 445 file are invalid, and should be ignored. 446 447Dependencies on EXT_texture3D 448 449 If EXT_texture3D is not implemented, then the references to 450 TexImage3DEXT in this file are invalid, and should be ignored. 451 452Dependencies on EXT_subtexture 453 454 If EXT_subtexture is not implemented, then the references to 455 TexSubImage1DEXT, TexSubImage2DEXT, and TexSubImage3DEXT in this file 456 are invalid, and should be ignored. 457 458Dependencies on EXT_histogram 459 460 If EXT_histogram is not implemented, then the references to 461 GetHistogramEXT and GetMinmaxEXT in this file are invalid, and should be 462 ignored. 463 464Dependencies on EXT_convolution 465 466 If EXT_convolution is not implemented, then the references to 467 ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT, 468 GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT, and 469 GetSeparableFilterEXT in this file are invalid, and should be ignored. 470 471Dependencies on SGI_color_table 472 473 If SGI_color_table is not implemented, then the references to 474 ColorTableSGI and GetColorTableSGI in this file are invalid, and should 475 be ignored. 476 477Dependencies on SGIS_texture4D 478 479 If SGIS_texture4D is not implemented, then the references to 480 TexImage4DSGIS and TexSubImage4DSGIS in this file are invalid, and should 481 be ignored. 482 483Dependencies on EXT_cmyka 484 485 If EXT_cmyka is not implemented, then the references to CMYK_EXT and 486 CMYKA_EXT in this file are invalid, and should be ignored. 487 488Errors 489 490 [For the purpose of this enumeration of errors, GenericPixelFunction 491 represents any OpenGL function that accepts or returns pixel data, using 492 parameters <type> and <format> to define the type and format of that 493 data. Currently these functions are DrawPixels, ReadPixels, TexImage1D, 494 TexImage2D, GetTexImage, TexImage3DEXT, TexSubImage1DEXT, 495 TexSubImage2DEXT, TexSubImage3DEXT, GetHistogramEXT, GetMinmaxEXT, 496 ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT, 497 GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT, 498 GetSeparableFilterEXT, ColorTableSGI, GetColorTableSGI, TexImage4DSGIS, 499 and TexSubImage4DSGIS.] 500 501 INVALID_OPERATION is generated by GenericPixelFunction if its <type> 502 parameter is UNSIGNED_BYTE_3_3_2_EXT and its <format> parameter does not 503 specify three components. Currently the only 3-component format is RGB. 504 505 INVALID_OPERATION is generated by GenericPixelFunction if its <type> 506 parameter is UNSIGNED_SHORT_4_4_4_4_EXT, UNSIGNED_SHORT_5_5_5_1_EXT, 507 UNSIGNED_INT_8_8_8_8_EXT, or UNSIGNED_INT_10_10_10_2_EXT and its 508 <format> parameter does not specify four components. Currently the only 509 4-component formats are RGBA, ABGR_EXT, and CMYK_EXT. 510 511New State 512 513 None 514 515New Implementation Dependent State 516 517 None 518