IBasicVideo Interface

The IBasicVideo interface supports the video properties of a generic video window. Generally, this is a video renderer that draws video into a window on the display.

The IBasicVideo interface supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as the Microsoft® Visual Basic® programming system). However, some operations require several properties to be changed simultaneously; for this reason, methods are provided that allow a number of related properties to be changed.

The IBasicVideo interface methods require only that the video renderer be connected. If it is not connected, all the interface methods return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

When working with video, the application can select a portion of the video to use. This portion is the source rectangle that the IBasicVideo interface controls. IBasicVideo enables you to set and retrieve the source rectangle. All the rectangles that IBasicVideo uses employ top, left, width, and height rather than top, left, right, and bottom, which is favored in Microsoft® Win32® programming. When no source rectangle has been set, the properties of the source rectangle return the full, native video size. All rectangle dimensions are given in pixels.

The video renderer filter supplied with Microsoft® DirectShow® implements this interface. It is also implemented by the filter graph manager (via a plug-in distributor) to pass method calls from the application to the video renderer filter's implementation of the interface. Implement this interface if you are writing a replacement video renderer filter or a replacement DirectShow plug-in distributor. You can use the CBaseBasicVideo class, which handles the IDispatch implementation for Automation, to help implement this interface.

When the filter graph manager exposes this interface, it is used by applications that must control the properties of the video renderer filter.

Methods in Vtable Order

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

IDispatch methods Description
GetTypeInfoCount Determines whether there is type information available for this dispinterface.
GetTypeInfo Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.

IBasicVideo methods Description
get_AvgTimePerFrame Retrieves the average time between successive frames in 100-nanosecond units.
get_BitRate Retrieves an approximate bit rate for the video stream.
get_BitErrorRate Retrieves an approximate bit error rate for the video stream.
get_VideoWidth Retrieves the current video width.
get_VideoHeight Retrieves the current video height.
put_SourceLeft Sets the x-axis coordinate for the source video rectangle.
get_SourceLeft Retrieves the x-axis coordinate for the source video rectangle.
put_SourceWidth Sets the width of the source video rectangle.
get_SourceWidth Retrieves the width of the source video rectangle.
put_SourceTop Sets the y-axis coordinate for the source video rectangle.
get_SourceTop Retrieves the y-axis coordinate for the source video rectangle.
put_SourceHeight Sets the height of the source video rectangle.
get_SourceHeight Retrieves the height of the source video rectangle.
put_DestinationLeft Sets the x-axis coordinate for the destination video rectangle.
get_DestinationLeft Retrieves the x-axis coordinate for the destination video rectangle.
put_DestinationWidth Sets the width of the destination video rectangle.
get_DestinationWidth Retrieves the width of the destination video rectangle.
put_DestinationTop Sets the y-axis coordinate for the destination video rectangle.
get_DestinationTop Retrieves the y-axis coordinate for the destination video rectangle.
put_DestinationHeight Sets the height of the destination video rectangle.
get_DestinationHeight Retrieves the height of the destination video rectangle.
SetSourcePosition Sets the source video rectangle.
GetSourcePosition Retrieves the source video rectangle.
SetDefaultSourcePosition Informs the renderer to use the default source rectangle.
SetDestinationPosition Sets the destination rectangle for the window.
GetDestinationPosition Retrieves the destination video rectangle for the window.
SetDefaultDestinationPosition Sets the default destination position for the window.
GetVideoSize Retrieves the native video dimensions.
GetVideoPaletteEntries Retrieves the color palette entries required by the video.
GetCurrentImage Returns a copy of the current image that is waiting at the renderer.
IsUsingDefaultSource Determines if the renderer is using the default source rectangle.
IsUsingDefaultDestination Determines if the renderer is using the default destination rectangle.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDispatch methods	Description
GetTypeInfoCount	Determines whether there is type information available for this dispinterface.
GetTypeInfo	Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames	Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke	Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IBasicVideo methods	Description
get_AvgTimePerFrame	Retrieves the average time between successive frames in 100-nanosecond units.
get_BitRate	Retrieves an approximate bit rate for the video stream.
get_BitErrorRate	Retrieves an approximate bit error rate for the video stream.
get_VideoWidth	Retrieves the current video width.
get_VideoHeight	Retrieves the current video height.
put_SourceLeft	Sets the x-axis coordinate for the source video rectangle.
get_SourceLeft	Retrieves the x-axis coordinate for the source video rectangle.
put_SourceWidth	Sets the width of the source video rectangle.
get_SourceWidth	Retrieves the width of the source video rectangle.
put_SourceTop	Sets the y-axis coordinate for the source video rectangle.
get_SourceTop	Retrieves the y-axis coordinate for the source video rectangle.
put_SourceHeight	Sets the height of the source video rectangle.
get_SourceHeight	Retrieves the height of the source video rectangle.
put_DestinationLeft	Sets the x-axis coordinate for the destination video rectangle.
get_DestinationLeft	Retrieves the x-axis coordinate for the destination video rectangle.
put_DestinationWidth	Sets the width of the destination video rectangle.
get_DestinationWidth	Retrieves the width of the destination video rectangle.
put_DestinationTop	Sets the y-axis coordinate for the destination video rectangle.
get_DestinationTop	Retrieves the y-axis coordinate for the destination video rectangle.
put_DestinationHeight	Sets the height of the destination video rectangle.
get_DestinationHeight	Retrieves the height of the destination video rectangle.
SetSourcePosition	Sets the source video rectangle.
GetSourcePosition	Retrieves the source video rectangle.
SetDefaultSourcePosition	Informs the renderer to use the default source rectangle.
SetDestinationPosition	Sets the destination rectangle for the window.
GetDestinationPosition	Retrieves the destination video rectangle for the window.
SetDefaultDestinationPosition	Sets the default destination position for the window.
GetVideoSize	Retrieves the native video dimensions.
GetVideoPaletteEntries	Retrieves the color palette entries required by the video.
GetCurrentImage	Returns a copy of the current image that is waiting at the renderer.
IsUsingDefaultSource	Determines if the renderer is using the default source rectangle.
IsUsingDefaultDestination	Determines if the renderer is using the default destination rectangle.

