1Name 2 3 EXT_pbuffer 4 5Name Strings 6 7 WGL_EXT_pbuffer 8 9Version 10 11 Date: 1/27/1999 Version 1.6 12 13Number 14 15 171 16 17Dependencies 18 19 WGL_EXT_extensions_string is required. 20 WGL_EXT_pixel_format is required. 21 WGL_EXT_make_current_read affects the definition of this extension. 22 23Overview 24 25 This extension defines pixel buffers (pbuffer for short). Pbuffers are 26 additional non-visible rendering buffers for an OpenGL renderer. 27 Pbuffers are equivalent to a window that has the same pixel format 28 descriptor with the following exceptions: 29 30 1. There is no rendering to a pbuffer by GDI. 31 32 2. The pixel format descriptors used for a pbuffer can only be those 33 that are supported by the ICD. Generic formats are not valid. 34 35 4. The allocation of a pbuffer can fail if there are insufficient 36 resources (i.e., all the pbuffer memory has been allocated). 37 38 The intent of the pbuffer semantics is to enable implementations to 39 allocate pbuffers in non-visible frame buffer memory. These 40 pbuffers are intended to be "static" resources in that a program 41 will typically allocate them only once rather than as a part of its 42 rendering loop. (Pbuffers should be deallocated when the program is 43 no longer using them -- for example, if the program is iconified.) 44 45 The frame buffer resources that are associated with a pbuffer are 46 also static and are deallocated only when the pbuffer is destroyed. 47 48New Procedures and Functions 49 50 HPBUFFEREXT wglCreatePbufferEXT(HDC hDC, 51 int iPixelFormat, 52 int iWidth, 53 int iHeight, 54 const int *piAttribList); 55 56 HDC wglGetPbufferDCEXT(HPBUFFEREXT hPbuffer); 57 58 int wglReleasePbufferDCEXT(HPBUFFEREXT hPbuffer, 59 HDC hDC); 60 61 BOOL wglDestroyPbufferEXT(HPBUFFEREXT hPbuffer); 62 63 BOOL wglQueryPbufferEXT(HPBUFFEREXT hPbuffer, 64 int iAttribute, 65 int *piValue); 66 67New Tokens 68 69 Accepted by the <attribute> parameter of wglGetPixelFormatAttribivEXT, 70 wglGetPixelFormatAttribfvEXT, and wglChoosePixelFormatEXT: 71 72 WGL_DRAW_TO_PBUFFER_EXT 0x202D 73 WGL_MAX_PBUFFER_PIXELS_EXT 0x202E 74 WGL_MAX_PBUFFER_WIDTH_EXT 0x202F 75 WGL_MAX_PBUFFER_HEIGHT_EXT 0x2030 76 WGL_OPTIMAL_PBUFFER_WIDTH_EXT 0x2031 77 WGL_OPTIMAL_PBUFFER_HEIGHT_EXT 0x2032 78 79 Accepted by the <piAttribList> parameter of wglCreatePbufferEXT: 80 81 WGL_PBUFFER_LARGEST_EXT 0x2033 82 83 Accepted by the <iAttribute> parameter of wglQueryPbufferEXT: 84 85 WGL_PBUFFER_WIDTH_EXT 0x2034 86 WGL_PBUFFER_HEIGHT_EXT 0x2035 87 88Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation) 89 90 None 91 92Additions to Chapter 3 of the 1.2 Specification (Rasterization) 93 94 None 95 96Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations 97and the Frame buffer) 98 99 None 100 101Additions to Chapter 5 of the 1.2 Specification (Special Functions) 102 103 None 104 105Additions to Chapter 6 of the 1.2 Specification (State and State Requests) 106 107 None 108 109Additions to the WGL Specification 110 111 A pixel buffer (pbuffer) can be created with wglCreatePbufferEXT 112 which returns a handle associated with the pbuffer. 113 114 HPBUFFEREXT wglCreatePbufferEXT(HDC hDC, 115 int iPixelFormat, 116 int iWidth, 117 int iHeight, 118 const int *piAttribList); 119 120 <hDC> specifies a device context for the device on which the pbuffer 121 is created. <iPixelFormat> specifies a non-generic pixel format 122 descriptor index. Support for pbuffers may be restricted to 123 specific pixel formats. Use wglGetPixelFormatAttribivEXT or 124 wglGetPixelFormatAttribfvEXT to query the WGL_DRAW_TO_PBUFFER_EXT 125 attribute to determine which pixel formats support the creation of 126 pbuffers. 127 128 <iWidth> and <iHeight> specify the pixel width and height of the 129 rectangular pbuffer. 130 131 <piAttribList> is a list of attributes {type, value} pairs containing 132 integer attribute values. All of the attributes in the <piAttribList> 133 are followed by the corresponding required value. The list is 134 terminated with a value of 0. 135 136 The following attributes are supported by wglCreatePbufferEXT: 137 138 WGL_PBUFFER_LARGEST_EXT If this attribute is set to a 139 non-zero value, the largest 140 available pbuffer is allocated 141 when the allocation of the pbuffer 142 would otherwise fail due to 143 insufficient resources. The width 144 or height of the allocated pbuffer 145 never exceeds <iWidth> and <iHeight>, 146 respectively. Use wglQueryPbufferEXT 147 to retrieve the dimensions of the 148 allocated pbuffer. 149 150 The resulting pbuffer will contain color buffers and ancillary 151 buffers as specified by <iPixelFormat>. Note that pbuffers use 152 framebuffer resources so applications should consider deallocating 153 them when they are not in use. 154 155 It is possible to create a pbuffer with back buffers and to swap 156 the front and back buffers by calling wglSwapLayerBuffers. The 157 contents of the back buffers after the swap depends on the 158 <iPixelFormat>. (Pbuffers are the same as windows in this respect.) 159 160 When wglCreatePbufferEXT fails to create a pbuffer, NULL is returned. 161 To get extended error information, call GetLastError. Possible errors 162 are as follows: 163 164 ERROR_INVALID_PIXEL_FORMAT Pixel format is not valid. 165 ERROR_NO_SYSTEM_RESOURCES Insufficient resources exist. 166 ERROR_INVALID_DATA <iWidth> or <iHeight> is negative 167 or zero. 168 ERROR_INVALID_DATA <piAttribList> is not a valid attribute. 169 170 To create a device context for the pbuffer, call 171 172 HDC wglGetPbufferDCEXT(HPBUFFEREXT hPbuffer); 173 174 where <hPbuffer> is a handle returned from a previous call to 175 wglCreatePbufferEXT. A device context is returned by 176 wglGetPbufferDCEXT which can be used to associate a rendering 177 context with the pbuffer. Any rendering context created with 178 a wglCreateContext that is "compatible" with the <iPixelFormat> may be 179 used to render into the pbuffer. (See the description of 180 wglCreateContext, wglMakeCurrent, and wglMakeCurrentReadEXT for a 181 definition of "compatible".) 182 183 When wglGetPbufferDCEXT fails, NULL is returned. To get extended 184 error information, call GetLastError. Possible errors are as follows: 185 186 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 187 188 To release a device context obtained from a previous call to 189 wglGetPbufferDCEXT, call 190 191 int wglReleasePbufferDCEXT(HPBUFFEREXT hPbuffer, 192 HDC hDC); 193 194 If the return value is a value of 1, the device context was released. 195 If the device context was not released, the return value is 0. To get 196 extended error information, call GetLastError. Possible errors are 197 as follows: 198 199 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 200 ERROR_DC_NOT_FOUND <hDC> is not a valid DC. 201 202 A pbuffer is destroyed by calling 203 204 BOOL wglDestroyPbufferEXT(HPBUFFEREXT hPbuffer); 205 206 The pbuffer is destroyed once it is no longer current to any rendering 207 context. When a pbuffer is destroyed, any memory resources that are 208 attached to it are freed and its handle is no longer valid. 209 210 If wglDestroyPbufferEXT fails, FALSE is returned. To get extended 211 error information, call GetLastError. Possible errors are as follows: 212 213 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 214 215 To query the maximum width, height, or number of pixels in any given 216 pbuffer for a specific pixel format, use wglGetPixelFormatAttribivEXT 217 or wglGetPixelFormatAttribfvEXT with <attribute> set to one of 218 WGL_MAX_PBUFFER_WIDTH_EXT, WGL_MAX_PBUFFER_HEIGHT_EXT, or 219 WGL_MAX_PBUFFER_PIXELS_EXT. 220 221 WGL_MAX_PBUFFER_WIDTH_EXT and WGL_MAX_PBUFFER_HEIGHT_EXT indicate the 222 maximum width and height that can be passed into wglCreatePbufferEXT 223 and WGL_MAX_PBUFFER_PIXELS_EXT indicates the maximum number of pixels 224 (width x height) for a pbuffer. Note that an implementation may 225 return a value for WGL_MAX_PBUFFER_PIXELS_EXT that is less than the 226 maximum width times the maximum height. Also, the value for 227 WGL_MAX_PBUFFER_PIXELS_EXT is static and assumes that no other 228 pbuffers are contending for the framebuffer memory. Thus it may 229 not be possible to allocate a pbuffer of the size given by 230 WGL_MAX_PBUFFER_PIXELS_EXT. 231 232 On some implementations, there may be an optimum width and height 233 to use when allocating a pbuffer. (For example, the implementation 234 may use fixed size tiles to allocate pbuffers.) Use 235 WGL_OPTIMAL_PBUFFER_WIDTH_EXT and WGL_OPTIMAL_PBUFFER_HEIGHT to 236 determine this width and height. If the value returned is zero, 237 there is no optimal width or height value. 238 239 To query an attribute associated with a specific pbuffer, call 240 241 BOOL wglQueryPbufferEXT(HPBUFFEREXT hPbuffer, 242 int iAttribute, 243 int *piValue); 244 245 with <hPbuffer> set to a previously returned pbuffer handle. 246 <iAttribute> must be set to one of WGL_PBUFFER_WIDTH_EXT or 247 WGL_PBUFFER_HEIGHT_EXT. 248 249 If wglQueryPbufferEXT fails, FALSE is returned. To get extended 250 error information, call GetLastError. Possible errors are as follows: 251 252 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 253 ERROR_INVALID_DATA <iAttribute> is not a valid attribute. 254 255 Because there is no way to extend wgl, these calls are defined in the 256 ICD and can be called by obtaining the address with wglGetProcAddress. 257 Because this is not a GL extension, it is not included in the 258 GL_EXTENSIONS string. 259 260New State 261 262 None 263 264New Implementation Dependent State 265 266 None 267