| Name |
| |
| EXT_pixel_format |
| |
| Name Strings |
| |
| WGL_EXT_pixel_format |
| |
| Version |
| |
| $Date: 1999/04/03 08:41:17 $ $Revision: 1.4 $ |
| |
| Number |
| |
| 170 |
| |
| Dependencies |
| |
| WGL_EXT_extensions_string is required. |
| |
| 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. |
| |
| 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. |
| |
| 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); |
| |
| 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 |
| |
| 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 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. |
| |
| New State |
| |
| None |
| |
| New Implementation Dependent State |
| |
| None |
| |