IOverlay::SetColorKey method (strmif.h)

Article
02/22/2024

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The SetColorKey method changes the color key.

Syntax

HRESULT SetColorKey(
  [in, out] COLORKEY *pColorKey
);

Parameters

[in, out] pColorKey

Pointer to the color key value to be set. If successful, the actual color key value selected is copied to this parameter.

Return value

Returns S_OK if successful, E_POINTER if pColorKey is NULL, or E_INVALIDARG if the value of pColorKey is invalid for the current palette or pixel format.

Remarks

If you change the color key using the SetColorKey method, all the advise links will receive an IOverlayNotify::OnColorKeyChange callback method with the new color.

When using IOverlay::Advise on a palettized display, a filter can either install a color key (using SetColorKey) or install a palette (using IOverlay::SetPalette), but not both. This is because color keys in this mode require a palette to be realized that would conflict with SetPalette. Color keys can be uninstalled by requesting a color key with the CK_NOCOLORKEY flag. Likewise, any palette installed through SetPalette can be uninstalled by calling SetPalette and passing in NULL parameters (that is, SetPalette(0,NULL)).

Trying to set a palette when a color key is installed returns a VFW_E_PALETTE_SET error. Trying to set a color key when a palette is installed returns VFW_E_COLOR_KEY_SET.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib