CImageDisplay Class

CImageDisplay class hierarchy

The CImageDisplay class initializes itself with a display format so that other objects can query or reset the display type. It also provides member functions to check display formats and accept only those video formats that can be efficiently rendered by using GDI calls.

Protected Data Members

m_Display VIDEOINFO structure corresponding to the current device display type.

Member Functions

CheckBitFields Checks that the bit fields on a VIDEOINFO structure are correct.
CheckHeaderValidity Determines if a BITMAPINFOHEADER structure is valid.
CheckMediaType Determines if the filter can support the media type proposed by the output pin.
CheckPaletteHeader Determines if the palette on a VIDEOINFO structure is correct.
CheckVideoType Compares a video type to determine if it is compatible with the current display mode.
CImageDisplay Constructs a CImageDisplay object.
CountPrefixBits Counts the number of prefix bits.
CountSetBits Counts the total number of bits set in a field.
GetBitMasks Retrieves a set of color element bitmasks for the supplied VIDEOINFO structure.
GetColourMask Retrieves a set of individual color element masks.
GetDisplayDepth Retrieves the bit depth of the current display mode.
GetDisplayFormat Retrieves a VIDEOINFO structure representing the current display mode.
IsPalettized Determines if the display uses a palette.
RefreshDisplayType Updates the CImageDisplay object with the current display type.
UpdateFormat Updates the VIDEOINFO structure to remove implicit assumptions.

CImageDisplay::CheckBitFields

CImageDisplay Class

Checks that the bit fields in the VIDEOINFO structure are correct.

Syntax

BOOL CheckBitFields(
    const VIDEOINFO *pInput
    );

Parameters

pInput
Pointer to the VIDEOINFO structure to check.

Return Value

Returns one of the following values.

TRUE Bit fields are correct.
FALSE Bit fields contain an error.

Remarks

The assumption throughout the object is that any bitmasks are allowed no more than 8 bits to store a color component. This member function checks that the bit count assumption is enforced, and also ensures that all the bits set are contiguous.
This is a protected member function.

CImageDisplay::CheckHeaderValidity

CImageDisplay Class

Determines if a BITMAPINFOHEADER structure is valid.

Syntax

BOOL CheckHeaderValidity(
    const VIDEOINFO *pInput
    );

Parameters

pInput
Pointer to the VIDEOINFO structure that contains the bitmap details.

Return Value

Returns one of the following values.

TRUE Format is valid.
FALSE Format contains an error.

Remarks

The BITMAPINFOHEADER structure might be rejected for a number of reasons. These might include a number-of-planes entry greater or less than one, the size of the structure not being equal to the size of BITMAPINFOHEADER, or, perhaps, being asked to validate a YUV format (this member function only validates RGB formats; it will always return FALSE for YUV types).

CImageDisplay::CheckMediaType

CImageDisplay Class

Determines if the filter can support the media type proposed by the output pin.

Syntax

HRESULT CheckMediaType(
    const CMediaType *pmtIn
    );

Parameters

pmtIn
Pointer to the media type to check.

Return Value

Returns an HRESULT value.

Remarks

This helper member function can be used to validate a video media type. It examines the major and minor type GUIDs and verifies that the format GUID defines a VIDEOINFO structure.

CImageDisplay::CheckPaletteHeader

CImageDisplay Class

Determines if the palette on a VIDEOINFO structure is correct.

Syntax

BOOL CheckPaletteHeader(
    const VIDEOINFO *pInput
    );

Parameters

pInput
Pointer to the VIDEOINFO structure to validate.

Return Value

Returns one of the following values.

TRUE Palette is correct.
FALSE No valid palette.

Remarks

This member function returns FALSE if the format specifies that no palette is available (it might be a true-color format). It also returns FALSE if the number of palette colors used (or those that are important) exceeds the number specified for the video format.

CImageDisplay::CheckVideoType

CImageDisplay Class

Compares a video type to determine if it is compatible with the current display mode.

Syntax

HRESULT CheckVideoType(
    const VIDEOINFO *pInput
    );

Parameters

pInput
Pointer to the VIDEOINFO structure to validate.

Return Value

Returns NOERROR if successful or E_INVALIDARG if unsuccessful.

Remarks

Many video rendering filters want a function to determine if proposed formats are okay. This member function checks the VIDEOINFO structure passed as a media type and returns NOERROR if the media type is valid; otherwise, it returns E_INVALIDARG434. Note, however, that only formats that can be easily displayed on the current display device are accepted; so, for example, a 16-bit device will not accept 24-bit images. Because most displays draw 8-bit palettized images efficiently, this format is always accepted unless the display is 16-color VGA.

CImageDisplay::CImageDisplay

CImageDisplay Class

Constructs a CImageDisplay object.

Syntax

CImageDisplay(void);

Return Value

No return value.

Remarks

The CImageDisplay class helps renderers that want to determine the format of the current display mode. This member function retrieves the display mode and creates a VIDEOINFO structure that represents its format. The class supplies that format for clients through member functions such as IsPalettized and GetDisplayFormat. If a client detects the display format has changed (perhaps it receives a WM_DISPLAYCHANGED message), it should call RefreshDisplayType.

CImageDisplay::CountPrefixBits

CImageDisplay Class

Counts the number of prefix bits.

Syntax

DWORD CountPrefixBits(
    const DWORD Field
    );

Parameters

