DDPIXELFORMAT

Article
06/30/2006

This 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;
    DWORD dwPrivateFormatBitCount;
  };
  union
  {
    DWORD dwRBitMask;
    DWORD dwYBitMask;
    DWORD dwStencilBitDepth;
    DWORD dwLuminanceBitMask;
    DWORD dwBumpDuBitMask;
    DWORD dwOperations;
  };
  union
  {
    DWORD dwGBitMask;
    DWORD dwUBitMask;
    DWORD dwZBitMask;
    DWORD dwBumpDvBitMask;
    struct
    {
      WORD wFlipMSTypes;
      WORD wBltMSTypes;
    } MultiSampleCaps;
    };
  union
  {
    DWORD dwBBitMask;
    DWORD dwVBitMask;
    DWORD dwStencilBitMask;
    DWORD dwBumpLuminanceBitMask;
  };
  union
  {
    DWORD dwRGBAlphaBitMask;
    DWORD dwYUVAlphaBitMask;
    DWORD dwLuminanceAlphaBitMask;
    DWORD dwRGBZBitMask;
    DWORD dwYUVZBitMask;
  };
} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

Members

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

dwFlags
Set of flags that specify optional control flags. This member is a bitwise OR of any of the flags shown in the following table.

Flag	Description
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 color components in the pixel are premultiplied by the alpha value in the pixel. If this flag is set, the DDPF_ALPHAPIXELS flag must also be set. If this flag is not set but the DDPF_ALPHAPIXELS flag is set, the color components in the pixel format are not premultiplied by alpha. In this case, the color components must be multiplied by the alpha value at the time that an alpha-blending operation is performed.
DDPF_BUMPDUDV	The bump map dUdV data in the pixel format is valid.
DDPF_BUMPHEIGHT	The bump map height data in the pixel format is valid.
DDPF_COMPRESSED	The surface accepts pixel data in the specified format and compresses it during the write operation.
DDPF_FOURCC	The FourCC code is valid.
DDPF_LUMINANCE	Luminance data in the pixel format is valid. Use this flag for luminance-only or luminance-plus-alpha surfaces; the bit depth is then specified in the dwLuminanceBitCount member.
DDPF_LUMINANCEPIXELS	Luminance data in the pixel format is valid. Use this flag when hanging luminance off, for example, bump map surfaces. The bit mask for the luminance portion of the pixel is then specified in the dwBumpLuminanceBitMask member.
DDPF_PALETTEINDEXED1	The surface is 1-bit color indexed.
DDPF_PALETTEINDEXED2	The surface is 2-bit color indexed.
DDPF_PALETTEINDEXED4	The surface is 4-bit color indexed.
DDPF_PALETTEINDEXED8	The surface is 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 accepts RGB data and translates it during the write operation to YUV data. The format of the data to be written is contained in the pixel format structure. The DDPF_RGB flag is set.
DDPF_STENCILPIXELS	The surface encodes stencil and depth information in each pixel of the z-buffer.
DDPF_YUV	The YUV data in the pixel format structure is valid.
DDPF_ZBUFFER	The pixel format describes a z-buffer-only surface.
DDPF_ZPIXELS	The surface is in RGBZ format.

dwFourCC
Specifies the FourCC code.
dwRGBBitCount
Specifies the number of RGB bits per pixel (4, 8, 16, 24, or 32).
dwYUVBitCount
Specifies the number of YUV bits per pixel.
dwZBufferBitDepth
Specifies the z-buffer bit depth (8, 16, 24, or 32 bits).
dwAlphaBitDepth
Specifies the Alpha channel bit depth.
dwLuminanceBitCount
Specifies the number of bits per pixel.
dwBumpBitCount
Specifies the number of bits per bumpel, total.
dwPrivateFormatBitCount
Specifies the bits per pixel of a pixel format private to the driver (that is, not one of the standard ones defined by Direct3D).
dwRBitMask
Specifies the mask for red bits.
dwYBitMask
Specifies the mask for Y bits.
dwStencilBitDepth
Specifies the bit depth of the stencil buffer. This member specifies how many bits are reserved within each pixel of the z-buffer for stencil information.
dwLuminanceBitMask
Specifies the mask for luminance bits.
dwBumpDuBitMask
Specifies the mask for bump map U delta bits.

dwOperations
Specifies the intended operations that can be performed on surfaces with this pixel format, for example, whether they can be used as textures, cube maps, volume textures, or render targets. The operations that can be reported are as shown in the following table.

