1Name 2 3 WGL_ARB_pbuffer 4 5Name Strings 6 7 WGL_ARB_pbuffer 8 9Contact 10 11 Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com) 12 Bimal Poddar, Intel (bimal.poddar 'at' intel.com) 13 Steve Urquhart, Intelligraphics (steveu 'at' intelligraphics.com) 14 15Notice 16 17 Copyright (c) 2000-2013 The Khronos Group Inc. Copyright terms at 18 http://www.khronos.org/registry/speccopyright.html 19 20Specification Update Policy 21 22 Khronos-approved extension specifications are updated in response to 23 issues and bugs prioritized by the Khronos OpenGL Working Group. For 24 extensions which have been promoted to a core Specification, fixes will 25 first appear in the latest version of that core Specification, and will 26 eventually be backported to the extension document. This policy is 27 described in more detail at 28 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 29 30Status 31 32 Complete. Approved by ARB on March 15, 2000 33 34Version 35 36 Last Modified Date: 03/12/2002 37 Author Revision: 1.1 38 39 Based on: WGL_EXT_pbuffer specification 40 Date: 4/21/1999 Version 1.8 41 42Number 43 44 ARB Extension #11 45 46Dependencies 47 48 WGL_ARB_extensions_string is required. 49 WGL_ARB_pixel_format is required. 50 WGL_ARB_make_current_read affects the definition of this extension. 51 52Overview 53 54 This extension defines pixel buffers (pbuffer for short). Pbuffers 55 are additional non-visible rendering buffers for an OpenGL 56 renderer. Pbuffers are equivalent to a window that has the same 57 pixel format descriptor with the following exceptions: 58 59 1. There is no rendering to a pbuffer by GDI. 60 61 2. The pixel format descriptors used for a pbuffer can only be 62 those that are supported by the ICD. Generic formats are not 63 valid. 64 65 3. The allocation of a pbuffer can fail if there are insufficient 66 resources (i.e., all the pbuffer memory has been allocated). 67 68 4. The pixel buffer might be lost if a display mode change occurs. 69 A query is provided that can be called after a display mode 70 change to determine the state of the pixel buffer. 71 72 The intent of the pbuffer semantics is to enable implementations to 73 allocate pbuffers in non-visible frame buffer memory. These 74 pbuffers are intended to be "static" resources in that a program 75 will typically allocate them only once rather than as a part of its 76 rendering loop. (Pbuffers should be deallocated when the program 77 is no longer using them -- for example, if the program is 78 iconified.) 79 80 The frame buffer resources that are associated with a pbuffer are 81 also static and are deallocated when the pbuffer is destroyed or 82 possibly when a display mode change occurs. 83 84IP Status 85 86 TBD 87 88Issues 89 90 1. Should the OPTIMUM width and heights and PBUFFER_LARGEST_ARB be 91 taken out of the spec since they may be misleading or hard for 92 some implementations to support? 93 94 PBUFFER_LARGEST_ARB has been left in the extension. It was 95 originally requested by an application. The OPTIMUM queries 96 have been removed to match the GLX pixel buffer specification. 97 98 99New Procedures and Functions 100 101 DECLARE_HANDLE(HPBUFFERARB); 102 103 HPBUFFERARB wglCreatePbufferARB(HDC hDC, 104 int iPixelFormat, 105 int iWidth, 106 int iHeight, 107 const int *piAttribList); 108 109 HDC wglGetPbufferDCARB(HPBUFFERARB hPbuffer); 110 111 int wglReleasePbufferDCARB(HPBUFFERARB hPbuffer, 112 HDC hDC); 113 114 BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); 115 116 BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, 117 int iAttribute, 118 int *piValue); 119 120New Tokens 121 122 Accepted by the <attribute> parameter of wglChoosePixelFormatEXT: 123 124 WGL_DRAW_TO_PBUFFER_ARB 0x202D 125 126 Accepted by the <attribute> parameter of 127 wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT: 128 129 WGL_DRAW_TO_PBUFFER_ARB 0x202D 130 WGL_MAX_PBUFFER_PIXELS_ARB 0x202E 131 WGL_MAX_PBUFFER_WIDTH_ARB 0x202F 132 WGL_MAX_PBUFFER_HEIGHT_ARB 0x2030 133 134 Accepted by the <piAttribList> parameter of wglCreatePbufferARB: 135 136 WGL_PBUFFER_LARGEST_ARB 0x2033 137 138 Accepted by the <iAttribute> parameter of wglQueryPbufferARB: 139 140 WGL_PBUFFER_WIDTH_ARB 0x2034 141 WGL_PBUFFER_HEIGHT_ARB 0x2035 142 WGL_PBUFFER_LOST_ARB 0x2036 143 144Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation) 145 146 None 147 148Additions to Chapter 3 of the 1.2 Specification (Rasterization) 149 150 None 151 152Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations 153and the Frame buffer) 154 155 None 156 157Additions to Chapter 5 of the 1.2 Specification (Special Functions) 158 159 None 160 161Additions to Chapter 6 of the 1.2 Specification (State and State Requests) 162 163 None 164 165Additions to the GLX Specification 166 167 This specification is written for WGL. 168 169GLX Protocol 170 171 This specification is written for WGL. 172 173Additions to the WGL Specification 174 175 A pixel buffer (pbuffer) can be created with wglCreatePbufferARB 176 which returns a handle associated with the pbuffer. 177 178 HPBUFFERARB wglCreatePbufferARB(HDC hDC, 179 int iPixelFormat, 180 int iWidth, 181 int iHeight, 182 const int *piAttribList); 183 184 <hDC> specifies a device context for the device on which the 185 pbuffer is created. <iPixelFormat> specifies a non-generic pixel 186 format descriptor index. Support for pbuffers may be restricted 187 to specific pixel formats. Use wglGetPixelFormatAttribivEXT or 188 wglGetPixelFormatAttribfvEXT to query the WGL_DRAW_TO_PBUFFER_ARB 189 attribute to determine which pixel formats support the creation of 190 pbuffers. 191 192 <iWidth> and <iHeight> specify the pixel width and height of the 193 rectangular pbuffer. 194 195 <piAttribList> is a list of attributes {type, value} pairs 196 containing integer attribute values. All of the attributes in the 197 <piAttribList> are followed by the corresponding required value. 198 The list is terminated with a value of 0. 199 200 The following attributes are supported by wglCreatePbufferARB: 201 202 WGL_PBUFFER_LARGEST_ARB If this attribute is set to a 203 non-zero value, the largest 204 available pbuffer is allocated 205 when the allocation of the pbuffer 206 would otherwise fail due to 207 insufficient resources. The width 208 or height of the allocated pbuffer 209 never exceeds <iWidth> and <iHeight>, 210 respectively. Use wglQueryPbufferARB 211 to retrieve the dimensions of the 212 allocated pbuffer. 213 214 The resulting pbuffer will contain color buffers and ancillary 215 buffers as specified by <iPixelFormat>. Note that pbuffers use 216 framebuffer resources so applications should consider deallocating 217 them when they are not in use. 218 219 It is possible to create a pbuffer with back buffers and to swap 220 the front and back buffers by calling wglSwapLayerBuffers. The 221 contents of the back buffers after the swap depends on the 222 <iPixelFormat>. (Pbuffers are the same as windows in this respect.) 223 224 When wglCreatePbufferARB fails to create a pbuffer, NULL is 225 returned. To get extended error information, call GetLastError. 226 Possible errors are as follows: 227 228 ERROR_INVALID_PIXEL_FORMAT Pixel format is not valid. 229 230 ERROR_NO_SYSTEM_RESOURCES Insufficient resources exist. 231 232 ERROR_INVALID_DATA <iWidth> or <iHeight> is negative 233 or zero. 234 235 ERROR_INVALID_DATA <piAttribList> is not a valid 236 attribute. 237 238 To create a device context for the pbuffer, call 239 240 HDC wglGetPbufferDCARB(HPBUFFERARB hPbuffer); 241 242 where <hPbuffer> is a handle returned from a previous call to 243 wglCreatePbufferARB. A device context is returned by 244 wglGetPbufferDCARB which can be used to associate a rendering 245 context with the pbuffer. Any rendering context created with 246 a wglCreateContext that is "compatible" with the <iPixelFormat> may 247 be used to render into the pbuffer. (See the description of 248 wglCreateContext, wglMakeCurrent, and wglMakeCurrentReadEXT for a 249 definition of "compatible".) 250 251 When wglGetPbufferDCARB fails, NULL is returned. To get extended 252 error information, call GetLastError. Possible errors are as 253 follows: 254 255 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 256 257 To release a device context obtained from a previous call to 258 wglGetPbufferDCARB, call 259 260 int wglReleasePbufferDCARB(HPBUFFERARB hPbuffer, 261 HDC hDC); 262 263 If the return value is a value of 1, the device context was released. 264 If the device context was not released, the return value is 0. To 265 get extended error information, call GetLastError. Possible errors 266 are as follows: 267 268 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 269 ERROR_DC_NOT_FOUND <hDC> is not a valid DC. 270 271 A pbuffer is destroyed by calling 272 273 BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); 274 275 The pbuffer is destroyed once it is no longer current to any 276 rendering context. When a pbuffer is destroyed, any memory 277 resources that are attached to it are freed and its handle is no 278 longer valid. 279 280 If wglDestroyPbufferARB fails, FALSE is returned. To get extended 281 error information, call GetLastError. Possible errors are as 282 follows: 283 284 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 285 286 To query the maximum width, height, or number of pixels in any 287 given pbuffer for a specific pixel format, use 288 wglGetPixelFormatAttribivEXT or wglGetPixelFormatAttribfvEXT with 289 <attribute> set to one of WGL_MAX_PBUFFER_WIDTH_ARB, 290 WGL_MAX_PBUFFER_HEIGHT_ARB, or WGL_MAX_PBUFFER_PIXELS_ARB. 291 292 WGL_MAX_PBUFFER_WIDTH_ARB and WGL_MAX_PBUFFER_HEIGHT_ARB indicate 293 the maximum width and height that can be passed into 294 wglCreatePbufferARB and WGL_MAX_PBUFFER_PIXELS_ARB indicates the 295 maximum number of pixels (width x height) for a pbuffer. Note 296 that an implementation may return a value for 297 WGL_MAX_PBUFFER_PIXELS_ARB that is less than the maximum width 298 times the maximum height. Also, the value for 299 WGL_MAX_PBUFFER_PIXELS_ARB is static and assumes that no other 300 pbuffers are contending for the framebuffer memory. Thus it may 301 not be possible to allocate a pbuffer of the size given by 302 WGL_MAX_PBUFFER_PIXELS_ARB. 303 304 To query an attribute associated with a specific pbuffer, call 305 306 BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, 307 int iAttribute, 308 int *piValue); 309 310 with <hPbuffer> set to a previously returned pbuffer handle. 311 <iAttribute> must be set to one of WGL_PBUFFER_WIDTH_ARB, 312 WGL_PBUFFER_HEIGHT_ARB, or WGL_PBUFFER_LOST_ARB. 313 314 The WGL_PBUFFER_LOST_ARB query can be used to determine if the 315 pixel buffer memory was lost due to a display mode change. A value 316 of TRUE is returned in <iAttribute> if the display mode change lost 317 the memory for the pixel buffer. It is not an error to render to 318 a pixel buffer in this state, but the effect of rendering to it is 319 the same as if the pixel buffer was destroyed: the context state 320 will be updated, but the values of the returned pixels are 321 undefined. The pixel buffer must be destroyed and recreated if 322 the pixel buffer memory has been lost. A value of FALSE is 323 returned to indicate that the contents of the pixel buffer are 324 unaffected by the display mode change. 325 326 If wglQueryPbufferARB fails, FALSE is returned. To get extended 327 error information, call GetLastError. Possible errors are as 328 follows: 329 330 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 331 ERROR_INVALID_DATA <iAttribute> is not a valid attribute. 332 333Dependencies on WGL_ARB_pixel_format 334 335 The WGL_ARB_pixel_format extension must be used to determine a 336 pixel format that can be used to create the pixel buffer. 337 338Dependencies on WGL_ARB_extensions_string 339 340 Because there is no way to extend wgl, these calls are defined in 341 the ICD and can be called by obtaining the address with 342 wglGetProcAddress. Because this extension is a WGL extension, it 343 is not included in the GL_EXTENSIONS string. Its existence can be 344 determined with the WGL_ARB_extensions_string extension. 345 346New State 347 348 None 349 350New Implementation Dependent State 351 352 None 353 354Conformance Testing 355 356 All of the current conformance tests can be run on a pixel buffer 357 to validate its conformance. The only change to the conformance 358 tests would be to create a context for the pixel buffer. 359 360Revision History 361 362 12/16/1999 0.1 363 - First ARB draft based on the EXT specification. 364 365 02/28/2000 0.2 366 - Added a query for a damaged pixel buffer due to a display 367 mode change. 368 369 03/15/2000 0.3 370 - Changed the lost definition of a pixel buffer. 371 - Removed the OPTIMAL size queries. 372 - Added a dependency on WGL_ARB_pixel_format. 373 374 03/22/2000 1.0 375 - Changed "mode change" to "display mode change". 376 - Added the condition that the resources associated with a 377 pbuffer may be lost due to a display mode change. 378 - Fixed issue 1 to address the OPTIMUM values. 379 - Added the declaration of HPBUFFERARB in the Procedures and 380 Functions section. 381 - Changed the wording of "undamaged" to "unaffected" 382 - Approved by ARB: 10-0-0. 383 384 03/12/2002 1.1 385 - Updated contact information. 386