Name

    WGL_ARB_pixel_format

Name Strings

    WGL_ARB_pixel_format

Contact

    Pat Brown, NVIDIA (pbrown 'at' nvidia.com)
    Paula Womack

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 3/15/2000.

Version

    Last Modified Date: March 25, 2009
    Author Revision: 1.3

Number

    ARB Extension #9

Dependencies

    WGL_ARB_extensions_string is required.

Overview

    This extension adds functions to query pixel format attributes and
    to choose from the list of supported pixel formats.

    These functions treat pixel formats as opaque types: attributes are
    specified by name rather than by accessing them directly as fields
    in a structure. Thus the list of attributes can be easily extended.

    Attribute names are defined which correspond to all of the values in
    the PIXELFORMATDESCRIPTOR and LAYERPLANEDESCRIPTOR data structures.
    Additionally this interface allows pixel formats to be supported
    which have attributes that cannot be represented using the standard
    pixel format functions, i.e. DescribePixelFormat,
    DescribeLayerPlane, ChoosePixelFormat, SetPixelFormat, and
    GetPixelFormat.

IP Status

    No issues.

Issues and Notes

  1. No provision is made to support extended pixel format attributes in
     metafiles.
  2. Should the transparent value pixel format attribute have separate red,
     green and blue values? Yes.
  3. What data type should the transparent value be? This is no longer an
     issue since the transparent value is no longer a packed pixel value (it
     has separate r,g,b,a and index values).
  4. Should we add DONT_CARE values for some of the pixel format attributes?
     No we should just ignore attributes that aren't specified in the list
     passed to wglChoosePixelFormatARB.
  5. Should wglGetPixelFormatAttrib*vARB ignore the <iLayerPlane> parameter
     when the attribute specified only applies to the main planes (e.g.,
     when the attribute is set to WGL_NUMBER_OVERLAYS) or should it require
     <iLayerPlane> to be set to zero? It will just ignore the parameter.
     This allows these attributes to be queried at the same time as
     attributes of the overlay planes.
  6. Should wglGetPixelFormatAttribivARB convert floating point values to
     fixed point? No, wglChoosePixelFormatARB needs a way to accept floating
     point values. pfAttribFList accomplishes this.
  7. Should wglChoosePixelFormatARB take an <iLayerPlane> parameter?
     Typically <iLayerPlane> would be set to zero and a pixel format would
     be selected based on the attributes of the main plane, so there is no
     <iLayerPlane> parameter. This should be OK; applications won't
     typically select a pixel format on the basis of overlay attributes.
     They can always call wglGetPixelFormatAttrib*vARB to get a pixel format
     that has the desired overlay values.
  8. Application programmers must check to see if a particular extension is
     supported before using any pixel format attributes associated with the
     extension. For example, if WGL_ARB_pbuffer is not supported then it is
     an error to specify WGL_DRAW_TO_PBUFFER_ARB in the attribute list to
     wglGetPixelFormatAttrib*vARB or wglChoosePixelFormatARB.
  9. Should WGLChoosePixelFormatARB consider pixel formats at other display
     depths? It would be useful to have an argument to
     WGLChoosePixelFormatARB indicating what display depth should be used.
     However, there is no good way to implement this in the ICD since pixel
     format handles are sequential indices and the pixel format for index n
     differs depending on the display mode.
 10. Should we allow non-displayable pixel formats for pbuffers? Yes,
     although many (most?) implementations will use displayable pixel
     formats for pbuffers, this is a useful feature and the spec should
     allow for it.
 11. Should we create all new calls for pixel formats, specifically should
     we introduce SetPixelFormatARB? No, this doesn't offer any value over
     the existing SetPixelFormat call.
 12. Should we add support for triple buffering? No, triple buffering needs
     to be covered by a separate extension.

New Procedures and Functions

    BOOL wglGetPixelFormatAttribivARB(HDC hdc,
                                      int iPixelFormat,
                                      int iLayerPlane,
                                      UINT nAttributes,
                                      const int *piAttributes,
                                      int *piValues);

    BOOL wglGetPixelFormatAttribfvARB(HDC hdc,
                                      int iPixelFormat,
                                      int iLayerPlane,
                                      UINT nAttributes,
                                      const int *piAttributes,
                                      FLOAT *pfValues);

    BOOL wglChoosePixelFormatARB(HDC hdc,
                                 const int *piAttribIList,
                                 const FLOAT *pfAttribFList,
                                 UINT nMaxFormats,
                                 int *piFormats,
                                 UINT *nNumFormats);

