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, blend levels, spect ratio correction, and colorkeys of streams.
When to Implement
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.
When to Use
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 colorkey being used by a video stream. |
| GetColorKey | Retrieves the colorkey being used by a video stream. |
| SetBlendingParameter | Sets the blending parameter which defines how a secondary stream is blended with a primary stream. |
| GetBlendingParameter | Retrieves the value of the blending parameter which 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. |
Retrieves the aspect ratio correction mode for window resizing.
STDMETHOD GetAspectRatioMode(
AM_ASPECT_RATIO_MODE* pamAspectRatioMode
) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_NOTIMPL | Method called on secondary stream. |
| E_INVALIDARG | Value invalid or NULL. |
| NOERROR | No error. |
IMixerPinConfig::SetAspectRatioMode
Retrieves the value of the blending parameter which defines how a secondary stream is blended with a primary stream.
STDMETHOD GetBlendingParameter(
DWORD *pdwBlendingParameter
) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_UNEXPECTED | Method called on primary stream. |
| E_INVALIDARG | Value outside of possible range (0-255). |
| NOERROR | No error. |
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.
IMixerPinConfig::SetBlendingParameter
Retrieves the colorkey being used by a video stream.
STDMETHOD GetColorKey(
COLORKEY *pColorKey,
DWORD *pColor ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_INVALIDARG | Invalid arguments, both parameters are NULL. |
| E_FAIL | GetColorKey failed because the colorkey isn't known. |
| NOERROR | No error. |
Getting the value on the primary stream will retrieve the destination colorkey being used by the overlay surface. Getting this value on the secondary pin returns the colorkey 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 colorkey.
Retrieves the position of the stream in the display window.
STDMETHOD GetRelativePosition(
DWORD *pdwLeft,
DWORD *pdwTop,
DWORD *pdwRight,
DWORD *pdwBottom ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_INVALIDARG | Coordinates not in the {0, 0, 10,000, 10,000} range. |
| NOERROR | No error. |
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}.
IMixerPinConfig::SetRelativePosition
Retrieves the z-order of a particular video stream.
STDMETHOD GetZOrder(
DWORD *pdwZOrder ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation returns E_NOTIMPL.
The larger the value returned by the pdwZOrder parameter, the farther the video stream is from the user's eyes.
Sets the aspect ratio correction mode for window resizing.
STDMETHOD SetAspectRatioMode(
AM_ASPECT_RATIO_MODE amAspectRatioMode
) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_NOTIMPL | Method called on secondary stream. |
| E_INVALIDARG | Invalid arguement. |
| NOERROR | No error. |
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.
IMixerPinConfig::GetAspectRatioMode
Sets the blending parameter which defines how a secondary stream is blended with a primary stream.
STDMETHOD SetBlendingParameter(
DWORD dwBlendingParameter
) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_UNEXPECTED | Method called on primary stream. |
| E_INVALIDARG | Value outside of possible range (0 to 255). |
| NOERROR | No error. |
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.
IMixerPinConfig::GetBlendingParameter
Sets the colorkey being used by a video stream.
STDMETHOD SetColorKey(
COLORKEY *pColorKey ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation returns E_NOTIMPL.
The term colorkey has different meanings depending on which stream it is referring to. The colorkey of the primary stream refers to the destination colorkey being used by the overlay surface. The colorkey of the secondary stream refers to the source colorkey used, when blitting from an offscreen surface to the primary surface.
Applications should set the colorkey 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 it should change it.
Setting the colorkey on the secondary stream can be used to make the stream transparent (nonrectangular). 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 colorkey on the corresponding pin to that color. This ensures that all pixels are transferred except those specified by the colorkey. If possible the colorkey of the secondary stream should be made the same as that of the primary stream to give a slight performance advantage.
Note Setting this value on the primary stream sets the destination colorkey being used by the overlay surface. By default, the destination colorkey is used as the colorkey for all transparent (secondary) streams.
Sets the position of the stream in the display window.
STDMETHOD SetRelativePosition(
DWORD dwLeft,
DWORD dwTop,
DWORD dwRight,
DWORD dwBottom ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
| Value | Meaning |
| E_INVALIDARG | Coordinates not in the {0, 0, 10,000, 10,000} range. |
| NOERROR | No error. |
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.
IMixerPinConfig::GetRelativePosition
Sets the z-order of a particular video stream.
STDMETHOD SetZOrder(
DWORD dwZOrder ) PURE;
Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation returns E_NOTIMPL.
The z-order indicates which streams can clip other streams. Specifying a value of zero for the dwZOrder parameter places that stream on top of all others. The greater the value, the farther away from the eyes of the user.
The relative order of multiple streams is significant only if the video images overlap.
Specifying the same z-order for two overlaping streams can cause strange video artifacts.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.