WGL_ARB_buffer_region
WGL_ARB_buffer_region
Dale Kirkland, Intergraph (kirkland 'at' ingr.com)
Complete. Approved by ARB on 12/8/1999
Last Modified Date: December 10, 2000
Intergraph Revision 1.0
ARB Extension #4
The extension is written against the OpenGL 1.2.1 Specification
although it should work on any previous OpenGL specification.
The WGL_EXT_extensions_string extension is required.
The buffer region extension is a mechanism that allows an area of
an OpenGL window to be saved in off-screen memory for quick
restores. The off-screen memory can either be frame buffer memory
or system memory, although frame buffer memory might offer optimal
performance.
A buffer region can be created for the front color, back color,
depth, and/or stencil buffer. Multiple buffer regions for the same
buffer type can exist.
None
1. Do we need the glBufferRegionEnabled call that is in the
Kinetix extensions?
The reason behind this function was so that a single driver
could be used on adapters with various amounts of memory -- the
extension would always be present but its use would depend on a
separate call. The same functionality could be achieved by not
advertising this extension or always returning a value of NULL
from wglCreateBufferRegionARB.
2. Should the width/height be specified on the create.
Because applications create regions that are not used, it would
be better to leave the size as a parameter on the save.
3. Should information be added to the create to allow for layer
support?
Layer support has been added.
4. Which DC gets used for buffer region operations?
The DC that was allocated on the CreateBufferRegionARB call is
saved and used for subsequent save and restore operations. It
must remain valid during the life of the buffer region. This is
analogous to the RC method for handling the DC.
5. Does the driver do a flush before the save and restore?
In keeping with the same paradigm as SwapBuffers, a flush will
be made by the driver for the RC bound to the calling thread
before the save and restore operations.
6. Which coordinate system is used?
The KTX_buffer_region and WIN_swap_hint extensions specify the
(x,y) origin as the lower left corner of the rectangle. This
extension adopts the same philosophy.
   New Procedures and Functions |
