1Name 2 3 EXT_pixel_format 4 5Name Strings 6 7 WGL_EXT_pixel_format 8 9Version 10 11 $Date: 1999/04/03 08:41:17 $ $Revision: 1.4 $ 12 13Number 14 15 170 16 17Dependencies 18 19 WGL_EXT_extensions_string is required. 20 21Overview 22 23 This extension adds functions to query pixel format attributes 24 and to choose from the list of pixel formats supported by a device. 25 26 These functions treat pixel formats as opaque types: attributes 27 are specified by name rather than by accessing them directly as 28 fields in a structure. Thus the list of attributes can be easily 29 extended. 30 31 Attribute names are defined which correspond to all of the values 32 in the PIXELFORMATDESCRIPTOR and LAYERPLANEDESCRIPTOR data structures. 33 Additionally this interface allows pixel formats to be supported 34 which have attributes that cannot be represented using the standard 35 pixel format functions, i.e. DescribePixelFormat, DescribeLayerPlane, 36 ChoosePixelFormat, SetPixelFormat, and GetPixelFormat. 37 38Issues 39 40 1. No provision is made to support extended pixel format attributes in 41 metafiles. 42 2. The transparent value pixel format attribute doesn't have separate red, 43 green and blue values. This is OK since this can be done as an 44 additional extension. 45 3. Should we add DONT_CARE values for some of the pixel format attributes? 46 No we should just ignore attributes that aren't specified in the list 47 passed to wglChoosePixelFormatEXT. 48 4. Should wglGetPixelFormatAttrib*vEXT ignore the <iLayerPlane> parameter 49 when the attribute specified only applies to the main planes (e.g., 50 when the attribute is set to WGL_NUMBER_OVERLAYS) or should it require 51 <iLayerPlane> to be set to zero? It will just ignore the parameter. 52 5. Should wglGetPixelFormatAttribivEXT convert floating point values to 53 fixed point? No, wglChoosePixelFormatEXT needs a way to accept floating 54 point values. pfAttribFList accomplishes this. 55 6. Should wglChoosePixelFormatEXT take an <iLayerPlane> parameter? Typically 56 <iLayerPlane> would be set to zero and a pixel format would be selected 57 based on the attributes of the main plane, so there is no <iLayerPlane> 58 parameter. This should be OK; applications won't typically select a 59 pixel format on the basis of overlay attributes. They can always call 60 wglGetPixelFormatAttrib*vEXT to get a pixel format that has the desired 61 overlay values. 62 7. Application programmers must check to see if a particular extension 63 is supported before using any pixel format attributes associated with 64 the extension. For example, if WGL_EXT_pbuffer is not supported then 65 it is an error to specify WGL_DRAW_TO_PBUFFER_EXT in the attribute list 66 to wglGetPixelFormatAttrib*vEXT or wglChoosePixelFormatEXT. 67 68New Procedures and Functions 69 70 BOOL wglGetPixelFormatAttribivEXT(HDC hdc, 71 int iPixelFormat, 72 int iLayerPlane, 73 UINT nAttributes, 74 int *piAttributes, 75 int *piValues); 76 77 BOOL wglGetPixelFormatAttribfvEXT(HDC hdc, 78 int iPixelFormat, 79 int iLayerPlane, 80 UINT nAttributes, 81 int *piAttributes, 82 FLOAT *pfValues); 83 84 BOOL wglChoosePixelFormatEXT(HDC hdc, 85 const int *piAttribIList, 86 const FLOAT *pfAttribFList, 87 UINT nMaxFormats, 88 int *piFormats, 89 UINT *nNumFormats); 90 91New Tokens 92 93 Accepted in the <piAttributes> parameter array of 94 wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT: 95 96 WGL_NUMBER_PIXEL_FORMATS_EXT 0x2000 97 98 Accepted in the <piAttributes> parameter array of 99 wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT, 100 and in the <piAttribIList> and <pfAttribFList> parameter arrays 101 of wglChoosePixelFormatEXT: 102 103 WGL_DRAW_TO_WINDOW_EXT 0x2001 104 WGL_DRAW_TO_BITMAP_EXT 0x2002 105 WGL_ACCELERATION_EXT 0x2003 106 WGL_NEED_PALETTE_EXT 0x2004 107 WGL_NEED_SYSTEM_PALETTE_EXT 0x2005 108 WGL_SWAP_LAYER_BUFFERS_EXT 0x2006 109 WGL_SWAP_METHOD_EXT 0x2007 110 WGL_NUMBER_OVERLAYS_EXT 0x2008 111 WGL_NUMBER_UNDERLAYS_EXT 0x2009 112 WGL_TRANSPARENT_EXT 0x200A 113 WGL_TRANSPARENT_VALUE_EXT 0x200B 114 WGL_SHARE_DEPTH_EXT 0x200C 115 WGL_SHARE_STENCIL_EXT 0x200D 116 WGL_SHARE_ACCUM_EXT 0x200E 117 WGL_SUPPORT_GDI_EXT 0x200F 118 WGL_SUPPORT_OPENGL_EXT 0x2010 119 WGL_DOUBLE_BUFFER_EXT 0x2011 120 WGL_STEREO_EXT 0x2012 121 WGL_PIXEL_TYPE_EXT 0x2013 122 WGL_COLOR_BITS_EXT 0x2014 123 WGL_RED_BITS_EXT 0x2015 124 WGL_RED_SHIFT_EXT 0x2016 125 WGL_GREEN_BITS_EXT 0x2017 126 WGL_GREEN_SHIFT_EXT 0x2018 127 WGL_BLUE_BITS_EXT 0x2019 128 WGL_BLUE_SHIFT_EXT 0x201A 129 WGL_ALPHA_BITS_EXT 0x201B 130 WGL_ALPHA_SHIFT_EXT 0x201C 131 WGL_ACCUM_BITS_EXT 0x201D 132 WGL_ACCUM_RED_BITS_EXT 0x201E 133 WGL_ACCUM_GREEN_BITS_EXT 0x201F 134 WGL_ACCUM_BLUE_BITS_EXT 0x2020 135 WGL_ACCUM_ALPHA_BITS_EXT 0x2021 136 WGL_DEPTH_BITS_EXT 0x2022 137 WGL_STENCIL_BITS_EXT 0x2023 138 WGL_AUX_BUFFERS_EXT 0x2024 139 140 Accepted in the <piAttribIList> and <pfAttribFList> parameter arrays 141 of wglChoosePixelFormatEXT. And returned in the <piValues> parameter 142 array of wglGetPixelFormatAttribivEXT, and the <pfValues> parameter 143 array of wglGetPixelFormatAttribfvEXT, 144 145 WGL_NO_ACCELERATION_EXT 0x2025 146 WGL_GENERIC_ACCELERATION_EXT 0x2026 147 WGL_FULL_ACCELERATION_EXT 0x2027 148 149 WGL_SWAP_EXCHANGE_EXT 0x2028 150 WGL_SWAP_COPY_EXT 0x2029 151 WGL_SWAP_UNDEFINED_EXT 0x202A 152 153 WGL_TYPE_RGBA_EXT 0x202B 154 WGL_TYPE_COLORINDEX_EXT 0x202C 155 156Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation) 157 158 None 159 160Additions to Chapter 3 of the 1.2 Specification (Rasterization) 161 162 None 163 164Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations 165and the Frame buffer) 166 167 None 168 169Additions to Chapter 5 of the 1.2 Specification (Special Functions) 170 171 None 172 173Additions to Chapter 6 of the 1.2 Specification (State and State Requests) 174 175 None 176 177Additions to the WGL Specification 178 179 Pixel Formats 180 181 WGL uses pixel format indices to refer to the pixel formats supported by a 182 device. The standard pixel format functions DescribePixelFormat, 183 DescribeLayerPlane, ChoosePixelFormat, SetPixelFormat, and GetPixelFormat 184 specify pixel format attributes using the PIXELFORMATDESCRIPTOR and 185 LAYERPLANEDESCRIPTOR data structures. 186 187 An additional set of functions may be used to query and specify pixel 188 format attributes by name. 189 190 Querying Pixel Format Attributes 191 192 The following two functions can be used to query pixel format attributes 193 by specifying a list of attributes to be queried and providing a buffer 194 in which to receive the results from the query. These functions can be 195 used to query the attributes of both the main plane and layer planes 196 of a given pixel format. 197 198 BOOL wglGetPixelFormatAttribivEXT(HDC hdc, 199 int iPixelFormat, 200 int iLayerPlane, 201 UINT nAttributes, 202 int *piAttributes, 203 int *piValues); 204 205 <hdc> specifies the device context on which the pixel format is 206 supported. 207 208 <iPixelFormat> is an index that specifies the pixel format. The pixel 209 formats that a device context supports are identified by positive 210 one-based integer indexes. 211 212 <iLayerPlane> specifies which plane is being queried. Positive values 213 of <iLayerPlane> identify overlay planes, where 1 is the first overlay 214 plane over the main plane, 2 is the second overlay plane over the 215 first overlay plane, and so on. Negative values identify underlay 216 planes, where -1 is the first underlay plane under the main plane, 217 -2 is the second underlay plane under the first underlay plane and 218 so on. Use zero for the main plane. 219 220 <nAttributes> specifies the number of attributes being queried. 221 222 <piAttributes> specifies an array of pixel format attribute identifiers 223 which specify the attributes to be queried. The following values are 224 accepted: 225 226 WGL_NUMBER_PIXEL_FORMATS_EXT 227 The number of pixel formats for the device context. The 228 <iLayerPlane> and <iPixelFormat> parameters are ignored if this 229 attribute is specified. 230 231 WGL_DRAW_TO_WINDOW_EXT 232 True if the pixel format can be used with a window. The <iLayerPlane> 233 parameter is ignored if this attribute is specified. 234 235 WGL_DRAW_TO_BITMAP_EXT 236 True if the pixel format can be used with a memory bitmap. The 237 <iLayerPlane> parameter is ignored if this attribute is specified. 238 239 WGL_ACCELERATION_EXT 240 Indicates whether the pixel format is supported by the driver. 241 If this is set to WGL_NO_ACCELERATION_EXT then only the software 242 renderer supports this pixel format; if this is set to 243 WGL_GENERIC_ACCELERATION_EXT then the pixel format is supported by 244 an MCD driver; if this is set to WGL_FULL_ACCELERATION_EXT then the 245 pixel format is supported by an ICD driver. 246 247 WGL_NEED_PALETTE_EXT 248 A logical palette is required to achieve the best results for this 249 pixel type. The <iLayerPlane> parameter is ignored if this attribute 250 is specified. 251 252 WGL_NEED_SYSTEM_PALETTE_EXT 253 The hardware supports one hardware palette in 256-color mode only. 254 The <iLayerPlane> parameter is ignored if this attribute is 255 specified. 256 257 WGL_SWAP_LAYER_BUFFERS_EXT 258 True if the hardware can swap layer planes independently of the 259 main planes. The <iLayerPlane> parameter is ignored if this 260 attribute is specified. 261 262 WGL_SWAP_METHOD_EXT 263 If the color buffer has a back buffer, then this indicates how 264 they are swapped. If it is set to WGL_SWAP_EXCHANGE_EXT then 265 swapping exchanges the front and back buffer contents; if it is 266 set to WGL_SWAP_COPY_EXT then swapping copies the back buffer 267 contents to the front buffer; if it is set to 268 WGL_SWAP_UNDEFINED_EXT then the back buffer contents are copied 269 to the front buffer but the back buffer contents are undefined 270 after the operation. The <iLayerPlane> parameter is ignored if 271 this attribute is specified. 272 273 WGL_NUMBER_OVERLAYS_EXT 274 The number of overlay planes. The <iLayerPlane> parameter is ignored 275 if this attribute is specified. 276 277 WGL_NUMBER_UNDERLAYS_EXT 278 The number of underlay planes. The <iLayerPlane> parameter is 279 ignored if this attribute is specified. 280 281 WGL_TRANSPARENT_EXT 282 True if transparency is supported. Use the WGL_TRANSPARENT_VALUE 283 attribute to retrieve the transparent color value. 284 285 WGL_TRANSPARENT_VALUE_EXT 286 Specifies the transparent color or index value. Typically this 287 value is the same for all layer planes. 288 289 WGL_SHARE_DEPTH_EXT 290 True if the layer plane shares the depth buffer with the main 291 planes. If <iLayerPlane> is zero, this is always true. 292 293 WGL_SHARE_STENCIL_EXT 294 True if the layer plane shares the stencil buffer with the main 295 planes. If <iLayerPlane> is zero, this is always true. 296 297 WGL_SHARE_ACCUM_EXT 298 True if the layer plane shares the accumulation buffer with the 299 main planes. If <iLayerPlane> is zero, this is always true. 300 301 WGL_SUPPORT_GDI_EXT 302 True if GDI rendering is supported. 303 304 WGL_SUPPORT_OPENGL_EXT 305 True if OpenGL is supported. 306 307 WGL_DOUBLE_BUFFER_EXT 308 True if the color buffer has back/front pairs. 309 310 WGL_STEREO_EXT 311 True if the color buffer has left/right pairs. 312 313 WGL_PIXEL_TYPE_EXT 314 The type of pixel data. This can be set to WGL_TYPE_RGBA_EXT or 315 WGL_TYPE_COLORINDEX_EXT. 316 317 WGL_COLOR_BITS_EXT 318 The number of color bitplanes in each color buffer. For RGBA pixel 319 types, it is the size of the color buffer, excluding the alpha 320 bitplanes, For color-index pixels, it is the size of the color 321 index buffer. 322 323 WGL_RED_BITS_EXT 324 The number of red bitplanes in each RGBA color buffer. 325 326 WGL_RED_SHIFT_EXT 327 The shift count for red bitplanes in each RGBA color buffer. 328 329 WGL_GREEN_BITS_EXT 330 The number of green bitplanes in each RGBA color buffer. 331 332 WGL_GREEN_SHIFT_EXT 333 The shift count for green bitplanes in each RGBA color buffer. 334 335 WGL_BLUE_BITS_EXT 336 The number of blue bitplanes in each RGBA color buffer. 337 338 WGL_BLUE_SHIFT_EXT 339 The shift count for blue bitplanes in each RGBA color buffer. 340 341 WGL_ALPHA_BITS_EXT 342 The number of alpha bitplanes in each RGBA color buffer. 343 344 WGL_ALPHA_SHIFT_EXT 345 The shift count for alpha bitplanes in each RGBA color buffer. 346 347 WGL_ACCUM_BITS_EXT 348 The total number of bitplanes in the accumulation buffer. 349 350 WGL_ACCUM_RED_BITS_EXT 351 The number of red bitplanes in the accumulation buffer. 352 353 WGL_ACCUM_GREEN_BITS_EXT 354 The number of green bitplanes in the accumulation buffer. 355 356 WGL_ACCUM_BLUE_BITS_EXT 357 The number of blue bitplanes in the accumulation buffer. 358 359 WGL_ACCUM_ALPHA_BITS_EXT 360 The number of alpha bitplanes in the accumulation buffer. 361 362 WGL_DEPTH_BITS_EXT 363 The depth of the depth (z-axis) buffer. 364 365 WGL_STENCIL_BITS_EXT 366 The depth of the stencil buffer. 367 368 WGL_AUX_BUFFERS_EXT 369 The number of auxiliary buffers. 370 371 <piValues> points to a buffer into which the results of the query 372 will be placed. Floating point attribute values are rounded to the 373 nearest integer value. The caller must allocate this array and it 374 must have at least nAttributes entries. 375 376 If the function succeeds, the return value is TRUE. If the 377 function fails, the return value is FALSE. To get extended error 378 information, call GetLastError. 379 380 An error is generated if <piAttributes> contains an invalid 381 attribute, if <iPixelFormat> is larger than the number of pixel 382 formats, if <iLayerPlane> doesn't refer to an existing layer plane, 383 or if <hdc> is invalid. 384 385 If FALSE is returned, <piValues> will not have been modified. 386 387 BOOL wglGetPixelFormatAttribfvEXT(HDC hdc, 388 int iPixelFormat, 389 int iLayerPlane, 390 UINT nAttributes, 391 int *piAttributes, 392 FLOAT *pfValues); 393 394 395 <hdc> specifies the device context on which the pixel format is 396 supported. 397 398 <iPixelFormat> is an index that specifies the pixel format. The pixel 399 formats that a device context supports are identified by positive 400 one-based integer indexes. 401 402 <iLayerPlane> specifies which plane is being queried. Positive values 403 of <iLayerPlane> identify overlay planes, where 1 is the first overlay 404 plane over the main plane, 2 is the second overlay plane over the 405 first overlay plane, and so on. Negative values identify underlay 406 planes, where -1 is the first underlay plane under the main plane, 407 -2 is the second underlay plane under the first underlay plane and 408 so on. Use zero for the main plane. 409 410 <piAttributes> is an array of pixel format attribute identifiers which 411 specify the attributes to be queried. The values accepted are the 412 same as for wglGetPixelFormatAttribivEXT. 413 414 <pfValues> is a pointer to a buffer into which the results of the query 415 will be placed. Integer attribute values are converted floating point 416 The caller must allocate this array and it must have at least 417 <nAttributes> entries. 418 419 If the function succeeds, the return value is TRUE. If the 420 function fails, the return value is FALSE. To get extended error 421 information, call GetLastError. 422 423 An error is generated if <piAttributes> contains an invalid 424 attribute, if <iPixelFormat> is larger than the number of pixel 425 formats, if <iLayerPlane> doesn't refer to an existing layer plane, 426 or if <hdc> is invalid. 427 428 If FALSE is returned, <pfValues> will not have been modified. 429 430 Supported Pixel Formats 431 432 The maximum index of the pixel formats which can be referenced 433 by the standard pixel format functions is returned by a successful 434 call to DescribePixelFormat. This may be less than the maximum 435 index of the pixel formats which can be referenced by 436 wglGetPixelFormatAttribivEXT and wglGetPixelFormatAttribfvEXT. 437 (determined by querying WGL_NUMBER_PIXEL_FORMATS_EXT). 438 439 The pixel format of a "displayable" object (e.g. window, bitmap) is 440 specified by passing its index to SetPixelFormat. Therefore, pixel 441 formats which cannot be referenced by the standard pixel format 442 functions are "non displayable". 443 444 Indices are assigned to pixel formats in the following order: 445 446 1. Accelerated pixel formats that are displayable 447 448 2. Accelerated pixel formats that are displayable and which 449 have extended attributes 450 451 3. Generic pixel formats 452 453 4. Accelerated pixel formats that are non displayable 454 455 ChoosePixelFormat will never select pixel formats from either 456 group 2 or group 4. Each pixel format in group 2 is required to 457 appear identical to some pixel format in group 1 when queried by 458 DescribePixelFormat. Consequently, ChoosePixelFormat will always 459 select a format from group 1 when it might otherwise have selected 460 a format from group 2. Pixel formats in group 4 cannot be accessed 461 by ChoosePixelFormat at all. 462 463 The following function may be used to select from among all of the 464 pixel formats supported by a device. This function accepts attributes 465 for the main planes. A list of pixel formats that match the 466 specified attributes is returned with the "best" pixel formats 467 at the start of the list (order is device dependent). 468 469 BOOL wglChoosePixelFormatEXT(HDC hdc, 470 const int *piAttribIList, 471 const FLOAT *pfAttribFList, 472 UINT nMaxFormats, 473 int *piFormats, 474 UINT *nNumFormats); 475 476 <hdc> specifies the device context. 477 478 <piAttribIList> specifies a list of attribute {type, value} pairs 479 containing integer attribute values. All the attributes in 480 <piAttribIList> are followed by the corresponding desired value. 481 The list is terminated with 0. 482 483 <pfAttribFList> specifies a list of attribute {type, value} pairs 484 containing floating point attribute values. All the attributes in 485 <pfAttribFList> are followed by the corresponding desired value. 486 The list is terminated with 0. 487 488 <nMaxFormats> specifies the maximum number of pixel formats to be 489 returned. 490 491 <piFormats> points to an array of returned indices of the matching 492 pixel formats. The best pixel formats (i.e., closest match and best 493 format for the hardware) are at the head of the list. The caller must 494 allocate this array and it must have at least <nMaxFormats> entries. 495 496 <nNumFormats> returns the number of matching formats. This value may 497 be larger than <nMaxFormats>. 498 499 If the function succeeds, the return value is TRUE. If the function 500 fails the return value is FALSE. To get extended error information, 501 call GetLastError. 502 503 If FALSE is returned, <piFormats> will not have been modified. 504 505 wglChoosePixelFormatEXT selects pixel formats to return based on 506 the attribute values specified in <piAttribIList> and <pfAttribFList>. 507 All attribute values described in wglGetPixelFormatAttribiv are 508 supported with the exception of WGL_NUMBER_PIXEL_FORMATS_EXT. 509 510 All attributes except WGL_NUMBER_OVERLAYS_EXT, WGL_NUMBER_UNDERLAYS_EXT, 511 WGL_SWAP_LAYER_BUFFERS_EXT, WGL_SHARE_DEPTH_EXT, WGL_SHARE_STENCIL_EXT 512 and WGL_SHARE_ACCUM_EXT apply to the main planes and not to any layer 513 planes. Applications that need to find a pixel format that supports a 514 layer plane with specific buffer attributes, must go through the list 515 that is returned and call wglGetPixelFormatAttrib*vEXT to find one with 516 the appropriate attributes. 517 518 Attributes that are specified in neither <piAttribIList> nor 519 <pfAttribFList> are ignored (i.e., they are not looked at during the 520 selection process). 521 522 If both <piAttribIList> and <pfAttribFList> are NULL or empty then 523 all pixel formats for this device are returned. 524 525 An error is generated if <piAttribIList> or <pfAttribFList> contain an 526 invalid attribute or if <hdc> is invalid. 527 528 Although it is not an error, the new API calls should not be mixed with 529 old API calls. It is not necessary to change existing OpenGL programs. 530 However, application writers should be encouraged to use the new API 531 whenever possible. 532 533New State 534 535 None 536 537New Implementation Dependent State 538 539 None 540 541