Name WGL_ARB_pbuffer Name Strings WGL_ARB_pbuffer Contact Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com) Bimal Poddar, Intel (bimal.poddar 'at' intel.com) Steve Urquhart, Intelligraphics (steveu 'at' intelligraphics.com) Notice Copyright (c) 2000-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by ARB on March 15, 2000 Version Last Modified Date: 03/12/2002 Author Revision: 1.1 Based on: WGL_EXT_pbuffer specification Date: 4/21/1999 Version 1.8 Number ARB Extension #11 Dependencies WGL_ARB_extensions_string is required. WGL_ARB_pixel_format is required. WGL_ARB_make_current_read affects the definition of this extension. Overview This extension defines pixel buffers (pbuffer for short). Pbuffers are additional non-visible rendering buffers for an OpenGL renderer. Pbuffers are equivalent to a window that has the same pixel format descriptor with the following exceptions: 1. There is no rendering to a pbuffer by GDI. 2. The pixel format descriptors used for a pbuffer can only be those that are supported by the ICD. Generic formats are not valid. 3. The allocation of a pbuffer can fail if there are insufficient resources (i.e., all the pbuffer memory has been allocated). 4. The pixel buffer might be lost if a display mode change occurs. A query is provided that can be called after a display mode change to determine the state of the pixel buffer. The intent of the pbuffer semantics is to enable implementations to allocate pbuffers in non-visible frame buffer memory. These pbuffers are intended to be "static" resources in that a program will typically allocate them only once rather than as a part of its rendering loop. (Pbuffers should be deallocated when the program is no longer using them -- for example, if the program is iconified.) The frame buffer resources that are associated with a pbuffer are also static and are deallocated when the pbuffer is destroyed or possibly when a display mode change occurs. IP Status TBD Issues 1. Should the OPTIMUM width and heights and PBUFFER_LARGEST_ARB be taken out of the spec since they may be misleading or hard for some implementations to support? PBUFFER_LARGEST_ARB has been left in the extension. It was originally requested by an application. The OPTIMUM queries have been removed to match the GLX pixel buffer specification. New Procedures and Functions DECLARE_HANDLE(HPBUFFERARB); HPBUFFERARB wglCreatePbufferARB(HDC hDC, int iPixelFormat, int iWidth, int iHeight, const int *piAttribList); HDC wglGetPbufferDCARB(HPBUFFERARB hPbuffer); int wglReleasePbufferDCARB(HPBUFFERARB hPbuffer, HDC hDC); BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, int iAttribute, int *piValue); New Tokens Accepted by the parameter of wglChoosePixelFormatEXT: WGL_DRAW_TO_PBUFFER_ARB 0x202D Accepted by the parameter of wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT: WGL_DRAW_TO_PBUFFER_ARB 0x202D WGL_MAX_PBUFFER_PIXELS_ARB 0x202E WGL_MAX_PBUFFER_WIDTH_ARB 0x202F WGL_MAX_PBUFFER_HEIGHT_ARB 0x2030 Accepted by the parameter of wglCreatePbufferARB: WGL_PBUFFER_LARGEST_ARB 0x2033 Accepted by the parameter of wglQueryPbufferARB: WGL_PBUFFER_WIDTH_ARB 0x2034 WGL_PBUFFER_HEIGHT_ARB 0x2035 WGL_PBUFFER_LOST_ARB 0x2036 Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation) None Additions to Chapter 3 of the 1.2 Specification (Rasterization) None Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations and the Frame buffer) None Additions to Chapter 5 of the 1.2 Specification (Special Functions) None Additions to Chapter 6 of the 1.2 Specification (State and State Requests) None Additions to the GLX Specification This specification is written for WGL. GLX Protocol This specification is written for WGL. Additions to the WGL Specification A pixel buffer (pbuffer) can be created with wglCreatePbufferARB which returns a handle associated with the pbuffer. HPBUFFERARB wglCreatePbufferARB(HDC hDC, int iPixelFormat, int iWidth, int iHeight, const int *piAttribList); specifies a device context for the device on which the pbuffer is created. specifies a non-generic pixel format descriptor index. Support for pbuffers may be restricted to specific pixel formats. Use wglGetPixelFormatAttribivEXT or wglGetPixelFormatAttribfvEXT to query the WGL_DRAW_TO_PBUFFER_ARB attribute to determine which pixel formats support the creation of pbuffers. and specify the pixel width and height of the rectangular pbuffer. is a list of attributes {type, value} pairs containing integer attribute values. All of the attributes in the are followed by the corresponding required value. The list is terminated with a value of 0. The following attributes are supported by wglCreatePbufferARB: 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 and , respectively. Use wglQueryPbufferARB to retrieve the dimensions of the allocated pbuffer. The resulting pbuffer will contain color buffers and ancillary buffers as specified by . 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 . (Pbuffers are the same as windows in this respect.) 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 or is negative or zero. ERROR_INVALID_DATA is not a valid attribute. To create a device context for the pbuffer, call HDC wglGetPbufferDCARB(HPBUFFERARB hPbuffer); where is a handle returned from a previous call to wglCreatePbufferARB. A device context is returned by wglGetPbufferDCARB which can be used to associate a rendering context with the pbuffer. Any rendering context created with a wglCreateContext that is "compatible" with the may be used to render into the pbuffer. (See the description of wglCreateContext, wglMakeCurrent, and wglMakeCurrentReadEXT for a definition of "compatible".) When wglGetPbufferDCARB fails, NULL is returned. To get extended error information, call GetLastError. Possible errors are as follows: ERROR_INVALID_HANDLE is not a valid handle. To release a device context obtained from a previous call to wglGetPbufferDCARB, call int wglReleasePbufferDCARB(HPBUFFERARB hPbuffer, HDC hDC); If the return value is a value of 1, the device context was released. If the device context was not released, the return value is 0. To get extended error information, call GetLastError. Possible errors are as follows: ERROR_INVALID_HANDLE is not a valid handle. ERROR_DC_NOT_FOUND is not a valid DC. A pbuffer is destroyed by calling BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); The pbuffer is destroyed once it is no longer current to any rendering context. When a pbuffer is destroyed, any memory resources that are attached to it are freed and its handle is no longer valid. If wglDestroyPbufferARB fails, FALSE is returned. To get extended error information, call GetLastError. Possible errors are as follows: ERROR_INVALID_HANDLE is not a valid handle. To query the maximum width, height, or number of pixels in any given pbuffer for a specific pixel format, use wglGetPixelFormatAttribivEXT or wglGetPixelFormatAttribfvEXT with set to one of WGL_MAX_PBUFFER_WIDTH_ARB, WGL_MAX_PBUFFER_HEIGHT_ARB, or WGL_MAX_PBUFFER_PIXELS_ARB. WGL_MAX_PBUFFER_WIDTH_ARB and WGL_MAX_PBUFFER_HEIGHT_ARB indicate the maximum width and height that can be passed into wglCreatePbufferARB and WGL_MAX_PBUFFER_PIXELS_ARB indicates the maximum number of pixels (width x height) for a pbuffer. Note that an implementation may return a value for WGL_MAX_PBUFFER_PIXELS_ARB that is less than the maximum width times the maximum height. Also, the value for WGL_MAX_PBUFFER_PIXELS_ARB is static and assumes that no other pbuffers are contending for the framebuffer memory. Thus it may not be possible to allocate a pbuffer of the size given by WGL_MAX_PBUFFER_PIXELS_ARB. To query an attribute associated with a specific pbuffer, call BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, int iAttribute, int *piValue); with set to a previously returned pbuffer handle. must be set to one of WGL_PBUFFER_WIDTH_ARB, WGL_PBUFFER_HEIGHT_ARB, or WGL_PBUFFER_LOST_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 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. If wglQueryPbufferARB fails, FALSE is returned. To get extended error information, call GetLastError. Possible errors are as follows: ERROR_INVALID_HANDLE is not a valid handle. ERROR_INVALID_DATA is not a valid attribute. Dependencies on WGL_ARB_pixel_format The WGL_ARB_pixel_format extension must be used to determine a pixel format that can be used to create the pixel buffer. Dependencies on WGL_ARB_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_ARB_extensions_string extension. New State None New Implementation Dependent State None Conformance Testing All of the current conformance tests can be run on a pixel buffer to validate its conformance. The only change to the conformance tests would be to create a context for the pixel buffer. Revision History 12/16/1999 0.1 - First ARB draft based on the EXT specification. 02/28/2000 0.2 - Added a query for a damaged pixel buffer due to a display mode change. 03/15/2000 0.3 - Changed the lost definition of a pixel buffer. - Removed the OPTIMAL size queries. - Added a dependency on WGL_ARB_pixel_format. 03/22/2000 1.0 - Changed "mode change" to "display mode change". - Added the condition that the resources associated with a pbuffer may be lost due to a display mode change. - Fixed issue 1 to address the OPTIMUM values. - Added the declaration of HPBUFFERARB in the Procedures and Functions section. - Changed the wording of "undamaged" to "unaffected" - Approved by ARB: 10-0-0. 03/12/2002 1.1 - Updated contact information.