Name EXT_pbuffer Name Strings WGL_EXT_pbuffer Version Date: 1/27/1999 Version 1.6 Number 171 Dependencies WGL_EXT_extensions_string is required. WGL_EXT_pixel_format is required. WGL_EXT_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. 4. The allocation of a pbuffer can fail if there are insufficient resources (i.e., all the pbuffer memory has been allocated). 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 only when the pbuffer is destroyed. New Procedures and Functions HPBUFFEREXT wglCreatePbufferEXT(HDC hDC, int iPixelFormat, int iWidth, int iHeight, const int *piAttribList); HDC wglGetPbufferDCEXT(HPBUFFEREXT hPbuffer); int wglReleasePbufferDCEXT(HPBUFFEREXT hPbuffer, HDC hDC); BOOL wglDestroyPbufferEXT(HPBUFFEREXT hPbuffer); BOOL wglQueryPbufferEXT(HPBUFFEREXT hPbuffer, int iAttribute, int *piValue); New Tokens Accepted by the parameter of wglGetPixelFormatAttribivEXT, wglGetPixelFormatAttribfvEXT, and wglChoosePixelFormatEXT: WGL_DRAW_TO_PBUFFER_EXT 0x202D WGL_MAX_PBUFFER_PIXELS_EXT 0x202E WGL_MAX_PBUFFER_WIDTH_EXT 0x202F WGL_MAX_PBUFFER_HEIGHT_EXT 0x2030 WGL_OPTIMAL_PBUFFER_WIDTH_EXT 0x2031 WGL_OPTIMAL_PBUFFER_HEIGHT_EXT 0x2032 Accepted by the parameter of wglCreatePbufferEXT: WGL_PBUFFER_LARGEST_EXT 0x2033 Accepted by the parameter of wglQueryPbufferEXT: WGL_PBUFFER_WIDTH_EXT 0x2034 WGL_PBUFFER_HEIGHT_EXT 0x2035 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 WGL Specification A pixel buffer (pbuffer) can be created with wglCreatePbufferEXT which returns a handle associated with the pbuffer. HPBUFFEREXT wglCreatePbufferEXT(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_EXT 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 wglCreatePbufferEXT: WGL_PBUFFER_LARGEST_EXT 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 wglQueryPbufferEXT 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 wglCreatePbufferEXT 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 wglGetPbufferDCEXT(HPBUFFEREXT hPbuffer); where is a handle returned from a previous call to wglCreatePbufferEXT. A device context is returned by wglGetPbufferDCEXT 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 wglGetPbufferDCEXT 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 wglGetPbufferDCEXT, call int wglReleasePbufferDCEXT(HPBUFFEREXT 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 wglDestroyPbufferEXT(HPBUFFEREXT 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 wglDestroyPbufferEXT 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_EXT, WGL_MAX_PBUFFER_HEIGHT_EXT, or WGL_MAX_PBUFFER_PIXELS_EXT. WGL_MAX_PBUFFER_WIDTH_EXT and WGL_MAX_PBUFFER_HEIGHT_EXT indicate the maximum width and height that can be passed into wglCreatePbufferEXT and WGL_MAX_PBUFFER_PIXELS_EXT 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_EXT that is less than the maximum width times the maximum height. Also, the value for WGL_MAX_PBUFFER_PIXELS_EXT 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_EXT. On some implementations, there may be an optimum width and height to use when allocating a pbuffer. (For example, the implementation may use fixed size tiles to allocate pbuffers.) Use WGL_OPTIMAL_PBUFFER_WIDTH_EXT and WGL_OPTIMAL_PBUFFER_HEIGHT to determine this width and height. If the value returned is zero, there is no optimal width or height value. To query an attribute associated with a specific pbuffer, call BOOL wglQueryPbufferEXT(HPBUFFEREXT hPbuffer, int iAttribute, int *piValue); with set to a previously returned pbuffer handle. must be set to one of WGL_PBUFFER_WIDTH_EXT or WGL_PBUFFER_HEIGHT_EXT. If wglQueryPbufferEXT 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. 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 is not a GL extension, it is not included in the GL_EXTENSIONS string. New State None New Implementation Dependent State None