1Name 2 3 NV_draw_texture 4 5Name Strings 6 7 GL_NV_draw_texture 8 9Contributors 10 11 Steven Holte, NVIDIA Corporation (sholte 'at' nvidia.com) 12 13Contact 14 15 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 16 17Status 18 19 Complete 20 21Version 22 23 Last Modified Date: 9/19/2012 24 NVIDIA Revision: 2 25 26Number 27 28 OpenGL Extension #430 29 OpenGL ES Extension #126 30 31Dependencies 32 33 This extension is written against the OpenGL 4.1 Specification 34 (Compatibility Profile). 35 36 This extension can also be used with OpenGL ES 2.0 or later (see the section, 37 "Interactions with OpenGL ES," below). 38 39 This extension interacts with EXT_shadow_samplers. 40 41Overview 42 43 This extension provides a new function, DrawTextureNV(), allowing 44 applications to draw an screen-aligned rectangle displaying some or all of 45 the contents of a two-dimensional or rectangle texture. Callers specify a 46 texture object, an optional sampler object, window coordinates of the 47 rectangle to draw, and texture coordinates corresponding to the corners of 48 the rectangle. For each fragment produced by the rectangle, DrawTextureNV 49 interpolates the texture coordinates, performs a texture lookup, and uses 50 the texture result as the fragment color. 51 52 No shaders are used by DrawTextureNV; the results of the texture lookup 53 are used in lieu of a fragment shader output. The fragments generated are 54 processed by all per-fragment operations. In particular, 55 DrawTextureNV() fully supports blending and multisampling. 56 57 While this functionality can be obtained in unextended OpenGL by drawing a 58 rectangle and using a fragment shader to do a texture lookup, 59 DrawTextureNV() is likely to have better power efficiency on 60 implementations supporting this extension. Additionally, use of this 61 extension frees the application developer from having to set up 62 specialized shaders, transformation matrices, vertex attributes, and 63 various other state in order to render the rectangle. 64 65New Procedures and Functions 66 67 void DrawTextureNV(GLuint texture, GLuint sampler, 68 GLfloat x0, GLfloat y0, 69 GLfloat x1, GLfloat y1, 70 GLfloat z, 71 GLfloat s0, GLfloat t0, 72 GLfloat s1, GLfloat t1); 73 74New Tokens 75 76 None. 77 78Additions to Chapter 2 of the OpenGL 4.1 Specification (OpenGL Operation) 79 80 Modify Section 2.19, Conditional Rendering, p. 183 81 82 (modify first paragraph to specify that DrawTextureNV is affected by 83 conditional rendering) ... is false, all rendering commands between 84 BeginConditionalRender and the corresponding EndConditionalRender are 85 discarded. In this case, Begin, End, ...and DrawTextureNV (section 4.3.X) 86 have no effect. 87 88 89Additions to Chapter 3 of the OpenGL 4.1 Specification (Rasterization) 90 91 Modify Section 3.1, Discarding Primitives Before Rasterization, p. 204 92 93 (modify the end of the second paragraph) When enabled, RASTERIZER_DISCARD 94 also causes the [[compatibility profile only: Accum, Bitmap, CopyPixels, 95 DrawPixels,]] Clear, ClearBuffer*, and DrawTextureNV commands to be 96 ignored. 97 98Additions to Chapter 4 of the OpenGL 4.1 Specification (Per-Fragment 99Operations and the Frame Buffer) 100 101 (Insert new section after Section 4.3.1, Writing to the Stencil or 102 Depth/Stencil Buffers, p. 380) 103 104 Section 4.3.X, Drawing Textures 105 106 The command: 107 108 void DrawTextureNV(GLuint texture, GLuint sampler, 109 GLfloat x0, GLfloat y0, 110 GLfloat x1, GLfloat y1, 111 GLfloat z, 112 GLfloat s0, GLfloat t0, 113 GLfloat s1, GLfloat t1); 114 115 is used to draw a screen-aligned rectangle displaying a portion of the 116 contents of the texture <texture>. The four corners of this 117 screen-aligned rectangle have the floating-point window coordinates 118 (<x0>,<y0>), (<x0>,<y1>), (<x1>,<y1>), and (<x1>,<y0>). A fragment will 119 be generated for each pixel covered by the rectangle. Coverage along the 120 edges of the rectangle will be determined according to polygon 121 rasterization rules. If the framebuffer does not have a multisample 122 buffer, or if MULTISAMPLE is disabled, fragments will be generated 123 according to the polygon rasterization algorithm described in section 124 3.6.1. Otherwise, fragments will be generated for the rectangle using the 125 multisample polygon rasterization algorithm described in section 3.6.6. 126 In either case, the set of fragments generated is not affected by other 127 state affecting polygon rasterization -- in particular, the CULL_FACE, 128 POLYGON_SMOOTH, and POLYGON_OFFSET_FILL enables and PolygonMode state have 129 no effect. All fragments generated for the rectangle will have a Z window 130 coordinate of <z>. 131 132 The color associated with each fragment produced will be obtained by using 133 an interpolated source coordinate (s,t) to perform a lookup into <texture> 134 The (s,t) source coordinate for each fragment is interpolated over the 135 rectangle in the manner described in section 3.6.1, where the (s,t) 136 coordinates associated with the four corners of the rectangle are: 137 138 (<s0>, <t0>) for the corner at (<x0>, <y0>), 139 (<s1>, <t0>) for the corner at (<x1>, <y0>), 140 (<s1>, <t1>) for the corner at (<x1>, <y1>), and 141 (<s0>, <t1>) for the corner at (<x0>, <y1>). 142 143 The interpolated texture coordinate (s,t) is used to obtain a texture 144 color (Rs,Gs,Bs,As) from the <texture> using the process described in 145 section 3.9. The sampler state used for the texture access will be taken 146 from the texture object <texture> if <sampler> is zero, or from the 147 sampler object given by <sampler> otherwise. The filtered texel <tau> is 148 converted to an (Rb,Gb,Bb,Ab) vector according to table 3.25 and swizzled 149 as described in Section 3.9.16. [[Core Profile Only: The section 150 referenced here is present only in the compatibility profile; this 151 language should be changed to reference the relevant language in the core 152 profile.]] 153 154 The fragments produced by the rectangle are not processed by fragment 155 shaders [[Compatibility Profile: or fixed-function texture, color sum, or 156 fog operations]]. These fragments are processed by all of the 157 per-fragment operations in section 4.1. For the purposes of the scissor 158 test (section 4.1.2), the enable and scissor rectangle for the first 159 element in the array of scissor test enables and rectangles are used. 160 161 The error INVALID_VALUE is generated by DrawTextureNV if <texture> is not 162 the name of a texture object, or if <sampler> is neither zero nor the name 163 of a sampler object. The error INVALID_OPERATION is generated if the 164 target of <texture> is not TEXTURE_2D or TEXTURE_RECTANGLE, <texture> is 165 not complete, if <sampler> is zero and the TEXTURE_COMPARE_MODE parameter 166 of <texture> is COMPARE_REF_TO_TEXTURE, or if <sampler> is non-zero and 167 the TEXTURE_COMPARE_MODE_PARAMETER of <sampler> is COMPARE_REF_TO_TEXTURE. 168 169 170Additions to Chapter 5 of the OpenGL 4.1 Specification (Special Functions) 171 172 None. 173 174Additions to Chapter 6 of the OpenGL 4.1 Specification (State and 175State Requests) 176 177 None. 178 179Additions to Appendix A of the OpenGL 4.1 Specification (Invariance) 180 181 None. 182 183Additions to the AGL/GLX/WGL Specifications 184 185 None. 186 187GLX Protocol 188 189 !!! TBD 190 191Errors 192 193 INVALID_VALUE is generated by DrawTextureNV if <texture> is not the name 194 of a texture object, or if <sampler> is neither zero nor the name of a 195 sampler object. 196 197 INVALID_OPERATION is generated by DrawTextureNV if the target of <texture> 198 is not TEXTURE_2D or TEXTURE_RECTANGLE, <texture> is not complete, if 199 <sampler> is zero and the TEXTURE_COMPARE_MODE parameter of <texture> is 200 COMPARE_REF_TO_TEXTURE, or if <sampler> is non-zero and the 201 TEXTURE_COMPARE_MODE_PARAMETER of <sampler> is COMPARE_REF_TO_TEXTURE. 202 203New State 204 205 None. 206 207 208New Implementation Dependent State 209 210 None. 211 212Interactions with OpenGL ES 213 214 If implemented for OpenGL ES, NV_draw_texture acts as described in this spec, 215 except: 216 217 * Ignore the references to conditional rendering including changes to 218 section 2.19 "Conditional Rendering". 219 * Ignore all references to RASTERIZER_DISCARD including changes to 220 section 3.1 "Discarding Primitives Before Rasterization". 221 * Ignore references to MULTISAMPLE. 222 * Ignore references to POLYGON_SMOOTH and PolygonMode. 223 * Ignore references to TEXTURE_RECTANGLE. 224 * If the version of OpenGL ES is less than 3.0, the sampler parameter 225 must always be 0. 226 * If the version of OpenGL ES is less than 3.0, ignore references to 227 texture swizzles. 228 229Interactions with OpenGL ES and EXT_shadow_samplers 230 231 If implemented for OpenGL ES with the EXT_shadow_samplers extension, 232 replace references to TEXTURE_COMPARE_FUNC, TEXTURE_COMPARE_MODE, and 233 COMPARE_REF_TO_TEXTURE, with references to TEXTURE_COMPARE_FUNC_EXT, 234 TEXTURE_COMPARE_FUNC_EXT and COMPARE_REF_TO_TEXTURE_EXT. 235 236 If implemented for OpenGL ES without the EXT_shadow_samplers extension, 237 ignore references to these symbols. 238 239Issues 240 241 (1) Why provide this extension when you can do the same thing by drawing a 242 quad with a simple fragment shader using texture mapping? 243 244 RESOLVED: This extension is intended to provide a high-performance 245 power-efficient fixed-function path for drawing the contents of a 246 texture onto the screen. No vertex shader is required to position the 247 vertices of the quad, and no fragment shader is required to perform a 248 texture lookup. 249 250 (2) Why provide this extension when you can do something similar with 251 DrawPixels? 252 253 RESOLVED: DrawPixels provides similar functionality, but can only 254 access client memory or a pixel buffer object. If the data to be drawn 255 on-screen come from a texture, it would be necessary to read the 256 contents of the texture back to client memory or a pixel buffer object 257 before drawing. 258 259 Additionally, the rendering process for DrawPixels has several 260 limitations. Addressing a subset of the source data requires either 261 pointer manipulation or the use of the separate PixelStore APIs, and 262 doesn't permit sub-pixel addressing in the source data. While 263 DrawPixels supports scaling via the PixelZoom, the zooming capability 264 provides only point-sampled filtering. Additionally, DrawPixels is not 265 supported in the core profile of OpenGL, or in OpenGL ES. 266 267 (3) Why provide this extension when you can do something similar with 268 BlitFramebuffer? 269 270 RESOLVED: BlitFramebuffer also provides similar functionality, but it 271 does not permit per-fragment operations like blending, which is a 272 significant limitation for some important "2D" use cases of this API 273 (e.g., compositing several images from textures). Additionally, need to 274 attach the texture to a framebuffer object, set up a read buffer, and 275 bind the framebuffer object as the read framebuffer result in several 276 additional steps not present in the DrawTextureNV API. 277 278 (4) The DrawTextureNV API only supports 2D or rectangle textures. Should 279 we provide support for accessing other types of texture (1D, 3D, cube 280 maps, arrays)? Or even for pulling a "2D" image out of a more complex 281 texture (like identifying a texture face, or a layer of a 2D array 282 texture or a 3D texture)? 283 284 RESOLVED: No, we are choosing to keep the API simple and support only 285 2D/rectangle textures. Adding in support for 3D or array textures would 286 require additional texture coordinates that would clutter up the "2D" 287 API or a separate "DrawTexture3DNV" API taking (s,t,r) coordinates. 288 Adding in support for pulling out a face/layer of a texture with 289 multiple layers would inject similar clutter or new APIs. 290 291 Note that the face/layer selection could also be handled by a 292 Direct3D-like "resource view" API that would allow callers to create 293 multiple "views" of a source texture. In particular, one might be able 294 to use such an extension to create a "virtual" 2D texture object that 295 refers to a single face/layer of a cube map, 2D array, or 3D texture. 296 297 (5) Should we support multisample textures (TEXTURE_2D_MULTISAMPLE)? 298 299 RESOLVED: No. Current texture mapping support for multisample texture 300 only allows for selection of a single numbered texture. There are no 301 filtered texture lookup capabilities for these sorts of textures. 302 303 BlitFramebuffer does support sourcing a multisample texture (via a 304 framebuffer object attachement), but its capabilities are also fairly 305 limited -- copies are only supported either by first resolving multiple 306 samples down to a single sample, or doing a straight sample-by-sample 307 copy to a matching multisample buffer. 308 309 (6) What sort of coordinates should be used to access the texture? 310 311 RESOLVED: We use the same coordinate system as is used for normal 312 texture lookups for a given texture target. 313 314 For textures with a TEXTURE_RECTANGLE target, we use non-normalized 315 coordinates -- to draw a 640x480 rectangle texture on top of a 640x480 316 window, you would call: 317 318 glDrawTexture(texture, sampler, 319 0, 0, 640, 480, /* destination */ 320 0, 0, 640, 480 /* texture */); 321 322 For textures with a TEXTURE_2D target, we use normalized coordinates. 323 The same example as above with a 640x480 2D texture would use: 324 325 glDrawTexture(texture, sampler, 326 0, 0, 640, 480, /* destination */ 327 0, 0, 1, 1 /* texture */); 328 329 (7) What limitations apply to the texture accesses in DrawTextureNV? 330 331 RESOLVED: We do not support any texture targets other than TEXTURE_2D 332 and TEXTURE_RECTANGLE. We also do not support shadow mapping via the 333 TEXTURE_COMPARE_MODE parameter, given that we don't provide any 334 interface for specifying a depth reference value. In either case, an 335 INVALID_OPERATION error will be generated if an unsupported feature is 336 used. 337 338 (8) Is anisotropic texture filtering supported? 339 340 RESOLVED: Yes. However, anisotropic filtering may result in lower 341 performance and power efficiency and should be used only if 342 required. Given that the destination is a screen-aligned rectangle and 343 the portion of texture sampled from is a texture-aligned rectangle, the 344 footprints of pixels in texture space are regular. Unless the 345 DrawTextureNV command uses a non-uniform scale, anisotropic filtering 346 should provide no benefit. 347 348 (9) Are texture swizzles supported? 349 350 RESOLVED: Yes. 351 352 (10) Does DrawTextureNV support multisample rasterization? 353 354 RESOLVED: Yes. The coordinates of the destination rectangle are 355 floating-point values, allowing for rectangle boundaries not on pixel 356 edges. When multisample rasterization is enabled, pixels on the edge of 357 the rectangle may be partially covered, in which case only some samples 358 of the pixel will be updated. This multisample support allows for 359 smoother panning of the drawn rectangles than one could get with the 360 pixel-aligned updates provided by the BlitFramebuffer API. 361 362 (11) Does DrawTextureNV support per-sample shading (i.e., a different 363 color for each sample in the destination rectangle)? 364 365 RESOLVED: No. 366 367 (12) Should any per-fragment operations be supported by this extension? 368 369 RESOLVED: Yes, we will all support fragment operations. In particular, 370 blending is particularly important for "2D" operations such as 371 compositing image layers. It seems interesting to allow stencil 372 operations to "cut out" portions of the primitive. It also seems 373 interesting to allow depth testing be used to compare the DrawTextureNV 374 rectangle (at a fixed depth) against previously rendered primitives 375 (either "3D" or "2D"). 376 377 (13) Should we provide a mode to override/disable selected per-fragment 378 operations when performing DrawTextureNV? 379 380 RESOLVED: No. An override would be useful if we expected applications 381 to be performing operations like toggling between regularly rendered 382 primitives (with depth testing enabled) and "flat" DrawTexture2D output 383 (not wanting depth testing) at a fine granularity. It's not clear that 384 such usage would be common. If we expect switching between modes only 385 at a coarse granularity, it would be simpler to require the application 386 to apply the (infrequent) overrides themselves instead of adding clutter 387 to the DrawTextureNV API. 388 389 (14) Is it legal to call DrawTextureNV while transform feedback is active? 390 If so, what is recorded? 391 392 UNRESOLVED: Yes, it's legal to call DrawTextureNV during transform 393 feedback. Nothing should be recorded in this case. This is consistent 394 with the handling of other "special" rendering operations (like 395 DrawPixels and BlitFramebuffer). This behavior falls out of the 396 definition of transform feedback with no spec changes required; there 397 are no geometric primitives sent through the pipeline for DrawTextureNV 398 that could be recorded. 399 400 (15) How does DrawTextureNV interact with RASTERIZER_DISCARD? 401 402 UNRESOLVED: If RASTERIZER_DISCARD is enabled, DrawTextureNV will be 403 discarded. This is consistent with the behavior of DrawPixels. 404 405 Note: It appears that BlitFramebuffer is not affected by 406 RASTERIZER_DISCARD, though the extensions that introduced this command 407 don't explicitly address this one way or the other. 408 409 (16) Should samples generated by DrawTextureNV be counted in occlusion 410 queries? 411 412 UNRESOLVED: Yes. Occlusion query is just another per-fragment 413 operation, and we support all the other ones. 414 415 (17) How does this extension interact with the DEPTH_CLAMP enable? 416 417 UNRESOLVED: When enabled, depth clamping will be performed on 418 DrawTextureNV fragments. This appears to be consistent with the spec 419 language, as applied to DrawPixels. There are two parts to depth 420 clamping: (a) clipping to the near/far frustum clip planes are 421 disabled, and (b) clamping is applied to fragment Z as part of the depth 422 test. There's no language suggesting that (b) doesn't apply to color 423 DrawPixels or Bitmap commands. (DrawPixels with DEPTH_COMPONENT pixels 424 is a different beast that doesn't go through the regular pixel path, and 425 ARB_depth_clamp says that clamping doesn't apply there.) 426 427 Note that if depth testing is disabled, the depth clamp enable has no 428 effect on DrawTextureNV, since (a) doesn't apply because DrawTextureNV 429 doesn't generate a geometric primitive that could be clipped. 430 431 (18) How does the rectangle rendered by DrawTextureNV interact with 432 polygon rasterization features (culling, polygon smooth, polygon 433 mode, polygon offset)? 434 435 RESOLVED: None of these features affect DrawTextureNV. The spec refers 436 to the polygon rasterization of the spec only because we apply the same 437 coverage computation rules to DrawTextureNV as are used for 438 rasterization of single-sample and multisample polygons. 439 440 (19) How does this extension interact with conditional rendering? 441 442 UNRESOLVED: If DrawTextureNV is called inside a BeginConditionalRender 443 and EndConditionalRender pair and the query object indicates that 444 rendering should be discarded, the DrawTextureNV command is also 445 discarded. This is consistent with the behavior of DrawPixels. 446 447 448Revision History 449 450 Rev. Date Author Changes 451 ---- -------- -------- ----------------------------------------- 452 1 pbrown Internal revisions. 453 2 09/19/12 sholte Added ES interactions 454