| 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 <attribute> 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 <piAttribList> parameter of wglCreatePbufferEXT: |
| |
| WGL_PBUFFER_LARGEST_EXT 0x2033 |
| |
| Accepted by the <iAttribute> 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); |
| |
| <hDC> specifies a device context for the device on which the pbuffer |
| is created. <iPixelFormat> 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. |
| |
| <iWidth> and <iHeight> specify the pixel width and height of the |
| rectangular pbuffer. |
| |
| <piAttribList> is a list of attributes {type, value} pairs containing |
| integer attribute values. All of the attributes in the <piAttribList> |
| 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 <iWidth> and <iHeight>, |
| respectively. Use wglQueryPbufferEXT |
| to retrieve the dimensions of the |
| allocated pbuffer. |
| |
| The resulting pbuffer will contain color buffers and ancillary |
| buffers as specified by <iPixelFormat>. 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 |
| <iPixelFormat>. (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 <iWidth> or <iHeight> is negative |
| or zero. |
| ERROR_INVALID_DATA <piAttribList> is not a valid attribute. |
| |
| To create a device context for the pbuffer, call |
| |
| HDC wglGetPbufferDCEXT(HPBUFFEREXT hPbuffer); |
| |
| where <hPbuffer> 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 <iPixelFormat> 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 <hPbuffer> 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 <hPbuffer> is not a valid handle. |
| ERROR_DC_NOT_FOUND <hDC> 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 <hPbuffer> 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 <attribute> 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 <hPbuffer> set to a previously returned pbuffer handle. |
| <iAttribute> 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 <hPbuffer> is not a valid handle. |
| ERROR_INVALID_DATA <iAttribute> 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 |