IVPBaseConfig Interface

IVPBaseConfig enables a video port (VP) or overlay mixer filter to communicate with a VP driver (decoder), to set and retrieve configuration information. This interface assumes that the mixer filter creates the video port. The IVPConfig interface derives from this interface. See also IVPBaseNotify and IVPNotify.

The Windows Driver Model (WDM) Ksproxy filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need this functionality on a platform that does not support WDM, or when you need to alter the default behavior.

The Overlay Mixer filter uses this interface so you won't need to use it in most cases. Use this interface when you implement your own overlay mixer filter.

Methods in Vtable Order

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

IVPBaseConfig methods Description
GetConnectInfo Retrieves connection information structures.
SetConnectInfo Sets the index for the current video port connection information.
GetVPDataInfo Retrieves the current video port data information.
GetMaxPixelRate Retrieves the maximum pixels per second rate for a given width and height.
InformVPInputFormats Informs the device what video formats the video port supports.
GetVideoFormats Retrieves the video formats the decoder supports.
SetVideoFormat Sets the format that the video will use.
SetInvertPolarity Reverses the current polarity the decoder uses.
GetOverlaySurface Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.
SetDirectDrawKernelHandle Sets the Microsoft® DirectDraw® kernel handle for the decoder's minidriver to use.
SetVideoPortID Sets the port ID that the video will use.
SetDDSurfaceKernelHandle Sets the kernel handle that the DirectDraw surface will use.
SetSurfaceParameters Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IVPBaseConfig methods	Description
GetConnectInfo	Retrieves connection information structures.
SetConnectInfo	Sets the index for the current video port connection information.
GetVPDataInfo	Retrieves the current video port data information.
GetMaxPixelRate	Retrieves the maximum pixels per second rate for a given width and height.
InformVPInputFormats	Informs the device what video formats the video port supports.
GetVideoFormats	Retrieves the video formats the decoder supports.
SetVideoFormat	Sets the format that the video will use.
SetInvertPolarity	Reverses the current polarity the decoder uses.
GetOverlaySurface	Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.
SetDirectDrawKernelHandle	Sets the Microsoft® DirectDraw® kernel handle for the decoder's minidriver to use.
SetVideoPortID	Sets the port ID that the video will use.
SetDDSurfaceKernelHandle	Sets the kernel handle that the DirectDraw surface will use.
SetSurfaceParameters	Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.

IVPBaseConfig::GetConnectInfo

IVPBaseConfig Interface

Retrieves connection information structures.

Syntax

HRESULT GetConnectInfo(
    LPDWORD pdwNumConnectInfo,
    LPDDVIDEOPORTCONNECT pddVPConnectInfo
    );

Parameters

pdwNumConnectInfo

[in, out] Pointer to a buffer that contains the number of DDVIDEOPORTCONNECT structures provided by the pddVPConnectInfo parameter. Contains the actual number of structures returned on output. If pddVPConnectInfo is NULL, this method updates this parameter with the number of structures supported by the driver.

pddVPConnectInfo

[in, out] Pointer to an array of DDVIDEOPORTCONNECT structures that the driver fills in. Specify NULL to retrieve the total number of formats supported.

Return Value

Returns NOERROR if the count or structures were retrieved, or a driver error.

Remarks

This method retrieves the various connection information structures such as GUID and port width structures, in an array of structures specified by pddVPConnectInfo. The callee must allocate the correct amount of space for the number of structures requested.
Set the index for connection information by using the IVPBaseConfig::SetConnectInfo method.

IVPBaseConfig::GetMaxPixelRate

IVPBaseConfig Interface

Retrieves the maximum pixels per second rate for a given width and height.

Syntax

HRESULT GetMaxPixelRate(
    LPAMVPSIZE pamvpSize,
    LPDWORD pdwMaxPixelsPerSecond
    );

Parameters

pamvpSize
[in, out] Pointer to an AMVPSIZE structure containing the desired width and height. The structure receives the final dimensions upon return.
pdwMaxPixelsPerSecond
[out] Pointer to the retrieved maximum pixels per second rate.

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_INVALIDARG Invalid argument.
NOERROR The maximum pixel rate was retrieved.

Remarks

This method retrieves the maximum pixels per second rate expected for a given format and a given scaling factor. If the decoder does not support those scaling factors, then it returns the rate and the nearest scaling factors it supports.

IVPBaseConfig::GetOverlaySurface

IVPBaseConfig Interface

Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.

Syntax

HRESULT GetOverlaySurface(
    LPDIRECTDRAWSURFACE *ppddOverlaySurface
    );

Parameters

ppddOverlaySurface
[out] Address of a pointer to the retrieved DirectDraw® overlay surface object.

Return Value

Returns NOERROR if the overlay surface object was returned. (Default implementation sets the surface to NULL and returns NOERROR.)

Remarks

The Overlay Mixer uses this function to determine if the driver requires the Overlay Mixer to use its overlay surface and if so to get a pointer to it. If this function returns NULL, then the Overlay Mixer allocates its own surface.

IVPBaseConfig::GetVideoFormats

IVPBaseConfig Interface

Retrieves the video formats the decoder supports.

Syntax

HRESULT GetVideoFormats(
    LPDWORD pdwNumFormats,
    LPDDPIXELFORMAT pddPixelFormats
    );

Parameters

