CImagePalette Class

The CImagePalette class is a specialized class for image renderers that must create and manage palettes. It can be used to create palette handles from a media format containing a VIDEOINFO structure in the format block. To maximize performance, the class attempts to create a palette that is an identity palette (that is, one that exactly matches the current system palette), and compares palettes before updating to ensure that palettes are changed only when actually required.

Protected Data Members

m_hPalette Palette handle owned by this object.
m_pBaseWindow Window in which to realize the palette.
m_pDrawImage Object that will perform the drawing.
m_pMediaFilter Media filter to send events to.

Member Functions

CImagePalette Constructs a CImagePalette object.
CopyPalette Copies the palette out of any YUV or true-color VIDEOINFOHEADER structure into a palettized VIDEOINFOHEADER structure.
MakeIdentityPalette Ensures the palette entries will become an identity palette.
MakePalette Retrieves the color palette from the specified video image.
PreparePalette Specifies an entry point for updating and creating palettes.
RemovePalette Releases any palette resources allocated.
ShouldUpdate Specifies an internal helper member function for updating palettes dynamically.

CImagePalette::CImagePalette

CImagePalette Class

Constructs a CImagePalette object.

Syntax

CImagePalette(
    CBaseFilter *pBaseFilter,
    CBaseWindow *pBaseWindow,
    CDrawImage *pDrawImage
);

Parameters

pBaseFilter
Pointer to the filter that owns this class.
pBaseWindow
Pointer to the window to realize palette in.
pDrawImage
Pointer to the object that draws using this palette.

Return Value

No return value.

Remarks

This class looks after the creation, management, and deletion of a window palette. It is passed in a number of other objects that might be interested in palettes. The class is optimized so that requested palette changes will be acted on only if the new set of colors differs from the current set. This is a performance optimization, because changing palettes is an expensive process.
This constructor is passed in the owning filter (pBaseFilter), which must be a valid pointer. When the class actually creates a palette, it tells the owning filter to send an EC_PALETTE_CHANGED message to the filter graph manager. The constructor might also be passed two further object pointers. If pBaseWindow is not null, when the renderer creates a new palette the class automatically installs it in this window. When told to remove a palette, the class also removes the palette from the base window and installs a standard VGA palette instead.
The constructor can also be passed a drawing object derived from the CDrawImage class. If this is non-NULL, when creating a new palette the class will inform the drawing object that the palette has changed (this is usually used in conjunction with a window object). This ensures that the drawing object is notified when the palette changes so that it can update any samples it has that were created using CreateDIBSection (because they might need their internal color tables updated).

CImagePalette::CopyPalette

CImagePalette Class

Copies the palette out of any YUV or true-color VIDEOINFOHEADER structure into a palettized VIDEOINFOHEADER structure.

Syntax

HRESULT CopyPalette(
    const CMediaType *pSrc,
    const CMediaType *pDest
);

Parameters

pSrc
Pointer to the source media type.
pDest
Pointer to the destination media type.

Return Value

Returns NOERROR if successful or S_FALSE if no palette is available.

Remarks

This member function is used when changing palettes on DirectDraw® samples. A filter acting as a source to the renderer can attach a palette to any buffer and pass it to the renderer as a new VIDEOINFOHEADER format. The renderer can then call CopyPalette to make a new palette from that format, and copy the palette colors into the new connection type.

CImagePalette::MakeIdentityPalette

CImagePalette Class

Modifies the PALETTEENTRY structure to create an identity palette.

Syntax

HRESULT MakeIdentityPalette(
    PALETTEENTRY *pEntry,
    INT iColours,
    LPSTR szDevice
);

Parameters

pEntry
Pointer to an array of prospective palette colors.
iColours
Number of colors in the array.
szDevice
Pointer to an LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.

Return Value

Returns NOERROR if successful or S_FALSE if unsuccessful.

Remarks

When a palette is installed in a window, GDI does a fair job of compressing the requested colors where possible. So, for example, if the array contains five entries of black, they will be compressed into one palette entry. This is useful for most applications; however, when drawing video it will force GDI to map the pixels in the supplied image to the compressed palette (which results in serious performance penalties).
Therefore, the PALETTEENTRY fields supplied must be adjusted so that they will never have colors compressed. This means that when the window displaying the image has the foreground focus, the palette created by this object will map directly to the palette selected in the display device: a so-called identity palette.

CImagePalette::MakePalette

CImagePalette Class

Retrieves the color palette from the specified video image.

Syntax

HPALETTE MakePalette(
    const VIDEOINFOHEADER *pVideoInfo,
    LPSTR szDevice
);

Parameters

pVideoInfo
Pointer to the container for the palette colors required.
szDevice
Pointer to an LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.

Return Value

Returns a handle to the new palette (NULL if it fails).

CImagePalette::PreparePalette

CImagePalette Class

Specifies an entry point for creating and installing palettes.

Syntax

HRESULT PreparePalette(
    const CMediaType *pmtNew,
    const CMediaType *pmtOld,
    LPSTR szDevice
);

Parameters

pmtNew
Pointer to the media type holding new palette information.
pmtOld
Pointer to the media type holding old palette information.
szDevice
Pointer to an LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.

Return Value

Returns an HRESULT value.

Remarks

This is the main entry point for creating new palettes. It tries to detect situations where the palette colors requested have not changed (in which case it does not need to create a new palette). It uses the old media type to determine if the colors have changed. It also handles optionally installing the palette in a window (if supplied) and notifying the filter graph manager of a change in palettes (it uses the filter passed in to the constructor for this). Finally, it handles notifying the draw object of palette changes (also optional, depending on whether a draw object was passed in to the constructor).

CImagePalette::RemovePalette

CImagePalette Class

Removes and deletes any palette previously created.

Syntax

HRESULT RemovePalette(void);

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

CImagePalette::ShouldUpdate

CImagePalette Class

Determines whether it is necessary to create a new palette.

Syntax

BOOL ShouldUpdate(
    const VIDEOINFOHEADER *pNewInfo,
    const VIDEOINFOHEADER *pOldInfo
);

Parameters

pNewInfo
Pointer to a VIDEOINFOHEADER structure containing the new set of colors.
pOldInfo
Pointer to a VIDEOINFOHEADER structure containing the old set of colors.

Return Value

Returns one of the following values.

TRUE A new palette is required.

FALSE The existing palette suffices.

Remarks

Use this function to test whether it is necessary to create a new palette. If the original type does not use a palette and the new one does (or vice versa), this method returns TRUE. If neither formats use a palette, this method returns FALSE. If both formats use a palette, the colors are compared, and if they match, the method returns FALSE.

m_hPalette	Palette handle owned by this object.
m_pBaseWindow	Window in which to realize the palette.
m_pDrawImage	Object that will perform the drawing.
m_pMediaFilter	Media filter to send events to.

CImagePalette	Constructs a CImagePalette object.
CopyPalette	Copies the palette out of any YUV or true-color VIDEOINFOHEADER structure into a palettized VIDEOINFOHEADER structure.
MakeIdentityPalette	Ensures the palette entries will become an identity palette.
MakePalette	Retrieves the color palette from the specified video image.
PreparePalette	Specifies an entry point for updating and creating palettes.
RemovePalette	Releases any palette resources allocated.
ShouldUpdate	Specifies an internal helper member function for updating palettes dynamically.

TRUE	A new palette is required.
FALSE	The existing palette suffices.