IMixerPinConfig Interface

The IMixerPinConfig interface is exposed on the input pins of overlay mixer filters and contains methods that manipulate video streams in various ways. The overlay mixer filter contains multiple input pins that are dynamically created as video input streams are added. The video stream on the first pin is known as the primary stream and subsequent streams are known as secondary streams.

Use this interface to manipulate the parameters involved in mixing various video streams. These parameters include getting and setting position, z-order, blending and transparency levels, aspect ratio correction, and color keys of streams.

When setting the position of video streams in the display window, the default relative position of all secondary streams is {0, 0, 0, 0}. Therefore, use the SetRelativePosition method on secondary streams to ensure that all video streams are placed properly.

Microsoft® DirectShow® implements this interface on the input pins of overlay mixer filters. Developers should implement this interface when they create filters that mix video streams.

Applications use this interface to get and set attributes when mixing multiple video streams.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IMixerPinConfig methods Description

SetRelativePosition Sets the position of the stream in the display window.
GetRelativePosition Retrieves the position of the stream in the display window.
SetZOrder Sets the z-order of a particular video stream.
GetZOrder Retrieves the z-order of a particular video stream.
SetColorKey Sets the color key being used by a video stream.
GetColorKey Retrieves the color key being used by a video stream.
SetBlendingParameter Sets the blending parameter that defines how a secondary stream is blended with a primary stream.
GetBlendingParameter Retrieves the value of the blending parameter that defines how a secondary stream is blended with a primary stream.
SetAspectRatioMode Sets the aspect ratio correction mode for window resizing.
GetAspectRatioMode Retrieves the aspect ratio correction mode for window resizing.
SetStreamTransparent Sets the stream to transparent.
SetStreamTransparent Determines whether a stream is transparent.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IMixerPinConfig methods	Description
SetRelativePosition	Sets the position of the stream in the display window.
GetRelativePosition	Retrieves the position of the stream in the display window.
SetZOrder	Sets the z-order of a particular video stream.
GetZOrder	Retrieves the z-order of a particular video stream.
SetColorKey	Sets the color key being used by a video stream.
GetColorKey	Retrieves the color key being used by a video stream.
SetBlendingParameter	Sets the blending parameter that defines how a secondary stream is blended with a primary stream.
GetBlendingParameter	Retrieves the value of the blending parameter that defines how a secondary stream is blended with a primary stream.
SetAspectRatioMode	Sets the aspect ratio correction mode for window resizing.
GetAspectRatioMode	Retrieves the aspect ratio correction mode for window resizing.
SetStreamTransparent	Sets the stream to transparent.
SetStreamTransparent	Determines whether a stream is transparent.

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig Interface

Retrieves the aspect ratio correction mode for window resizing.

Syntax

HRESULT GetAspectRatioMode(
    AM_ASPECT_RATIO_MODE *pamAspectRatioMode
    ) PURE;

Parameters

pamAspectRatioMode
[out] Pointer to an AM_ASPECT_RATIO_MODE enumerated type member.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_NOTIMPL Method called on secondary stream.
E_INVALIDARG Value invalid or NULL.
NOERROR No error.

See Also

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig Interface

Retrieves the value of the blending parameter that defines how a secondary stream is blended with a primary stream.

Syntax

HRESULT GetBlendingParameter(
    DWORD *pdwBlendingParameter
    ) PURE;

Parameters

pdwBlendingParameter
[out] Pointer to a value between 0 and 255 that indicates the amount of blending between a primary stream and a secondary stream.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_UNEXPECTED Method called on primary stream.
E_INVALIDARG Value outside of possible range (0-255).
NOERROR No error.

Remarks

A value of zero indicates that the secondary stream is invisible; a value of 255 indicates the primary stream is invisible in the area that the secondary stream occupies.

See Also

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig::GetColorKey

IMixerPinConfig Interface

Retrieves the color key being used by a video stream.

Syntax

HRESULT GetColorKey(
    COLORKEY *pColorKey,
    DWORD *pColor ) PURE;

Parameters

pColorKey
[out] Pointer to a COLORKEY structure that contains the key type and a palette index.
pColor
[out] Pointer to a value indicating the 8-bit palette index of the COLORKEY returned if the current display mode is 8-bit palettized. Otherwise it is a value representing the color key in the pixel format of the current display mode.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_INVALIDARG Invalid arguments, both parameters are NULL.
E_FAIL GetColorKey failed because the color key isn't known.
NOERROR No error.

Remarks

Getting the value on the primary stream will retrieve the destination color key being used by the overlay surface. Getting this value on the secondary pin returns the color key being used by that particular stream.
Current DirectShow implementation of this interface can return NULL for either the pColorKey or the pColor parameters; however, the method will fail and return E_INVALIDARG if both parameters are NULL.
Note The DWORD value returned by the pColor parameter is the actual color being used. So, if the bit depth of the display is 8, 16, 24, 32 the last 8, 16, 24 or 32 bits of the DWORD specify the actual value of the color key.

See Also

IMixerPinConfig::SetColorKey

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig Interface

Determines whether a stream is transparent.

Syntax

HRESULT GetStreamTransparent(
    BOOL *pbStreamTransparent
    ) PURE;

Parameters

pbStreamTransparent
[out] Pointer to a value indicating whether the stream is transparent. TRUE indicates transparent stream; FALSE indicates not a transparent stream.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_NOTIMPL Method is not supported.
NOERROR No error.

See Also

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig::GetRelativePosition

IMixerPinConfig Interface

Retrieves the position of the stream in the display window.

Syntax

HRESULT GetRelativePosition(
    DWORD *pdwLeft,
    DWORD *pdwTop,
    DWORD *pdwRight,
    DWORD *pdwBottom ) PURE;

Parameters

pdwLeft
[out] Pointer to a value indicating the x-coordinate in the top-left corner of the display window.
pdwTop
[out] Pointer to a value indicating the y-coordinate in the top-left corner of the display window.
pdwRight
[out] Pointer to a value indicating the x-coordinate in the bottom-right corner of the display window.
pdwBottom
[out] Pointer to a value indicating the y-coordinate in the bottom-right corner of the display window.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_INVALIDARG Coordinates not in the {0, 0, 10,000, 10,000} range.
NOERROR No error.

Remarks

This method assumes window coordinates of {0, 0, 10,000, 10,000}. If the video stream is being rendered in the bottom right quarter of the display window, this method would return {5,000, 5,000, 10,000, 10,000}.

See Also

IMixerPinConfig::SetRelativePosition

IMixerPinConfig::GetZOrder

IMixerPinConfig Interface

Retrieves the z-order of a particular video stream.

This method is not currently implemented and returns E_NOTIMPL.

Syntax

HRESULT GetZOrder(
    DWORD *pdwZOrder
    ) PURE;

Parameters

pdwZOrder
[out] Pointer to a value indicating the order in which streams will clip each other.

Return Value

Returns E_NOTIMPL.

Remarks

Images with larger z-values are always in front of images with smaller z-values.

See Also

IMixerPinConfig::SetZOrder

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig Interface

Sets the aspect ratio correction mode for window resizing.

Syntax

HRESULT SetAspectRatioMode(
    AM_ASPECT_RATIO_MODE amAspectRatioMode
    ) PURE;

Parameters

amAspectRatioMode
[in] Value specifying one of the AM_ASPECT_RATIO_MODE enumerated type members.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_NOTIMPL Method called on secondary stream.
E_INVALIDARG Invalid argument.
NOERROR No error.

Remarks

Currently this function is implemented only on the primary pin of the Overlay Mixer filter. Calling it on a secondary pin will result in an error.

See Also

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig Interface

Sets the blending parameter that defines how a secondary stream is blended with a primary stream.

Syntax

HRESULT SetBlendingParameter(
    DWORD dwBlendingParameter
    ) PURE;

Parameters

dwBlendingParameter
[in] Value between 0 and 255 that indicates the amount of blending between a primary stream and a secondary stream.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_UNEXPECTED Method called on primary stream.
E_INVALIDARG Value outside of possible range (0 to 255).
NOERROR No error.

Remarks

The value of the dwBlendingParameter parameter must be between 0 and 255, where 0 makes the secondary stream invisible and 255 makes the primary stream invisible in the area that the secondary stream occupies. If no value is set the default is 255.
This method is not intended to be called on the primary stream.
Note Current DirectShow implementation of this interface allows only values of 0 or 255 for the dwBlendingParameter parameter. Any other values are invalid.

See Also

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig::SetColorKey

IMixerPinConfig Interface

Sets the color key being used by a video stream.

Syntax

HRESULT SetColorKey(
    COLORKEY *pColorKey
) PURE;

Parameters

