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