IBasicVideo::get_AvgTimePerFrame

IBasicVideo Interface

Retrieves the average time between successive frames in 100-nanosecond units.

Syntax

HRESULT get_AvgTimePerFrame(
    REFTIME *pAvgTimePerFrame
);

Parameters

pAvgTimePerFrame
[out] Pointer to the time between frames.

Return Value

Returns an HRESULT value.

IBasicVideo::get_BitErrorRate

IBasicVideo Interface

Retrieves a bit error rate for the video stream (one error for approximately this many bits).

Syntax

HRESULT get_BitErrorRate(
    long *pBitErrorRate
);

Parameters

pBitErrorRate
[out] Pointer to the approximate bit error rate.

Return Value

Returns an HRESULT value.

IBasicVideo::get_BitRate

IBasicVideo Interface

Retrieves an approximate bit rate for the video stream (in bits per second).

Syntax

HRESULT get_BitRate(
    long *pBitRate
);

Parameters

pBitRate
[out] Pointer to the approximate bit rate.

Return Value

Returns an HRESULT value.

IBasicVideo::GetCurrentImage

IBasicVideo Interface

Retrieves the current image waiting at the renderer.

Syntax

HRESULT GetCurrentImage(
    long *pBufferSize,
    long *pDIBImage
);

Parameters

pBufferSize
[in, out] Pointer to the size of the buffer the caller is passing in.
pDIBImage
[out] Pointer to a buffer where the complete image will be stored in device-independent bitmap (DIB) format. The buffer must be cast to a long pointer for the function.

Return Value

Returns an HRESULT value.

Remarks

An application can use this method to get a copy of the current image the video renderer holds when paused. The size of the buffer required to hold the image can be obtained by calling the method with a null image pointer. In this case, the buffer size is filled out with the byte count required. The buffer size pointer must always be valid. If the application calls this method and the buffer size is too small to hold the complete image, the renderer returns E_OUTOFMEMORY.
Pause the video renderer before calling this method. Calling this method in any other state than paused returns VFW_E_NOT_PAUSED. Depending on what data the source filter has available, the video renderer is not guaranteed to service this request. If no image is available, it returns E_FAIL.
When called successfully, the output image pointer is filled with the entire DIB image, including the Microsoft Win32 BITMAPINFOHEADER structure, any required palette, and bit masks as defined in the Win32 BITMAPINFO structure. The format of the image that is returned depends on the type provided by the source filter, and cannot be explicitly defined in advance. Typically, the image will be a 24-bit, 16-bit, or 8-bit palettized image.

IBasicVideo::get_DestinationHeight

IBasicVideo Interface

Retrieves the height of the destination rectangle.

Syntax

HRESULT get_DestinationHeight(
    long *pDestinationHeight
);

Parameters

pDestinationHeight
[out] Pointer to the current height, in pixels.

Return Value

Returns an HRESULT value.

IBasicVideo::get_DestinationLeft

IBasicVideo Interface

Retrieves the destination x-axis origin coordinate.

Syntax

HRESULT get_DestinationLeft(
    long *pDestinationLeft
);

Parameters

pDestinationLeft
[out] Pointer to the current x-axis origin.

Return Value

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle width.

IBasicVideo::GetDestinationPosition

IBasicVideo Interface

Retrieves the position of the destination rectangle in window coordinates.

Syntax

HRESULT GetDestinationPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

Parameters

pLeft
[out] Pointer to the x-axis origin of the destination window.
pTop
[out] Pointer to the y-axis origin of the destination window.
pWidth
[out] Pointer to the width of the destination window, in pixels.
pHeight
[out] Pointer to the height of the destination window, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::get_DestinationLeft, IBasicVideo::get_DestinationTop, IBasicVideo::get_DestinationWidth, and IBasicVideo::get_DestinationHeight methods.

IBasicVideo::get_DestinationTop

IBasicVideo Interface

Retrieves the destination y-axis origin coordinate.

Syntax

HRESULT get_DestinationTop(
    long *pDestinationTop
);

Parameters

pDestinationTop
[out] Pointer to the current y-axis origin.

Return Value

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle height.

IBasicVideo::get_DestinationWidth

IBasicVideo Interface

Retrieves the width of the destination rectangle.

Syntax

HRESULT get_DestinationWidth(
    long *pDestinationWidth
);

Parameters

pDestinationWidth
[out] Pointer to the current width, in pixels.

Return Value

Returns an HRESULT value.

IBasicVideo::get_SourceHeight

IBasicVideo Interface

Retrieves the height of the source rectangle.

Syntax

HRESULT get_SourceHeight(
    long *pSourceHeight
);

Parameters

pSourceHeight
[out] Pointer to the current rectangle height, in pixels.

Return Value

Returns an HRESULT value.

IBasicVideo::get_SourceLeft

IBasicVideo Interface

Retrieves the source rectangle x-axis coordinate.

Syntax

HRESULT get_SourceLeft(
    long *pSourceLeft
);

Parameters

pSourceLeft
[out] Pointer to the x-axis origin of the source rectangle.

Return Value

Returns an HRESULT value.

Remarks

This method has no effect on the source rectangle width.

IBasicVideo::GetSourcePosition

IBasicVideo Interface

Retrieves the source position rectangle, clipped to the available video.

Syntax

HRESULT GetSourcePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

Parameters

pLeft
[out] Pointer to the x-axis origin of the source window.
pTop
[out] Pointer to the y-axis origin of the source window.
pWidth
[out] Pointer to the width of the source window, in pixels.
pHeight
[out] Pointer to the height of the source window, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::get_SourceLeft, IBasicVideo::get_SourceTop, IBasicVideo::get_SourceWidth, and IBasicVideo::get_SourceHeight methods.