pdwNumFormats
[in, out] Pointer to the number of DDPIXELFORMAT structures provided by the pddPixelFormats parameter. When called, this method updates this parameter with the actual number of structures retrieved. If pddPixelFormats is NULL, this method updates this parameter with the total number of formats the driver supports.
pddPixelFormats
[in, out] Pointer to an array of DDPIXELFORMAT structures that the driver fills. Specify NULL to retrieve only the count of supported formats in pdwNumFormats.

Return Value

Returns NOERROR if the count or structures were returned, or a driver error otherwise.

Remarks

This method queries for either the number of DDPIXELFORMAT structures supported by the driver, or retrieves as many structures as can fit into the provided buffer space.
The callee must allocate the correct amount of space for the number of structures requested.
Set the video format by using IVPBaseConfig::SetVideoFormat.

IVPBaseConfig::GetVPDataInfo

IVPBaseConfig Interface

Retrieves the current video port data information.

Syntax

HRESULT GetVPDataInfo(
    LPAMVPDATAINFO pamvpDataInfo
    );

Parameters

pamvpDataInfo
[in, out] Pointer to the AMVPDATAINFO data information structure.

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_INVALIDARG Invalid argument.
NOERROR The video port data information was retrieved.

IVPBaseConfig::InformVPInputFormats

IVPBaseConfig Interface

Informs the device what video formats the video port supports.

Syntax

HRESULT InformVPInputFormats(
    DWORD dwNumFormats,
    LPDDPIXELFORMAT pDDPixelFormats
    );

Parameters

dwNumFormats
[in] Number of video formats contained in the pDDPixelFormats parameter.
pDDPixelFormats
[in] Pointer to an array of pixel format structures (DDPIXELFORMAT) to send to the device.

Return Value

Returns S_FALSE if failure, or NOERROR otherwise.

Remarks

The supplied array of supported video port formats might determine what formats the device, in turn, proposes.

IVPBaseConfig::SetConnectInfo

IVPBaseConfig Interface

Sets the index for the current video port connection information.

Syntax

HRESULT SetConnectInfo(
    DWORD dwChosenEntry
    );

Parameters

dwChosenEntry
[in] Index of new video port connect information (zero-based) to pass to the driver.

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_INVALIDARG Invalid argument.
NOERROR The video port connect information was set.

Remarks

Retrieve connection information by using IVPBaseConfig::GetConnectInfo.

IVPBaseConfig::SetDDSurfaceKernelHandle

IVPBaseConfig Interface

Sets the kernel handle to be used by the DirectDraw surface.

Syntax

HRESULT SetDDSurfaceKernelHandle(
    DWORD dwDDKernelHandle
    );

Parameters

dwDDKernelHandle
[in] DirectDraw surface handle for kernel mode, passed as a DWORD value.

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_INVALIDARG Invalid argument.
NOERROR The specified handle is set successfully.

Remarks

This method sets the DirectDraw handle on the mini driver to enable it to communicate with the video port directly.

IVPBaseConfig::SetDirectDrawKernelHandle

IVPBaseConfig Interface

Sets the DirectDraw® kernel handle for the decoder's minidriver to use.

Syntax

HRESULT SetDirectDrawKernelHandle(
    DWORD dwDDKernelHandle
    );

Parameters

dwDDKernelHandle
[in] DirectDraw kernel level handle passed as a DWORD value.

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_INVALIDARG Invalid argument.
NOERROR The specified handle was set successfully.

IVPBaseConfig::SetInvertPolarity

IVPBaseConfig Interface

Reverses the current polarity the decoder uses.

Syntax

HRESULT SetInvertPolarity(void);

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.
NOERROR The polarity was reversed.

Remarks

Reversing polarity means asking the decoder to treat even fields like odd fields and vice versa.

IVPBaseConfig::SetSurfaceParameters

IVPBaseConfig Interface

Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.

Syntax

HRESULT SetSurfaceParameters(
    DWORD dwPitch,
    DWORD dwXOrigin,
    DWORD dwYOrigin ) PURE;

Parameters

dwPitch
[in] Pitch of the surface. Distance (or pitch) in pixels between the start pixels of two consecutive lines of the surface.
dwXOrigin
[in] X-value of the pixel at which valid data starts.
dwYOrigin
[in] Y-value of the pixel at which valid data starts.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The current default implementation returns NOERROR if the call completed successfully, or E_NOTIMPL if the method is not implemented.

IVPBaseConfig::SetVideoFormat

IVPBaseConfig Interface

Sets the format to be used by the video.

Syntax

HRESULT SetVideoFormat(
    DWORD dwChosenEntry
    );

Parameters

dwChosenEntry
[in] Value specifying the index (zero-based) of the video pixel format to use.

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_INVALIDARG Invalid argument.
NOERROR The new video format was set.

Remarks

Retrieve the video formats by using IVPBaseConfig::GetVideoFormats.

IVPBaseConfig::SetVideoPortID

IVPBaseConfig Interface

Sets the port ID which the video will use.

Syntax

HRESULT SetVideoPortID (
    DWORD dwVideoPortID
    );

Parameters

dwVideoPortID
[in] DirectDraw video port ID.

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_INVALIDARG Invalid argument.
NOERROR The specified port ID is set successfully.

Remarks

This method sets the DirectDraw video port ID on the mini driver to enable it to communicate with the video port directly.

E_FAIL	Failure.
E_POINTER	NULL pointer argument.
E_INVALIDARG	Invalid argument.
NOERROR	The maximum pixel rate was retrieved.