Field
Input bitmask field.

Return Value

No return value.

Remarks

Given a bitmask, this helper member function counts the number of zero bits up to the least significant set bit. So, for a binary number 00000100, the member function returns 2 (decimal). The member function does, however, work on DWORD values, so it counts from the least significant bit up through the DWORD to the last bit (0x80000000). If no bits are found, this will return the (impossible) value 32 (decimal).
This is a protected member function.

CImageDisplay::CountSetBits

CImageDisplay Class

Counts the total number of bits set in a field.

Syntax

DWORD CountSetBits(
    const DWORD Field
    );

Parameters

Field
Field in which to count bit sets.

Return Value

Returns the number of bit sets.

Remarks

This is a protected member function.

CImageDisplay::GetBitMasks

CImageDisplay Class

Retrieves a set of color element bitmasks for the supplied VIDEOINFO structure.

Syntax

const DWORD *GetBitMasks(
    const VIDEOINFO *pVideoInfo
    );

Parameters

pVideoInfo
Pointer to the input VIDEOINFO structure format.

Return Value

No return value.

Remarks

This member function should be called only with RGB formats. If the RGB format has a bit depth of 16/32 bits per pixel, it will return the bitmasks for the individual red, green, and blue color elements (for example, RGB565 is 0xF800, 0x07E0, and 0x001F). For RGB24, this will return 0xFF0000, 0xFF00, and 0xFF. For palettized formats, this will return all zeros.

CImageDisplay::GetColourMask

CImageDisplay Class

Retrieves a set of individual color element masks.

Syntax

BOOL GetColourMask(
    DWORD *pMaskRed,
    DWORD *pMaskGreen,
    DWORD *pMaskBlue
    );

Parameters

pMaskRed
Pointer to the red mask.
pMaskGreen
Pointer to the green mask.
pMaskBlue
Pointer to the blue mask.

Return Value

Returns one of the following values.

TRUE Masks were filled out correctly.
FALSE No masks were available for the display.

Remarks

Given a video format described by a VIDEOINFO structure, this member function returns the mask that is used to obtain the range of acceptable colors for this type (for example, the mask for a 24-bit true color format is 0xFF in all cases). A 16-bit 5:6:5 display format uses 0xF8, 0xFC, and 0xF8. Therefore, given any RGB triplets, this member function can find one that is compatible with the display format by using a bitwise-AND operation.

CImageDisplay::GetDisplayDepth

CImageDisplay Class

Retrieves the bit depth of the current display mode.

Syntax

WORD GetDisplayDepth(void);

Return Value

Returns the number of bits per pixel used on the display.

CImageDisplay::GetDisplayFormat

CImageDisplay Class

Retrieves a VIDEOINFO structure representing the current display mode.

Syntax

const VIDEOINFO *GetDisplayFormat(void);

Return Value

Returns a VIDEOINFO structure representing the display format.

CImageDisplay::IsPalettized

CImageDisplay Class

Determines if the display uses a palette.

Syntax

BOOL IsPalettized(void);

Return Value

Returns TRUE if the display uses a palette; otherwise, returns FALSE.

CImageDisplay::RefreshDisplayType

CImageDisplay Class

Updates the CImageDisplay object with the current display type.

Syntax

HRESULT RefreshDisplayType(
    LPSTR szDeviceName
    );

Parameters

szDeviceName
Name of the device to update. If omitted, this parameter defaults to the main device.

Return Value

Returns NOERROR if successful; E_FAIL if unsuccessful.

Remarks

This member function should be called when a WM_DISPLAYCHANGED message is received.

CImageDisplay::UpdateFormat

CImageDisplay Class

Updates the VIDEOINFO structure to remove implicit assumptions.

Syntax

HRESULT UpdateFormat(
    VIDEOINFO *pVideoInfo
    );

Parameters

pVideoInfo
Pointer to the VIDEOINFO structure to update.

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

This member function is probably suitable only for specific filters to use. The BITMAPINFO structure has certain fields that are not well specified. In particular, the number of colors specified for a palette can be zero, in which case it is defined to be the maximum for that format type. This member function updates these fields so that their contents are explicit.

CheckBitFields	Checks that the bit fields on a VIDEOINFO structure are correct.
CheckHeaderValidity	Determines if a BITMAPINFOHEADER structure is valid.
CheckMediaType	Determines if the filter can support the media type proposed by the output pin.
CheckPaletteHeader	Determines if the palette on a VIDEOINFO structure is correct.
CheckVideoType	Compares a video type to determine if it is compatible with the current display mode.
CImageDisplay	Constructs a CImageDisplay object.
CountPrefixBits	Counts the number of prefix bits.
CountSetBits	Counts the total number of bits set in a field.
GetBitMasks	Retrieves a set of color element bitmasks for the supplied VIDEOINFO structure.
GetColourMask	Retrieves a set of individual color element masks.
GetDisplayDepth	Retrieves the bit depth of the current display mode.
GetDisplayFormat	Retrieves a VIDEOINFO structure representing the current display mode.
IsPalettized	Determines if the display uses a palette.
RefreshDisplayType	Updates the CImageDisplay object with the current display type.
UpdateFormat	Updates the VIDEOINFO structure to remove implicit assumptions.

TRUE	Bit fields are correct.
FALSE	Bit fields contain an error.

TRUE	Masks were filled out correctly.
FALSE	No masks were available for the display.