CImageDisplay Class

This 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

Name	Description
m_Display	VIDEOINFOHEADER structure corresponding to the current device display type.

Member Functions

Name	Description
CheckBitFields	Checks that the bit fields on a VIDEOINFOHEADER 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 VIDEOINFOHEADER 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 VIDEOINFOHEADER structure.
GetColourMask	Retrieves a set of individual color element masks.
GetDisplayDepth	Retrieves the bit depth of the current display mode.
GetDisplayFormat	Retrieves a VIDEOINFOHEADER 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 VIDEOINFOHEADER structure to remove implicit assumptions.

---

CImageDisplay::CheckBitFields

CImageDisplay Class

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

BOOL CheckBitFields(
  const VIDEOINFO *pInput
  );

Parameters

pInput

VIDEOINFOHEADER structure to check.

Return Values

Returns one of the following values.

Value	Meaning
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.

BOOL CheckHeaderValidity(
  const VIDEOINFO *pInput
  );

Parameters

pInput

VIDEOINFOHEADER structure that contains the bitmap details.

Return Values

Returns one of the following values.

Value	Meaning
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.

HRESULT CheckMediaType(
  const CMediaType *pmtIn
  );

Parameters

pmtIn

Media type to check.

Return Values

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 VIDEOINFOHEADER structure.

---

CImageDisplay::CheckPaletteHeader

CImageDisplay Class

Determines if the palette on a VIDEOINFOHEADER structure is correct.

BOOL CheckPaletteHeader(
  const VIDEOINFO *pInput
  );

Parameters

pInput

VIDEOINFOHEADER structure to validate.

Return Values

Returns one of the following values.

Value	Meaning
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.

HRESULT CheckVideoType(
  const VIDEOINFO *pInput
  );

Parameters

pInput

VIDEOINFOHEADER structure to validate.

Return Values

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 VIDEOINFOHEADER 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.

CImageDisplay( );

Return Values

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 VIDEOINFOHEADER 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

Helper member function to count the number of prefix bits.

DWORD CountPrefixBits(
  const DWORD Field
  );

Parameters

Field

Input bitmask field.

Return Values

No return value.

Remarks

Given a bitmask, this 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 number of bit sets in the Field parameter.

DWORD CountSetBits(
  const DWORD Field
  );

Parameters

Field

Field in which to count bit sets.

Return Values

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 VIDEOINFOHEADER structure.

const DWORD *GetBitMasks(
  const VIDEOINFO *pVideoInfo
  );

Parameters

pVideoInfo

Input VIDEOINFOHEADER structure format.

Return Values

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.

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

Parameters

pMaskRed

Holds red mask.

pMaskGreen

Holds green mask.

pMaskBlue

Holds blue mask.

Return Values

Returns one of the following values.

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

Remarks

Given a video format described by a VIDEOINFOHEADER 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.

WORD GetDisplayDepth( );

Return Values

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

---

CImageDisplay::GetDisplayFormat

CImageDisplay Class

Retrieves a VIDEOINFOHEADER structure representing the current display mode.

const VIDEOINFO *GetDisplayFormat( );

Return Values

Returns a VIDEOINFOHEADER structure representing the display format.

---

CImageDisplay::IsPalettized

CImageDisplay Class

Determines if the display uses a palette.

BOOL IsPalettized( );

Return Values

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

---

CImageDisplay::RefreshDisplayType

CImageDisplay Class

Updates the CImageDisplay object with the current display type.

HRESULT RefreshDisplayType(
  LPSTR szDeviceName
  );

Parameters

szDeviceName

LPSTR value that contains the name of the device to update. If omitted, this parameter defaults to the main device.

Return Values

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 VIDEOINFOHEADER structure to remove implicit assumptions.

HRESULT UpdateFormat(
  VIDEOINFO *pVideoInfo
  );

Parameters

pVideoInfo

VIDEOINFOHEADER structure to update.

Return Values

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page