• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    WGL_ARB_buffer_region
4
5Name Strings
6
7    WGL_ARB_buffer_region
8
9Contact
10
11    Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com)
12
13Notice
14
15    Copyright (c) 1999-2013 The Khronos Group Inc. Copyright terms at
16        http://www.khronos.org/registry/speccopyright.html
17
18Specification Update Policy
19
20    Khronos-approved extension specifications are updated in response to
21    issues and bugs prioritized by the Khronos OpenGL Working Group. For
22    extensions which have been promoted to a core Specification, fixes will
23    first appear in the latest version of that core Specification, and will
24    eventually be backported to the extension document. This policy is
25    described in more detail at
26        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
27
28Status
29
30    Complete. Approved by ARB on 12/8/1999
31
32Version
33
34    Last Modified Date: March 12, 2002
35    Revision: 1.1
36
37Number
38
39    ARB Extension #4
40
41Dependencies
42
43    The extension is written against the OpenGL 1.2.1 Specification
44    although it should work on any previous OpenGL specification.
45
46    The WGL_EXT_extensions_string extension is required.
47
48Overview
49
50    The buffer region extension is a mechanism that allows an area of
51    an OpenGL window to be saved in off-screen memory for quick
52    restores.  The off-screen memory can either be frame buffer memory
53    or system memory, although frame buffer memory might offer optimal
54    performance.
55
56    A buffer region can be created for the front color, back color,
57    depth, and/or stencil buffer.  Multiple buffer regions for the same
58    buffer type can exist.
59
60IP Status
61
62    None
63
64Issues
65
66    1. Do we need the glBufferRegionEnabled call that is in the
67       Kinetix extensions?
68
69       The reason behind this function was so that a single driver
70       could be used on adapters with various amounts of memory -- the
71       extension would always be present but its use would depend on a
72       separate call.  The same functionality could be achieved by not
73       advertising this extension or always returning a value of NULL
74       from wglCreateBufferRegionARB.
75
76    2. Should the width/height be specified on the create.
77
78       Because applications create regions that are not used, it would
79       be better to leave the size as a parameter on the save.
80
81    3. Should information be added to the create to allow for layer
82       support?
83
84       Layer support has been added.
85
86    4. Which DC gets used for buffer region operations?
87
88       The DC that was allocated on the CreateBufferRegionARB call is
89       saved and used for subsequent save and restore operations.  It
90       must remain valid during the life of the buffer region.  This is
91       analogous to the RC method for handling the DC.
92
93    5. Does the driver do a flush before the save and restore?
94
95       In keeping with the same paradigm as SwapBuffers, a flush will
96       be made by the driver for the RC bound to the calling thread
97       before the save and restore operations.
98
99    6. Which coordinate system is used?
100
101       The KTX_buffer_region and WIN_swap_hint extensions specify the
102       (x,y) origin as the lower left corner of the rectangle.  This
103       extension adopts the same philosophy.
104
105
106New Procedures and Functions
107
108    HANDLE wglCreateBufferRegionARB(HDC hDC,
109                                    int iLayerPlane,
110                                    UINT uType)
111
112    VOID wglDeleteBufferRegionARB(HANDLE hRegion)
113
114    BOOL wglSaveBufferRegionARB(HANDLE hRegion,
115                                int x,
116                                int y,
117                                int width,
118                                int height)
119
120    BOOL wglRestoreBufferRegionARB(HANDLE hRegion,
121                                   int x,
122                                   int y,
123                                   int width,
124                                   int height,
125                                   int xSrc,
126                                   int ySrc)
127
128
129New Tokens
130
131    Accepted by the <uType> parameter of wglCreateBufferRegionARB is the
132    bitwise OR of any of the following values:
133
134      WGL_FRONT_COLOR_BUFFER_BIT_ARB          0x00000001
135      WGL_BACK_COLOR_BUFFER_BIT_ARB           0x00000002
136      WGL_DEPTH_BUFFER_BIT_ARB                0x00000004
137      WGL_STENCIL_BUFFER_BIT_ARB              0x00000008
138
139
140Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
141
142    None
143
144
145Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)
146
147    None
148
149
150Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment
151Operations and the Frame Buffer)
152
153    None
154
155
156Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
157
158    None
159
160
161Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and
162State Requests)
163
164    None
165
166
167Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
168
169    None
170
171
172Additions to the GLX Specification
173
174    None
175
176GLX Protocol
177
178    None
179
180Additions to the WGL Specification
181
182    A buffer region can be created with wglCreateBufferRegionARB
183    which returns a handle associated with the buffer region.
184
185      HANDLE wglCreateBufferRegionARB(HDC hDC,
186                                      INT iLayerPlane,
187                                      UINT uType)
188
189    <hDC> specifies a device context for the device on which the buffer
190    region is created. <iLayerPlane> specifies the layer.  Positive
191    values identify overlay planes, negative values identify underlay
192    planes.  A value of 0 identifies the main plane.
193
194    <uType> is a bitwise OR of any of the following values indicating
195    which buffers can be saved or restored.  Multiple bits can be set
196    and may result in better performance if multiple buffers are saved
197    or restored.
198
199        WGL_FRONT_COLOR_BUFFER_BIT_ARB
200        WGL_BACK_COLOR_BUFFER_BIT_ARB
201        WGL_DEPTH_BUFFER_BIT_ARB
202        WGL_STENCIL_BUFFER_BIT_ARB
203
204    For stereo windows, WGL_FRONT_COLOR_BUFFER_BIT_ARB implies both the
205    left and right front buffers, and WGL_BACK_COLOR_BUFFER_BIT_ARB
206    implies both the left and right back buffers.
207
208    When wglCreateBufferRegionARB fails to create a buffer region, a
209    value of NULL is returned.  To get extended error information, call
210    GetLastError.
211
212    Image, depth, and stencil data can be saved into the buffer region
213    by calling wglSaveBufferRegionARB.
214
215      BOOL wglSaveBufferRegionARB(HANDLE hRegion,
216                                  int x,
217                                  int y,
218                                  int width,
219                                  int height)
220
221    <hRegion> is a handle to a buffer region previously created with
222    wglCreateBufferRegionARB.  The DC specified when the region was
223    created is used as the device context specifying the window.
224
225    <x> and <y> specify the window position for the source rectangle.
226    <width> and <height> specify the width and height of the source
227    rectangle.  Data outside the window for the specified rectangle is
228    undefined.  The OpenGL coordinate system is used for specifying the
229    rectangle (<x> and <y> specify the lower-left corner of the
230    rectangle).
231
232    If an RC is current to the calling thread, a flush will occur
233    before the save operation.
234
235    The saved buffer region area can be freed by calling
236    wglSaveBufferRegionARB with <width> or <height> set to a value
237    of 0.
238
239    If the call to wglSaveBufferRegionARB is successful, a value of
240    TRUE is returned.  Otherwise, a value of FALSE is returned.  To
241    get extended error information, call GetLastError.
242
243    A previously saved region can be restored (multiple times) with
244    the wglRestoreBufferRegionARB function.
245
246      BOOL wglRestoreBufferRegionARB(HANDLE hRegion,
247                                     int x,
248                                     int y,
249                                     int width,
250                                     int height,
251                                     int xSrc,
252                                     int ySrc)
253
254    <hRegion> is a handle to a buffer region previously created with
255    wglCreateBufferRegionARB.  The DC specified when the region was
256    created is used as the device context specifying the window.
257
258    <x> and <y> specify the window position for the destination
259    rectangle.  <width> and <height> specify the width and height of
260    the destination rectangle.  The OpenGL coordinate system is used
261    for specifying the rectangle (<x> and <y> specify the lower-left
262    corner of the rectangle).
263
264    <xSrc> and <ySrc> specify the position in the buffer region for
265    the source of the data.  Any portion of the rectangle outside of
266    the saved region is ignored.
267
268    If an RC is current to the calling thread, a flush will occur
269    before the restore operation.
270
271    If the call to wglRestoreBufferRegionARB is successful, a value of
272    TRUE is returned.  Otherwise, a value of FALSE is returned.  To
273    get extended error information, call GetLastError.
274
275    The buffer region can be deleted with wglDeleteBufferRegionARB.
276
277      VOID wglDeleteBufferRegionARB(HANDLE hRegion)
278
279    <hRegion> is a handle to a buffer region previously created with
280    wglCreateBufferRegionARB.  Any saved data associated with <hRegion>
281    is discarded.  The DC used to create the region must still be valid
282    for the delete to work.
283
284Dependencies on WGL_EXT_extensions_string
285
286    Because there is no way to extend wgl, these calls are defined in
287    the ICD and can be called by obtaining the address with
288    wglGetProcAddress.  Because this extension is a WGL extension, it
289    is not included in the GL_EXTENSIONS string.  Its existence can be
290    determined with the WGL_EXT_extensions_string extension.
291
292Errors
293
294    ERROR_NO_SYSTEM_RESOURCES is generated if memory cannot be
295    allocated for storing the saved data.
296
297    ERROR_INVALID_HANDLE is generated if <hRegion> is not a valid
298    handle that was previously returned by wglCreateBufferRegionARB.
299
300    ERROR_INVALID_DATA is generated if <uType> is zero or includes
301    an undefined bit.
302
303    ERROR_INVALID_DATA is generated if <width> or <height> is negative.
304
305New State
306
307    None
308
309New Implementation Dependent State
310
311    None
312
313Conformance Test
314
315    1. Clear the window to blue.
316    2. Save an area of the window using wglSaveBufferRegionARB.
317    3. Clear the window to red.
318    4. Restore the area of the window using wglRestoreBufferRegionARB.
319    5. Verify that the area was restored.
320    6. Repeat for the depth buffer.
321    7. Repeat for the stencil buffer.
322    8. Repeat for image and depth buffer.
323
324Revision History
325
326    12/10/99  1.0  ARB extension - based on the wgl_buffer_region
327                   extension.
328    03/12/02  1.1  Updated contact information.
329