HANDLE wglCreateBufferRegionARB(HDC hDC,
int iLayerPlane,
UINT uType)
VOID wglDeleteBufferRegionARB(HANDLE hRegion)
BOOL wglSaveBufferRegionARB(HANDLE hRegion,
int x,
int y,
int width,
int height)
BOOL wglRestoreBufferRegionARB(HANDLE hRegion,
int x,
int y,
int width,
int height,
int xSrc,
int ySrc)
Accepted by the <uType> parameter of wglCreateBufferRegionARB is the
bitwise OR of any of the following values:
WGL_FRONT_COLOR_BUFFER_BIT_ARB 0x00000001
WGL_BACK_COLOR_BUFFER_BIT_ARB 0x00000002
WGL_DEPTH_BUFFER_BIT_ARB 0x00000004
WGL_STENCIL_BUFFER_BIT_ARB 0x00000008
| 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 Appendix A of the OpenGL 1.2.1 Specification (Invariance) |
None
| Additions to the GLX Specification |
None
None
| Additions to the WGL Specification |
A buffer region can be created with wglCreateBufferRegionARB
which returns a handle associated with the buffer region.
HANDLE wglCreateBufferRegionARB(HDC hDC,
INT iLayerPlane,
UINT uType)
<hDC> specifies a device context for the device on which the buffer
region is created. <iLayerPlane> specifies the layer. Positive
values identify overlay planes, negative values identify underlay
planes. A value of 0 identifies the main plane.
<uType> is a bitwise OR of any of the following values indicating
which buffers can be saved or restored. Multiple bits can be set
and may result in better performance if multiple buffers are saved
or restored.
WGL_FRONT_COLOR_BUFFER_BIT_ARB
WGL_BACK_COLOR_BUFFER_BIT_ARB
WGL_DEPTH_BUFFER_BIT_ARB
WGL_STENCIL_BUFFER_BIT_ARB
For stereo windows, WGL_FRONT_COLOR_BUFFER_BIT_ARB implies both the
left and right front buffers, and WGL_BACK_COLOR_BUFFER_BIT_ARB
implies both the left and right back buffers.
When wglCreateBufferRegionARB fails to create a buffer region, a
value of NULL is returned. To get extended error information, call
GetLastError.
Image, depth, and stencil data can be saved into the buffer region
by calling wglSaveBufferRegionARB.
BOOL wglSaveBufferRegionARB(HANDLE hRegion,
int x,
int y,
int width,
int height)
<hRegion> is a handle to a buffer region previously created with
wglCreateBufferRegionARB. The DC specified when the region was
created is used as the device context specifying the window.
<x> and <y> specify the window position for the source rectangle.
<width> and <height> specify the width and height of the source
rectangle. Data outside the window for the specified rectangle is
undefined. The OpenGL coordinate system is used for specifying the
rectangle (<x> and <y> specify the lower-left corner of the
rectangle).
If an RC is current to the calling thread, a flush will occur
before the save operation.
The saved buffer region area can be freed by calling
wglSaveBufferRegionARB with <width> or <height> set to a value
of 0.
If the call to wglSaveBufferRegionARB is successful, a value of
TRUE is returned. Otherwise, a value of FALSE is returned. To
get extended error information, call GetLastError.
A previously saved region can be restored (multiple times) with
the wglRestoreBufferRegionARB function.
BOOL wglRestoreBufferRegionARB(HANDLE hRegion,
int x,
int y,
int width,
int height,
int xSrc,
int ySrc)
<hRegion> is a handle to a buffer region previously created with
wglCreateBufferRegionARB. The DC specified when the region was
created is used as the device context specifying the window.
<x> and <y> specify the window position for the destination
rectangle. <width> and <height> specify the width and height of
the destination rectangle. The OpenGL coordinate system is used
for specifying the rectangle (<x> and <y> specify the lower-left
corner of the rectangle).
<xSrc> and <ySrc> specify the position in the buffer region for
the source of the data. Any portion of the rectangle outside of
the saved region is ignored.
If an RC is current to the calling thread, a flush will occur
before the restore operation.
If the call to wglRestoreBufferRegionARB is successful, a value of
TRUE is returned. Otherwise, a value of FALSE is returned. To
get extended error information, call GetLastError.
The buffer region can be deleted with wglDeleteBufferRegionARB.
VOID wglDeleteBufferRegionARB(HANDLE hRegion)
<hRegion> is a handle to a buffer region previously created with
wglCreateBufferRegionARB. Any saved data associated with <hRegion>
is discarded. The DC used to create the region must still be valid
for the delete to work.
| Dependencies on WGL_EXT_extensions_string |
Because there is no way to extend wgl, these calls are defined in
the ICD and can be called by obtaining the address with
wglGetProcAddress. Because this extension is a WGL extension, it
is not included in the GL_EXTENSIONS string. Its existence can be
determined with the WGL_EXT_extensions_string extension.
ERROR_NO_SYSTEM_RESOURCES is generated if memory cannot be
allocated for storing the saved data.
ERROR_INVALID_HANDLE is generated if <hRegion> is not a valid
handle that was previously returned by wglCreateBufferRegionARB.
ERROR_INVALID_DATA is generated if <uType> is zero or includes
an undefined bit.
ERROR_INVALID_DATA is generated if <width> or <height> is negative.
None
| New Implementation Dependent State |
None
Conformance Test
1. Clear the window to blue.
2. Save an area of the window using wglSaveBufferRegionARB.
3. Clear the window to red.
4. Restore the area of the window using wglRestoreBufferRegionARB.
5. Verify that the area was restored.
6. Repeat for the depth buffer.
7. Repeat for the stencil buffer.
8. Repeat for image and depth buffer.
12/10/99 1.0 ARB extension - based on the wgl_buffer_region
extension.
 |  | Last update: November 14, 2006.
Cette page doit être lue avec un navigateur récent respectant le standard XHTML 1.1.
|
