Back to the OpenGL extension cross reference
WGL_ARB_render_texture
ARB_render_texture
Name Strings
WGL_ARB_render_texture
Contact
Bimal Poddar, Intel, bimal.poddar@intel.com
Paula Womack, Nvidia, PWomack@nvidia.com
Status
Complete. Approved by ARB on June 13, 2001
Version
Last Modified Date: July 16, 2001
Number
ARB Extension #20
Dependencies
OpenGL 1.1 is required.
WGL_ARB_extension_string is required.
WGL_ARB_pixel_format is required.
WGL_ARB_pbuffer is required.
WGL_ARB_make_current_read affects the definition of this extension.
GL_ARB_texture_cube_map affects the definition of this extension
The extension is written against the OpenGL 1.2.1 Specification.
Overview
This extension allows a color buffer to be used for both rendering and
texturing. When a color buffer is bound to a texture target it cannot
be rendered to. Once it has been released from the texture it can be
rendered to once again.
This extension may provide a performance boost and reduce memory
requirements on architectures that support rendering to the same
memory where textures reside and in the same memory format and layout
required by texturing. The functionality is similar to CopyTexImage1D
and CopyTexImage2D. However, some changes were made to make it easier
to avoid copying data:
- Only color buffers of a pbuffer can be bound as a texture. It is
not possible to use the color buffer of a window as a texture.
- The texture internal format is determined when the color buffer
is associated with the texture, guaranteeing that the color
buffer format is equivalent to the texture internal format.
- When a color buffer of a pbuffer is being used as a texture,
the pbuffer can not be used for rendering; this makes it
easier for implementations to avoid a copy of the image
since the semantics of the pointer swap are clear.
- The application must release the color buffer from the texture
before it can render to the pbuffer again. When the color buffer
is bound as a texture, draw and read operations on the pbuffer
are undefined.
- A mipmap attribute can be set, in which case memory will be
allocated up front for mipmaps. The application can render
the mipmap images or, if SGIS_generate_mipmap is supported,
they can be automatically generated when the color buffer is
bound as a texture.
- A texture target is associated with the pbuffer, so that cubemap
images can be rendered into a single color buffer.
Note that this extension may be used in conjunction with other
extensions to associate video images/buffers to pbuffers. Once the
video image is associated with a pbuffer it can be used as a texture.
Also, if SGIX_generate_mipmap is supported, it is possible to
create a complete set of mipmap images from a single color buffer.
IP Status
There are no known IP issues.
Issues
1. Should we support 3D textures? What about 1D textures?
3D textures - No. This adds a lot of implementation burden without
having a good usage model.
1D textures - Yes. Just a special case of 2D texture.
2. Should we allow a portion of the color buffer to be used as a texture?
No, if a different size texture is needed the application can just
create another pbuffer.
3. Do we need the MIPMAP_TEXTURE attribute?
Yes this is good to have since some architectures may require all or
some of the mipmaps to be stored together in memory.
4. Should we require power of 2 textures?
Yes, we will allow an implementation to fail if the texture size is
not a power of 2. This restriction can be relaxed later by the
exension that allows non-power of 2 texture.
5. Should the render texture attributes be per color buffer or per drawable?
There really isn't a mechanism for associating attributes with the color
buffer. Also, allowing different render texture attributes for each
color buffer makes the extension more difficult to implement without
providing a very useful tool for applications.
6. What should happen if the color buffer is used for rendering before it
is released from the texture?
There are three reasonable options: generate an error, create another
buffer or have the rendering results be undefined. Since this is an
error condition, and not a useful feature, we should pick the option
that is easiest to implement. For now, we choose to have the rendering
results be undefined--the rendering commands will be processed and the
context will be updated but the pbuffer may or may not be updated.
Note that the pbuffer that contains the color buffer can be bound to a
different context, so the invalid state must be stored with the pbuffer,
not the context.. (Also the texture object that contains the
color buffer's image may be released from the current context).
7. Should the new pbuffer attributes be available through GL queries?
No, like other pbuffer attributes you need to query them through the
window system extension. This extension does not make any changes to
OpenGL.
8. Should we allow a subset of mipmaps to be defined?
No.
9. What happens when a pbuffer is bound as a texture and then a mode
change occurs and the pbuffer is lost?
The texture is not lost in this case. OpenGL doesn't have the notion
of volatile textures and this extension should not introduce them.
(It may be an interesting additional extension). When a color buffer
is bound to a texture, it must be saved and restored by the driver,
whenever texture memory is lost (even on a windows mode change).
10. Should there be any restrictions on the texture operations that
can be performed on a color buffer?
Yes. We allow TexSubImage and CopyTexSubImage calls but disallow
TexImage and CopyTexImage calls. When a TexImage or CopyTexImage call
is made then the color buffer is released back to the pbuffer and
new memory is allocated for the texture. No mixing and matching of
images is allowed. In other words, it is not possible to render a
non-mipmapped image to a pbuffer, bind it to a texture and then
call TexImage2D to create the other mipmap levels. Modifying any
mipmap level via TexImage or CopyTexImage will cause the color
buffer to be released back to the pbuffer, even if that level
was not defined by the color buffer.
Also, if DeleteTextures is called on the texture target, then the
color buffer that is bound to the texture target is released back
to the pbuffer.
The implicit release of the color buffer is intended to work just
like an explicit release - i.e. the color buffer is available for
rendering without the app having to call ReleaseTexImage.
11. When the color buffer is released from the texture (back to the pbuffer)
should the contents be preserved?
No, this may prove difficult to implement on some architectures.
12. Should releasing the color buffer from the texture (back to the pbuffer)
affect the scissor or viewport?
No, since releasing the color buffer, does not change its size, it
should not affect the scissor or viewport. The application is also
responsible for updating the viewport and scissor when changing which
mipmap level it is rendering to (this is similar to window resize,
where the application is responsible for updating the scissor and
viewport).
13. How should swap buffers work when a color buffer is bound as a texture?
Since a color buffer (not a pbuffer) is bound to a texture, swap buffers
should be a no-op. Otherwise the name of the bound buffer (FRONT, BACK)
will change while it is bound. Note that swap buffers works just as
for a pbuffer when the color buffer is not bound as a texture.
14. What happens when the application binds one color buffer of a pbuffer
to a texture and then tries to render to another color buffer of the
pbuffer?
If any of the pbuffer's color buffers are bound to a texture, then
rendering results are undefined for all color buffers of the pbuffer.
15. Should it be an error to bind a color buffer of a pbuffer to a
texture, if that pbuffer is current to another thread?
No. It is not an error to make a drawable current to two threads right
now. Read and draw operations produce indeterminate results when the
pbuffer is bound to a texture.
16. Should we allow color buffers of all drawables (pbuffers and windows)
to be bound to textures?
For now we just allow pbuffers. This is simpler since they are not
shared with the window system and the color buffers are not part of the
visible framebuffer. Also, windows can be resized at any time and
handling this resize would unnecessarily complicate this extension.
17. Should we allow depth buffers to be bound as textures?
This extension does not provide for this but it would be an interesting
additional extension. When a color buffer is bound to a texture, only
the color buffer is moved--ancillary buffers continue to be bound to
the pbuffer.
This extension is written such that adding depth textures should
be very easy.
18. What happens when a color buffer is bound to a shared texture object?
Since the color buffer is associated with the texture object itself,
it should be shared.
19. Should we specify how this extension interacts with SGIS_generate_mipmap?
No, since this is a potential ARB extension and SGIS_generate_mipmap
is not. If SGIS_generate_mipmap is supported along with this extension,
then if wglBindTexImageARB is called and both GENERATE_MIPMAP_SGIS and
WGL_MIPMAP_TEXTURE_ARB are TRUE, then a set of mipmaps should be
generated. This behaviour needs to be documented in the
SGIS_generate_mipmap (or equivalent) extension.
20. Should we support borders on render textures?
No. Although borders are part of 1.2.1, they are often not supported
and better techniques (such as virtual textures) are starting to
become available for paging in large textures.
21. Should wglBindTexImageARB take an attribute indicating whether
mipmaps are defined or should this be implied from the
WGL_MIPMAP_TEXTURE_ARB attribute of the pbuffer?
This should be implied from the WGL_MIPMAP_TEXTURE_ARB attribute
since GL allows controls for the applications to use only level zero
image even if the pbuffer has been defined large enough to
store mipmaps.
22. This extension introduces pbuffer attributes that can be modified.
(Previously all pbuffer attributes were static and could not be
changed.) Should we allow the non-static attributes to be set when the
pbuffer is created or should we require the application to call
wglSetPbufferAttribARB?
We require the application to call wglSetPbufferAttribARB to set
non-static Pbuffer attributes since this seems to be more consistent
with OpenGL specification.
23. Do we need WGL_TEXTURE_FORMAT_ARB or is WGL_ALPHA_BITS_ARB enough
to distinguish between selecting RGB vs. RGBA textures? Additionally,
how is this parameter defined for non texture buffers.
Resolved: In order to accomodate RGBA visuals to support RGB textures
(i.e. ignore alpha) and to allow the specification to be extensible
for depth textures, WGL_TEXTURE_FORMAT_ARB is required in this
specification. This parameter is defined as WGL_NO_TEXTURE_ARB for
non texture buffers.
24. Should luminance and Intensity texture formats be allowed?
No. WGL doesn't support single-channel framebuffer formats. Allowing
these formats would require a copy to reformat a RGB/RGBA framebuffer
to a Luminance or Intensity format. If luminance framebuffer gets
added to WGL, then this feature can be added at that time.
Implementation Notes
1. In order to prevent releases of a pbuffer from the texture object
and to deal with implicit release followed by an explicit release,
the GL implementation can keep a reference to any texture pbuffer
in the texture object. When the pbuffer is released, this handle
is set to NULL. Subsequent requests for releasing the texture
pbuffer are ignored.
2. The implicit release of the color buffers has been specifed to
work just like the explicit release so that the implementation
can delete a texture object (one of the implicit free cases) without
having to track whether the texture was associated with any color buffers.
Intended Usage
To define a cube map texture, single threaded case
1) Create the rendering window. Call wglChoosePixelFormatARB and
find a suitable pixel format for rendering the image. Set the pixel
format for the rendering window to this pixel format.
2) Create the pbuffer. Call wglChoosePixelFormatARB and find a
suitable pixel format for rendering the texture.
WGL_DRAW_TO_PBUFFER and WGL_BIND_TO_TEXTURE_RGB_ARB or
WGL_BIND_TO_TEXTURE_RGBA_ARB must be TRUE. Create the pbuffer
with this pixel format. Set the pbuffer width and height to the
width and height of the level zero image. Set WGL_TEXTURE_FORMAT_ARB
to be WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB. Also set
WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_CUBE_MAP_ARB.
3) Create a context for the pbuffer. Make the context current to the
pbuffer and initialize the context's attributes.
4) Render all the cube map faces to the pbuffer. Call
wglSetPbufferAttribARB to set the cube map face before rendering
each face. Call glFlush.
5) Create a context for the window. Make the context current to the
window and intialize the contexts attributes. Bind a texture object
to the TEXTURE_CUBE_MAP_ARB target and set the texture parameters
to the desired values.
6) Call wglBindTexImageARB to bind the pbuffer drawable to the cube
map texture. Set <iBuffer> to WGL_FRONT or WGL_BACK depending upon
which color buffer was used for rendering the cube map.
7) Render to the window using the cube map texture.
8) Call wglReleaseTexImageARB to release the color buffer of the
pbuffer. Goto step 4 to generate more frames.
To define a 2D texture, single threaded case
In step 2, set the WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_2D_ARB.
Since a 2D texture does not have multiple faces, in step 5
there is no need to call wglSetPbufferAttribARB.
In addition, if mipmaps are to be generated, the step 5 should
be repeated multiple times with calls to wglSetPbufferAttribARB
to set different mip levels.
BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)
BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)
BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer,
const int *piAttribList)
Accepted by the <piAttributes> parameter of wglGetPixelFormatAttribivARB,
wglGetPixelFormatAttribfvARB, and the <piAttribIList> and <pfAttribIList>
parameters of wglChoosePixelFormatARB:
WGL_BIND_TO_TEXTURE_RGB_ARB 0x2070
WGL_BIND_TO_TEXTURE_RGBA_ARB 0x2071
Accepted by the <piAttribList> parameter of wglCreatePbufferARB and
by the <iAttribute> parameter of wglQueryPbufferARB:
WGL_TEXTURE_FORMAT_ARB 0x2072
WGL_TEXTURE_TARGET_ARB 0x2073
WGL_MIPMAP_TEXTURE_ARB 0x2074
Accepted as a value in the <piAttribList> parameter of
wglCreatePbufferARB and returned in the value parameter of
wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_FORMAT_ARB:
WGL_TEXTURE_RGB_ARB 0x2075
WGL_TEXTURE_RGBA_ARB 0x2076
WGL_NO_TEXTURE_ARB 0x2077
Accepted as a value in the <piAttribList> parameter of
wglCreatePbufferARB and returned in the value parameter of
wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_TARGET_ARB:
WGL_TEXTURE_CUBE_MAP_ARB 0x2078
WGL_TEXTURE_1D_ARB 0x2079
WGL_TEXTURE_2D_ARB 0x207A
WGL_NO_TEXTURE_ARB 0x2077
Accepted by the <piAttribList> parameter of wglSetPbufferAttribARB and
by the <iAttribute> parameter of wglQueryPbufferARB:
WGL_MIPMAP_LEVEL_ARB 0x207B
WGL_CUBE_MAP_FACE_ARB 0x207C
Accepted as a value in the <piAttribList> parameter of
wglSetPbufferAttribARB and returned in the value parameter of
wglQueryPbufferARB when <iAttribute> is WGL_CUBE_MAP_FACE_ARB:
WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB 0x207D
WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB 0x207E
WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB 0x207F
WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB 0x2080
WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB 0x2081
WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB 0x2082
Accepted by the <iBuffer> parameter of wglBindTexImageARB and
wglReleaseTexImageARB:
WGL_FRONT_LEFT_ARB 0x2083
WGL_FRONT_RIGHT_ARB 0x2084
WGL_BACK_LEFT_ARB 0x2085
WGL_BACK_RIGHT_ARB 0x2086
WGL_AUX0_ARB 0x2087
WGL_AUX1_ARB 0x2088
WGL_AUX2_ARB 0x2089
WGL_AUX3_ARB 0x208A
WGL_AUX4_ARB 0x208B
WGL_AUX5_ARB 0x208C
WGL_AUX6_ARB 0x208D
WGL_AUX7_ARB 0x208E
WGL_AUX8_ARB 0x208F
WGL_AUX9_ARB 0x2090
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)
None.
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
None.
Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State
Requests)
None.
Additions to the WGL Specification
Add to the description of <piAttributes> in wglGetPixelFormatAttribivARB
and <pfAttributes> in wglGetPixelFormatfv:
WGL_BIND_TO_TEXTURE_RGB_ARB
WGL_BIND_TO_TEXTURE_RGBA_ARB
True if the color buffers can be bound to a RGB/RGBA texture.
Currently only pbuffers can be bound as textures so this attribute
will only be TRUE if WGL_DRAW_TO_PBUFFER is also TRUE. It is
possible to bind a RGBA visual to a RGB texture in
which case the values in the alpha component of the visual
are ignored when the color buffer is used as a RGB texture.
Implementations may choose not to support WGL_BIND_TO_TEXTURE_RGB_ARB
for RGBA visuals.
Add new table entries to match criteria in description of
wglChoosePixelFormatARB:
Attribute Type Match Criteria
WGL_BIND_TO_TEXTURE_RGB_ARB boolean exact
WGL_BIND_TO_TEXTURE_RGBA_ARB boolean exact
Modify wglCreatePbufferARB:
HPBUFFERARB wglCreatePbufferARB (HDC hDC, int iPixelFormat,
int iWidth, int iHeight, const int *piAttribList);
...
<iWidth> and <iHeight> specify the pixel width and height of the
rectangular pbuffer. If the texture format is set to
WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB using
WGL_TEXTURE_FORMAT_ARB, then the pbuffer width and height
specify the size of the level zero texture image or, in the
case of a cube map texture, each level zero image.
<piAttribList> is a list of attribute {type, value} pairs containing
integer attribute values. All of the attributes in <piAttribList>
are followed by the corresponding required value. The list is
terminated with a value of 0.
<piAttribList> may be NULL or empty in which case all attributes assume
their default values as described below.
The following attributes are supported by wglCreatePbufferARB:
WGL_TEXTURE_FORMAT_ARB
This attribute indicates the format of the texture that will be
created when a pbuffer is bound to a texture map.
It can be set to WGL_TEXTURE_RGB_ARB, WGL_TEXTURE_RGBA_ARB or
WGL_NO_TEXTURE_ARB. The default value is WGL_NO_TEXTURE_ARB.
WGL_TEXTURE_TARGET_ARB
This attribute indicates the target for the texture that will be
created when the pbuffer is created with a texture format of
WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB. This attribute can
be set to WGL_NO_TEXTURE_ARB, WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB
or WGL_TEXTURE_CUBE_MAP_ARB. The default value is WGL_NO_TEXTURE_ARB.
WGL_MIPMAP_TEXTURE_ARB
If this attribute is set to a non-zero value, and the texture format
is set to WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB, then storage
for mipmaps will be allocated. The default value is FALSE.
WGL_PBUFFER_LARGEST_ARB
If this attribute is set to a non-zero value, the largest
available pbuffer is allocated when the allocation of the pbuffer
would otherwise fail due to insufficient resources. The width or
height of the allocated pbuffer never exceeds <iWidth> and <iHeight>,
respectively. Also, if the pbuffer will be used as a texture
(i.e., the value of the WGL_TEXTURE_TARGET_ARB attribute is
WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB or WGL_TEXTURE_CUBE_MAP_ARB
and texture format is WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB),
then the aspect ratio will be preserved and the new width and
height will be valid sizes for the corresponding texture target.
(e.g. Both the width and height will be a power of 2 if the
implementation only supports power of 2 textures. Similarily,
the width and height will be equal for a cube map texture).
Use wglQueryPbufferARB to retrieve the dimensions of the
allocated pbuffer. The default value for this attribute is FALSE.
The resulting pbuffer will contain color buffers and ancillary
buffers as specified by <iPixelFormat>. Note that pbuffers use
framebuffer resources so applications should consider deallocating
them when they are not in use.
It is possible to create a pbuffer with back buffers and to swap the
front and back buffers by calling wglSwapLayerBuffers. The
contents of the back buffers after the swap depends on the
<iPixelFormat>. (Pbuffers are the same as windows in this respect.)
The contents of the depth and stencil buffers may not be preserved
when rendering a texture to the pbuffer and switching which image
of the texture is rendered to (e.g., switching from rendering one
mipmap level to rendering another).
When wglCreatePbufferARB fails to create a pbuffer, NULL is returned.
To get extended error information, call GetLastError. Possible
errors are as follows:
ERROR_INVALID_PIXEL_FORMAT Pixel format is not valid.
ERROR_NO_SYSTEM_RESOURCES Insufficient resources exist.
ERROR_INVALID_DATA <iWidth> or <iHeight> is negative or zero.
ERROR_INVALID_DATA WGL_TEXTURE_TARGET_ARB attribute is
set to WGL_TEXTURE_CUBE_MAP_ARB, and
iWidth does not equal iHeight.
ERROR_INVALID_DATA WGL_TEXTURE_TARGET_ARB attribute is set
to WGL_TEXTURE_1D_ARB, and iHeight is
not set to one.
ERROR_INVALID_DATA The pixel format attribute
WGL_TEXTURE_FORMAT_ARB is
WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB
and WGL_PBUFFER_WIDTH and/or
WGL_PBUFFER_HEIGHT specify an invalid
size for the implementation (e.g., the
texture size is not a power of 2).
ERROR_INVALID_DATA An attribute in <piAttribList> is not a
valid attribute.
ERROR_INVALID_DATA The texture format is set to
WGL_NO_TEXTURE_ARB and texture target
is set to something other than
WGL_NO_TEXTURE_ARB.
ERROR_INVALID_DATA The texture format is set to some target
besides WGL_NO_TEXTURE_ARB and texture
target is set to WGL_NO_TEXTURE_ARB.
....
Modify wglDestroyPbufferARB:
A pbuffer is destroyed by calling
BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer);
The pbuffer is destroyed once it is no longer current to any
rendering context and once all color buffers that are bound to a
texture object have been released. When a pbuffer is destroyed,
any memory resources that are attached to it are freed
and its handle is no longer valid.
....
Add wglSetPbufferAttribARB:
To set an attribute of a pbuffer call
BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer,
const int *piAttribList);
with <hPbuffer> set to a previously returned pbuffer handle.
<piAttribList> is a list of attribute {type, value} pairs containing
integer values. All the attributes in <piAttribList> are followed by
the corresponding desired value. The list is terminated with 0.
If <piAttribList> is NULL or empty then this function is a no-op.
The following values are accepted:
WGL_MIPMAP_LEVEL_ARB
For mipmap textures, this attribute indicates which level of the
mipmap should be rendered. The default value is zero. If the value
of this attribute is outside the range of supported mipmap level,
the closest valid mipmap level is selected for rendering.
WGL_CUBE_MAP_FACE_ARB
For cube map textures, this attribute indicates which face of the
cube map should be rendered; it must be set to one of
WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB,
WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB,
WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB,
WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB,
WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB,
WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB.
The default value is WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB.
If wglSetPbufferAttribARB fails, FALSE is returned. To get extended
error information, call GetLastError. Possible errors are as follows:
ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle.
ERROR_INVALID_DATA Bad attribute specified in <piAttribList>.
ERROR_INVALID_DATA WGL_MIPMAP_LEVEL_ARB does not specify
a valid mipmap level.
ERROR_INVALID_DATA WGL_CUBE_MAP_IMAGE_ARB is not set to a
valid value.
....
Modify wglQueryPbufferARB:
To query an attribute associated with a specific pbuffer, call
BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, int iAttribute,
int *piValue);
with <hPbuffer> set to a previously returned pbuffer handle.
<iAttribute> must be set to one of WGL_PBUFFER_WIDTH_ARB,
WGL_PBUFFER_HEIGHT_ARB, WGL_PBUFFER_LOST_ARB, WGL_TEXTURE_TARGET_ARB,
WGL_MIPMAP_TEXTURE_ARB, WGL_MIPMAP_LEVEL_ARB, WGL_CUBE_MAP_FACE_ARB
or WGL_TEXTURE_FORMAT_ARB.
The WGL_PBUFFER_LOST_ARB query can be used to determine if the pixel
buffer memory was lost due to a display mode change. A value of
TRUE is returned in buffer <piValue> if the display mode change lost
the memory for the pixel buffer. It is not an error to render to a
pixel buffer in this state, but the effect of rendering to it is the
same as if the pixel buffer was destroyed: the context state will
be updated, but the values of the returned pixels are undefined.
The pixel buffer must be destroyed and recreated if the pixel buffer
memory has been lost. A value of FALSE is returned to indicate
that the contents of the pixel buffer are unaffected by the display
mode change.
When a color buffer of a pbuffer is bound as a texture, then the
contents of that texture must be preserved until the color buffer is
released. If the pbuffer is lost, any color buffers that are bound
to textures will be freed when they are released back to the pbuffer
by calling wglReleaseTexImage.
If wglPbufferAttribARB fails, FALSE is returned. To get extended
error information, call GetLastError. Possible errors are as follows:
ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle.
ERROR_INVALID_DATA <iAttribute> is not a valid attribute.
....
Add wglBindTexImageARB and wglReleaseTexImageARB:
The command
BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)
defines a one-dimensional texture image or two-dimensional
texture image or a set of two-dimensional cube map texture images.
The texture image or images consist of the image data in <iBuffer>
for the specified pbuffer, <hPbuffer>, and need not be copied.
The texture target, the texture format and the size of the
texture components are derived from attributes of pbuffer
specified by <hPbuffer>.
Note that any existing images associated with the different
mipmap levels of the texture object are freed (it is as if
TexImage was called with an image of zero width).
The pbuffer attribute WGL_TEXTURE_FORMAT_ARB determines the base
internal format of the texture. The component sizes are also
determined by pbuffer attributes as shown in the table below.
Texture Component Size
R WGL_RED_BITS_ARB
G WGL_GREEN_BITS_ARB
B WGL_BLUE_BITS_ARB
A WGL_ALPHA_BITS_ARB
Table x.x: Size of texture components
The texture targets are derived from the WGL_TEXTURE_TARGET_ARB
attribute of <hPbuffer>. If the texture target for the pbuffer is
WGL_TEXTURE_CUBE_MAP_ARB then <iBuffer> defines a set of cubemap
images for the cube map texture objects which are bound to the
current context (hereafter referred to as the current texture
object). Note that when the texture target is
WGL_TEXTURE_CUBE_MAP_ARB, all cube map texture targets are defined
by a single call to wglBindTexImageARB. If the texture target is
WGL_TEXTURE_2D_ARB, then <iBuffer> defines a 2D texture for the
current 2D texture object; if the texture target is WGL_TEXTURE_1D_ARB,
then <iBuffer> defines a 1D texture for the current 1D texture object.
The possible values for <iBuffer> are WGL_FRONT_LEFT_ARB,
WGL_FRONT_RIGHT_ARB, WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, and
WGL_AUX0_ARB through WGL_AUXn_ARB.
If <hPbuffer> is the calling thread's current drawable,
wglBindTexImageARB performs an implicit glFlush.
After this function is called, the pbuffer associated with <iBuffer>
is no longer available for reading or writing. Any read
operation, such as glReadPixels, which reads values from any of the
pbuffer's color buffers or ancillary buffers, will produce
indeterminate results. In addition, any draw operation that is
done to the pbuffer prior to wglReleaseTexImageARB being called,
produces indeterminant results. Specifically, if the pbuffer is
current to a context and thread then rendering commands will be
processed and the context state will be updated but the pbuffer may
or may not be written. Also, SwapBuffers is a no-op if it is called
on this pbuffer.
Note that the color buffer is bound to a texture object. If the
texture object is shared between contexts, then the
color buffer is also shared. If a texture object is deleted
before wglReleaseTexImageARB is called, then the color buffer is
released and the pbuffer is made available for reading and writing.
It is not an error to call TexImage2D, TexImage1D,
CopyTexImage1D or CopyTexImage2D to replace an image of a texture
object that has a color buffer bound to it. However, these calls
will cause the color buffer to be released back to the pbuffer and
new memory will be allocated for the texture. Note that the color
buffer is released even if the image that is being defined is a
mipmap level that was not defined by the color buffer.
wglBindTexImageARB is ignored if there is no current rendering
context.
If wglBindTexImageARB fails, FALSE is returned. To get extended
error information, call GetLastError. Possible errors are as follows:
ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle.
ERROR_INVALID_DATA <iBuffer> is not a valid value.
ERROR_INVALID_OPERATION The pbuffer attribute
WGL_TEXTURE_FORMAT_ARB is set to
WGL_NO_TEXTURE_ARB.
ERROR_INVALID_OPERATION <iBuffer> is already bound to the texture
To release a color buffer that is being used as a texture call
BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)
This releases the specified color buffer back to the pbuffer. The
pbuffer is made available for reading and writing when it no
longer has any color buffers bound as textures.
<iBuffer> must be one of WGL_FRONT_LEFT_ARB, WGL_FRONT_RIGHT_ARB,
WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, or WGL_AUX0_ARB through
WGL_AUXn_ARB.
The contents of the color buffer are undefined when it is first
released. In particular there is no guarantee that the texture
image is still present. However, the contents of other color
buffers is unaffected by this call. Also, the contents of the depth,
stencil and accumulation buffers are not affected by
wglBindTexImageARB and wglReleaseTexImageARB.
If the specified color buffer is no longer bound to a texture (e.g.,
because the texture object was deleted) then this call is a
noop; no error is generated.
After a color buffer is released from a texture (either explicitly
by calling wglReleaseTexImageARB or implicitly by calling a
routine such as TexImage2D), all texture images that were defined
by the color buffer become NULL (it is as if TexImage was
called with an image of zero width).
If wglReleaseTexImageARB fails, FALSE is returned. To get extended
error information, call GetLastError. Possible errors are as follows:
ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle.
ERROR_INVALID_DATA <iBuffer> is not a valid value.
ERROR_INVALID_OPERATION The pbuffer attribute
WGL_TEXTURE_FORMAT_ARB is set to
WGL_NO_TEXTURE_ARB.
New State
None
Dependencies on GL_ARB_texture_cube_map
If GL_ARB_texture_cube_map is not supported then all references to
WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB,
WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB,
WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB,
WGL_TEXTURE_CUBE_MAP_ARB and WGL_CUBE_MAP_FACE_ARB are deleted.
Revision History
07/16/01 bpoddar 1. Added WGL_TEXTURE_CUBE_MAP_POSITIVE_*_ARB
enums to the new tokens section.
2. Added clarification on MIPMAP_LEVEL_ARB usage.
3. Removed 1 invalid error condition from
wglBindTexImage.
4. Changed parameter references to <parameter>.
07/12/01 bpoddar Fixed minor typos and added enum values.
06/22/01 bpoddar Minor language edits from ARB participants.
04/09/01 bpoddar 1. Renamed WGL_TEXTURE_TYPE_ARB to
WGL_TEXTURE_TARGET_ARB.
2. Cleaned up behavior of WGL_TEXTURE_FORMAT_ARB.
03/23/01 bpoddar 1. Updated the implementation notes section
with the discussion at the ARB.
2. Replaced ERROR_??? with specified errors
3. Clarified width and height selection rules
for WGL_PBUFFER_LARGEST.
4. Added policy for dealing with mip levels
both on Bind and Release.
5. Specified behavior for implicit release and
added comment to implementation section.
6. Added couple of errors to SetPbufferAttrib.
03/06/01 bpoddar 1. Deleted references to 3D texture
2. Deleted references to LUMINANCE, INTENSITY
textures.
3. wglBindTexImageARB no longer provides a
separate mipmap attribute (issue #21).
4. Removed references to multiple texture
objects for cube maps.
5. Added issue # 23.
6. Added implementation notes section.
12/01/00 pwomack Updated issues list. Require non-static pbuffer
attributes to be set via SetPbufferAttrib (they
cannot be set when the pbuffer is created.)
The WGL_TEXTURE_TARGET_ARB attribute now takes
WGL_NO_TEXTURE_ARB as a value, so the app can
indicate that the pbuffer will never be bound
as a texture. If a pbuffer is created with
WGL_TEXTURE_TARGET_ARB set to WGL_NO_TEXTURE_ARB,
then an error results if an attempt is made to
bind it as a texture. Specified default values
for all attribute lists. When a color buffer is
bound as a texture then drawing to the pbuffer
gives undefined results (previously the
rendering was lost). When a color buffer is
bound as a texture, calling TexImage or
CopyTexImage releases the color buffer back to
the pbuffer.
11/12/00 pwomack Created. Copied from GLX extension. Added WGL
calls and removed all GLX-centric stuff.
Implementation Support
List of OpenGL implementations supporting the WGL_ARB_render_texture extension
Original File
Original text file for the WGL_ARB_render_texture extension
Page generated on Sun Nov 20 18:36:05 2005