pColorKey
[in] Pointer to a COLORKEY structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The term color key has different meanings depending on which stream it is referring to. The color key of the primary stream refers to the destination color key being used by the overlay surface. The color key of the secondary stream refers to the source color key used, when blitting from an offscreen surface to the primary surface.
Applications should set the color key of the primary pin to an obscure color (some color which, in all probability, will not be present on the desktop). Overlay mixer filters will try to pick an obscure color, but if the application knows that the specified color is part of some other content, then the application should change it.
Setting the color key on the secondary stream can be used to make the stream transparent and enable nonrectangular images. For example, if the secondary stream is closed-captioned text, then the closed-captioned text decoder should paint a solid color in the background and then set the color key on the corresponding pin to that color. This ensures that all pixels are transferred except those specified by the color key. If possible, applications should set the color key of the secondary stream to the same as that of the primary stream to give a slight performance advantage.
Setting this value on the primary stream sets the destination color key being used by the overlay surface. By default, the destination color key is used as the color key for all transparent (secondary) streams.
Valid arguments for the pColorKey parameter include CK_INDEX when video display mode is set to 256 colors, and CK_RGB when video display mode is set to a higher color depth such as hi-color, 24-bit, or 32-bit. The CK_RGB flag must be specified along with the CK_INDEX. If CK_INDEX flag is set then the index will be used as palette index in 256 color mode. But you must provide a COLORREF with a valid true color so that if the display mode is changed on the fly, DirectShow can switch to using the specified true color. This is because a number of true colors can be mapped to a single palette index, but going the other way from the palette index to a true color is not one-to-one.
Note Currently, this method is implemented only for the primary input pin.

See Also

IMixerPinConfig::GetColorKey

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig Interface

Sets the stream to transparent.

Syntax

HRESULT SetStreamTransparent(
    BOOL bStreamTransparent
    ) PURE;

Parameters

bStreamTransparent
[in] Value specifying the transparency of the stream. Pass in TRUE to indicate stream is transparent; FALSE to indicate not a transparent stream.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_NOTIMPL Method is not supported.
NOERROR No error.

See Also

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig::SetRelativePosition

IMixerPinConfig Interface

Sets the position of the stream in the display window.

Syntax

HRESULT SetRelativePosition(
    DWORD dwLeft,
    DWORD dwTop,
    DWORD dwRight,
    DWORD dwBottom ) PURE;

Parameters

dwLeft
[in] Value specifying the x-coordinate in the upper-left corner of the display window.
dwTop
[in] Value specifying the y-coordinate in the upper-left corner of the display window.
dwRight
[in] Value specifying the x-coordinate in the bottom-right corner of the display window.
dwBottom
[in] Value specifying the y-coordinate in the bottom-right corner of the display window.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:

E_INVALIDARG Coordinates not in the {0, 0, 10,000, 10,000} range.
NOERROR No error.

Remarks

This method assumes window coordinates of {0, 0, 10,000, 10,000}. Therefore, if you want your video stream to be rendered in the bottom right quarter of the display window, you would call this method with the parameters {5,000, 5,000, 10,000, 10,000}.
Note Values greater than 10,000 are invalid and will cause an error.

See Also

IMixerPinConfig::GetRelativePosition

IMixerPinConfig::SetZOrder

IMixerPinConfig Interface

Sets the z-order of a particular video stream.

This method is not currently implemented and returns E_NOTIMPL.

Syntax

HRESULT SetZOrder(
  DWORD dwZOrder
) PURE;

Parameters

dwZOrder
[in] Value indicating the order in which streams will clip each other.

Return Value

Returns E_NOTIMPL.

Remarks

The z-order indicates which streams can clip other streams. Images with larger z-values are always in front of images with smaller z-values.
The relative order of multiple streams is significant only if the video images overlap.
Specifying the same z-order for two overlapping streams can cause strange video artifacts.

See Also

IMixerPinConfig::GetZOrder

E_NOTIMPL	Method called on secondary stream.
E_INVALIDARG	Value invalid or NULL.
NOERROR	No error.

E_UNEXPECTED	Method called on primary stream.
E_INVALIDARG	Value outside of possible range (0-255).
NOERROR	No error.

E_INVALIDARG	Invalid arguments, both parameters are NULL.
E_FAIL	GetColorKey failed because the color key isn't known.
NOERROR	No error.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_NOTIMPL	Method is not supported.
NOERROR	No error.

E_INVALIDARG	Coordinates not in the {0, 0, 10,000, 10,000} range.
NOERROR	No error.