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

Name	Description
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

Name	Description
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.

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

Parameters

pBaseFilter

Filter that this class is owned by.

pBaseWindow

Window to realize palette in.

pDrawImage

Object that draws using this palette.

Return Values

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.

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

Parameters

pSrc

Source media type.

pDest

Destination media type.

Return Values

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.

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

Parameters

pEntry

Array of prospective palette colors.

iColours

Number of colors in the array.

szDevice

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

Return Values

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.

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

Parameters

pVideoInfo

Container for the palette colors required.

szDevice

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

Return Values

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

---

CImagePalette::PreparePalette

CImagePalette Class

Specifies an entry point for creating and installing palettes.

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

Parameters

pmtNew

Media type holding new palette information.

pmtOld

Media type holding old palette information.

szDevice

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

Return Values

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.

HRESULT RemovePalette( );

Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

---

CImagePalette::ShouldUpdate

CImagePalette Class

Help member function that checks if two sets of colors match.

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

Parameters

pNewInfo

VIDEOINFOHEADER structure containing the new set of colors.

pOldInfo

VIDEOINFOHEADER structure containing the old set of colors.

Return Values

Returns one of the following values.

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

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

Top of Page