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 allows the source rectangle to be set and retrieved. 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.

When to Implement

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 to Use

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

HRESULT get_AvgTimePerFrame(
  REFTIME *pAvgTimePerFrame
  );

Parameters

pAvgTimePerFrame

[out] Time between frames.

Return Values

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

HRESULT get_BitErrorRate(
  long *pBitErrorRate
  );

Parameters

pBitErrorRate

[out] Approximate bit error rate.

Return Values

Returns an HRESULT value.

---

IBasicVideo::get_BitRate

IBasicVideo Interface

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

HRESULT get_BitRate(
  long *pBitRate
  );

Parameters

pBitRate

[out] Approximate bit rate.

Return Values

Returns an HRESULT value.

---

IBasicVideo::GetCurrentImage

IBasicVideo Interface

Retrieves the current image waiting at the renderer.

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

Parameters

pBufferSize

[in, out] 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 Values

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.

HRESULT get_DestinationHeight(
  long *pDestinationHeight
  );

Parameters

pDestinationHeight

[out] Current height.

Return Values

Returns an HRESULT value.

---

IBasicVideo::get_DestinationLeft

IBasicVideo Interface

Retrieves the destination x-axis origin coordinate.

HRESULT get_DestinationLeft(
  long *pDestinationLeft
  );

Parameters

pDestinationLeft

[out] Current x-axis origin.

Return Values

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.

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

Parameters

pLeft

[out] The x-axis origin of the destination window.

pTop

[out] The y-axis origin of the destination window.

pWidth

[out] Width of the destination window.

pHeight

[out] Height of the destination window.

Return Values

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.

HRESULT get_DestinationTop(
  long *pDestinationTop
  );

Parameters

pDestinationTop

[out] Current y-axis origin.

Return Values

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.

HRESULT get_DestinationWidth(
  long *pDestinationWidth
  );

Parameters

pDestinationWidth

[out] Current width.

Return Values

Returns an HRESULT value.

---

IBasicVideo::get_SourceHeight

IBasicVideo Interface

Retrieves the height of the source rectangle.

HRESULT get_SourceHeight(
  long *pSourceHeight
  );

Parameters

pSourceHeight

[out] Current rectangle height.

Return Values

Returns an HRESULT value.

---

IBasicVideo::get_SourceLeft

IBasicVideo Interface

Retrieves the source rectangle x-axis coordinate.

HRESULT get_SourceLeft(
  long *pSourceLeft
  );

Parameters

pSourceLeft

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

Return Values

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.

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

Parameters

pLeft

[out] The x-axis origin of the source window.

pTop

[out] The y-axis origin of the source window.

pWidth

[out] Width of the source window.

pHeight

[out] Height of the source window.

Return Values

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.

HRESULT get_SourceTop(
  long * pSourceTop
  );

Parameters

pSourceTop

[out] New top coordinate.

Return Values

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.

HRESULT get_SourceWidth(
  long *pSourceWidth
  );

Parameters

pSourceWidth

[out] Current width.

Return Values

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.

HRESULT get_VideoHeight(
  long *pVideoHeight
  );

Parameters

pVideoHeight

[out] Native height of the video.

Return Values

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.

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] Number of entries actually returned.

pPalette

[out] Pointer to an array of Microsoft Win32 PALETTEENTRY structures.

Return Values

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.

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

Parameters

pWidth

[out] Width of the video window.

pHeight

[out] Height of the video window.

Return Values

Returns an HRESULT value.

Remarks

This method retrieves the native video width and height, disregarding any source rectangle that might have been set. 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.

HRESULT get_VideoWidth(
  long *pVideoWidth
  );

Parameters

pVideoWidth

[out] Native width of the video.

Return Values

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.

HRESULT IsUsingDefaultDestination( );

Return Values

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 or not they are in use.

---

IBasicVideo::IsUsingDefaultSource

IBasicVideo Interface

Determines if the renderer is using the default source rectangle.

HRESULT IsUsingDefaultSource( );

Return Values

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 or not the settings are in use.

---

IBasicVideo::put_DestinationHeight

IBasicVideo Interface

Sets the height of the destination rectangle.

HRESULT put_DestinationHeight(
  long DestinationHeight
  );

Parameters

DestinationHeight

[in] New height.

Return Values

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.

HRESULT put_DestinationLeft(
  long DestinationLeft
  );

Parameters

DestinationLeft

[in] New x-axis origin.

Return Values

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.

HRESULT put_DestinationTop(
  long DestinationTop
  );

Parameters

DestinationTop

[in] New y-axis origin.

Return Values

Returns an HRESULT value.

---

IBasicVideo::put_DestinationWidth

IBasicVideo Interface

Sets the width of the destination rectangle.

HRESULT put_DestinationWidth(
  long DestinationWidth
  );

Parameters

DestinationWidth

[in] New width.

Return Values

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.

HRESULT put_SourceHeight(
  long SourceHeight
  );

Parameters

SourceHeight

[in] New rectangle height.

Return Values

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.

HRESULT put_SourceLeft(
  long SourceLeft
  );

Parameters

SourceLeft

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

Return Values

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.

HRESULT put_SourceTop(
  long SourceTop
  );

Parameters

SourceTop

[in] New top coordinate.

Return Values

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.

HRESULT put_SourceWidth(
  long SourceWidth
  );

Parameters

SourceWidth

[in] New width of the source rectangle.

Return Values

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.

HRESULT SetDefaultDestinationPosition( );

Return Values

Returns an HRESULT value.

---

IBasicVideo::SetDefaultSourcePosition

IBasicVideo Interface

Informs the renderer to use the default source rectangle.

HRESULT SetDefaultSourcePosition( );

Return Values

Returns an HRESULT value.

---

IBasicVideo::SetDestinationPosition

IBasicVideo Interface

Sets the destination rectangle in window coordinates.

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.

Height

[in] Height of the destination window.

Return Values

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.

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.

Height

[in] Height of the source window.

Return Values

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.

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

Top of Page