1Name 2 3 OES_draw_texture 4 5Name Strings 6 7 GL_OES_draw_texture 8 9Contact 10 11 Tom Olson (t-olson 'at' ti.com) 12 13Notice 14 15 Copyright (c) 2004-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Ratified by the Khronos BOP, Aug 5, 2004. 31 32Version 33 34 Last Modified Date: 21 July 2004 35 Author Revision 0.96 36 37Number 38 39 OpenGL ES Extension #7 40 41Dependencies 42 43 OES_fixed_point is required. 44 EXT_fog_coord affects the definition of this extension. 45 This extension is written against the OpenGL 1.3 and 46 OpenGL ES 1.0 Specifications. 47 48Overview 49 50 This extension defines a mechanism for writing pixel 51 rectangles from one or more textures to a rectangular 52 region of the screen. This capability is useful for 53 fast rendering of background paintings, bitmapped font 54 glyphs, and 2D framing elements in games. This 55 extension is primarily intended for use with OpenGL ES. 56 57 The extension relies on a new piece of texture state 58 called the texture crop rectangle, which defines a 59 rectangular subregion of a texture object. These 60 subregions are used as sources of pixels for the texture 61 drawing function. 62 63 Applications use this extension by configuring the 64 texture crop rectangle for one or more textures via 65 ActiveTexture() and TexParameteriv() with pname equal to 66 TEXTURE_CROP_RECT_OES. They then request a drawing 67 operation using DrawTex{sifx}[v]OES(). The effect of 68 the latter function is to generate a screen-aligned 69 target rectangle, with texture coordinates chosen to map 70 the texture crop rectangle(s) linearly to fragments in 71 the target rectangle. The fragments are then processed 72 in accordance with the fragment pipeline state. 73 74IP Status 75 76 No known IP issues. 77 78Issues 79 80 (1) Should we pass a texture name to the draw function, 81 or use the currently bound texture? 82 83 RESOLVED. Use the textures bound to currently 84 enabled texture units. This makes it easy for 85 drivers to implement DrawTex*() using existing 86 texture hardware. If we didn't do this, they would 87 have to save and restore the state of the texture 88 unit(s). 89 90 (2) Doesn't DrawPixels make this extension unnecessary? 91 92 RESOLVED. No. DrawPixels is hard to support 93 efficiently in hardware because the source pixels 94 are in application memory. Also, the pixel setup 95 pipeline (PixelTransfer, PixelMap etc.) is redundant 96 for the intended applications. Also, PixelZoom 97 looks ugly when the zoom factors are large, and there 98 is no way to control filtering. Using textures and 99 texture units solves all of these problems. 100 101 (3) Doesn't ARB_point_sprite make this extension unnecessary? 102 103 RESOLVED. No. Key differences include: 104 * ARB_point_sprite uses the entire source texture to 105 paint a point, i.e. its texture coordinates range 106 from 0.0 to 1.0. This extension allows a 107 subregion of a texture to be used as the source. 108 * ARB_point_sprite sprites are limited by the 109 maximum point size, which may be small. This 110 extension is limited only by the maximum supported 111 texture size and the screen size. 112 * ARB_point_sprite sprites are square. This 113 extension supports general rectangles as sprite 114 shapes. 115 * ARB_point_sprite sprites are clipped as points, so 116 if the center of a sprite falls outside the 117 frustrum, nothing is drawn. This extension draws 118 any portion of a sprite that lies within the 119 viewing frustrum. (There is a well-known 120 work-around for this, but it's ugly.) 121 122 (4) How is the texture sampled? 123 124 RESOLVED. It is sampled like a normal texture, and 125 not like an image sent to DrawPixels. This 126 facilitates implementing with texture hardware. 127 128 (5) How does this work when multisampling is enabled? 129 130 RESOLVED. Implementations should generate 131 multisample texture coordinates using the same 132 method they use in normal texture mapping. 133 Approximations are acceptable, e.g. they may use the 134 same texture value for all samples associated with a 135 fragment generated by DrawTex*(), even if they use 136 another policy for multisampled triangle rendering. 137 138 (6) Do we really want the full fragment pipeline to be 139 active? 140 141 RESOLVED. Yes, on grounds of orthogonality and 142 simplicity. Again, this makes it easy for existing 143 hardware to implement the extension. 144 145 (7) How does this interact with user clip planes? 146 147 RESOLVED. User clip planes are ignored. This is a 148 screen-level operation, so geometric entities like 149 clip planes are irrelevant. 150 151 (8) How does this interact with mip-mapping? 152 153 RESOLVED. It behaves exactly as in texturing. 154 This is really easy to do as LOD is a constant 155 across the target rectangle. 156 157 (9) What happens when multiple texture units are 158 enabled? 159 160 RESOLVED. All enabled texture units participate in 161 generating the final fragment color. Each unit 162 generates its own s,t based on its texture's crop 163 rectangle. 164 165 (10) Should the target location be specified by the 166 current raster position (RasterPos or WindowPos), 167 or by arguments to DrawTex*OES()? 168 169 RESOLVED. Use arguments passed to DrawTex*. In the 170 intended uses, the target will be set once per call, 171 so using arguments saves one inner loop function 172 call. 173 174 (11) Do we want stretch-blt capability? 175 176 RESOLVED. Yes. Supply a window size as well as 177 window position to DrawTex*() 178 179 (12) OpenGL ES issue: WindowPos (if we use it) adds 16 180 entry points ({23}{sifd}[v]), which seems like a lot 181 even if they are trivial. Can we live with a 182 subset? (Note that the 'd' versions go away, but 183 they are replaced by 'x' versions.) 184 185 RESOLVED. Moot, as we do not use WindowPos. But the 186 intent was to add only 3{si}[v] versions (four entry 187 points). This is not orthogonal and may be 188 surprising. But there is no intent to support 189 sub-pixel placement of rectangles, so the {fx} 190 versions are superfluous. {2} versions are easy to 191 express using {3} versions. Vector and individual 192 argument versions are kept to reduce the surprise 193 factor, and because constructing calls to a v-type 194 function is a huge pain if you don't already have 195 the data in vector format. 196 197 (13) TexCropRect*OES adds eight entry points. Can we live 198 with a subset? For the intended use, integer values 199 suffice, so the {fx} versions are superfluous. But 200 orthogonality and 'least-astonishment' are virtues 201 too. 202 203 RESOLVED. Moot. Replace with TexParameteriv(). 204 205 (14) Would it be better to remove the texture crop 206 rectangle from the state, and instead pass 207 parameters to DrawTextureOES()? 208 209 RESOLVED. No. Drawing the same pixel pattern multiple 210 times is a plausible usage scenario. 211 212 (15) Should texture crop rect parameters be stored internally 213 as integers, or as float/fixed? I.e. should we allow 214 the crop rect to include fractional texels? This is 215 more flexible, but is not the intended use. Software 216 implementations would have to add a test for the (normal) 217 special case of integer bounds. 218 219 RESOLVED. Integer only. Texture crop rect is 220 conceptually a subregion of an integer grid, so its 221 natural coordinates are integers. 222 223 (16) Should we have a single global crop rect, or one per 224 texture unit? 225 226 RESOLVED. Neither. We should have one per texture, 227 with TexParameter setting the rect for the currently 228 active texture. It isn't a lot of state, it 229 attaches the rect to a specific texture (which makes 230 sense) rather than a texture unit (which doesn't), 231 it is more orthogonal, and it allows tex coords to 232 be meaningful (if not actually useful) when multiple 233 texture units are enabled. 234 235 (17) Should the destination rectangle specified by 236 DrawTex*() be defined as integer only like the crop 237 rectangle, or should its parameters be real-valued? 238 239 RESOLVED. Real-valued. Since we now support 240 stretch-blit, we want the ability to animate the 241 scaling factor smoothly. If the destination rectangle 242 size is rounded to an integer, you won't get smooth 243 animation. 244 245New Procedures and Functions 246 247 Added to OpenGL 1.3 and OpenGL ES 1.0: 248 249 void DrawTex{sifx}OES(T X, T Y, T Z, T W, T H); 250 void DrawTex{sifx}vOES(T* coords); 251 252 Added to OpenGL ES 1.0: 253 254 void TexParameter{ifx}v(enum target, enum pname, T param); 255 256 257New Types 258 259 None 260 261 262New Tokens 263 264 Accepted by the <pname> parameter of TexParameter() 265 and GetTexParameter(): 266 267 TEXTURE_CROP_RECT_OES 0x8B9D 268 269 270Additions to Chapter 2 of the OpenGL 1.3 Specification 271(OpenGL Operation): 272 273 None 274 275 276Additions to Chapter 3 of the OpenGL 1.3 Specification 277(Rasterization): 278 279 In Table 3.19: Texture parameters and their values, p. 133, 280 add this line at the end of the table: 281 282 Name Type Legal Values 283 -------------------------------------------------------- 284 TEXTURE_CROP_RECT_OES 4 integers any value 285 286 287 In section 3.8.4, Texture Parameters, after paragraph 3 288 (page 132) insert new paragraph: 289 290 The texture parameter TEXTURE_CROP_RECT_OES controls the 291 operation of DrawTex{sifx}[v]OES(), as described in 292 section 5.7. It has no effect on the rasterization of 293 other primitives. 294 295 296Additions to Chapter 4 of the OpenGL 1.3 Specification 297(Per-Fragment Operations and the Frame Buffer): 298 299 None 300 301 302Additions to Chapter 5 of the OpenGL 1.3 Specification 303(Special Functions): 304 305 In Chapter 5, paragraph one, replace the last two words 306 ("and hints.") with the words "hints, and texture 307 rectangle drawing." 308 309 After section 5.6, p. 196, insert: 310 311 5.7 Texture Rectangle Drawing 312 313 OpenGL supports drawing sub-regions of a texture to 314 rectangular regions of the screen using the texturing 315 pipeline. Source region size and content are determined 316 by the texture crop rectangle(s) of the enabled 317 texture(s) (see section 3.8.14). 318 319 The functions 320 321 void DrawTex{sifx}OES(T Xs, T Ys, T Zs, T Ws, T Hs); 322 void DrawTex{sifx}vOES(T *coords); 323 324 draw a texture rectangle to the screen. Xs, Ys, and Zs 325 specify the position of the affected screen rectangle. 326 Xs and Ys are given directly in window (viewport) 327 coordinates. Zs is mapped to window depth Zw as follows: 328 329 { n, if z <= 0 330 Zw = { f, if z >= 1 331 { n + z * (f - n), otherwise 332 333 where <n> and <f> are the near and far values of 334 DEPTH_RANGE. Ws and Hs specify the width and height of 335 the affected screen rectangle in pixels. These values 336 may be positive or negative; however, if either (Ws <= 337 0) or (Hs <= 0), the INVALID_VALUE error is generated. 338 339 Calling one of the DrawTex functions generates a 340 fragment for each pixel that overlaps the screen 341 rectangle bounded by (Xs, Ys) and (Xs + Ws), (Ys + Hs). 342 For each generated fragment, the depth is given by Zw 343 as defined above, and the color by the current color. 344 345 If EXT_fog_coord is supported, and FOG_COORDINATE_SOURCE_EXT 346 is set to FOG_COORINATE_EXT, then the fragment distance for 347 fog purposes is set to CURRENT_FOG_COORDINATE. Otherwise, 348 the fragment distance for fog purposes is set to 0. 349 350 Texture coordinates for each texture unit are computed 351 as follows: 352 353 Let X and Y be the screen x and y coordinates of each 354 sample point associated with the fragment. Let Wt and 355 Ht be the width and height in texels of the texture 356 currently bound to the texture unit. (If the texture is 357 a mipmap, let Wt and Ht be the dimensions of the level 358 specified by TEXTURE_BASE_LEVEL.) Let Ucr, Vcr, Wcr and 359 Hcr be (respectively) the four integers that make up the 360 texture crop rectangle parameter for the currently bound 361 texture. The fragment texture coordinates (s, t, r, q) 362 are given by 363 364 s = (Ucr + (X - Xs)*(Wcr/Ws)) / Wt 365 t = (Vcr + (Y - Ys)*(Hcr/Hs)) / Ht 366 r = 0 367 q = 1 368 369 In the specific case where X, Y, Xs and Ys are all 370 integers, Wcr/Ws and Hcr/Hs are both equal to one, the 371 base level is used for the texture read, and fragments 372 are sampled at pixel centers, implementations are 373 required to ensure that the resulting u, v texture 374 indices are also integers. This results in a one-to-one 375 mapping of texels to fragments. 376 377 Note that Wcr and/or Hcr can be negative. The formulas 378 given above for s and t still apply in this case. The 379 result is that if Wcr is negative, the source rectangle 380 for DrawTex operations lies to the left of the reference 381 point (Ucr, Vcr) rather than to the right of it, and 382 appears right-to-left reversed on the screen after a 383 call to DrawTex. Similarly, if Hcr is negative, the 384 source rectangle lies below the reference point (Ucr, 385 Vcr) rather than above it, and appears upside-down on 386 the screen. 387 388 Note also that s, t, r, and q are computed for each 389 fragment as part of DrawTex rendering. This implies 390 that the texture matrix is ignored and has no effect on 391 the rendered result. 392 393 394Additions to Chapter 6 of the OpenGL 1.3 Specification 395(State and State Requests): 396 397 None 398 399 400Additions to Appendix A of the OpenGL 1.3 Specification 401(Invariance): 402 403 None 404 405 406Additions to the AGL/GLX/WGL Specifications: 407 408 None 409 410 411Additions to Chapter 2 of the OpenGL ES 1.0 Specification 412(OpenGL Operation): 413 414 None 415 416 417Additions to Chapter 3 of the OpenGL ES 1.0 Specification 418(Rasterization): 419 420 After the fourth paragraph of section 3.8, Texturing, 421 p. 17, insert a new paragraph: 422 423 DrawTexOES is supported. 424 425 In the (unnamed) table of supported texture functions, 426 p. 19, delete the entry for TexParameter{i[v] fv}(), and 427 replace the entry for TexParameterf() with the following: 428 429 OpenGL 1.3 Common Common-Lite 430 ------------------------------------------------ ------ ----------- 431 TexParameter{if}[v](enum target, enum param, T param) 432 target = TEXTURE_2D, pname = TEXTURE_CROP_RECT_OES (check) (check) 433 target = TEXTURE_1D, TEXTURE_3D, TEXTURE_CUBE_MAP - - 434 pname = TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER (check) (check) 435 pname = TEXTURE_WRAP_S, TEXTURE_WRAP_T (check) (check) 436 pname = TEXTURE_BORDER_COLOR - - 437 pname = TEXTURE_MIN_LOD, TEXTURE_MAX_LOD - - 438 pname = TEXTURE_BASE_LEVEL, TEXTURE_MAX_LEVEL - - 439 pname = TEXTURE_WRAP_R - - 440 pname = TEXTURE_PRIORITY - - 441 442 In the same table, modify the entry for 443 GetTexParameter{if}v() to read as follows: 444 445 OpenGL 1.3 Common Common-Lite 446 ------------------------------------------------------- ------ ----------- 447 GetTexParameter{if}v(enum target, enum param, T *params) (check) (dagger) 448 449 450Additions to Chapter 4 of the OpenGL ES 1.0 Specification 451(Per-Fragment Operations and the Frame Buffer): 452 453 None 454 455 456Additions to Chapter 5 of the OpenGL ES 1.0 Specification 457(Special Functions): 458 459 None 460 461 462Additions to Chapter 6 of the OpenGL ES 1.0 Specification 463(State and State Requests): 464 465 At the end of table 6.15, Texture Objects (cont.), p. 36, 466 insert a new entry: 467 468 State Exposed Queriable 469 ------------------------------------------- ------- --------- 470 TEXTURE_CROP_RECT_OES (check) (check) 471 472 473 Replace the fourth paragraph of Chapter 7, Core Additions and 474 Extensions, p. 46, with the following: 475 476 The Common and Common-Lite profiles add subsets of the 477 OES_byte_coordinates, OES_fixed_point, and 478 OES_single_precision ES-specific extensions as core 479 additions; OES_readFormat and 480 OES_compressed_paletted_texture as required profile 481 extensions; and OES_query_matrix and OES_draw_texture as 482 optional profile extensions. 483 484 485Additions to Chapter 7 of the OpenGL ES 1.0 Specification 486(Core Additions and Extensions): 487 488 At the end of Table 7.1: OES Extension Disposition, add a 489 new entry: 490 491 Extension Name Common Common-Lite 492 ------------------------ ------------------ ------------------ 493 OES_draw_texture optional extension optional extension 494 495 496 After section 7.6, Query Matrix, insert 497 498 499 7.7 Draw Texture 500 501 The optional OES_draw_texture extension allows rectangular 502 subregions of a texture to be written to the screen using 503 the fragment pipeline. Texture coordinates are generated 504 for each fragment in the destination rectangle, such that 505 texels in the source texture are mapped linearly to pixels 506 on the screen. 507 508 509GLX Protocol 510 511 None 512 513 514Errors 515 516 None 517 518 519Dependencies on OES_fixed_point 520 521 The DrawTex{sifx}[v]() function makes use of the 'x' 522 suffix and (in that form) accepts parameters of type fixed, 523 as defined in OES_fixed_point. 524 525 526Dependencies on EXT_fog_coord 527 528 EXT_fog_coord affects the distance that is used in the fog 529 equations for fragments generated by DrawTex{sifx}[v](). 530 If EXT_fog_coord is not supported, the fog distance for 531 each fragment is set to zero. If EXT_fog_coord is 532 supported, the fog distance depends on the value of 533 FOG_COORDINATE_SOURCE_EXT. If the latter is set to 534 FRAGMENT_DEPTH_EXT, the fog distance is again set to zero. 535 If FOG_COORDINATE_SOURCE_EXT is set to FOG_COORDINATE_EXT, 536 the distance is set to CURRENT_FOG_COORDINATE. 537 538 539New State 540 541 (table 6.16, Texture Objects (cont.), p. 224): 542 543 Initial 544 Get Value Type Get Command Value Description Sec Attribute 545 --------- ---- ----------- --------- ----------- --- --------- 546 TEXTURE_CROP_RECT 4xZ GetTexParameteriv 0,0,0,0 texture crop 5.7 texture 547 rectangle 548 549New Implementation Dependent State 550 551 None. 552 553 554Revision History 555 556 July 21, 2004 (v0.96) 557 - Modified to say that if Ws or Hs < 0 then an 558 INVALID_VALUE error is generated 559 560 July 16, 2004 (v0.95) 561 - Corrected a bug in the text description of DrawTex 562 with negative crop rectangle width or height. Thanks 563 to Petri Kero for the catch. 564 565 July 14, 2004 (v0.9) 566 - added a Zs parameter to the destination rectangle 567 location specification. This allows applications 568 to control the depth coordinate of fragments generated 569 by DrawTex(). 570 - Removed DOS-mode carriage returns. 571 572 June 29, 2004 (v0.8) 573 - Corrected dependencies to comply with ARB recommended 574 practice for extensions. 575 - Restructured the "Additions to the OpenGL ES 1.0 Spec" 576 sections to separate changes by chapter, following 577 ARB recommended practice for OpenGL and 578 GLX specifications. 579 - Modified TexParameter usage to be consistent with 580 OpenGL ES 1.1. 581 - Added a dependency on EXT_fog_coord. 582 - Inserted enumerant value. 583 584 June 16, 2004 (v0.7) 585 - Modified to make texture crop rectangle part of 586 texture state (set by TexParameter) rather than by 587 an ad hoc function (TexCropRectOES). 588 - Modified to provide stretch-blit functionality. 589 590 May 28, 2004 (v0.6) 591 - Formalized changes to 1.3 and ES 1.0 specs. 592 Modified to take screen coordinate arguments 593 rather than using the current raster position. 594 595 May 19, 2004 (v0.5) 596 - Simplified to support only one-to-one source 597 blit. Sprite functionality was moved to a 598 separate proposal. 599 600 May 4, 2004 (v0.4) 601 - Rewrote to use explicit source and destination 602 rectangles instead of overloading PixelZoom. 603 Made current raster rectangle explicit and 604 provided both screen space and object space 605 ways to define it. 606 607 April 13, 2004 608 - Initial version (v0.3) 609