Operation	Description
D3DFORMAT_OP_TEXTURE	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as MIP-mapped textures.
D3DFORMAT_OP_VOLUMETEXTURE	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as volume textures. Please note that this flag is independent of D3DFORMAT_OP_TEXTURE. Thus, it is possible to specify a pixel format that can only be used for volume textures and not for conventional, MIP-mapped textures.
D3DFORMAT_OP_CUBETEXTURE	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as cubic environment map textures. This flag is independent of D3DFORMAT_OP_TEXTURE. Thus, it is possible to specify a pixel format that can only be used for cubic environment map textures and not for conventional, MIP-mapped textures.
D3DFORMAT_OP_OFFSCREEN_RENDERTARGET	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as an offscreen render target regardless of the pixel format of the display mode, providing the pixel format of the current display mode was reported with the D3DFORMAT_OP_DISPLAYMODE and D3DFORMAT_OP_3DACCELERATION. If the pixel format of the current display mode did not have these flags set, it indicates no 3-D acceleration is available in this mode even if the render target is offscreen. This flag can be combined with D3DFORMAT_OP_TEXTURE to indicate that the device can render to textures of the specified pixel format.
D3DFORMAT_OP_SAME_FORMAT_RENDERTARGET	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as render targets but only when the pixel format of the surface matches the pixel format of the current display mode. This flag does not only apply to offscreen render target but can be specified on the pixel formats of display modes to indicate rendering target capability. This flag can be combined with D3DFORMAT_OP_TEXTURE to indicate that the device can render to textures of the specified pixel format.
D3DFORMAT_OP_ZSTENCIL	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as Z/Stencil buffers but only if the depth of the Z/Stencil surface matches the color depth of the rendering target to which the depth buffer is attached. When deciding on a match between Z/Stencil and color buffer depth, the pixel stride is used.
D3DFORMAT_OP_ZSTENCIL_WITH_ARBITRARY_COLOR_DEPTH	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as Z/Stencil buffers regardless of the color depth of the render target to which the surface is attached. When specifying this flag, you should specify D3DFORMAT_OP_ZSTENCIL as well.
D3DFORMAT_OP_SAME_FORMAT_UP_TO_ALPHA_RENDERTARGET	When this flag is specified in a pixel format, it indicates that surfaces of this format can be used as a render target if the current display mode is the same depth if the alpha channel is ignored; such as if the device can render to A8R8G8B8 when the display mode is X8R8G8B8, the format operation list entry for A8R8G8B8 should have this flag set.
D3DFORMAT_OP_DISPLAYMODE	When this flag is specified, it indicates that there is a display mode with this pixel format that has DirectDraw support (including Flip). This flag should not to be set on alpha formats.
D3DFORMAT_OP_3DACCELERATION	When this flag is specified, the graphics accelerator can support some level of Direct3D acceleration when in a display mode with this pixel format and also implies that the driver can create a context in this mode for some render target format. This flag must only be used when reporting display mode formats (by specifying the D3DFORMAT_OP_DISPLAYMODE). It is not required and indeed should not be set when reporting offscreen render targets formats.

dwGBitMask
Specifies the mask for green bits.
dwUBitMask
Specifies the mask for U bits.
dwZBitMask
Specifies the mask for Z bits.
dwBumpDvBitMask
Specifies the mask for bump map V delta bits.
wFlipMSTypes
Used when specifying surfaces that can be used when performing multisample rendering.
wBltMSTypes
Used when specifying surfaces that can be used when performing multisample rendering.
dwBBitMask
Specifies the mask for blue bits.
dwVBitMask
Specifies the mask for V bits.
dwStencilBitMask
Specifies the mask for stencil bits within each z-buffer pixel.
dwBumpLuminanceBitMask
Specifies the mask for luminance in a bump map.
dwRGBAlphaBitMask
Specify the masks for alpha channel.
dwYUVAlphaBitMask
Specify the masks for alpha channel.
dwLuminanceAlphaBitMask
Specifies the mask for luminance in the alpha channel.
dwRGBZBitMask
Specify the masks for the z channel.
dwYUVZBitMask
Specify the masks for the z channel.

Remarks

The run time now imposes some rules on the op list. The current rules are as follows:

Only one Endian-ness for any DS format is allowed, for example D15S1 or S1D15, not both independent of other bits.
A list should only include D3DFORMAT_OP_DISPLAYMODE for exactly one 16-bpp format. For example, it should not enumerate 5:5:5 and 5:6:5.
A list should not contain any alpha formats with D3DFORMAT_OP_DISPLAYMODE or D3DFORMAT_OP_3DACCELLERATION set.
Make sure no mode has D3DFORMAT_OP_3DACCELLERATION set that does not also have D3DFORMAT_OP_DISPLAYMODE set.

If the driver supports a lockable D16, it should report D3DFMT_D16_LOCKABLE in the op list; otherwise, it should report D3DFMT_D16.

Drivers supporting multisampling must fill MultiSampleCaps in the Depth/Stencil formats for which multisampling can be supported. This allows the run time to detect if a driver supports multisampling for combinations of render target and Z buffer formats. For additional information about the restrictions related to stretch blt multisampling, see the description of D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE cap in the rastercaps contained in the D3DCAPS8 structure in the SDK documentation.

The enumerated type D3DMULTISAMPLE_TYPE defined in D3d8types.h is used when setting the bits in wFlipMSTypes and wBltMSTypes. To specify support for a specific number of samples per pixel, simply logically shift 1 by the appropriate value from the D3DMULTISAMPLE_TYPE enumerated type less 1 or this into the appropriate field (wFlipMSTypes and wBltMSTypes).

For example, if the driver supports both two and four samples for pixel when flipping (fullscreen mode) and 4 samples per pixel when blitting (windowed mode) on the X8R8G8B8 surface, the following entry would be reported in the surface format list.

DDPIXELFORMAT ddpf;
 ZeroMemory(&ddpf, sizeof(ddpf));
 ddpf.dwSize       = sizeof(DDPIXELFORMAT);
 ddpf.dwFlags      = DDPF_D3DFORMAT;
 ddpf.dwFourCC     = D3DFMT_X8R8G8B8;
 ddpf.dwOperations = D3DFORMAT_OP_DISPLAYMODE |
                    D3DFORMAT_OP_3DACCELERATION;
 ddpf.MultiSampleCaps.wFlipMSTypes = (1 << (D3DMULTISAMPLE_4_SAMPLES – 1))
                                  | (1 << (D3DMULTISAMPLE_2_SAMPLES – 1));
 ddpf.MultiSampleCaps.wBltMSTypes = (1 << (D3DMULTISAMPLE_4_SAMPLES – 1));

It is not necessary to specify 1 << (D3DMULTISAMPLE_NONE - 1) when reporting formats. It is assumed that any format reported can also be used without multisampling. If the hardware supports multisample rendering with a z-buffer, the z-buffer formats reported should also include the supported samples per pixels.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ddraw.h.

Share via

DDPIXELFORMAT

Members

Remarks

Requirements

See Also

Additional resources