IBasicVideo::get_SourceTop

IBasicVideo Interface

Retrieves the source rectangle y-axis origin coordinate.

Syntax

HRESULT get_SourceTop(
    long *pSourceTop
);

Parameters

pSourceTop
[out] Pointer to the new top coordinate.

Return Value

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle height.

IBasicVideo::get_SourceWidth

IBasicVideo Interface

Retrieves the source rectangle width.

Syntax

HRESULT get_SourceWidth(
    long *pSourceWidth
);

Parameters

pSourceWidth
[out] Pointer to the current width, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method has no effect on the source rectangle x-axis coordinate.

IBasicVideo::get_VideoHeight

IBasicVideo Interface

Retrieves the current video height.

Syntax

HRESULT get_VideoHeight(
    long *pVideoHeight
);

Parameters

pVideoHeight
[out] Pointer to the native height of the video, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method returns the actual height of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native vertical dimension. Applications can use this method to negotiate size requirements with in-place container documents.

IBasicVideo::GetVideoPaletteEntries

IBasicVideo Interface

Retrieves the palette colors for the video.

Syntax

HRESULT GetVideoPaletteEntries(
    long StartIndex,
    long Entries,
    long *pRetrieved,
    long *pPalette
);

Parameters

StartIndex
[in] Start index for the palette.
Entries
[in] Number of palette entries required.
pRetrieved
[out] Pointer to the number of entries actually returned.
pPalette
[out] Pointer to an array of Microsoft Win32 PALETTEENTRY structures.

Return Value

Returns an HRESULT value.

Remarks

An application can query the colors required by the video with this method. An application can pass in a null pPalette parameter, and the pRetrieved parameter is filled in with the number of colors in use. The pPalette parameter is a pointer to an array of PALETTEENTRY structures. With the StartIndex and Entries parameters, an application can request any contiguous section of the palette in a single method. The interface was modeled on the Win32 GetSystemPaletteEntries function.

IBasicVideo::GetVideoSize

IBasicVideo Interface

Retrieves the native video dimensions.

Syntax

HRESULT GetVideoSize(
    long *pWidth,
    long *pHeight
);

Parameters

pWidth
[out] Pointer to the width of the video window, in pixels.
pHeight
[out] Pointer to the height of the video window, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method retrieves the native video width and height, disregarding any source rectangle that might have been set. Microsoft® ActiveX® controls or other applications can use this information to negotiate space in compound documents.

IBasicVideo::get_VideoWidth

IBasicVideo Interface

Retrieves the current video width.

Syntax

HRESULT get_VideoWidth(
    long *pVideoWidth
);

Parameters

pVideoWidth
[out] Pointer to the native width of the video, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method returns the actual width of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native horizontal dimension. Applications can use it to negotiate size requirements with in-place ActiveX documents.

IBasicVideo::IsUsingDefaultDestination

IBasicVideo Interface

Determines if the renderer is using the default destination rectangle.

Syntax

HRESULT IsUsingDefaultDestination(void);

Return Value

Returns an HRESULT value. Returns S_OK if using the default destination; otherwise, returns S_FALSE.

Remarks

The IBasicVideo::SetDefaultDestinationPosition method can be used to tell the filter to use the default settings for the destination rectangle. This method returns whether they are in use.

IBasicVideo::IsUsingDefaultSource

IBasicVideo Interface

Determines if the renderer is using the default source rectangle.

Syntax

HRESULT IsUsingDefaultSource(void);

Return Value

Returns an HRESULT value. Returns S_OK if using the default source; otherwise, returns S_FALSE.

Remarks

You can use the IBasicVideo::SetDefaultSourcePosition method to inform the filter to use the default settings for the source rectangle. This method returns whether the settings are in use.

IBasicVideo::put_DestinationHeight

IBasicVideo Interface

Sets the height of the destination rectangle.

Syntax

HRESULT put_DestinationHeight(
    long DestinationHeight
);

Parameters