New Tokens

    Accepted in the <piAttributes> parameter array of
    wglGetPixelFormatAttribivARB, and wglGetPixelFormatAttribfvARB, and
    as a type in the <piAttribIList> and <pfAttribFList> parameter
    arrays of wglChoosePixelFormatARB:

        WGL_NUMBER_PIXEL_FORMATS_ARB            0x2000
        WGL_DRAW_TO_WINDOW_ARB                  0x2001
        WGL_DRAW_TO_BITMAP_ARB                  0x2002
        WGL_ACCELERATION_ARB                    0x2003
        WGL_NEED_PALETTE_ARB                    0x2004
        WGL_NEED_SYSTEM_PALETTE_ARB             0x2005
        WGL_SWAP_LAYER_BUFFERS_ARB              0x2006
        WGL_SWAP_METHOD_ARB                     0x2007
        WGL_NUMBER_OVERLAYS_ARB                 0x2008
        WGL_NUMBER_UNDERLAYS_ARB                0x2009
        WGL_TRANSPARENT_ARB                     0x200A
        WGL_TRANSPARENT_RED_VALUE_ARB           0x2037
        WGL_TRANSPARENT_GREEN_VALUE_ARB         0x2038
        WGL_TRANSPARENT_BLUE_VALUE_ARB          0x2039
        WGL_TRANSPARENT_ALPHA_VALUE_ARB         0x203A
        WGL_TRANSPARENT_INDEX_VALUE_ARB         0x203B
        WGL_SHARE_DEPTH_ARB                     0x200C
        WGL_SHARE_STENCIL_ARB                   0x200D
        WGL_SHARE_ACCUM_ARB                     0x200E
        WGL_SUPPORT_GDI_ARB                     0x200F
        WGL_SUPPORT_OPENGL_ARB                  0x2010
        WGL_DOUBLE_BUFFER_ARB                   0x2011
        WGL_STEREO_ARB                          0x2012
        WGL_PIXEL_TYPE_ARB                      0x2013
        WGL_COLOR_BITS_ARB                      0x2014
        WGL_RED_BITS_ARB                        0x2015
        WGL_RED_SHIFT_ARB                       0x2016
        WGL_GREEN_BITS_ARB                      0x2017
        WGL_GREEN_SHIFT_ARB                     0x2018
        WGL_BLUE_BITS_ARB                       0x2019
        WGL_BLUE_SHIFT_ARB                      0x201A
        WGL_ALPHA_BITS_ARB                      0x201B
        WGL_ALPHA_SHIFT_ARB                     0x201C
        WGL_ACCUM_BITS_ARB                      0x201D
        WGL_ACCUM_RED_BITS_ARB                  0x201E
        WGL_ACCUM_GREEN_BITS_ARB                0x201F
        WGL_ACCUM_BLUE_BITS_ARB                 0x2020
        WGL_ACCUM_ALPHA_BITS_ARB                0x2021
        WGL_DEPTH_BITS_ARB                      0x2022
        WGL_STENCIL_BITS_ARB                    0x2023
        WGL_AUX_BUFFERS_ARB                     0x2024

    Accepted as a value in the <piAttribIList> and <pfAttribFList>
    parameter arrays of wglChoosePixelFormatARB, and returned in the
    <piValues> parameter array of wglGetPixelFormatAttribivARB, and the
    <pfValues> parameter array of wglGetPixelFormatAttribfvARB:

        WGL_NO_ACCELERATION_ARB                 0x2025
        WGL_GENERIC_ACCELERATION_ARB            0x2026
        WGL_FULL_ACCELERATION_ARB               0x2027

        WGL_SWAP_EXCHANGE_ARB                   0x2028
        WGL_SWAP_COPY_ARB                       0x2029
        WGL_SWAP_UNDEFINED_ARB                  0x202A

        WGL_TYPE_RGBA_ARB                       0x202B
        WGL_TYPE_COLORINDEX_ARB                 0x202C

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

    Pixel Formats

    WGL uses pixel format indices to refer to the pixel formats
    supported by a device. The standard pixel format functions
    DescribePixelFormat, DescribeLayerPlane, ChoosePixelFormat,
    SetPixelFormat, and GetPixelFormat specify pixel format attributes
    using the PIXELFORMATDESCRIPTOR and LAYERPLANEDESCRIPTOR data
    structures.

    An additional set of functions may be used to query and specify
    pixel format attributes by name.

    Querying Pixel Format Attributes

    The following two functions can be used to query pixel format
    attributes by specifying a list of attributes to be queried and
    providing a buffer in which to receive the results from the query.
    These functions can be used to query the attributes of both the main
    plane and layer planes of a given pixel format.

    BOOL wglGetPixelFormatAttribivARB(HDC hdc,
                                      int iPixelFormat,
                                      int iLayerPlane,
                                      UINT nAttributes,
                                      const int *piAttributes,
                                      int *piValues);

    <hdc> specifies the device context on which the pixel format is
    supported.

    <iPixelFormat> is an index that specifies the pixel format. The
    pixel formats that a device context supports are identified by
    positive one-based integer indexes.

    <iLayerPlane> specifies which plane is being queried. Positive
    values of <iLayerPlane> identify overlay planes, where 1 is the
    first overlay plane over the main plane, 2 is the second overlay
    plane over the first overlay plane, and so on. Negative values
    identify underlay planes, where -1 is the first underlay plane under
    the main plane, -2 is the second underlay plane under the first
    underlay plane and so on. Use zero for the main plane.

    <nAttributes> number of attributes being queried.

    <piAttributes> list containing an array of pixel format attribute
    identifiers which specify the attributes to be queried. The
    following values are accepted:

        WGL_NUMBER_PIXEL_FORMATS_ARB
        The number of pixel formats for the device context. The
        <iLayerPlane> and <iPixelFormat> parameters are ignored if this
        attribute is specified.

        WGL_DRAW_TO_WINDOW_ARB
        True if the pixel format can be used with a window. The
        <iLayerPlane> parameter is ignored if this attribute is
        specified.

        WGL_DRAW_TO_BITMAP_ARB
        True if the pixel format can be used with a memory bitmap. The
        <iLayerPlane> parameter is ignored if this attribute is
        specified.

        WGL_ACCELERATION_ARB
        Indicates whether the pixel format is supported by the driver.
        If this is set to WGL_NO_ACCELERATION_ARB then only the software
        renderer supports this pixel format; if this is set to
        WGL_GENERIC_ACCELERATION_ARB then the pixel format is supported
        by an MCD driver; if this is set to WGL_FULL_ACCELERATION_ARB
        then the pixel format is supported by an ICD driver.

        WGL_NEED_PALETTE_ARB
        A logical palette is required to achieve the best results for
        this pixel format. The <iLayerPlane> parameter is ignored if
        this attribute is specified.

        WGL_NEED_SYSTEM_PALETTE_ARB
        The hardware supports one hardware palette in 256-color mode
        only. The <iLayerPlane> parameter is ignored if this attribute
        is specified.

        WGL_SWAP_LAYER_BUFFERS_ARB
        True if the pixel format supports swapping layer planes
        independently of the main planes. If the pixel format does not
        support a back buffer then this is set to FALSE. The
        <iLayerPlane> parameter is ignored if this attribute is
        specified.

        WGL_SWAP_METHOD_ARB
        If the pixel format supports a back buffer, then this indicates
        how they are swapped. If this attribute is set to
        WGL_SWAP_EXCHANGE_ARB then swapping exchanges the front and back
        buffer contents; if it is set to WGL_SWAP_COPY_ARB then swapping
        copies the back buffer contents to the front buffer; if it is
        set to WGL_SWAP_UNDEFINED_ARB then the back buffer contents are
        copied to the front buffer but the back buffer contents are
        undefined after the operation. If the pixel format does not
        support a back buffer then this parameter is set to
        WGL_SWAP_UNDEFINED_ARB. The <iLayerPlane> parameter is ignored
        if this attribute is specified.

        WGL_NUMBER_OVERLAYS_ARB
        The number of overlay planes. The <iLayerPlane> parameter is
        ignored if this attribute is specified.

        WGL_NUMBER_UNDERLAYS_ARB
        The number of underlay planes. The <iLayerPlane> parameter is
        ignored if this attribute is specified.

        WGL_TRANSPARENT_ARB
        True if transparency is supported.

        WGL_TRANSPARENT_RED_VALUE_ARB
        Specifies the transparent red color value. Typically this value
        is the same for all layer planes. This value is undefined if
        transparency is not supported.

        WGL_TRANSPARENT_GREEN_VALUE_ARB
        Specifies the transparent green value. Typically this value is
        the same for all layer planes. This value is undefined if
        transparency is not supported.

        WGL_TRANSPARENT_BLUE_VALUE_ARB
        Specifies the transparent blue color value. Typically this value
        is the same for all layer planes. This value is undefined if
        transparency is not supported.

        WGL_TRANSPARENT_ALPHA_VALUE_ARB
        Specifies the transparent alpha value. This is reserved for
        future use.

        WGL_TRANSPARENT_INDEX_VALUE_ARB
        Specifies the transparent color index value. Typically this
        value is the same for all layer planes. This value is undefined
        if transparency is not supported.

        WGL_SHARE_DEPTH_ARB
        True if the layer plane shares the depth buffer with the main
        planes. If <iLayerPlane> is zero, this is always true.

        WGL_SHARE_STENCIL_ARB
        True if the layer plane shares the stencil buffer with the main
        planes. If <iLayerPlane> is zero, this is always true.

        WGL_SHARE_ACCUM_ARB
        True if the layer plane shares the accumulation buffer with the
        main planes. If <iLayerPlane> is zero, this is always true.

        WGL_SUPPORT_GDI_ARB
        True if GDI rendering is supported.

        WGL_SUPPORT_OPENGL_ARB
        True if OpenGL is supported.

        WGL_DOUBLE_BUFFER_ARB
        True if the color buffer has back/front pairs.

        WGL_STEREO_ARB
        True if the color buffer has left/right pairs.

        WGL_PIXEL_TYPE_ARB
        The type of pixel data. This can be set to WGL_TYPE_RGBA_ARB or
        WGL_TYPE_COLORINDEX_ARB.

        WGL_COLOR_BITS_ARB
        The number of color bitplanes in each color buffer. For RGBA
        pixel types, it is the size of the color buffer, excluding the
        alpha bitplanes. For color-index pixels, it is the size of the
        color index buffer.

        WGL_RED_BITS_ARB
        The number of red bitplanes in each RGBA color buffer.

        WGL_RED_SHIFT_ARB
        The shift count for red bitplanes in each RGBA color buffer.

        WGL_GREEN_BITS_ARB
        The number of green bitplanes in each RGBA color buffer.

        WGL_GREEN_SHIFT_ARB
        The shift count for green bitplanes in each RGBA color buffer.

        WGL_BLUE_BITS_ARB
        The number of blue bitplanes in each RGBA color buffer.

        WGL_BLUE_SHIFT_ARB
        The shift count for blue bitplanes in each RGBA color buffer.

        WGL_ALPHA_BITS_ARB
        The number of alpha bitplanes in each RGBA color buffer.

        WGL_ALPHA_SHIFT_ARB
        The shift count for alpha bitplanes in each RGBA color buffer.

        WGL_ACCUM_BITS_ARB
        The total number of bitplanes in the accumulation buffer.

        WGL_ACCUM_RED_BITS_ARB
        The number of red bitplanes in the accumulation buffer.

        WGL_ACCUM_GREEN_BITS_ARB
        The number of green bitplanes in the accumulation buffer.

        WGL_ACCUM_BLUE_BITS_ARB
        The number of blue bitplanes in the accumulation buffer.

        WGL_ACCUM_ALPHA_BITS_ARB
        The number of alpha bitplanes in the accumulation buffer.

        WGL_DEPTH_BITS_ARB
        The depth of the depth (z-axis) buffer.

        WGL_STENCIL_BITS_ARB
        The depth of the stencil buffer.

        WGL_AUX_BUFFERS_ARB
        The number of auxiliary buffers.

    <piValues> points to a buffer into which the results of the query
    will be placed. Floating point attribute values are rounded to the
    nearest integer value. The caller must allocate this array and it
    must have at least <nattributes> entries.

    If the function succeeds, the return value is TRUE. If the function
    fails, the return value is FALSE. To get extended error information,
    call GetLastError.

    An error is generated if <piAttributes> contains an invalid
    attribute, if <iPixelFormat> is not a positive integer or is larger
    than the number of pixel formats, if <iLayerPlane> doesn't refer to
    an existing layer plane, or if <hdc> is invalid.

    If FALSE is returned, the contents of <piValues> are undefined.

    BOOL wglGetPixelFormatAttribfvARB(HDC hdc,
                                      int iPixelFormat,
                                      int iLayerPlane,
                                      UINT nAttributes,
                                      const int *piAttributes,
                                      FLOAT *pfValues);

    <hdc> specifies the device context on which the pixel format is
    supported.

    <iPixelFormat> is an index that specifies the pixel format. The
    pixel formats that a device context supports are identified by
    positive one-based integer indexes.

    <iLayerPlane> specifies which plane is being queried. Positive
    values of <iLayerPlane> identify overlay planes, where 1 is the
    first overlay plane over the main plane, 2 is the second overlay
    plane over the first overlay plane, and so on. Negative values
    identify underlay planes, where -1 is the first underlay plane under
    the main plane, -2 is the second underlay plane under the first
    underlay plane and so on. Use zero for the main plane.

    <nAttributes> number of attributes being queried.

    <piAttributes> list containing an array of pixel format attribute
    identifiers which specify the attributes to be queried. The values
    accepted are the same as for wglGetPixelFormatAttribivARB.

    <pfValues> is a pointer to a buffer into which the results of the
    query will be placed. Integer attribute values are converted
    floating point The caller must allocate this array and it must have
    at least at least <nAttributes> entries.

    If the function succeeds, the return value is TRUE. If the function
    fails, the return value is FALSE. To get extended error information,
    call GetLastError.

    An error is generated if <piAttributes> contains an invalid
    attribute, if <iPixelFormat> is not a positive integer or is larger
    than the number of pixel formats, if <iLayerPlane> doesn't refer to
    an existing layer plane, or if <hdc> is invalid.

    If FALSE is returned, the contents of <pfValues> are undefined.

    Supported Pixel Formats

    The maximum index of the pixel formats which can be referenced by
    the standard pixel format functions is returned by a successful call
    to DescribePixelFormat. This may be less than the maximum index of
    the pixel formats which can be referenced by
    wglGetPixelFormatAttribivARB and wglGetPixelFormatAttribfvARB.
    (determined by querying WGL_NUMBER_PIXEL_FORMATS_ARB).

    The pixel format of a "displayable" object (e.g. window, bitmap) is
    specified by passing its index to SetPixelFormat. Therefore, pixel
    formats which cannot be referenced by the standard pixel format
    functions are "non displayable".

    Indices are assigned to pixel formats in the following order:

    1. Accelerated pixel formats that are displayable

    2. Accelerated pixel formats that are displayable and which have
       extended attributes

    3. Generic pixel formats

    4. Accelerated pixel formats that are non displayable

    ChoosePixelFormat will never select pixel formats from either group
    2 or group 4. Each pixel format in group 2 is required to appear
    identical to some pixel format in group 1 when queried by
    DescribePixelFormat. Consequently, ChoosePixelFormat will always
    select a format from group 1 when it might otherwise have selected a
    format from group 2. Pixel formats in group 4 cannot be accessed by
    ChoosePixelFormat at all.

    SetPixelFormat and DescribePixelFormat will only accept pixel
    formats from groups 1-3. If a non-displayable pixel format is
    specified to SetPixelFormat or DescribePixelFormat an error will
    result. These pixel formats are only for use with WGL extensions,
    such as WGLCreatePbufferARB.

    The following function may be used to select from among all of the
    available pixel formats (including both accelerated and generic
    formats and non-displayable formats). This function accepts
    attributes for the main planes. A list of pixel formats that match
    the specified attributes is returned with the "best" pixel formats
    at the start of the list (order is device dependent).

    BOOL wglChoosePixelFormatARB(HDC hdc,
                                 const int *piAttribIList,
                                 const FLOAT *pfAttribFList,
                                 UINT nMaxFormats,
                                 int *piFormats,
                                 UINT *nNumFormats);

    <hdc> specifies the device context.

    <piAttribIList> specifies a list of attribute {type, value} pairs
    containing integer attribute values. All the attributes in
    <piAttribIList> are followed by the corresponding desired value. The
    list is terminated with 0. If <piAttribList> is NULL then the result
    is the same as if <piAttribList> was empty.

    <pfAttribFList> specifies a list of attribute {type, value} pairs
    containing floating point attribute values. All the attributes in
    <pfAttribFList> are followed by the corresponding desired value. The
    list is terminated with 0. If <pfAttribList> is NULL then the result
    is the same as if <pfAttribList> was empty.

    <nMaxFormats> specifies the maximum number of pixel formats to be
    returned.

    <piFormats> points to an array of returned indices of the matching
    pixel formats. The best pixel formats (i.e., closest match and best
    format for the hardware) are at the head of the list. The caller
    must allocate this array and it must have at least <nMaxFormats>
    entries.

    <nNumFormats> returns the number of matching formats. The returned
    value is guaranteed to be no larger than <nMaxFormats>.

    If the function succeeds, the return value is TRUE. If the function
    fails the return value is FALSE. To get extended error information,
    call GetLastError. If no matching formats are found then nNumFormats
    is set to zero and the function returns TRUE.

    If FALSE is returned, the contents of <piFormats> are undefined.

    wglChoosePixelFormatARB selects pixel formats to return based on the
    attribute values specified in <piAttribIList> and <pfAttribFList>.
    Some attribute values must match the pixel format value exactly when
    the attribute is specified while others specify a minimum criteria,
    meaning that the pixel format value must meet or exceed the
    specified value. See the table below for details.


     Attribute                      Type        Match Criteria

     WGL_DRAW_TO_WINDOW_ARB         boolean     exact
     WGL_DRAW_TO_BITMAP_ARB         boolean     exact
     WGL_ACCELERATION_ARB           enum        exact
     WGL_NEED_PALETTE_ARB           boolean     exact
     WGL_NEED_SYSTEM_PALETTE_ARB    boolean     exact
     WGL_SWAP_LAYER_BUFFERS_ARB     boolean     exact
     WGL_SWAP_METHOD_ARB            enum        exact
     WGL_NUMBER_OVERLAYS_ARB        integer     minimum
     WGL_NUMBER_UNDERLAYS_ARB       integer     minimum
     WGL_SHARE_DEPTH_ARB            boolean     exact
     WGL_SHARE_STENCIL_ARB          boolean     exact
     WGL_SHARE_ACCUM_ARB            boolean     exact
     WGL_SUPPORT_GDI_ARB            boolean     exact
     WGL_SUPPORT_OPENGL_ARB         boolean     exact
     WGL_DOUBLE_BUFFER_ARB          boolean     exact
     WGL_STEREO_ARB                 boolean     exact
     WGL_PIXEL_TYPE_ARB             enum        exact
     WGL_COLOR_BITS_ARB             integer     minimum
     WGL_RED_BITS_ARB               integer     minimum
     WGL_GREEN_BITS_ARB             integer     minimum
     WGL_BLUE_BITS_ARB              integer     minimum
     WGL_ALPHA_BITS_ARB             integer     minimum
     WGL_ACCUM_BITS_ARB             integer     minimum
     WGL_ACCUM_RED_BITS_ARB         integer     minimum
     WGL_ACCUM_GREEN_BITS_ARB       integer     minimum
     WGL_ACCUM_BLUE_BITS_ARB        integer     minimum
     WGL_ACCUM_ALPHA_BITS_ARB       integer     minimum
     WGL_DEPTH_BITS_ARB             integer     minimum
     WGL_STENCIL_BITS_ARB           integer     minimum
     WGL_AUX_BUFFERS_ARB            integer     minimum

    All attributes except WGL_NUMBER_OVERLAYS_ARB, WGL_NUMBER_UNDERLAYS_ARB,
    WGL_SHARE_DEPTH_ARB, WGL_SHARE_STENCIL_ARB, and WGL_SHARE_ACCUM_ARB
    apply to the main planes and not to any layer planes. If
    WGL_SHARE_DEPTH_ARB, WGL_SHARE_STENCIL_ARB, and WGL_SHARE_ACCUM_ARB are
    specified in either <piAttribList> or <pfAttribList>, then a pixel
    format will only be selected if it has no overlays or underlays or if
    all of its overlays and underlays match the specified value.
    Applications that need to find a pixel format that supports a layer
    plane with other buffer attributes (such as WGL_SUPPORT_OPENGL_ARB set
    to TRUE), must go through the list that is returned and call
    wglGetPixelFormatAttrib*vARB to find one with the appropriate
    attributes.

    Attributes that are specified in neither <piAttribIList> nor
    <pfAttribFList> are ignored (i.e., they are not looked at during the
    selection process). In addition the following attributes are always
    ignored, even if specified: WGL_NUMBER_PIXEL_FORMATS_ARB,
    WGL_RED_SHIFT_ARB, WGL_GREEN_SHIFT_ARB, WGL_BLUE_SHIFT_ARB,
    WGL_ALPHA_SHIFT_ARB, WGL_TRANSPARENT_ARB,
    WGL_TRANSPARENT_RED_VALUE_ARB,WGL_TRANSPARENT_GREEN_VALUE_ARB,
    WGL_TRANSPARENT_BLUE_VALUE_ARB, WGL_TRANSPARENT_ALPHA_VALUE_ARB, and
    WGL_TRANSPARENT_INDEX_ARB.

    If both <piAttribIList> and <pfAttribFList> are NULL or empty then all
    pixel formats for this device are returned.

    An error is generated if <piAttribIList> or <pfAttribFList> contain an
    invalid attribute or if <hdc> is invalid.

    Although it is not an error, wglChoosePixelFormat and
    wglChoosePixelFormatARB should not be used together. It is not necessary
    to change existing OpenGL programs but application writers should use
    wglChoosePixelFormatARB whenever possible. New pixel format attributes
    introduced by extensions (such as the number of multisample buffers)
    will only be known to the new calls, wglChoosePixelFormatARB and
    wglGetPixelFormatAttrib*vARB..

