DDPIXELFORMAT structure (ksmedia.h)
The DDPIXELFORMAT structure describes the pixel format of a DirectDrawSurface object.
Syntax
typedef struct _DDPIXELFORMAT {
DWORD dwSize;
DWORD dwFlags;
DWORD dwFourCC;
union {
DWORD dwRGBBitCount;
DWORD dwYUVBitCount;
DWORD dwZBufferBitDepth;
DWORD dwAlphaBitDepth;
};
union {
DWORD dwRBitMask;
DWORD dwYBitMask;
};
union {
DWORD dwGBitMask;
DWORD dwUBitMask;
};
union {
DWORD dwBBitMask;
DWORD dwVBitMask;
};
union {
DWORD dwRGBAlphaBitMask;
DWORD dwYUVAlphaBitMask;
DWORD dwRGBZBitMask;
DWORD dwYUVZBitMask;
};
} DDPIXELFORMAT, *LPDDPIXELFORMAT;
Members
dwSize
Specifies the size in bytes of the DDPIXELFORMAT structure. The driver must initialize this member before the structure is used.
DirectX 9.0 and later versions only. Specifies, on input, the version of the Microsoft DirectX runtime being used by the application. This member is set to DD_RUNTIME_VERSION, which is 0x00000900 for DirectX 9.0, in the format member of the DD_GETFORMATDATA structure for a D3DGDI2_TYPE_GETFORMAT query.
dwFlags
Indicates a set of flags that specify optional control flags. This member is a bitwise OR of any of the following values:
| Flag | Meaning |
|---|---|
| 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 | Bump map dUdV data in the pixel format is valid. |
| DDPF_BUMPHEIGHT | 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_D3DFORMAT | Indicates a DirectX 8.0 and later format capability entry in the texture format list. This flag is not exposed to applications. |
| 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, bumpmap surfaces. The bitmask for the luminance portion of the pixel is then specified in the dwBumpLuminanceBitMask member. |
| DDPF_NOVEL_TEXTURE_FORMAT | Indicates a new surface format that the runtime might not expose to all applications. |
| 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_STENCILBUFFER | 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 a surface format code including any of the codes in the D3DFORMAT enumerated type. Some FOURCC codes are part of D3DFORMAT. For more information about D3DFORMAT, see the SDK documentation. Hardware vendors can also define and supply format codes that are specific to their hardware.
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.
dwRBitMask
Specifies the mask for red bits.
dwYBitMask
Specifies the mask for Y bits.
dwGBitMask
Specifies the mask for green bits.
dwUBitMask
Specifies the mask for U bits.
dwBBitMask
Specifies the mask for blue bits.
dwVBitMask
Specifies the mask for V bits.
dwRGBAlphaBitMask
Mask for alpha channel.
dwYUVAlphaBitMask
Mask for alpha channel.
dwRGBZBitMask
Mask for Z channel.
dwYUVZBitMask
Mask for Z channel.
Remarks
The DirectX 8.0 and later runtime imposes the following rules on the operation (op) list:
Only one Endian-ness (big or little) 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 16bpp 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.
The D3DFORMAT_OP_3DACCELLERATION flag can only be set when the D3DFORMAT_OP_DISPLAYMODE flag is also 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 in the MultiSampleCaps in the Depth/Stencil formats for which multisampling can be supported. This allows the runtime 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 and OR this into the appropriate field (wFlipMSTypes and wBltMSTypes).
For example, if the driver supports both two and four samples per pixel when flipping (fullscreen mode) and four samples per pixel when blitting (windowed mode) on 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
| Requirement | Value |
|---|---|
| Header | ksmedia.h (include Ddraw.h) |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for