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.

When to Implement

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.

When to Use

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

HRESULT GetConnectInfo(
  LPDWORD pdwNumConnectInfo,
  LPDDVIDEOPORTCONNECT pddVPConnectInfo
  );

Parameters

pdwNumConnectInfo

[in/out] Points 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] Points to an array of DDVIDEOPORTCONNECT structures that the driver fills in. Specify NULL to retrieve the total number of formats supported.

Return Values

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.

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 Values

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.

Value	Meaning
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.

HRESULT GetOverlaySurface(
  LPDIRECTDRAWSURFACE *ppddOverlaySurface
  );

Parameters

ppddOverlaySurface

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

Return Values

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.

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 Values

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.

HRESULT GetVPDataInfo(
  LPAMVPDATAINFO pamvpDataInfo
  );

Parameters

pamvpDataInfo

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

Return Values

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.

Value	Meaning
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.

HRESULT InformVPInputFormats(
  DWORD dwNumFormats,
  LPDDPIXELFORMAT pDDPixelFormats
  );

Parameters

dwNumFormats

[in] Number of video formats contained in the pDDPixelFormats parameter.

pDDPixelFormats

[in] Array of pixel format structures (DDPIXELFORMAT) to send to the device.

Return Values

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.

HRESULT SetConnectInfo(
  DWORD dwChosenEntry
  );

Parameters

dwChosenEntry

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

Return Values

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.

Value	Meaning
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.

HRESULT SetDDSurfaceKernelHandle(
  DWORD dwDDKernelHandle
  );

Parameters

dwDDKernelHandle

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

Return Values

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.

Value	Meaning
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.

HRESULT SetDirectDrawKernelHandle(
  DWORD dwDDKernelHandle
  );

Parameters

dwDDKernelHandle

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

Return Values

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.

Value	Meaning
E_FAIL	Failure.
E_INVALIDARG	Invalid argument.
NOERROR	The specified handle was set successfully.

Remarks

Sets the DirectDraw kernel level handle on the minidriver to enable it to communicate with DirectDraw directly.

---

IVPBaseConfig::SetInvertPolarity

IVPBaseConfig Interface

Reverses the current polarity the decoder uses.

HRESULT SetInvertPolarity(void);

Return Values

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.

Value	Meaning
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.

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 Values

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.

HRESULT SetVideoFormat(
  DWORD dwChosenEntry
  );

Parameters

dwChosenEntry

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

Return Values

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.

Value	Meaning
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.

HRESULT SetVideoPortID (
  DWORD dwVideoPortID
  );

Parameters

dwVideoPortID

[in] DirectDraw video port ID.

Return Values

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.

Value	Meaning
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.

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

Top of Page