back  Return to list

WGL_EXT_pixel_format
homeprevnext Name
  
    EXT_pixel_format  
  
homeprevnext Name Strings
  
    WGL_EXT_pixel_format  
  
homeprevnext Version
  
    $Date: 1999/04/03 08:41:17 $ $Revision: 1.4 $  
  
homeprevnext Number
  
    170  
  
homeprevnext Dependencies
  
    WGL_EXT_extensions_string is required.  
  
homeprevnext Overview
  
    This extension adds functions to query pixel format attributes  
    and to choose from the list of pixel formats supported by a device.  
  
    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.  
  
homeprevnext Issues
  
    1. No provision is made to support extended pixel format attributes in  
       metafiles.  
    2. The transparent value pixel format attribute doesn't have separate red,  
       green and blue values. This is OK since this can be done as an  
       additional extension.  
    3. 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 wglChoosePixelFormatEXT.  
    4. Should wglGetPixelFormatAttrib*vEXT 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.  
    5. Should wglGetPixelFormatAttribivEXT convert floating point values to  
       fixed point? No, wglChoosePixelFormatEXT needs a way to accept floating  
       point values. pfAttribFList accomplishes this.  
    6. Should wglChoosePixelFormatEXT 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*vEXT to get a pixel format that has the desired  
       overlay values.  
    7. 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_EXT_pbuffer is not supported then  
       it is an error to specify WGL_DRAW_TO_PBUFFER_EXT in the attribute list  
       to wglGetPixelFormatAttrib*vEXT or wglChoosePixelFormatEXT.  
  
homeprevnext New Procedures and Functions
  
    BOOL wglGetPixelFormatAttribivEXT(HDC hdc,  
                                      int iPixelFormat,  
                                      int iLayerPlane,  
                                      UINT nAttributes,  
                                      int *piAttributes,  
                                      int *piValues);  
  
    BOOL wglGetPixelFormatAttribfvEXT(HDC hdc,  
                                      int iPixelFormat,  
                                      int iLayerPlane,  
                                      UINT nAttributes,  
                                      int *piAttributes,  
                                      FLOAT *pfValues);  
  
    BOOL wglChoosePixelFormatEXT(HDC hdc,  
                                 const int *piAttribIList,  
                                 const FLOAT *pfAttribFList,  
                                 UINT nMaxFormats,  
                                 int *piFormats,  
                                 UINT *nNumFormats);  
  
homeprevnext New Tokens
  
    Accepted in the <piAttributes> parameter array of  
    wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT:  
  
        WGL_NUMBER_PIXEL_FORMATS_EXT         0x2000  
  
    Accepted in the <piAttributes> parameter array of  
    wglGetPixelFormatAttribivEXT, and wglGetPixelFormatAttribfvEXT,  
    and in the <piAttribIList> and <pfAttribFList> parameter arrays  
    of wglChoosePixelFormatEXT:  
  
        WGL_DRAW_TO_WINDOW_EXT               0x2001  
        WGL_DRAW_TO_BITMAP_EXT               0x2002  
        WGL_ACCELERATION_EXT                 0x2003  
        WGL_NEED_PALETTE_EXT                 0x2004  
        WGL_NEED_SYSTEM_PALETTE_EXT          0x2005  
        WGL_SWAP_LAYER_BUFFERS_EXT           0x2006  
        WGL_SWAP_METHOD_EXT                  0x2007  
        WGL_NUMBER_OVERLAYS_EXT              0x2008  
        WGL_NUMBER_UNDERLAYS_EXT             0x2009  
        WGL_TRANSPARENT_EXT                  0x200A  
        WGL_TRANSPARENT_VALUE_EXT            0x200B  
        WGL_SHARE_DEPTH_EXT                  0x200C  
        WGL_SHARE_STENCIL_EXT                0x200D  
        WGL_SHARE_ACCUM_EXT                  0x200E  
        WGL_SUPPORT_GDI_EXT                  0x200F  
        WGL_SUPPORT_OPENGL_EXT               0x2010  
        WGL_DOUBLE_BUFFER_EXT                0x2011  
        WGL_STEREO_EXT                       0x2012  
        WGL_PIXEL_TYPE_EXT                   0x2013  
        WGL_COLOR_BITS_EXT                   0x2014  
        WGL_RED_BITS_EXT                     0x2015  
        WGL_RED_SHIFT_EXT                    0x2016  
        WGL_GREEN_BITS_EXT                   0x2017  
        WGL_GREEN_SHIFT_EXT                  0x2018  
        WGL_BLUE_BITS_EXT                    0x2019  
        WGL_BLUE_SHIFT_EXT                   0x201A  
        WGL_ALPHA_BITS_EXT                   0x201B  
        WGL_ALPHA_SHIFT_EXT                  0x201C  
        WGL_ACCUM_BITS_EXT                   0x201D  
        WGL_ACCUM_RED_BITS_EXT               0x201E  
        WGL_ACCUM_GREEN_BITS_EXT             0x201F  
        WGL_ACCUM_BLUE_BITS_EXT              0x2020  
        WGL_ACCUM_ALPHA_BITS_EXT             0x2021  
        WGL_DEPTH_BITS_EXT                   0x2022  
        WGL_STENCIL_BITS_EXT                 0x2023  
        WGL_AUX_BUFFERS_EXT                  0x2024  
  
    Accepted in the <piAttribIList> and <pfAttribFList> parameter arrays  
    of wglChoosePixelFormatEXT.  And returned in the <piValues> parameter  
    array of wglGetPixelFormatAttribivEXT, and the <pfValues> parameter  
    array of wglGetPixelFormatAttribfvEXT,  
  
        WGL_NO_ACCELERATION_EXT              0x2025  
        WGL_GENERIC_ACCELERATION_EXT         0x2026  
        WGL_FULL_ACCELERATION_EXT            0x2027  
  
        WGL_SWAP_EXCHANGE_EXT                0x2028  
        WGL_SWAP_COPY_EXT                    0x2029  
        WGL_SWAP_UNDEFINED_EXT               0x202A  
  
        WGL_TYPE_RGBA_EXT                    0x202B  
        WGL_TYPE_COLORINDEX_EXT              0x202C  
  