New State

    None

New Implementation Dependent State

    None

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
    extension string returned by glGetString. Its existence can be
    determined with the WGL_ARB_extensions_string extension.

Revision History

Changes from EXT_pixel_format:

   * Added WGL prefix to name to avoid possible name collisions
   * EXT suffix changed to ARB
   * Updated to new template, adding contact, status and revision sections
   * Version is no longer an RCS version
   * Attribute list passed to wglGetPixelFormatAttrib*v is type const
   * Separate red,green,blue,alpha and index transparent values
   * WGL_SWAP_LAYER_BUFFERS and WGL_SWAP_METHOD values defined for single
     buffered pixel formats
   * Array of return values for wglGetPixelFormatAttrib*v and
     wglChoosePixelFormatARB is undefined if function fails
   * Error returned if iPixelFormat is zero or negative in
     wglGetPixelFormat*v
   * Under "Supported Pixel Formats", indicate that SetPixelFormat and
     DescribePixelFormat do not accept non displayable pixel formats.
     Passing one in results in an error
   * If either piAttribIList of pfAttribFList are NULL when
     wglChoosePixelFormatARB is called then it is as if they were empty
   * Clarify that wglChoosePixelFormatARB returns TRUE even if no matching
     formats found
   * wglChoosePixelFormatARB will only match an overlay attribute (eg,
     WGL_SHARE_DEPTH_ARB) if there are no overlay planes or if all
     overlay/underlay plane attributes match the specified criteria
   * Be careful about using term hardware (change to pixel format where
     appropriate)
   * wglChoosePixelFormatARB now ignores the following attributes (in
     addition to WGL_NUMBER_PIXEL_FORMATS_ARB): WGL_*_SHIFT_ARB,
     WGL_TRANSPARENT_ARB, WGL_TRANSPARENT_*_VALUE_ARB.
   * Clarify that new pixel format attributes (eg, attributes introduced by
     extensions such as multisampling) are only known to the new pixel
     format calls, wglChoosePixelFormatARB and wglGetPixelFormat*vARB.
   * Add dependency on WGL_ARB_extensions_string

    03/12/2002  1.1
        - Updated contact information.

    07/29/2008  1.2
        - Updated contact information.

    03/25/2009  1.3
        - mjk: Fixed <nNumFormats> description