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. |
Retrieves the average time between successive frames in 100-nanosecond units.
HRESULT get_AvgTimePerFrame(
REFTIME *pAvgTimePerFrame
);
Returns an HRESULT value.
Retrieves a bit error rate for the video stream (one error for approximately this many bits).
HRESULT get_BitErrorRate(
long *pBitErrorRate
);
Returns an HRESULT value.
Retrieves an approximate bit rate for the video stream (in bits per second).
HRESULT get_BitRate(
long *pBitRate
);
Returns an HRESULT value.
Retrieves the height of the destination rectangle.
HRESULT get_DestinationHeight(
long *pDestinationHeight
);
Returns an HRESULT value.
Retrieves the destination x-axis origin coordinate.
HRESULT get_DestinationLeft(
long *pDestinationLeft
);
Returns an HRESULT value.
Setting this coordinate does not affect the destination rectangle width.
Retrieves the destination y-axis origin coordinate.
HRESULT get_DestinationTop(
long *pDestinationTop
);
Returns an HRESULT value.
Setting this coordinate does not affect the destination rectangle height.
Retrieves the width of the destination rectangle.
HRESULT get_DestinationWidth(
long *pDestinationWidth
);
Returns an HRESULT value.
Retrieves the height of the source rectangle.
HRESULT get_SourceHeight(
long *pSourceHeight
);
Returns an HRESULT value.
Retrieves the source rectangle x-axis coordinate.
HRESULT get_SourceLeft(
long *pSourceLeft
);
Returns an HRESULT value.
This method has no effect on the source rectangle width.
Retrieves the source rectangle y-axis origin coordinate.
HRESULT get_SourceTop(
long * pSourceTop
);
Returns an HRESULT value.
Setting this method has no effect on the source rectangle height.
Retrieves the source rectangle width.
HRESULT get_SourceWidth(
long *pSourceWidth
);
Returns an HRESULT value.
This method has no effect on the source rectangle x-axis coordinate.
Retrieves the current video height.
HRESULT get_VideoHeight(
long *pVideoHeight
);
Returns an HRESULT value.
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 OLE documents.
Retrieves the current video width.
HRESULT get_VideoWidth(
long *pVideoWidth
);
Returns an HRESULT value.
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.
Retrieves the current image waiting at the renderer.
HRESULT GetCurrentImage(
long *pBufferSize,
long *pDIBImage
);
Returns an HRESULT value.
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.
Retrieves the position of the destination rectangle in window coordinates.
HRESULT GetDestinationPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
This method has the same effect as individually calling the IBasicVideo::get_DestinationLeft, IBasicVideo::get_DestinationTop, IBasicVideo::get_DestinationWidth, and IBasicVideo::get_DestinationHeight methods.
Retrieves the source position rectangle, clipped to the available video.
HRESULT GetSourcePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
This method has the same effect as individually calling the IBasicVideo::get_SourceLeft, IBasicVideo::get_SourceTop, IBasicVideo::get_SourceWidth, and IBasicVideo::get_SourceHeight methods.
Retrieves the palette colors for the video.
HRESULT GetVideoPaletteEntries(
long StartIndex,
long Entries,
long *pRetrieved,
long *pPalette
);
Returns an HRESULT value.
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.
Retrieves the native video dimensions.
HRESULT GetVideoSize(
long *pWidth,
long *pHeight
);
Returns an HRESULT value.
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.
Determines if the renderer is using the default destination rectangle.
HRESULT IsUsingDefaultDestination( );
Returns an HRESULT value. Returns S_OK if using the default destination; otherwise, returns S_FALSE.
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.
Determines if the renderer is using the default source rectangle.
HRESULT IsUsingDefaultSource( );
Returns an HRESULT value. Returns S_OK if using the default source; otherwise, returns S_FALSE.
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.
Sets the height of the destination rectangle.
HRESULT put_DestinationHeight(
long DestinationHeight
);
Returns an HRESULT value.
Setting this coordinate does not affect the destination rectangle y-axis origin.
Sets the destination x-axis origin coordinate.
HRESULT put_DestinationLeft(
long DestinationLeft
);
Returns an HRESULT value.
Setting this coordinate does not affect the destination rectangle width.
Sets the destination y-axis origin coordinate.
HRESULT put_DestinationTop(
long DestinationTop
);
Returns an HRESULT value.
Sets the width of the destination rectangle.
HRESULT put_DestinationWidth(
long DestinationWidth
);
Returns an HRESULT value.
Setting this coordinate does not affect the destination rectangle x-axis origin.
Sets the height of the source rectangle.
HRESULT put_SourceHeight(
long SourceHeight
);
Returns an HRESULT value.
Setting the height of the source rectangle has no effect on the source y-axis coordinate.
Sets the source rectangle x-axis coordinate.
HRESULT put_SourceLeft(
long SourceLeft
);
Returns an HRESULT value.
Setting this method has no effect on the source rectangle width.
Sets the source rectangle y-axis origin coordinate.
HRESULT put_SourceTop(
long SourceTop
);
Returns an HRESULT value.
Setting this method has no effect on the source rectangle height.
Sets the source rectangle width.
HRESULT put_SourceWidth(
long SourceWidth
);
Returns an HRESULT value.
Setting this method has no effect on the source rectangle x-axis coordinate.
Sets the default destination position of the video window so that the renderer uses the entire window for playback.
HRESULT SetDefaultDestinationPosition( );
Returns an HRESULT value.
Informs the renderer to use the default source rectangle.
HRESULT SetDefaultSourcePosition( );
Returns an HRESULT value.
Sets the destination rectangle in window coordinates.
HRESULT SetDestinationPosition(
long Left,
long Top,
long Width,
long Height
);
Returns an HRESULT value.
This method has the same effect as individually calling the IBasicVideo::put_DestinationLeft, IBasicVideo::put_DestinationTop, IBasicVideo::put_DestinationWidth, and IBasicVideo::put_DestinationHeight methods.
Sets the source rectangle and is clipped against the available video.
HRESULT SetSourcePosition(
long Left,
long Top,
long Width,
long Height
);
Returns an HRESULT value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.