DestinationHeight
[in] New height, in pixels.

Return Value

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle y-axis origin.

IBasicVideo::put_DestinationLeft

IBasicVideo Interface

Sets the destination x-axis origin coordinate.

Syntax

HRESULT put_DestinationLeft(
    long DestinationLeft
);

Parameters

DestinationLeft
[in] New x-axis origin.

Return Value

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle width.

IBasicVideo::put_DestinationTop

IBasicVideo Interface

Sets the destination y-axis origin coordinate.

Syntax

HRESULT put_DestinationTop(
    long DestinationTop
);

Parameters

DestinationTop
[in] New y-axis origin.

Return Value

Returns an HRESULT value.

IBasicVideo::put_DestinationWidth

IBasicVideo Interface

Sets the width of the destination rectangle.

Syntax

HRESULT put_DestinationWidth(
    long DestinationWidth
);

Parameters

DestinationWidth
[in] New width, in pixels.

Return Value

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle x-axis origin.

IBasicVideo::put_SourceHeight

IBasicVideo Interface

Sets the height of the source rectangle.

Syntax

HRESULT put_SourceHeight(
    long SourceHeight
);

Parameters

SourceHeight
[in] New rectangle height, in pixels.

Return Value

Returns an HRESULT value.

Remarks

Setting the height of the source rectangle has no effect on the source y-axis coordinate.

IBasicVideo::put_SourceLeft

IBasicVideo Interface

Sets the source rectangle x-axis coordinate.

Syntax

HRESULT put_SourceLeft(
    long SourceLeft
);

Parameters

SourceLeft
[in] The x-axis origin of the source rectangle.

Return Value

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle width.

IBasicVideo::put_SourceTop

IBasicVideo Interface

Sets the source rectangle y-axis origin coordinate.

Syntax

HRESULT put_SourceTop(
    long SourceTop
);

Parameters

SourceTop
[in] New top coordinate.

Return Value

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle height.

IBasicVideo::put_SourceWidth

IBasicVideo Interface

Sets the source rectangle width.

Syntax

HRESULT put_SourceWidth(
    long SourceWidth
);

Parameters

SourceWidth
[in] New width of the source rectangle, in pixels.

Return Value

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle x-axis coordinate.

IBasicVideo::SetDefaultDestinationPosition

IBasicVideo Interface

Sets the default destination position of the video window so that the renderer uses the entire window for playback.

Syntax

HRESULT SetDefaultDestinationPosition(void);

Return Value

Returns an HRESULT value.

IBasicVideo::SetDefaultSourcePosition

IBasicVideo Interface

Informs the renderer to use the default source rectangle.

Syntax

HRESULT SetDefaultSourcePosition(void);

Return Value

Returns an HRESULT value.

IBasicVideo::SetDestinationPosition

IBasicVideo Interface

Sets the destination rectangle in window coordinates.

Syntax

HRESULT SetDestinationPosition(
    long Left,
    long Top,
    long Width,
    long Height
);

Parameters

Left
[in] The x-axis origin of the destination window.
Top
[in] The y-axis origin of the destination window.
Width
[in] Width of the destination window, in pixels.
Height
[in] Height of the destination window, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::put_DestinationLeft, IBasicVideo::put_DestinationTop, IBasicVideo::put_DestinationWidth, and IBasicVideo::put_DestinationHeight methods.

IBasicVideo::SetSourcePosition

IBasicVideo Interface

Sets the source rectangle and is clipped against the available video.

Syntax

HRESULT SetSourcePosition(
    long Left,
    long Top,
    long Width,
    long Height
);

Parameters

Left
[in] The x-axis origin of the source window.
Top
[in] The y-axis origin of the source window.
Width
[in] Width of the source window, in pixels.
Height
[in] Height of the source window, in pixels.

Return Value

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::put_SourceLeft, IBasicVideo::put_SourceTop, IBasicVideo::put_SourceWidth, and IBasicVideo::put_SourceHeight methods.
Setting this coordinate does not affect the destination rectangle height.