DDPIXELFORMAT

Article
06/30/2006

The DDPIXELFORMAT structure describes the pixel format of a DirectDrawSurface object for the IDirectDrawSurface5::GetPixelFormat method.

typedef struct _DDPIXELFORMAT{ 
    DWORD dwSize; 
    DWORD dwFlags; 
    DWORD dwFourCC; 
    union 
    { 
        DWORD dwRGBBitCount; 
        DWORD dwYUVBitCount; 
        DWORD dwZBufferBitDepth; 
        DWORD dwAlphaBitDepth; 
        DWORD dwLuminanceBitCount;
        DWORD dwBumpBitCount;     
    } DUMMYUNIONNAMEN(1);
    union 
    { 
        DWORD dwRBitMask; 
        DWORD dwYBitMask; 
        DWORD dwStencilBitDepth;   
        DWORD dwLuminanceBitMask; 
        DWORD dwBumpDuBitMask;    
    } DUMMYUNIONNAMEN(2);
    union 
    { 
        DWORD dwGBitMask; 
        DWORD dwUBitMask; 
        DWORD dwZBitMask;       
        DWORD dwBumpDvBitMask;   
    } DUMMYUNIONNAMEN(3);
    union 
    { 
        DWORD dwBBitMask; 
        DWORD dwVBitMask; 
        DWORD dwStencilBitMask;   
        DWORD dwBumpLuminanceBitMask; 
    } DUMMYUNIONNAMEN(4);
    union 
    { 
        DWORD dwRGBAlphaBitMask; 
        DWORD dwYUVAlphaBitMask; 
        DWORD dwLuminanceAlphaBitMask; 
        DWORD dwRGBZBitMask; 
        DWORD dwYUVZBitMask; 
    } DUMMYUNIONNAMEN(5);
} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.

dwFlags
Optional control flags.

DDPF_ALPHA	The pixel format describes an alpha-only surface.
DDPF_ALPHAPIXELS	The surface has alpha channel information in the pixel format.
DDPF_ALPHAPREMULT	The surface uses the premultiplied alpha format. That is, the color components in each pixel are premultiplied by the alpha component.
DDPF_BUMPLUMINANCE	The luminance data in the pixel format is valid, and the dwLuminanceBitMask member describes valid luminance bits for a luminance-only or luminance-alpha surface.
DDPF_BUMPDUDV	Bump-map data in the pixel format is valid. Bump-map information is in the dwBumpBitCount, dwBumpDuBitMask, dwBumpDvBitMask, and dwBumpLuminanceBitMask members.
DDPF_COMPRESSED	The surface will accept pixel data in the specified format and compress it during the write operation.
DDPF_FOURCC	The dwFourCC member is valid and contains a FOURCC code describing a non-RGB pixel format.
DDPF_LUMINANCE	The pixel format describes a luminance-only or luminance-alpha surface.
DDPF_PALETTEINDEXED1 DDPF_PALETTEINDEXED2 DDPF_PALETTEINDEXED4 DDPF_PALETTEINDEXED8	The surface is 1-, 2-, 4-, or 8-bit color indexed.
DDPF_PALETTEINDEXEDTO8	The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette.
DDPF_RGB	The RGB data in the pixel format structure is valid.
DDPF_RGBTOYUV	The surface will accept RGB data and translate it during the write operation to YUV data. The format of the data to be written will be contained in the pixel format structure. The DDPF_RGB flag will be set.
DDPF_STENCILBUFFER	The surface encodes stencil and depth information in each pixel of the Z-buffer. This flag can only be used if the DDPF_ZBUFFER flag is also specified.
DDPF_YUV	The YUV data in the pixel format structure is valid.
DDPF_ZBUFFER	The pixel format describes a Z-buffer surface.
DDPF_ZPIXELS	The surface contains Z-buffer information in the pixels.

dwFourCC
FourCC code. For more information see, Four Character Codes (FOURCC).
dwRGBBitCount
RGB bits per pixel (4, 8, 16, 24, or 32).
dwYUVBitCount
YUV bits per pixel (4, 8, 16, 24, or 32).
dwZBufferBitDepth
Z-buffer bit depth (8, 16, 24, or 32).
dwAlphaBitDepth
Alpha channel bit depth (1, 2, 4, or 8) for an alpha-only surface (DDPF_ALPHA). For pixel formats that contain alpha information interleaved with color data (DDPF_ALPHAPIXELS), you must count the bits in the dwRGBAlphaBitMask member to obtain the bit-depth of the alpha component.
dwLuminanceBitCount
Total luminance bits per pixel. This member applies only to luminance-only and luminance-alpha surfaces.
dwBumpBitCount
Total bump-map bits per pixel in a bump-map surface.
dwRBitMask
Mask for red bits.
dwYBitMask
Mask for Y bits.
dwStencilBitDepth
Bit depth of the stencil buffer. This member specifies how many bits are reserved within each pixel of the Z-buffer for stencil information (the total number of Z-bits is equal to dwZBufferBitDepth minus dwStencilBitDepth).
dwLuminanceBitMask
Mask for luminance bits.
dwBumpDuBitMask
Mask for bump-map U delta bits.
dwGBitMask
Mask for green bits.
dwUBitMask
Mask for U bits.
dwZBitMask
Mask for Z bits.
dwBumpDvBitMask
Mask for bump-map V delta bits.
dwBBitMask
Mask for blue bits.
dwVBitMask
Mask for V bits.
dwStencilBitMask
Mask for stencil bits within each Z-buffer pixel.
dwBumpLuminanceBitMask
Mask for luminance in a bump-map pixel.
dwRGBAlphaBitMask and dwYUVAlphaBitMask and dwLuminanceAlphaBitMask
Masks for alpha channel.
dwRGBZBitMask and dwYUVZBitMask
Masks for the Z channel.

Remarks

The dwAlphaBitDepth member reflects the bit depth of an alpha-only pixel format (DDPF_ALPHA). For pixel formats that include the alpha component with color components (DDPF_ALPHAPIXELS), the alpha bit depth is obtained by counting the bits in the various mask members.

The following example function returns the number of bits set in a given bitmask:

WORD GetNumberOfBits( DWORD dwMask )
{
    WORD wBits = 0;
    while( dwMask )
    {
        dwMask = dwMask & ( dwMask - 1 );  
        wBits++;
    }
    return wBits;
}

The unions in this structure have been updated to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

Requirements

Runs on	Versions	Declared in
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h

See Also

Off-Screen Surface Formats

Last updated on Tuesday, July 13, 2004

DDPIXELFORMAT

Additional resources