DirectShow Animated Header -- IBasicVideo Object DirectShow Animated Header -- IBasicVideo Object* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: IBasicAudio Object
*Next Topic: IFilterInfo Object

IBasicVideo Object


The filter graph manager exposes the IBasicVideo object, which 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 video renderer must be connected to use IBasicVideo object methods. If it isn't connected, all methods return run-time error 521. Properties set on a video renderer generally 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 object controls. IBasicVideo allows the source rectangle to be set and retrieved. All IBasicVideo rectangles have top, left, width, and height properties. When no source rectangle has been set, the properties of the source rectangle return the full, native video size.

Properties
Name Description
AvgTimePerFrame Retrieves the average time between successive frames in 100-nanosecond units.
BitErrorRate Retrieves an approximate bit error rate for the video stream.
BitRate Retrieves an approximate bit rate for the video stream.
DestinationLeft Sets or retrieves the x-axis coordinate for the destination video rectangle.
DestinationHeight Sets or retrieves the height of the destination video rectangle.
DestinationTop Sets or retrieves the y-axis coordinate for the destination video rectangle.
DestinationWidth Sets or retrieves the width of the destination video rectangle.
SourceHeight Sets or retrieves the height of the source video rectangle.
SourceLeft Sets or retrieves the x-axis coordinate for the source video rectangle.
SourceTop Sets or retrieves the y-axis coordinate for the source video rectangle.
SourceWidth Sets or retrieves the width of the source video rectangle.
VideoHeight Retrieves the current video height.
VideoWidth Retrieves the current video width.

Methods
Name Description
GetCurrentImage Returns a copy of the image that is currently waiting at the renderer.
GetDestinationPosition Retrieves the destination rectangle for the window.
GetSourcePosition Retrieves the source video rectangle.
GetVideoPaletteEntries Retrieves the color palette entries required by the video.
GetVideoSize Retrieves the native video dimensions.
IsUsingDefaultSource Indicates whether the default source is being used.
SetDefaultDestinationPosition Sets the default destination position for the window.
SetDefaultSourcePosition Informs the renderer to use the default source rectangle.
SetDestinationPosition Sets the destination rectangle for the window.
SetSourcePosition Sets the source video rectangle.


AvgTimePerFrame Property (IBasicVideo Object)

IBasicVideo Object

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

objVideo.AvgTimePerFrame

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.


BitErrorRate Property (IBasicVideo Object)

IBasicVideo Object

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

objVideo.BitErrorRate

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.


BitRate Property (IBasicVideo Object)

IBasicVideo Object

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

objVideo.BitRate

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.


DestinationHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the height of the destination rectangle.

objVideo.DestinationHeight [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value for the destination rectangle height.
Remarks

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


DestinationLeft Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the destination x-axis origin coordinate.

objVideo.DestinationLeft [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value of the destination x-axis origin.
Remarks

Setting this coordinate does not affect the destination rectangle width.


DestinationTop Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the destination y-axis origin coordinate.

objVideo.DestinationTop [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value of the y-axis origin.
Remarks

Setting this coordinate does not affect the destination rectangle height.


DestinationWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the width of the destination rectangle.

objVideo.DestinationWidth [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New width value.
Remarks

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


GetCurrentImage Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the image currently waiting at the renderer.

objVideo.GetCurrentImage BufferSize, DIBImage

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
BufferSize
Long value that specifies the size of the buffer the caller is passing in. GetCurrentImage sets this value to the actual number of bytes in the buffer before exiting.
DIBImage
Long value that will contain the buffer where the complete image will be stored in device-independent bitmap (DIB) format. You must pass the buffer by reference.
Remarks

Pause the video renderer before calling this method; calling this method in any other state returns run-time error 549. Depending on what data the source filter has available, the video renderer is not guaranteed to service this request.

An application can use this method to get a copy of the current image the video renderer holds when paused by calling the method with DIBImage set to Nothing.


GetDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the position of the destination rectangle in window coordinates.

objVideo.GetDestinationPosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long integer value that will contain the destination window's x-axis origin.
Top
Long integer value that will contain the destination window's y-axis origin.
Width
Long integer value that will contain the destination window's width.
Height
Long integer value that will contain the destination window's height.
Remarks

This method has the same effect as individually retrieving the DestinationLeft, DestinationTop, DestinationWidth, and DestinationHeight properties.


GetSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the source position that is clipped to the available video.

objVideo.GetSourcePosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long integer value that will contain the source window's x-axis origin.
Top
Long integer value that will contain the source window's y-axis origin.
Width
Long integer value that will contain the source window's width.
Height
Long integer value that will contain the source window's height.
Remarks

This method has the same effect as retrieving the values of the SourceLeft, SourceTop, SourceWidth, and SourceHeight properties.


GetVideoPaletteEntries Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the palette colors for the video.

objVideo.GetVideoPaletteEntries StartIndex, Entries, Retrieved, Palette

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
StartIndex
Long integer value that specifies the start index for the palette.
Entries
Long integer value that specifies the number of palette entries required.
Retrieved
Long integer value that will contain the number of entries actually returned in Palette.
Palette
Long integer value that will contain a pointer to an array of Microsoft® Win32® PALETTEENTRY structures.


GetVideoSize Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the native video dimensions.

objVideo.GetVideoSize Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Width
Long integer value that will contain the video window's width.
Height
Long integer value that will contain the video window's height.
Remarks

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.


IsUsingDefaultSource Method (IBasicVideo Object)

IBasicVideo Object

Retrieves whether or not this object is using the default source.

objVideo.IsUsingDefaultSource

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Return Values

True indicates that the IBasicVideo object is using the default source; False indicates that it is not.


SetDefaultDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

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

objVideo.SetDefaultDestinationPosition

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.


SetDefaultSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

Informs the renderer to use the default source rectangle.

objVideo.SetDefaultSourcePosition

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.


SetDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

Sets the destination rectangle in window coordinates.

objVideo.SetDestinationPosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long value specifying the x-axis origin of the destination window, in pixels.
Top
Long value specifying the y-axis origin of the destination window, in pixels.
Width
Long value specifying the width of the destination window, in pixels.
Height
Long value specifying the height of the destination window, in pixels.
Remarks

This method has the same effect as setting the DestinationLeft, DestinationTop, DestinationWidth, and DestinationHeight properties individually.


SetSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

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

objVideo.SetSourcePosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long value specifying the x-axis origin of the source window.
Top
Long value specifying the y-axis origin of the source window.
Width
Long value specifying the width of the source window.
Height
Long value specifying the height of the source window.
Remarks

This method has the same effect as setting the SourceLeft, SourceTop, SourceWidth, and SourceHeight properties individually.


SourceHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the height of the source rectangle.

objVideo.SourceHeight [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the current rectangle height, in pixels.
Remarks

Setting the height of the source rectangle has no effect on the width and other source values.


SourceLeft Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle's x-coordinate.

objVideo.SourceLeft [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value for the x-axis origin of the source rectangle.
Remarks

Changes to this property do not affect the width and other source values.


SourceTop Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle y-axis origin coordinate.

objVideo.SourceTop [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the distance from the top of the display to the top of the current window, in pixels.
Remarks

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


SourceWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle width.

objVideo.SourceWidth [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the current width, in pixels.
Remarks

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


VideoHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves the native height of the video.

objVideo.VideoHeight

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
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. It can be used by applications to negotiate size requirements with in-place container documents.


VideoWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves the native width of the video.

objVideo.VideoWidth

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
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. It can be used by applications to negotiate size requirements with in-place container documents.

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

*Top of Page