xglcomp

annotate doc/texture_from_pixmap.txt @ 6:3f908f812ec7

find changesets by author, revision, files, or words in the commit message
added docs
author John Tsiombikas <nuclear@member.fsf.org>
date Fri, 29 Jan 2016 10:23:08 +0200
parents
children
rev   line source
nuclear@6 1 Name
nuclear@6 2
nuclear@6 3 EXT_texture_from_pixmap
nuclear@6 4
nuclear@6 5 Name Strings
nuclear@6 6
nuclear@6 7 GLX_EXT_texture_from_pixmap
nuclear@6 8
nuclear@6 9 Contributors
nuclear@6 10
nuclear@6 11 James Jones, NVIDIA
nuclear@6 12 Aaron Plattner, NVIDIA
nuclear@6 13 Andy Ritger, NVIDIA
nuclear@6 14
nuclear@6 15 Contact
nuclear@6 16
nuclear@6 17 David Reveman, Novell, Inc. (davidr 'at' novell.com)
nuclear@6 18
nuclear@6 19 Status
nuclear@6 20
nuclear@6 21 Complete
nuclear@6 22
nuclear@6 23 Version
nuclear@6 24
nuclear@6 25 17 (10 Feb 2009)
nuclear@6 26
nuclear@6 27 Number
nuclear@6 28
nuclear@6 29 344
nuclear@6 30
nuclear@6 31 Dependencies
nuclear@6 32
nuclear@6 33 OpenGL 1.1 is required.
nuclear@6 34 GLX 1.3 is required.
nuclear@6 35 GL_EXT_framebuffer_object affects the definition of this extension.
nuclear@6 36 GL_ARB_texture_rectangle affects the definition of this extension.
nuclear@6 37 GL_ARB_texture_non_power_of_two affects the definition of this extension.
nuclear@6 38 GL_SGIS_generate_mipmap affects the definition of this extension.
nuclear@6 39
nuclear@6 40 Overview
nuclear@6 41
nuclear@6 42 This extension allows a color buffer to be used for both rendering and
nuclear@6 43 texturing.
nuclear@6 44
nuclear@6 45 Only color buffers of pixmaps can be used for texturing by this extension
nuclear@6 46 but other types of drawables can be supported by future extensions layered
nuclear@6 47 on top of this extension.
nuclear@6 48
nuclear@6 49 The functionality of this extension is similar to WGL_ARB_render_texture.
nuclear@6 50 However, the purpose of this extension is not to provide
nuclear@6 51 "render to texture" like functionality but rather the ability to bind
nuclear@6 52 an existing X drawable to a texture. Though, there is nothing that
nuclear@6 53 prohibits it from being used for "render to texture".
nuclear@6 54
nuclear@6 55 - Windows are problematic as they can change size and therefore are not
nuclear@6 56 supported by this extension.
nuclear@6 57
nuclear@6 58 - Only a color buffer of a GLX pixmap created using an FBConfig with
nuclear@6 59 attribute GLX_BIND_TO_TEXTURE_RGB_EXT or GLX_BIND_TO_TEXTURE_RGBA_EXT
nuclear@6 60 set to TRUE can be bound as a texture.
nuclear@6 61
nuclear@6 62 - The texture internal format is determined when the color buffer
nuclear@6 63 is associated with the texture, guaranteeing that the color
nuclear@6 64 buffer format is equivalent to the texture internal format.
nuclear@6 65
nuclear@6 66 - A client can create a complete set of mipmap images if
nuclear@6 67 EXT_framebuffer_object is supported.
nuclear@6 68
nuclear@6 69
nuclear@6 70 IP Status
nuclear@6 71
nuclear@6 72 There are no known IP issues.
nuclear@6 73
nuclear@6 74 Issues
nuclear@6 75
nuclear@6 76 1. What should this extension be called?
nuclear@6 77
nuclear@6 78 Even though it is very similar to WGL_ARB_render_texture that name is
nuclear@6 79 not appropriate as the intention of this extension is not
nuclear@6 80 "render to texture" like functionality.
nuclear@6 81
nuclear@6 82 EXT_texture_from_pixmap seams most appropriate. Layering of future
nuclear@6 83 extensions on top of this extension for using other type of drawables
nuclear@6 84 as textures follows the same conventions as vertex/pixel buffer objects
nuclear@6 85 and vertex/fragment programs.
nuclear@6 86
nuclear@6 87
nuclear@6 88 2. Should we allow applications to render to different mipmap levels and
nuclear@6 89 cube map faces?
nuclear@6 90
nuclear@6 91 In order to discourage the use of this extension as a render to texture
nuclear@6 92 mechanism, cube maps and rendering directly to mip-map levels > 0 will
nuclear@6 93 not be supported. A new FBConfig attribute is introduced that specifies
nuclear@6 94 whether or not drawables created with that config will support multiple
nuclear@6 95 mipmap levels when bound to a texture. The other mipmap levels can be
nuclear@6 96 filled in by the EXT_framebuffer_object GenerateMipmapEXT function.
nuclear@6 97
nuclear@6 98 Specifying which level of a pixmap was being rendered to on a per-drawable
nuclear@6 99 basis, as was done in the WGL_ARB_render_texture extension, also
nuclear@6 100 introduces concurrency issues. The state of the drawable when it was
nuclear@6 101 being rendered two by two separate threads of execution and both were
nuclear@6 102 changing the mipmap level was difficult to define.
nuclear@6 103
nuclear@6 104 It is also desireable to keep this extension as simple as possible.
nuclear@6 105 Adding functionality that complicates the implementation and that is not
nuclear@6 106 directly relevenat to the goal of exposing a mechanism for texturing from
nuclear@6 107 arbitrary X pixmaps is not productive. If the ability to render directly
nuclear@6 108 to all levels of a texture is needed, EXT_framebuffer_object is the
nuclear@6 109 extension that should be used.
nuclear@6 110
nuclear@6 111
nuclear@6 112 3. Should 1D textures be supported?
nuclear@6 113
nuclear@6 114 X servers layered on top of an OpenGL implementation might not be able
nuclear@6 115 to support this. A new FBConfig attribute is introduced specifying
nuclear@6 116 which texture targets a drawable created with the given FBConfig can
nuclear@6 117 be bound to.
nuclear@6 118
nuclear@6 119
nuclear@6 120 4. What should the default value for GLX_TEXTURE_TARGET_EXT be? Should
nuclear@6 121 users be required to set this value if GLX_TEXTURE_FORMAT_EXT is not
nuclear@6 122 GLX_TEXTURE_FORMAT_NONE_EXT?
nuclear@6 123
nuclear@6 124 The implementation is capable of choosing a reasonable default, we simply
nuclear@6 125 need to specify the correct way to do so. We can base the ordering on
nuclear@6 126 the properties of the pixmap and the texturing capabilities of the
nuclear@6 127 pixmap's FBConfig and the implementation.
nuclear@6 128
nuclear@6 129 The order is:
nuclear@6 130
nuclear@6 131 - If GL_ARB_texture_non_power_of_two is supported GL_TEXTURE_2D will
nuclear@6 132 be used for all pixmap sizes.
nuclear@6 133
nuclear@6 134 - If only GL_ARB_texture_rectangle is supported GL_TEXTURE_2D will
nuclear@6 135 be used for all power of two pixmap sizes and GL_TEXTURE_RECTANGLE_ARB
nuclear@6 136 will be used for all non power of two pixmap sizes.
nuclear@6 137
nuclear@6 138
nuclear@6 139 5. Should users be required to re-bind the drawable to a texture after
nuclear@6 140 the drawable has been rendered to?
nuclear@6 141
nuclear@6 142 It is difficult to define what the contents of the texture would be if
nuclear@6 143 we don't require this. Also, requiring this would allow implementations
nuclear@6 144 to perform an implicit copy at this point if they could not support
nuclear@6 145 texturing directly out of renderable memory.
nuclear@6 146
nuclear@6 147 The problem with defining the contents of the texture after rendering
nuclear@6 148 has occured to the associated drawable is that there is no way to
nuclear@6 149 synchronize the use of the buffer as a source and as a destination.
nuclear@6 150 Direct OpenGL rendering is not necessarily done in the same command
nuclear@6 151 stream as X rendering. At the time the pixmap is used as the source
nuclear@6 152 for a texturing operation, it could be in a state halfway through a
nuclear@6 153 copyarea operation in which half of it is say, white, and half is the
nuclear@6 154 result of the copyarea operation. How is this defined? Worse, some
nuclear@6 155 other OpenGL application could be halfway through a frame of rendering
nuclear@6 156 when the composite manager sources from it. The buffer might just
nuclear@6 157 contain the results of a "glClear" operation at that point.
nuclear@6 158
nuclear@6 159 To gurantee tear-free rendering, a composite manager would run as follows:
nuclear@6 160
nuclear@6 161 -receive request for compositing:
nuclear@6 162 XGrabServer()
nuclear@6 163 glXWaitX() or XSync()
nuclear@6 164 glXBindTexImageEXT()
nuclear@6 165
nuclear@6 166 <Do rendering/compositing>
nuclear@6 167
nuclear@6 168 glXReleaseTexImageEXT()
nuclear@6 169 XUngrabServer()
nuclear@6 170
nuclear@6 171 Apps that don't synchronize like this would get what's available,
nuclear@6 172 and that may or may not be what they expect.
nuclear@6 173
nuclear@6 174
nuclear@6 175 6. What is the result of calling GenerateMipmapEXT on a drawable that
nuclear@6 176 was not created with mipmap levels?
nuclear@6 177
nuclear@6 178 The results are undefined.
nuclear@6 179
nuclear@6 180
nuclear@6 181 7. Rendering done by the window system may be y-inverted compared
nuclear@6 182 to the standard OpenGL texture representation. More specifically:
nuclear@6 183 the X Window system uses a coordinate system where the origin is in
nuclear@6 184 the upper left; however, the GL uses a coordinate system where the
nuclear@6 185 origin is in the lower left. Should we define the contents of the
nuclear@6 186 texture as the y-inverted contents of the drawable?
nuclear@6 187
nuclear@6 188 X implementations may represent their drawables differently internally,
nuclear@6 189 so y-inversion should be exposed as an FBConfig attribute.
nuclear@6 190 Applications will need to query this attribute and adjust their rendering
nuclear@6 191 appropriately.
nuclear@6 192
nuclear@6 193 If a drawables is y-inverted and is bound to a texture, the contents of the
nuclear@6 194 texture will be y-inverted with respect to the standard GL memory layout.
nuclear@6 195 This means the contents of a pixmap of size (width, height) at pixmap
nuclear@6 196 coordinate (x, y) will be at location (x, height-y-1) in the texture.
nuclear@6 197 Applications will need to adjust their texture coordinates accordingly to
nuclear@6 198 avoid drawing the texture contents upside down.
nuclear@6 199
nuclear@6 200
nuclear@6 201 8. Why wasn't this extension based on FBO instead of ARB_render_texture?
nuclear@6 202 Isn't the render_texture extension deprecated?
nuclear@6 203
nuclear@6 204 At first glance, FBO may seem like the perfect framework to base a spec
nuclear@6 205 for texturing from pixmap surfaces on. It replaced the
nuclear@6 206 WGL_ARB_render_texture specification, which provided a mechanism to
nuclear@6 207 texture from pbuffer surfaces. However, this train of thought is another
nuclear@6 208 side effect of the unfortunate naming of the WGL_ARB_render_texture
nuclear@6 209 specification. FBO and the orginal render_texture specification were
nuclear@6 210 two different solutions to the problem of how to render to and texture
nuclear@6 211 from the same surface. WGL_ARB_render_texture provided a method to bind
nuclear@6 212 a texture to a drawable surface, as this extension does. FBO provides the
nuclear@6 213 opposite solution, allowing rendering to arbitrary surfaces including
nuclear@6 214 textures. In the case of FBO, the application doing the rendering knows
nuclear@6 215 that it needs to render to an alternate surface. In our usage case, the
nuclear@6 216 application doing the rendering is arbitrary, and has no knowledge that another
nuclear@6 217 application wants to use the surface it is rendering to as a texture. The
nuclear@6 218 only application able to name the surface is the one texturing from it.
nuclear@6 219 Therefore, it makes sense to provide a mechanism for binding a texture to
nuclear@6 220 an arbitrary surface in general, and a pixmap in this particular case.
nuclear@6 221
nuclear@6 222
nuclear@6 223 9. Why not allow binding directly to an X pixmap without creating an
nuclear@6 224 intermediate GLX pixmap?
nuclear@6 225
nuclear@6 226 Architecturally, GLX has moved away from operating directly on X
nuclear@6 227 drawables. This allows GLX specific attributes to be associated with the
nuclear@6 228 GLX drawables. In this case, it is important to associate an FBConfig
nuclear@6 229 with the drawable. The FBConfig contains attributes specifying the
nuclear@6 230 internal format the GL will use when utilizing the drawable's framebuffer
nuclear@6 231 as a texture.
nuclear@6 232
nuclear@6 233
nuclear@6 234 New Procedures and Functions
nuclear@6 235
nuclear@6 236 void glXBindTexImageEXT (Display *display,
nuclear@6 237 GLXDrawable drawable,
nuclear@6 238 int buffer,
nuclear@6 239 const int *attrib_list)
nuclear@6 240
nuclear@6 241 void glXReleaseTexImageEXT (Display *display,
nuclear@6 242 GLXDrawable drawable,
nuclear@6 243 int buffer)
nuclear@6 244
nuclear@6 245
nuclear@6 246 New Tokens
nuclear@6 247
nuclear@6 248 Accepted by the <Attribute> parameter of glXGetFBConfigAttrib and
nuclear@6 249 the <attrib_list> parameter of glXChooseFBConfig:
nuclear@6 250
nuclear@6 251 GLX_BIND_TO_TEXTURE_RGB_EXT 0x20D0
nuclear@6 252 GLX_BIND_TO_TEXTURE_RGBA_EXT 0x20D1
nuclear@6 253 GLX_BIND_TO_MIPMAP_TEXTURE_EXT 0x20D2
nuclear@6 254 GLX_BIND_TO_TEXTURE_TARGETS_EXT 0x20D3
nuclear@6 255 GLX_Y_INVERTED_EXT 0x20D4
nuclear@6 256
nuclear@6 257 Accepted as an attribute in the <attrib_list> parameter of
nuclear@6 258 glXCreatePixmap, and by the <attribute> parameter of glXQueryDrawable:
nuclear@6 259
nuclear@6 260 GLX_TEXTURE_FORMAT_EXT 0x20D5
nuclear@6 261 GLX_TEXTURE_TARGET_EXT 0x20D6
nuclear@6 262 GLX_MIPMAP_TEXTURE_EXT 0x20D7
nuclear@6 263
nuclear@6 264 Accepted as a value in the <attrib_list> parameter of glXCreatePixmap
nuclear@6 265 and returned in the <value> parameter of glXQueryDrawable when
nuclear@6 266 <attribute> is GLX_TEXTURE_FORMAT_EXT:
nuclear@6 267
nuclear@6 268 GLX_TEXTURE_FORMAT_NONE_EXT 0x20D8
nuclear@6 269 GLX_TEXTURE_FORMAT_RGB_EXT 0x20D9
nuclear@6 270 GLX_TEXTURE_FORMAT_RGBA_EXT 0x20DA
nuclear@6 271
nuclear@6 272 Accepted as bits in the GLX_BIND_TO_TEXTURE_TARGETS_EXT variable:
nuclear@6 273
nuclear@6 274 GLX_TEXTURE_1D_BIT_EXT 0x00000001
nuclear@6 275 GLX_TEXTURE_2D_BIT_EXT 0x00000002
nuclear@6 276 GLX_TEXTURE_RECTANGLE_BIT_EXT 0x00000004
nuclear@6 277
nuclear@6 278 Accepted as a value in the <attrib_list> parameter of glXCreatePixmap
nuclear@6 279 and returned in the <value> parameter of glXQueryDrawable when
nuclear@6 280 <attribute> is GLX_TEXTURE_TARGET_EXT:
nuclear@6 281
nuclear@6 282 GLX_TEXTURE_1D_EXT 0x20DB
nuclear@6 283 GLX_TEXTURE_2D_EXT 0x20DC
nuclear@6 284 GLX_TEXTURE_RECTANGLE_EXT 0x20DD
nuclear@6 285
nuclear@6 286 Accepted by the <Buffer> parameter of glXBindTexImageEXT and
nuclear@6 287 glXReleaseTexImageEXT:
nuclear@6 288
nuclear@6 289 GLX_FRONT_LEFT_EXT 0x20DE
nuclear@6 290 GLX_FRONT_RIGHT_EXT 0x20DF
nuclear@6 291 GLX_BACK_LEFT_EXT 0x20E0
nuclear@6 292 GLX_BACK_RIGHT_EXT 0x20E1
nuclear@6 293 GLX_FRONT_EXT GLX_FRONT_LEFT_EXT
nuclear@6 294 GLX_BACK_EXT GLX_BACK_LEFT_EXT
nuclear@6 295 GLX_AUX0_EXT 0x20E2
nuclear@6 296 GLX_AUX1_EXT 0x20E3
nuclear@6 297 GLX_AUX2_EXT 0x20E4
nuclear@6 298 GLX_AUX3_EXT 0x20E5
nuclear@6 299 GLX_AUX4_EXT 0x20E6
nuclear@6 300 GLX_AUX5_EXT 0x20E7
nuclear@6 301 GLX_AUX6_EXT 0x20E8
nuclear@6 302 GLX_AUX7_EXT 0x20E9
nuclear@6 303 GLX_AUX8_EXT 0x20EA
nuclear@6 304 GLX_AUX9_EXT 0x20EB
nuclear@6 305
nuclear@6 306
nuclear@6 307 GLX Protocol
nuclear@6 308
nuclear@6 309 Two new GLX protocol commands are added.
nuclear@6 310
nuclear@6 311 BindTexImageEXT
nuclear@6 312 1 CARD8 opcode (X assigned)
nuclear@6 313 1 16 GLX opcode (glXVendorPrivate)
nuclear@6 314 2 6+n request length
nuclear@6 315 4 1330 vendor specific opcode
nuclear@6 316 4 CARD32 context tag
nuclear@6 317 4 GLX_DRAWABLE drawable
nuclear@6 318 4 INT32 buffer
nuclear@6 319 4 CARD32 num_attributes
nuclear@6 320 4*n LISTofATTRIBUTE_PAIR attribute, value pairs.
nuclear@6 321
nuclear@6 322 ReleaseTexImageEXT
nuclear@6 323 1 CARD8 opcode (X assigned)
nuclear@6 324 1 16 GLX opcode (glXVendorPrivate)
nuclear@6 325 2 5 request length
nuclear@6 326 4 1331 vendor specific opcode
nuclear@6 327 4 CARD32 context tag
nuclear@6 328 4 GLX_DRAWABLE drawable
nuclear@6 329 4 INT32 buffer
nuclear@6 330
nuclear@6 331
nuclear@6 332 Errors
nuclear@6 333
nuclear@6 334 Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
nuclear@6 335
nuclear@6 336 None.
nuclear@6 337
nuclear@6 338 Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)
nuclear@6 339
nuclear@6 340 None.
nuclear@6 341
nuclear@6 342 Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment
nuclear@6 343 Operations and the Frame Buffer)
nuclear@6 344
nuclear@6 345 None.
nuclear@6 346
nuclear@6 347 Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
nuclear@6 348
nuclear@6 349 None.
nuclear@6 350
nuclear@6 351 Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State
nuclear@6 352 Requests)
nuclear@6 353
nuclear@6 354 None.
nuclear@6 355
nuclear@6 356 Additions to the GLX Specification
nuclear@6 357
nuclear@6 358 Add to table 3.1, GLXFBConfig Attributes:
nuclear@6 359
nuclear@6 360 Attribute Type Notes
nuclear@6 361 ------------------------------- ------- -------------------------------------------------------------------
nuclear@6 362 GLX_BIND_TO_TEXTURE_RGB_EXT boolean True if color buffers can be bound to RGB texture
nuclear@6 363 GLX_BIND_TO_TEXTURE_RGBA_EXT boolean True if color buffers can be bound to RGBA texture
nuclear@6 364 GLX_BIND_TO_MIPMAP_TEXTURE_EXT boolean True if color buffers can be bound to textures with multiple levels
nuclear@6 365 GLX_BIND_TO_TEXTURE_TARGETS_EXT bitmask Bitmask of texture targets color buffers can be bound to
nuclear@6 366 GLX_Y_INVERTED_EXT boolean True if the drawable's framebuffer is y-inverted. This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target.
nuclear@6 367
nuclear@6 368 Additions to table 3.4, Default Match Criteria for GLXFBConfig attributes:
nuclear@6 369
nuclear@6 370 Attribute Default Selection Criteria Priority
nuclear@6 371 ------------------------------- -------------------- ------------------ ---------
nuclear@6 372 GLX_BIND_TO_TEXTURE_RGB_EXT GLX_DONT_CARE Exact
nuclear@6 373 GLX_BIND_TO_TEXTURE_RGBA_EXT GLX_DONT_CARE Exact
nuclear@6 374 GLX_BIND_TO_MIPMAP_TEXTURE_EXT GLX_DONT_CARE Exact
nuclear@6 375 GLX_BIND_TO_TEXTURE_TARGETS_EXT - Mask
nuclear@6 376 GLX_Y_INVERTED_EXT GLX_DONT_CARE Exact
nuclear@6 377
nuclear@6 378 Modifications to 3.3.3, "Configuration Management"
nuclear@6 379
nuclear@6 380 Add after paragraph 17 in the description of FBConfigs:
nuclear@6 381
nuclear@6 382 GLX_Y_INVERTED_EXT is a boolean describing the memory layout used for
nuclear@6 383 drawables created with the GLXFBConfig. The attribute is True if the
nuclear@6 384 drawable's framebuffer will be y-inverted. This can be used to determine
nuclear@6 385 if y-inverted texture coordinates need to be used when texturing from this
nuclear@6 386 drawable when it is bound to a texture target.
nuclear@6 387
nuclear@6 388 Modifications to 3.3.5, "Offscreen Rendering"
nuclear@6 389
nuclear@6 390 Modify paragraph 3 of the description of glXCreatePixmap:
nuclear@6 391
nuclear@6 392 <attrib_list> specifies a list of attributes for the pixmap. The list has
nuclear@6 393 the same structure as described for glXChooseFBConfig. Currently the
nuclear@6 394 following attributes can be specified in attrib_list:
nuclear@6 395 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT, GLX_MIPMAP_TEXTURE_EXT,
nuclear@6 396 attrib_list may be NULL or empty (first attribute of None), in which case
nuclear@6 397 all attributes assume their default values as described below.
nuclear@6 398
nuclear@6 399 GLX_TEXTURE_FORMAT_EXT describes the texture format this pixmap can be
nuclear@6 400 bound to. Valid values are GLX_TEXTURE_FORMAT_RGB_EXT,
nuclear@6 401 GLX_TEXTURE_FORMAT_RGBA_EXT, and GLX_TEXTURE_FORMAT_NONE_EXT.
nuclear@6 402
nuclear@6 403 GLX_TEXTURE_TARGET_EXT can be set to GLX_TEXTURE_1D_EXT,
nuclear@6 404 GLX_TEXTURE_2D_EXT, or GLX_TEXTURE_RECTANGLE_EXT; it indicates the type
nuclear@6 405 of texture that will be created when GLX_TEXTURE_FORMAT_EXT is not
nuclear@6 406 GLX_TEXTURE_FORMAT_NONE_EXT. The default value of GLX_TEXTURE_TARGET_EXT
nuclear@6 407 depends on the capabilities in <config> and the dimensions of the pixmap.
nuclear@6 408 If <config> has GLX_TEXTURE_2D_BIT set and one or more of the following is
nuclear@6 409 true:
nuclear@6 410
nuclear@6 411 * GLX_TEXTURE_RECTANGLE_BIT_EXT is not set in <config>
nuclear@6 412
nuclear@6 413 * GL_ARB_texture_non_power_of_two is supported
nuclear@6 414
nuclear@6 415 * the pixmap's width and height are powers of 2
nuclear@6 416
nuclear@6 417 the default value for GLX_TEXTURE_TARGET_EXT is GLX_TEXTURE_2D_EXT.
nuclear@6 418
nuclear@6 419 Otherwise, the first supported target is chosen in this order:
nuclear@6 420 GLX_TEXTURE_RECTANGLE_EXT, GLX_TEXTURE_1D_EXT.
nuclear@6 421
nuclear@6 422 GLX_MIPMAP_TEXTURE_EXT indicates that storage for mipmaps should be
nuclear@6 423 allocated. Space for mipmaps will be set aside if GLX_TEXTURE_FORMAT_EXT
nuclear@6 424 is not GLX_TEXTURE_FORMAT_NONE_EXT and GLX_MIPMAP_TEXTURE_EXT is TRUE.
nuclear@6 425 The default value is FALSE.
nuclear@6 426
nuclear@6 427 Modify paragraph 5 of the description of glXCreatePixmap:
nuclear@6 428
nuclear@6 429 ...If <pixmap> is not a valid Pixmap XID, then a BadPixmap error is
nuclear@6 430 generated. A BadConfig error is generated if any of the following
nuclear@6 431 conditions are true:
nuclear@6 432
nuclear@6 433 * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGB_EXT and
nuclear@6 434 <config> does not have GLX_BIND_TO_TEXTURE_RGB set to TRUE.
nuclear@6 435
nuclear@6 436 * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGBA_EXT and
nuclear@6 437 <config> does not have GLX_BIND_TO_TEXTURE_RGBA set to TRUE.
nuclear@6 438
nuclear@6 439 * GLX_MIPMAP_TEXTURE_EXT is set to TRUE and <config> does not
nuclear@6 440 have GLX_BIND_TO_MIPMAP_EXT set to TRUE.
nuclear@6 441
nuclear@6 442 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_1D_EXT
nuclear@6 443 and <config> does not have GLX_TEXTURE_1D_BIT_EXT set.
nuclear@6 444
nuclear@6 445 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_2D_EXT
nuclear@6 446 and <config> does not have GLX_TEXTURE_2D_BIT_EXT set.
nuclear@6 447
nuclear@6 448 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_RECTANGLE_EXT
nuclear@6 449 and <config> does not have GLX_TEXTURE_RECTANGLE_BIT_EXT set.
nuclear@6 450
nuclear@6 451 A BadValue error is generated if GLX_TEXTURE_FORMAT_EXT is not
nuclear@6 452 GLX_TEXTURE_FORMAT_NONE_EXT and the width or height of <pixmap> are
nuclear@6 453 incompatible with the specified value of GLX_TEXTURE_TARGET_EXT on this
nuclear@6 454 implementation. (e.g., the pixmap size is not a power of 2 and
nuclear@6 455 GL_ARB_texture_rectangle is not supported).
nuclear@6 456
nuclear@6 457 Modify paragraph 1 of the description of glXDestroyPixmap:
nuclear@6 458
nuclear@6 459 ...The storage for the GLX pixmap will be freed when it is not current
nuclear@6 460 to any client and all color buffers that are bound to a texture object
nuclear@6 461 have been released.
nuclear@6 462
nuclear@6 463
nuclear@6 464 Modifications to seciton 3.3.6, "Querying Attributes"
nuclear@6 465
nuclear@6 466 Modify paragraph 1 of the description of glXQueryDrawable:
nuclear@6 467
nuclear@6 468 ...<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT,
nuclear@6 469 GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID,
nuclear@6 470 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT or GLX_MIPMAP_TEXTURE_EXT
nuclear@6 471 or a BadValue error is generated.
nuclear@6 472
nuclear@6 473 Modify paragraph 3 of the description of glXQueryDrawable:
nuclear@6 474
nuclear@6 475 ...If <draw> is a GLXWindow or GLXPixmap and <attribute> is set to
nuclear@6 476 GLX_PRESERVED_CONTENTS or GLX_LARGEST_PBUFFER, or if <draw> is a
nuclear@6 477 GLXWindow or GLXPbuffer and <attribute> is set to GLX_TEXTURE_FORMAT_EXT,
nuclear@6 478 GLX_TEXTURE_TARGET_EXT, or GLX_MIPMAP_TEXTURE_EXT, the contents of <value>
nuclear@6 479 are undefined.
nuclear@6 480
nuclear@6 481 Add a new section 3.3.6.1, "Texturing From Drawables"
nuclear@6 482
nuclear@6 483 The command
nuclear@6 484
nuclear@6 485 void glXBindTexImageEXT (Display *dpy,
nuclear@6 486 GLXDrawable draw,
nuclear@6 487 int buffer,
nuclear@6 488 int *attrib_list);
nuclear@6 489
nuclear@6 490 defines a one- or two-dimensional texture image. The texture image is taken
nuclear@6 491 from <buffer> and need not be copied. The texture target, the texture
nuclear@6 492 format, and the size of the texture components are derived from attributes
nuclear@6 493 of <draw>.
nuclear@6 494
nuclear@6 495 The drawable attribute GLX_TEXTURE_FORMAT_EXT determines the base internal
nuclear@6 496 format of the texture. The component sizes are also determined by drawable
nuclear@6 497 attributes as shown in table 3.4a.
nuclear@6 498
nuclear@6 499 Add new table 3.4a: Size of texture components:
nuclear@6 500
nuclear@6 501 Texture component Size
nuclear@6 502 ----------------- --------------
nuclear@6 503 R GLX_RED_SIZE
nuclear@6 504 G GLX_GREEN_SIZE
nuclear@6 505 B GLX_BLUE_SIZE
nuclear@6 506 A GLX_ALPHA_SIZE
nuclear@6 507
nuclear@6 508 The texture target is derived from the GLX_TEXTURE_TARGET_EXT attribute of
nuclear@6 509 <draw>. If the texture target for the drawable is GLX_TEXTURE_2D_EXT or
nuclear@6 510 GLX_TEXTURE_RECTANGLE_EXT, then buffer defines a 2D texture for the current
nuclear@6 511 2D or rectangle texture object respectively; if the texture target is
nuclear@6 512 GLX_TEXTURE_1D_EXT, then buffer defines a 1D texture for the current 1D
nuclear@6 513 texture object.
nuclear@6 514
nuclear@6 515 If <buffer> is not one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT,
nuclear@6 516 GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, or GLX_AUX0_EXT through
nuclear@6 517 GLX_AUXn_EXT, where n is one less than the number of AUX buffers supported
nuclear@6 518 by the FBConfig used to create <draw>, or if the requested buffer is
nuclear@6 519 missing, a BadValue error is generated.
nuclear@6 520
nuclear@6 521 <attrib_list> specifies a list of attributes for the texture. The list has
nuclear@6 522 the same structure as described for glXChooseFBConfig. If <attrib_list> is
nuclear@6 523 NULL or empty (first attribute of None), then all attributes assume their
nuclear@6 524 default values. <attrib_list> must be NULL or empty.
nuclear@6 525
nuclear@6 526 If <dpy> and <draw> are the display and drawable for the calling thread's
nuclear@6 527 current context, glXBindTexImageEXT performs an implicit glFlush.
nuclear@6 528
nuclear@6 529 The contents of the texture after the drawable has been bound are defined
nuclear@6 530 as the result of all rendering that has completed before the call to
nuclear@6 531 glXBindTexImageEXT. In other words, the results of any operation which
nuclear@6 532 has caused damage on the drawable prior to the glXBindTexImageEXT call
nuclear@6 533 will be represented in the texture.
nuclear@6 534
nuclear@6 535 Rendering to the drawable while it is bound to a texture will leave the
nuclear@6 536 contents of the texture in an undefined state. However, no
nuclear@6 537 synchronization between rendering and texturing is done by GLX. It is
nuclear@6 538 the application's responsibility to implement any synchronization
nuclear@6 539 required.
nuclear@6 540
nuclear@6 541 If a texture object is deleted before glXReleaseTexImageEXT is called,
nuclear@6 542 the color buffer is released.
nuclear@6 543
nuclear@6 544 It is not an error to call TexImage2D, TexImage1D, CopyTexImage1D, or
nuclear@6 545 CopyTexImage2D to replace an image of a texture object that has a color
nuclear@6 546 buffer bound to it. However, these calls will cause the color buffer to be
nuclear@6 547 released and new memory to be allocated for the texture. Note that the
nuclear@6 548 color buffer is released even if the image that is being defined is a mipmap
nuclear@6 549 level that was not defined by the color buffer. GenerateMipmapEXT is an
nuclear@6 550 exception. GenerateMipmapEXT can be used to define mipmap levels for
nuclear@6 551 drawables that have been created with GLX_MIPMAP_TEXTURE_EXT set. Calling
nuclear@6 552 GenerateMipmapEXT on a drawable that was created without
nuclear@6 553 GLX_MIPMAP_TEXTURE_EXT is undefined.
nuclear@6 554
nuclear@6 555 The results of calling glXBindTexImageEXT when GENERATE_MIPMAP_SGIS is TRUE
nuclear@6 556 are undefined.
nuclear@6 557
nuclear@6 558 If glXBindTexImageEXT is called and the drawable attribute
nuclear@6 559 GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch
nuclear@6 560 error is generated.
nuclear@6 561
nuclear@6 562 Currently, only pixmaps can be bound to textures. If <draw> is not a
nuclear@6 563 valid GLXPixmap, then a GLXBadPixmap error is generated.
nuclear@6 564
nuclear@6 565 glXBindTexImageEXT is ignored if there is no current GLX rendering context.
nuclear@6 566
nuclear@6 567 To release a color buffer that is being used as a texture, call
nuclear@6 568
nuclear@6 569 void glXReleaseTexImageEXT (Dislpay *dpy, GLXDrawable draw, int buffer);
nuclear@6 570
nuclear@6 571 <buffer> must be one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT,
nuclear@6 572 GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, and GLX_AUX0_EXT through
nuclear@6 573 GLX_AUXn_EXT, where n is one less than the number of AUX buffers
nuclear@6 574 supported by the FBConfig used to create <draw> or a BadValue error
nuclear@6 575 is generated.
nuclear@6 576
nuclear@6 577 The contents of the color buffer are unaffected by glXReleaseTexImageEXT.
nuclear@6 578
nuclear@6 579 If the specified color buffer is no longer bound to a texture (e.g.,
nuclear@6 580 because the texture object was deleted), then glXReleaseTexImageEXT has no effect;
nuclear@6 581 no error is generated.
nuclear@6 582
nuclear@6 583 When a color buffer is released (e.g., by calling glXReleaseTexImageEXT or
nuclear@6 584 implicitly by calling a routine such as TexImage2D), all textures that were
nuclear@6 585 defined by the color buffer become NULL.
nuclear@6 586
nuclear@6 587 If glXReleaseTexImageEXT is called and the drawable attribute
nuclear@6 588 GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch
nuclear@6 589 error is generated.
nuclear@6 590
nuclear@6 591 Currently, only pixmaps can be bound to textures. If <draw> is not a
nuclear@6 592 valid GLXPixmap, then a GLXBadPixmap error is generated.
nuclear@6 593
nuclear@6 594
nuclear@6 595 Usage Examples
nuclear@6 596
nuclear@6 597 Example 1: Bind redirected window to texture:
nuclear@6 598
nuclear@6 599 XGetWindowAttributes (display, window, &attrib);
nuclear@6 600
nuclear@6 601 visualid = XVisualIDFromVisual (attrib.visual);
nuclear@6 602
nuclear@6 603 fbconfigs = glXGetFBConfigs (display, screen, &nfbconfigs);
nuclear@6 604 for (i = 0; i < nfbconfigs; i++)
nuclear@6 605 {
nuclear@6 606 visinfo = glXGetVisualFromFBConfig (display, fbconfigs[i]);
nuclear@6 607 if (!visinfo || visinfo->visualid != visualid)
nuclear@6 608 continue;
nuclear@6 609
nuclear@6 610 glXGetFBConfigAttrib (display, fbconfigs[i], GLX_DRAWABLE_TYPE, &value);
nuclear@6 611 if (!(value & GLX_PIXMAP_BIT))
nuclear@6 612 continue;
nuclear@6 613
nuclear@6 614 glXGetFBConfigAttrib (display, fbconfigs[i],
nuclear@6 615 GLX_BIND_TO_TEXTURE_TARGETS_EXT,
nuclear@6 616 &value);
nuclear@6 617 if (!(value & GLX_TEXTURE_2D_BIT_EXT))
nuclear@6 618 continue;
nuclear@6 619
nuclear@6 620 glXGetFBConfigAttrib (display, fbconfigs[i],
nuclear@6 621 GLX_BIND_TO_TEXTURE_RGBA_EXT,
nuclear@6 622 &value);
nuclear@6 623 if (value == FALSE)
nuclear@6 624 {
nuclear@6 625 glXGetFBConfigAttrib (display, fbconfigs[i],
nuclear@6 626 GLX_BIND_TO_TEXTURE_RGB_EXT,
nuclear@6 627 &value);
nuclear@6 628 if (value == FALSE)
nuclear@6 629 continue;
nuclear@6 630 }
nuclear@6 631
nuclear@6 632 glXGetFBConfigAttrib (display, fbconfigs[i],
nuclear@6 633 GLX_Y_INVERTED_EXT,
nuclear@6 634 &value);
nuclear@6 635 if (value == TRUE)
nuclear@6 636 {
nuclear@6 637 top = 0.0f;
nuclear@6 638 bottom = 1.0f;
nuclear@6 639 }
nuclear@6 640 else
nuclear@6 641 {
nuclear@6 642 top = 1.0f;
nuclear@6 643 bottom = 0.0f;
nuclear@6 644 }
nuclear@6 645
nuclear@6 646 break;
nuclear@6 647 }
nuclear@6 648
nuclear@6 649 if (i == nfbconfigs)
nuclear@6 650 /* error 1 */
nuclear@6 651
nuclear@6 652 pixmap = XCompositeNameWindowPixmap (display, window);
nuclear@6 653 pixmapAttribs = { GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT,
nuclear@6 654 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT,
nuclear@6 655 None };
nuclear@6 656 glxpixmap = glXCreatePixmap (display, fbconfigs[i], pixmap, pixmapAttribs);
nuclear@6 657
nuclear@6 658 glGenTextures (1, &texture);
nuclear@6 659 glBindTexture (GL_TEXTURE_2D, texture);
nuclear@6 660
nuclear@6 661 glXBindTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT, NULL);
nuclear@6 662
nuclear@6 663 glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
nuclear@6 664 glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
nuclear@6 665
nuclear@6 666 /* draw using pixmap as texture */
nuclear@6 667 glBegin (GL_QUADS);
nuclear@6 668
nuclear@6 669 glTexCoord2d (0.0f, bottom);
nuclear@6 670 glVertex2d (0.0f, 0.0f);
nuclear@6 671
nuclear@6 672 glTexCoord2d (0.0f, top);
nuclear@6 673 glVertex2d (0.0f, 1.0f);
nuclear@6 674
nuclear@6 675 glTexCoord2d (1.0f, top);
nuclear@6 676 glVertex2d (1.0f, 1.0f);
nuclear@6 677
nuclear@6 678 glTexCoord2d (1.0f, bottom);
nuclear@6 679 glVertex2d (1.0f, 0.0f);
nuclear@6 680
nuclear@6 681 glEnd ();
nuclear@6 682
nuclear@6 683 glXReleaseTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT);
nuclear@6 684
nuclear@6 685
nuclear@6 686 Version History
nuclear@6 687
nuclear@6 688 1. 26 Nov 2005 - DavidR
nuclear@6 689 Initial version
nuclear@6 690 2. 01 Dec 2005 - JamesJ
nuclear@6 691 -Adapted spec language from draft version of GLX_ARB_render_texture.
nuclear@6 692 -Added glXDrawableAttribute to set attributes.
nuclear@6 693 -Modified glXBindTexImageEXT to take an attrib_list parameter.
nuclear@6 694 -Added support for cubemap and 1D texture targets.
nuclear@6 695 -Added attribute to set the texture target when creating the
nuclear@6 696 drawable.
nuclear@6 697 -Updated the issues section.
nuclear@6 698 -Added mipmap support. Support is not required.
nuclear@6 699 -Specified results of texturing from a drawable when it has been
nuclear@6 700 rendered to while bound to a texture as undefined until
nuclear@6 701 glXReleaseTexImageEXT has been called. Allows implementations
nuclear@6 702 that need to perform an implicit copy after rendering occurs
nuclear@6 703 to be compatible with this specification.
nuclear@6 704 3. 04 Dec 2005 - DavidR
nuclear@6 705 -Changed name to GLX_EXT_texture_from_pixmap.
nuclear@6 706 -Changed spec regarding what happens when a pixmap that is bound
nuclear@6 707 to a texture is rendered to. Having textures be undefined once
nuclear@6 708 they are rendered to makes it useless for a compositing manager,
nuclear@6 709 which is a major use case for this extension.
nuclear@6 710 -Added support for not specifying texture target when creating a
nuclear@6 711 pixmap. Allows implementations to select whatever target it
nuclear@6 712 finds most suitable.
nuclear@6 713 4. 05 Dec 2005 - JamesJ
nuclear@6 714 -Changed the default value of GLX_TEXTURE_TARGET_EXT from
nuclear@6 715 GLX_NO_TEXTURE_EXT to something usable. Eliminated
nuclear@6 716 GLX_NO_TEXTURE_EXT.
nuclear@6 717 -Eliminated GLX_TEXTURE_NONE_EXT.
nuclear@6 718 -Removed language referring to sharing of color buffers when
nuclear@6 719 pixmaps are bound to textures.
nuclear@6 720 -Updated issues.
nuclear@6 721
nuclear@6 722 5. 13 Dec 2005 - JamesJ
nuclear@6 723 -Removed cube map support and rendering to multiple mipmap
nuclear@6 724 levels support.
nuclear@6 725
nuclear@6 726 6. 20 Jan 2006 - JamesJ
nuclear@6 727 -Specified textures are y-inverted.
nuclear@6 728
nuclear@6 729 7. 23 Jan 2006 - AaronP
nuclear@6 730 -Fix typos, make some things clearer. Replace ocurrences of "released
nuclear@6 731 back to the drawable" with "released".
nuclear@6 732
nuclear@6 733 8. 01 Feb 2006 - AndyR
nuclear@6 734 -Fix minor typos.
nuclear@6 735
nuclear@6 736 9. 03 Feb 2006 - JamesJ
nuclear@6 737 -Added some new issues and their resolutions.
nuclear@6 738 -Finalized some issues that had been in discussion.
nuclear@6 739 -Made drawable y-inversion a queryable attribute of the drawable.
nuclear@6 740 -Moved detailed explanation of y-inverted addressing to the issues
nuclear@6 741 section
nuclear@6 742 -Updated example to demonstrate proper use of the y-inverted
nuclear@6 743 attribute.
nuclear@6 744
nuclear@6 745 10. 06 Feb 2006 - DavidR
nuclear@6 746 -Made GLX_Y_INVERTED_EXT an FBConfig attribute instead of a drawable
nuclear@6 747 attribute.
nuclear@6 748 -Removed GLX_TEXTURE_CUBE_MAP_EXT.
nuclear@6 749 -Fix minor typo.
nuclear@6 750
nuclear@6 751 11. 07 Feb 2006 - JamesJ
nuclear@6 752 -Added description of GLX_Y_INVERTED_EXT GLXFBConfig attribute, based
nuclear@6 753 on description of the drawable attribute of the same name from
nuclear@6 754 and earlier version of the specification.
nuclear@6 755 -Removed language requiring applications to re-bind a pixmap to a
nuclear@6 756 texture to gurantee contents of the texture are updated after a
nuclear@6 757 pixmap has been rendered to.
nuclear@6 758 -Added Aaron Plattner and Andy Ritger to contributors section.
nuclear@6 759
nuclear@6 760 12. 14 Feb 2006 - JamesJ
nuclear@6 761 -Disallowed rendering to a drawable while it is bound as a texture
nuclear@6 762 and defined the exact contents of a texture after a drawable has
nuclear@6 763 been bound to it.
nuclear@6 764
nuclear@6 765 13. 09 Mar 2006 - JamesJ
nuclear@6 766 -Add a context tag member to the vendor private requests. This field
nuclear@6 767 is part of the vendor private header, and is needed to specify which
nuclear@6 768 context the BindTexImageEXT and ReleaseTexImageEXT requests correspond
nuclear@6 769 to.
nuclear@6 770 -Changed texture target bitfield values to not skip numbers removed in
nuclear@6 771 earlier updates.
nuclear@6 772
nuclear@6 773 14. 13 Mar 2006 - JamesJ
nuclear@6 774 -Only require GLX_SGIX_fbconfig + GLX 1.2.
nuclear@6 775 -Clarify language regarding the result of rendering to drawables bound
nuclear@6 776 to textures.
nuclear@6 777 -Added GLX_FRONT_EXT and GLX_BACK_EXT tokens.
nuclear@6 778
nuclear@6 779 15. 18 Apr 2006 - JamesJ
nuclear@6 780 -Allocated enum values and opcodes.
nuclear@6 781 -Require GLX 1.3. GLX_SGIX_fbconfig doesn't allow creating pixmaps
nuclear@6 782 with attributes.
nuclear@6 783 -Added more arguments for not supporting rendering to multiple levels
nuclear@6 784 of a texture with this extension.
nuclear@6 785 -Fixed the inconsistencies in the return type of glXBindTexImageEXT
nuclear@6 786 and glXReleaseTexImageEXT. It is now listed as void throughout.
nuclear@6 787
nuclear@6 788 16. 12 Sep 2006 - JamesJ
nuclear@6 789 -Fix ordering of GLX protocol
nuclear@6 790
nuclear@6 791 17. 10 Feb 2009 - Jon Leech
nuclear@6 792 -Fix typo reported by Jonathan Knispel.