homeprevnext Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation)
  
    None  
  
homeprevnext Additions to Chapter 3 of the 1.2 Specification (Rasterization)
  
    None  
  
homeprevnext Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations and the Frame buffer)
  
    None  
  
homeprevnext Additions to Chapter 5 of the 1.2 Specification (Special Functions)
  
    None  
  
homeprevnext Additions to Chapter 6 of the 1.2 Specification (State and State Requests)
  
    None  
  
homeprevnext 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 wglGetPixelFormatAttribivEXT(HDC hdc,  
                                          int iPixelFormat,  
                                          int iLayerPlane,  
                                          UINT nAttributes,  
                                          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> specifies the number of attributes being queried.  
  
    <piAttributes> specifies an array of pixel format attribute identifiers  
    which specify the attributes to be queried.  The following values are  
    accepted:  
  
        WGL_NUMBER_PIXEL_FORMATS_EXT  
        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_EXT  
        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_EXT  
        True if the pixel format can be used with a memory bitmap. The  
        <iLayerPlane> parameter is ignored if this attribute is specified.  
  
        WGL_ACCELERATION_EXT  
        Indicates whether the pixel format is supported by the driver.  
        If this is set to WGL_NO_ACCELERATION_EXT then only the software  
        renderer supports this pixel format; if this is set to  
        WGL_GENERIC_ACCELERATION_EXT then the pixel format is supported by  
        an MCD driver; if this is set to WGL_FULL_ACCELERATION_EXT then the  
        pixel format is supported by an ICD driver.  
  
        WGL_NEED_PALETTE_EXT  
        A logical palette is required to achieve the best results for this  
        pixel type. The <iLayerPlane> parameter is ignored if this attribute  
        is specified.  
  
        WGL_NEED_SYSTEM_PALETTE_EXT  
        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_EXT  
        True if the hardware can swap layer planes independently of the  
        main planes. The <iLayerPlane> parameter is ignored if this  
        attribute is specified.  
  
        WGL_SWAP_METHOD_EXT  
        If the color buffer has a back buffer, then this indicates how  
        they are swapped. If it is set to WGL_SWAP_EXCHANGE_EXT then  
        swapping exchanges the front and back buffer contents; if it is  
        set to WGL_SWAP_COPY_EXT then swapping copies the back buffer  
        contents to the front buffer; if it is set to  
        WGL_SWAP_UNDEFINED_EXT then the back buffer contents are copied  
        to the front buffer but the back buffer contents are undefined  
        after the operation. The <iLayerPlane> parameter is ignored if  
        this attribute is specified.  
  
        WGL_NUMBER_OVERLAYS_EXT  
        The number of overlay planes. The <iLayerPlane> parameter is ignored  
        if this attribute is specified.  
  
        WGL_NUMBER_UNDERLAYS_EXT  
        The number of underlay planes. The <iLayerPlane> parameter is  
        ignored if this attribute is specified.  
  
        WGL_TRANSPARENT_EXT  
        True if transparency is supported. Use the WGL_TRANSPARENT_VALUE  
        attribute to retrieve the transparent color value.  
  
        WGL_TRANSPARENT_VALUE_EXT  
        Specifies the transparent color or index value. Typically this  
        value is the same for all layer planes.  
  
        WGL_SHARE_DEPTH_EXT  
        True if the layer plane shares the depth buffer with the main  
        planes. If <iLayerPlane> is zero, this is always true.  
  
        WGL_SHARE_STENCIL_EXT  
        True if the layer plane shares the stencil buffer with the main  
        planes. If <iLayerPlane> is zero, this is always true.  
  
        WGL_SHARE_ACCUM_EXT  
        True if the layer plane shares the accumulation buffer with the  
        main planes. If <iLayerPlane> is zero, this is always true.  
  
        WGL_SUPPORT_GDI_EXT  
        True if GDI rendering is supported.  
  
        WGL_SUPPORT_OPENGL_EXT  
        True if OpenGL is supported.  
  
        WGL_DOUBLE_BUFFER_EXT  
        True if the color buffer has back/front pairs.  
  
        WGL_STEREO_EXT  
        True if the color buffer has left/right pairs.  
  
        WGL_PIXEL_TYPE_EXT  
        The type of pixel data. This can be set to WGL_TYPE_RGBA_EXT or  
        WGL_TYPE_COLORINDEX_EXT.  
  
        WGL_COLOR_BITS_EXT  
        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_EXT  
        The number of red bitplanes in each RGBA color buffer.  
  
        WGL_RED_SHIFT_EXT  
        The shift count for red bitplanes in each RGBA color buffer.  
  
        WGL_GREEN_BITS_EXT  
        The number of green bitplanes in each RGBA color buffer.  
  
        WGL_GREEN_SHIFT_EXT  
        The shift count for green bitplanes in each RGBA color buffer.  
  
        WGL_BLUE_BITS_EXT  
        The number of blue bitplanes in each RGBA color buffer.  
  
        WGL_BLUE_SHIFT_EXT  
        The shift count for blue bitplanes in each RGBA color buffer.  
  
        WGL_ALPHA_BITS_EXT  
        The number of alpha bitplanes in each RGBA color buffer.  
  
        WGL_ALPHA_SHIFT_EXT  
        The shift count for alpha bitplanes in each RGBA color buffer.  
  
        WGL_ACCUM_BITS_EXT  
        The total number of bitplanes in the accumulation buffer.  
  
        WGL_ACCUM_RED_BITS_EXT  
        The number of red bitplanes in the accumulation buffer.  
  
        WGL_ACCUM_GREEN_BITS_EXT  
        The number of green bitplanes in the accumulation buffer.  
  
        WGL_ACCUM_BLUE_BITS_EXT  
        The number of blue bitplanes in the accumulation buffer.  
  
        WGL_ACCUM_ALPHA_BITS_EXT  
        The number of alpha bitplanes in the accumulation buffer.  
  
        WGL_DEPTH_BITS_EXT  
        The depth of the depth (z-axis) buffer.  
  
        WGL_STENCIL_BITS_EXT  
        The depth of the stencil buffer.  
  
        WGL_AUX_BUFFERS_EXT  
        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 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, <piValues> will not have been modified.  
  
        BOOL wglGetPixelFormatAttribfvEXT(HDC hdc,  
                                          int iPixelFormat,  
                                          int iLayerPlane,  
                                          UINT nAttributes,  
                                          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.  
  
    <piAttributes> is an array of pixel format attribute identifiers which  
    specify the attributes to be queried.  The values accepted are the  
    same as for wglGetPixelFormatAttribivEXT.  
  
    <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  
    <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 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, <pfValues> will not have been modified.  
  
    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  
    wglGetPixelFormatAttribivEXT and wglGetPixelFormatAttribfvEXT.  
    (determined by querying WGL_NUMBER_PIXEL_FORMATS_EXT).  
  
    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.  
  
    The following function may be used to select from among all of the  
    pixel formats supported by a device.  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 wglChoosePixelFormatEXT(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.  
  
    <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.  
  
    <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. This value may  
    be 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 FALSE is returned, <piFormats> will not have been modified.  
  
    wglChoosePixelFormatEXT selects pixel formats to return based on  
    the attribute values specified in <piAttribIList> and <pfAttribFList>.  
    All attribute values described in wglGetPixelFormatAttribiv are  
    supported with the exception of WGL_NUMBER_PIXEL_FORMATS_EXT.  
  
    All attributes except WGL_NUMBER_OVERLAYS_EXT, WGL_NUMBER_UNDERLAYS_EXT,  
    WGL_SWAP_LAYER_BUFFERS_EXT, WGL_SHARE_DEPTH_EXT, WGL_SHARE_STENCIL_EXT  
    and WGL_SHARE_ACCUM_EXT apply to the main planes and not to any layer  
    planes.  Applications that need to find a pixel format that supports a  
    layer plane with specific buffer attributes, must go through the list  
    that is returned and call wglGetPixelFormatAttrib*vEXT 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).  
  
    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, the new API calls should not be mixed with  
    old API calls. It is not necessary to change existing OpenGL programs.  
    However, application writers should be encouraged to use the new API  
    whenever possible.  
  
homeprevnext New State
  
    None  
  
homeprevnext New Implementation Dependent State
  
    None  
  
  
Valid XHTML 1.1! Valid CSS! Last update: November 14, 2006.
Cette page doit être lue avec un navigateur récent respectant le standard XHTML 1.1.