1XXX - Not complete yet!!! 2 3Name 4 5 SGIX_pixel_tiles 6 7Name Strings 8 9 GL_SGIX_pixel_tiles 10 11Version 12 13 $Date: 1995/07/27 17:34:55 $ $Revision: 1.3 $ 14 15Number 16 17 46 18 19Dependencies 20 21 EXT_texture3D affects the definition of this extension 22 EXT_subtexture affects the definition of this extension 23 EXT_convolution is required 24 EXT_texture4D affects the definition of this extension 25 26Overview 27 28 This extension deals with the interaction of existing GL functions that 29 read pixels from memory, applications that use grids of tiles of pixels, 30 and convolution. 31 32 Applications that deal with large multi-dimensional images sometimes 33 break the image into a grid of rectangular tiles of pixels. Such an 34 approach can help control memory use and expedite roaming through an 35 image that is large with respect to the available memory. 36 37 GL functions that cause pixels to be read from memory (e.g., DrawPixels 38 and TexImage2D) assume the pixels are stored as a single series of rows 39 of pixels. The grid of tiles is essentially a sequence of the structures 40 that the pixel reading functions assume. When an application that uses 41 tiling uses a GL function such as DrawPixels, it must iterate 42 through the tiles, either coalescing the tiles into a single tile in 43 preparation for a single GL call or calling the GL function for each tile. 44 45 The convolution operation imposes strict ordering on the way pixels 46 in a subimage that crosses tile boundaries must be transferred: the rows 47 of pixels transferred must span the entire subimage. Applications 48 that use tiles of pixels and convolution must copy the subimage to be 49 transferred from the grid of tiles to a contiguous region, then pass the 50 now-contiguous rows of pixels to the convolution function. If the 51 coalescing of tiles is not needed for some other reason or is not a 52 side effect of some necessary operation, it is just redundant movement 53 of the pixels. 54 55 This extension seeks to eliminate the extra copy of data by extending the 56 existing GL functions to accept, as a source of pixels in memory, a 57 grid of tiles of pixels in addition to the current sequence of rows 58 of pixels. 59 60 61Issues 62 63 * This extension is currently defined for 1 to 4 dimensions. Convolution 64 is the driving force for this extension, yet is defined for only 1 and 65 2 dimensions. Should we remove support in this extension for 3 and 4 66 dimensions (until it exists in a convolution extension)? Should we 67 consider confining the extension to only 2 dimensions? 68 69 * We anticipate accelerators for moving pixels around in various 70 implementations. What is the right way to communicate information 71 between an application and the underlying acceleration 72 code/hardware? We believe that memory alignment will be important, 73 as will some sort of caching. What else should be considered? 74 Are there better ways to express the information? 75 76 * gluScaleImage, gluBuild1DMipmaps, and gluBuild2DMipmaps could be 77 handled similarly in an associated extension. Should this happen? 78 79 * Should EXT_color_table affect this extension? It does have some 80 DrawPixel-like semantics. 81 82Reasoning 83 84 * It is desirable to try to accelerate the GL pixel transfer operations 85 with special hardware or highly optimized code. Imaging applications 86 tend to lose the intended benefit of these optimizations in cases where 87 tiles of pixels are used; significant amounts of time are spent 88 repackaging data to correspond to the GL model and comply with the 89 constraints of convolution. Since support for imaging applications was 90 a primary impetus for the convolution extension, it seems appropriate 91 to extend the model of pixel storage to also support imaging 92 applications. 93 94 * For symmetry in the GL interface it would be reasonable to have 95 this extension cover the storage layout of both source and destination 96 pixels. The assymmetry exists because we are only concerned with 97 sources that will be undergoing convolution. A tiled destination 98 that results from convolution can be filled tile by tile. 99 100 * All the state in this extension is located in the client side. This 101 helps constrain the scope of the extension. No GLX protocol or server 102 side changes need to be made. 103 104New Procedures and Functions 105 106 None 107 108New Tokens 109 110 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 111 GetFloatv, and GetDoublev: 112 113 PIXEL_TILE_BEST_ALIGNMENT_SGIX 114 PIXEL_TILE_CACHE_INCREMENT_SGIX 115 116 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 117 GetFloatv, GetDoublev, PixelStoref, and PixelStorei: 118 119 PIXEL_TILE_WIDTH_SGIX 120 PIXEL_TILE_HEIGHT_SGIX 121 PIXEL_TILE_GRID_WIDTH_SGIX 122 PIXEL_TILE_GRID_HEIGHT_SGIX 123 PIXEL_TILE_GRID_DEPTH_SGIX 124 PIXEL_TILE_CACHE_SIZE_SGIX 125 126Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 127 128 None 129 130Additions to Chapter 3 of the 1.0 Specification (Rasterization) 131 132 The pixel storage modes are augmented to support 3D and 4D image formats 133 in memory as well as this extension. Table 3.1 is replaced with the table 134 below: 135 136 Parameter Name Type Initial Value Valid Range 137 -------------- ---- ------------- ----------- 138 UNPACK_SWAP_BYTES boolean FALSE TRUE/FALSE 139 UNPACK_LSB_FIRST boolean FALSE TRUE/FALSE 140 UNPACK_ROW_LENGTH integer 0 [0, infinity] 141 UNPACK_SKIP_ROWS integer 0 [0, infinity] 142 UNPACK_SKIP_PIXELS integer 0 [0, infinity] 143 UNPACK_ALIGNMENT integer 4 1, 2, 4, 8 144 UNPACK_IMAGE_HEIGHT_EXT integer 0 [0, infinity] 145 UNPACK_SKIP_IMAGES_EXT integer 0 [0, infinity] 146 UNPACK_IMAGE_DEPTH_SGIS integer 0 [0, infinity] 147 UNPACK_SKIP_VOLUMES_SGIS integer 0 [0, infinity] 148 PIXEL_TILE_WIDTH_SGIX integer 0 [0, infinity] 149 PIXEL_TILE_HEIGHT_SGIX integer 0 [0, infinity] 150 PIXEL_TILE_GRID_WIDTH_SGIX integer 0 [0, infinity] 151 PIXEL_TILE_GRID_HEIGHT_SGIX integer 0 [0, infinity] 152 PIXEL_TILE_GRID_DEPTH_SGIX integer 0 [0, infinity] 153 PIXEL_TILE_CACHE_SIZE_SGIX integer impl. dep. [0, infinity] 154 155 Table 3.1: PixelStore parameters pertaining to one or more of 156 DrawPixels, TexImage1D, TexImage2D, TexImage3DEXT, TexImage4DSGIS, 157 TexSubImage1DEXT, TexSubImage2DEXT, TexSubImage3DEXT, and 158 TexSubImage4DSGIS. 159 160 Section 3.6.3, starting with the third paragraph in the UNPACKING 161 section and continuing to the paragraph beginning with "Calling 162 DrawPixels with a type of BITMAP" is changed to read: 163 164 Groups held in memory as the source for a transfer operation can 165 be in one of two formats: as groups arranged in a single rectangle, or 166 as groups arranged in a grid of rectangles (or tiles). The method of 167 storage is indicated by the state of PIXEL_TILE_GRID_WIDTH_SGIX. If 168 PIXEL_TILE_GRID_WIDTH_SGIX is greater than 0, the image is contained in 169 a grid of tiles. If less than or equal to 0, the source is a single 170 rectangle. 171 172 UNPACKING A SINGLE RECTANGLE 173 ============================ 174 175 When groups in memory are treated as being arranged in a rectangle, the 176 rectangle consists of a series of rows, with the first element of the 177 first group of the first row pointed to by the pointer passed to 178 DrawPixels. If the value of UNPACK_ROW_LENGTH is not positive, then the 179 number of groups in a row is width; otherwise the number of groups is 180 UNPACK_ROW_LENGTH. If the first element of a row is at location p in 181 memory, then the location of the first element of the Nth row is obtained 182 by skipping 183 184 p + Nk 185 186 where N is the row number (counting from zero) and k is defined as 187 188 / nl s>=a, 189 k = < 190 \ a/s ceiling(snl/a) s<a 191 192 where n is the number of elements in a group, l is the number of groups 193 in the row, a is the value of UNPACK_ALIGNMENT, and s is the size, in 194 units of GL ubytes, of an element. If the number of bits per element 195 is not 1, 2, 4, or 8 times the number of bits in a GL ubyte, then 196 k = nl for all values of a. 197 198 There is a mechanism for selecting a subrectangle of groups from a 199 larger containing rectangle. This mechanism relies on three integer 200 parameters: UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, and UNPACK_SKIP_PIXELS. 201 Before obtaining the first group from memory, the pointer supplied to 202 DrawPixels is effectively advanced by (UNPACK_SKIP_PIXELS)n + 203 (UNPACK_SKIP_ROWS)k elements. Then width groups are obtained from 204 contiguous elements in memory (without advancing the pointer), after 205 which the pointer is advanced by k elements. height sets of width groups 206 of values are obtained this way. See Figure 3.8. 207 208 209 UNPACKING PIXEL TILES 210 ===================== 211 212 |<- TW ->| 213 |<---------- Grid Width ----------->| 214 215 -- -- +--------+--------+--------+--------+ 216 G | | | | | 217 r TH | +-+--------+--------+--+ | 218 i |t8 | |t9 |t10 |t11 | 219 d -- +------+-+--------+--------+--+-----+ 220 | | | | | | | 221 H | | | | | | | 222 e |t4 | |t5 |t6 |t7| | 223 i +------+-+--------+--------+--+-----+ 224 g | | | | | | | 225 h -- |<-SP->+-+--------+--------+--+ | 226 t SR |t0 |t1 |t2 |t3 | 227 -- -- +--------+--------+--------+--------+ 228 229 Figure 3.8.a???. Selecting a subimage from a tiled image source. 230 TW -> PIXEL_TILE_WIDTH_SGIX 231 TH -> PIXEL_TILE_HEIGHT_SGIX 232 SR -> UNPACK_SKIP_ROWS 233 SP -> UNPACK_SKIP_PIXELS 234 Grid Width -> PIXEL_TILE_GRID_WIDTH_SGIX 235 Grid Height -> PIXEL_TILE_GRID_HEIGHT_SGIX 236 237 238 When groups are held in memory as a grid of tiles, the image rectangle 239 consists of a series of rows of rectangular tiles. See Figure 3.8.a???. 240 Each tile consists of a series of tile rows. A row of the image will 241 cross all tiles in a row of the grid. Unlike the single rectangle 242 method for holding groups in memory, the number of groups in a row of 243 the tiled image is defined as PIXEL_TILE_WIDTH_SGIX * 244 PIXEL_TILE_GRID_WIDTH_SGIX, where PIXEL_TILE_WIDTH_SGIX is the number 245 of groups in a row of a single tile and PIXEL_TILE_GRID_WIDTH_SGIX is 246 the number of tiles in the width of the image. UNPACK_ROW_LENGTH is 247 ignored when using pixel tiles. 248 249 Groups are arranged within a single tile exactly as described above for 250 groups arranged in a single rectangle. The computation of the 251 starting address of a row within a tile is also the same. The method 252 for computing the starting address of a row in the image is to first 253 establish the row of tiles in the grid containing the row of groups in 254 the image, then to locate the address of the row within the tile. The 255 index of the first tile that contains the row can be computed as: 256 257 index = n * floor(r/h) 258 259 where index is the (0-based) index of the tile, n is the number of tiles 260 across the image, PIXEL_TILE_GRID_WIDTH_SGIX, r is the (0-based) group 261 row number, and h is the number of rows per tile, PIXEL_TILE_HEIGHT_SGIX. 262 The starting address within each of the tiles in the row across the 263 image is computed as defined in the simple rectangle case, but using a 264 row number that is the original row number modulo the number of rows 265 per tile, PIXEL_TILE_HEIGHT_SGIX. 266 267 That groups are being held in memory as a grid of tiles is indicated 268 by PIXEL_TILE_GRID_WIDTH_SGIX containing a value greater than 0. 269 The <pixels> parameter of DrawPixels, TexImage1D, TexImage2D, 270 TexImage3DEXT, TexImage4DSGIS, TexSubImage1DEXT, TexSubImage2DEXT, 271 TexSubImage3DEXT, or TexSubImage4DSGIS is a pointer to a vector of 272 starting addresses for each of the tiles. 273 274 When transferring a subimage from the grid of tiles, a complete row of 275 groups crossing the entire subimage is transferred before the first 276 group of the next subimage row is transferred. Thus, for a subimage that 277 crosses tiles, the sequence of groups transferred will be 278 indistinguishable from the sequence that would have occurred had the 279 subimage been taken from a simple rectangular image. 280 281 For 1-dimensional transfers, such as those of TexImage1D, and 282 TexSubImage1DEXT, PIXEL_TILE_GRID_WIDTH_SGIX must be set to a non-zero 283 positive value indicating pixel tiles are being used and 284 PIXEL_TILE_WIDTH_SGIX must be set to a positive value indicating the 285 tile width. 286 287 For 2-dimensional transfers, such as those of DrawPixels, TexImage2D, and 288 TexSubImage2DEXT, PIXEL_TILE_GRID_WIDTH_SGIX must be set to a non-zero 289 positive value indicating both that pixel tiles are being used and the 290 number of tiles in width of the image. PIXEL_TILE_WIDTH_SGIX and 291 PIXEL_TILE_HEIGHT_SGIX must be set to positive values indicating 292 the tile width and height (in groups), respectively. 293 294 3-dimensional transfers, such as those of TexImage3DEXT and 295 TexSubImage3DEXT, additionally require the specification of a 296 positive value for PIXEL_TILE_GRID_HEIGHT_SGIX. The value of 297 UNPACK_IMAGE_HEIGHT_EXT is ignored. A 3-dimensional space is stored as 298 a series of 2-dimensional images. The index of the first tile in the 299 Nth image is N * PIXEL_TILE_GRID_WIDTH_SGIX * 300 PIXEL_TILE_GRID_HEIGHT_SGIX. 301 302 4-dimensional transfers, such as those of TexImage4DSGIS and 303 TexSubImage4DSGIS, additionally require the specification of a 304 positive value for PIXEL_TILE_GRID_DEPTH_SGIX. The value of 305 UNPACK_IMAGE_DEPTH_SGIS is ignored. The 4-dimensional space is stored as 306 a series of 3-dimensional volumes. The index of the first tile in the 307 Nth volume is N * PIXEL_TILE_GRID_WIDTH_SGIX * 308 PIXEL_TILE_GRID_HEIGHT_SGIX * PIXEL_TILE_GRID_DEPTH_SGIX. 309 310 Some implementation-dependent pixel storage state is included to help 311 accelerate pixel transfers. PIXEL_TILE_BEST_ALIGNMENT_SGIX provides 312 the optimal memory alignment for the starting address of pixel tiles. 313 Anticipated acceleration schemes depend on the caching of information 314 from previous transfers to try to accelerate new transfers. The 315 particular resource needed to accelerate the transfer (e.g., locked 316 user memory) may be limited or particularly valuable to a user. 317 Two pixel store values, PIXEL_TILE_CACHE_INCREMENT_SGIX and 318 PIXEL_TILE_CACHE_SIZE_SGIX, are provided to give the user some control 319 over the amount of the resource in use. PIXEL_TILE_CACHE_SIZE_SGIX is 320 a variable that indicates the current amount of the caching resource in 321 use. It is settable to some set of discrete values. If the user attempts 322 to set PIXEL_TILE_CACHE_SIZE_SGIX to some value that is not in the set, 323 the variable will actually be set to the nearest acceptable value. Setting 324 the variable to 0 will turn any caching off and release the resource. 325 PIXEL_TILE_CACHE_INCREMENT_SGIX is a gettable value that indicates the 326 approximate change in cache size from the current value to the next 327 larger acceptable value. 328 329 BITMAP 330 ====== 331 332Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations 333and the Framebuffer) 334 335 None 336 337Additions to Chapter 5 of the 1.0 Specification (Special Functions) 338 339 None 340 341Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 342 343 None 344 345Additions to the GLX Specification 346 347 None 348 349Dependencies on EXT_texture3D 350 351 If EXT_texture3D is not supported, this extension does not support 3 352 and 4 dimensions, all discussion of 3 and 4 dimensions is void, references 353 to the function TexImage3DEXT are removed, and the following tokens are 354 no longer defined: 355 356 PIXEL_TILE_GRID_HEIGHT_SGIX 357 PIXEL_TILE_GRID_DEPTH_SGIX 358 359Dependencies on EXT_subtexture 360 361 If EXT_subtexture is not supported, references to TexSubImage1DEXT, 362 TexSubImage2DEXT, and TexSubImage3DEXT are removed from this extension. 363 364Dependencies on EXT_convolution 365 366 This extension requires EXT_convolution. If the EXT_convolution is 367 not supported, this extension is unnecessary. 368 369Dependencies on EXT_texture4D 370 371 If EXT_texture4D is not supported, this extension does not support 4 372 dimensions, all discussion of 4 dimensions is void, references to the 373 functions TexImage4DSGIS and TexSubImage4DSGIS are removed, and the 374 following token is no longer defined: 375 376 PIXEL_TILE_GRID_DEPTH_SGIX 377 378GLX Protocol 379 380 None 381 382Errors 383 384 GL_INVALID_OPERATION is generated by DrawPixels, TexImage1D, TexImage2D, 385 TexImage3DEXT, TexImage4DSGIS, TexSubImage1DEXT, TexSubImage2DEXT, 386 TexSubImage3DEXT, or TexSubImage4DSGIS if the groups are to be read from 387 pixel tiles and the specified size of the grid of pixel tiles is 388 insufficient to hold the specified subimage. 389 390New State 391 392 Get Value Get Command Type Value Attrib 393 --------- ----------- ---- ------- ------ 394 PIXEL_TILE_WIDTH_SGIX GetIntegerv Z+ 0 client 395 PIXEL_TILE_HEIGHT_SGIX GetIntegerv Z+ 0 client 396 PIXEL_TILE_GRID_WIDTH_SGIX GetIntegerv Z+ 0 client 397 PIXEL_TILE_GRID_HEIGHT_SGIX GetIntegerv Z+ 0 client 398 PIXEL_TILE_GRID_DEPTH_SGIX GetIntegerv Z+ 0 client 399 400New Implementation Dependent State 401 402 Get Value Get Command Type Attrib 403 --------- ----------- ---- ------ 404 PIXEL_TILE_BEST_ALIGNMENT_SGIX GetIntegerv Z+ client 405 PIXEL_TILE_CACHE_INCREMENT_SGIX GetIntegerv Z+ client 406 PIXEL_TILE_CACHE_SIZE_SGIX GetIntegerv Z+ client 407 408 409