IAMVideoCompression Interface

The IAMVideoCompression pin interface enables you to control compression parameters that aren't part of the media type.

The put_PFramesPerKeyFrame and get_PFramesPerKeyFrame methods refer to predicted (P) frames and bidirectional (B) frames, which are MPEG concepts and not generally applicable to simpler types of compressors.

Implement this interface on the output pin of a video capture or video compressor filter that provides compressed video data.

An application can use this interface to control how video is compressed, including characteristics such as the number of key frames and frame quality. Use it to retrieve a textual description of the compressor and other available information, including the compressor's capabilities.

Note This interface is not always available unless the output pin of a capture filter is connected to another filter in the graph.

Methods in Vtable Order

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

IAMVideoCompression methods Description
put_KeyFrameRate Sets the key-frame rate.
get_KeyFrameRate Retrieves the key-frame rate.
put_PFramesPerKeyFrame Sets the predicted (P) frame frequency.
get_PFramesPerKeyFrame Retrieves the P frame frequency.
put_Quality Sets the quality of the video image compression.
get_Quality Retrieves the current image quality setting.
put_WindowSize Sets the number of frames over which the compressor must maintain an average data rate.
get_WindowSize Retrieves the number of frames over which the compressor must maintain an average data rate.
GetInfo Retrieves compressor information.
OverrideKeyFrame Forces a particular frame to be a key frame.
OverrideFrameSize Overrides a particular frame's data rate.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMVideoCompression methods	Description
put_KeyFrameRate	Sets the key-frame rate.
get_KeyFrameRate	Retrieves the key-frame rate.
put_PFramesPerKeyFrame	Sets the predicted (P) frame frequency.
get_PFramesPerKeyFrame	Retrieves the P frame frequency.
put_Quality	Sets the quality of the video image compression.
get_Quality	Retrieves the current image quality setting.
put_WindowSize	Sets the number of frames over which the compressor must maintain an average data rate.
get_WindowSize	Retrieves the number of frames over which the compressor must maintain an average data rate.
GetInfo	Retrieves compressor information.
OverrideKeyFrame	Forces a particular frame to be a key frame.
OverrideFrameSize	Overrides a particular frame's data rate.

IAMVideoCompression::GetInfo

IAMVideoCompression Interface

Retrieves compressor information.

Syntax

HRESULT GetInfo(
    WCHAR *pszVersion,
    int *pcbVersion,
    LPWSTR pszDescription,
    int *pcbDescription,
    long *pDefaultKeyFrameRate,
    long *pDefaultPFramesPerKey,
    double *pDefaultQuality,
    long *pCapabilities
    ) PURE;

Parameters

pszVersion
[out] Pointer to a version string, such as "Version 2.1.0".
pcbVersion
[in, out] Size needed for a version string. Pointer to the number of bytes in the Unicode™ string, not the number of characters, so it must be twice the number of characters the string can hold. Call with this set to NULL to retrieve the current size.
pszDescription
[out] Pointer to a description string, such as "Awesome Video Compressor".
pcbDescription
[in, out] Size needed for a description string. Pointer to the number of bytes in the Unicode string, not the number of characters, so it must be twice the number of characters the string can hold. Call with this set to NULL to retrieve the current size.
pDefaultKeyFrameRate
[out] Pointer to receive the default key-frame rate.
pDefaultPFramesPerKey
[out] Pointer to receive the default predicted (P) frames per key frame.
pDefaultQuality
[out] Pointer to receive the default quality.
pCapabilities
[out] Pointer to receive the compression capabilities, which are a combination of the CompressionCaps data type flags.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoCompression::get_KeyFrameRate

IAMVideoCompression Interface

Retrieves the current key-frame rate.

Syntax

get_KeyFrameRate(
    long *pKeyFrameRate
    ) PURE;

Parameters

pKeyFrameRate
[out] Pointer to the compressor's current key-frame rate. A negative value means it is using the default frame rate for the video compressor. A zero value means only the first frame is a key frame.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanKeyFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

See Also

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_PFramesPerKeyFrame

IAMVideoCompression Interface

Retrieves the predicted (P) frame interval.

Syntax

HRESULT get_PFramesPerKeyFrame(
    long *pPFramesPerKeyFrame
    ) PURE;

Parameters

pPFramesPerKeyFrame
[out] Pointer to receive the number of P frames per key frame. A negative value means the compressor will use its default value.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanBFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.
As an example of the relationship between the types of frames, suppose a key frame occurs once in every 10 frames, and there are 3 P frames per key frame. The P frames will be spaced evenly between the key frames. The other 6 frames, which occur between the key frames and the P frames, will be bidirectional (B) frames.

See Also

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_Quality

IAMVideoCompression Interface

Retrieves the current image quality setting.

Syntax

HRESULT get_Quality(
    double *pQuality
    ) PURE;

Parameters

pQuality
[out] Pointer to the current quality setting.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The quality is a value between 0 and 1. One indicates the highest (best) quality and 0 indicates the lowest (worst) quality. A negative number means it is using the compressor default. The compressor interprets this number; this interpretation varies from compressor to compressor. When the compressor is not compressing to a specific data rate, the value will roughly determine the image size or quality.
To determine if the compressor supports this method, check for the CompressionCaps_CanQuality flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.
If you are compressing to a fixed data rate, a high quality value means use all of the data rate, and a low quality value means you can use much lower than the data rate.

IAMVideoCompression::get_WindowSize

IAMVideoCompression Interface

Retrieves the number of frames over which the compressor must maintain an average data rate.

Syntax

HRESULT get_WindowSize(
    DWORDLONG *pWindowSize
    );

Parameters

pWindowSize
[out] Pointer to a DWORDLONG value that will receive the window size.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMVideoCompression::put_WindowSize

IAMVideoCompression::OverrideFrameSize

IAMVideoCompression Interface

Overrides a frame's data rate.

Syntax

HRESULT OverrideFrameSize(
    long FrameNumber,
    long Size
    ) PURE;

Parameters

FrameNumber
[in] Frame number for which to change the size.
Size
[in] Desired size, in bytes, for the specified frame.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor might support this method, check for the CompressionCaps_CanCrunch flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method. The flag might also be set to indicate that the dwBitRate value can be set in the AM_MEDIA_TYPE's VIDEOINFOHEADER structure.
The frame number refers to which frame goes out of the filter after it is streaming. For example, frame 0 means the first frame this pin delivers. Frame 11 means the twelfth frame it delivers. Be sure to call this method before the filter delivers the frame for which you want to provide a different size.
Overriding the frame size (or "crunching" the frame) instructs the filter to make the frame size this many bytes or less instead of the originally planned size.

IAMVideoCompression::OverrideKeyFrame

IAMVideoCompression Interface

Forces a frame to be a key frame.

Syntax

HRESULT OverrideKeyFrame(
    long FrameNumber
    ) PURE;

Parameters

FrameNumber
[in] Number of the frame to be made a key frame when the graph runs, even if it wouldn't usually be a key frame.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

After a compressor creates a key frame, it might reset its count to determine when the next key frame should occur. For example, assume a key frame typically occurs once every 10 frames. If you mark frame 5 as a key frame using OverrideKeyFrame, the compressor might wait 10 more frames until creating the next key frame.

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression Interface

Sets the key-frame rate.

Syntax

HRESULT put_KeyFrameRate(
    long KeyFrameRate
    ) PURE;

Parameters

KeyFrameRate
[in] Desired key-frame rate. A negative value means use the default frame rate for the video compressor. A zero value means that only the first frame is a key frame.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanKeyFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

IAMVideoCompression::put_PFramesPerKeyFrame

IAMVideoCompression Interface

Sets predicted (P) frame interval.

Syntax

HRESULT put_PFramesPerKeyFrame(
    long PFramesPerKeyFrame
    ) PURE;

Parameters

PFramesPerKeyFrame
[in] Desired P frame interval. A negative value means use the default frame rate for the video compressor.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanBFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.
As an example of the relationship between the types of frames, suppose a key frame occurs once in every 10 frames, and there are 3 P frames per key frame. The P frames will be spaced evenly between the key frames. The other 6 frames, which occur between the key frames and the P frames, will be bidirectional (B) frames.

IAMVideoCompression::put_Quality

IAMVideoCompression Interface

Sets the quality of the video image.

Syntax

HRESULT put_Quality(
    double Quality
    ) PURE;

Parameters

Quality
[in] Desired quality.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The quality is a value between 0 and 1, inclusive. One indicates the highest (best) quality and 0 indicates the lowest (worst) quality. A negative number means use the compressor default. The compressor (codec) interprets this number; interpretation varies from codec to codec. When the compressor is not compressing to a specific data rate, the value will roughly determine the image size or quality.
To determine if the compressor supports this method, check the CompressionCaps_CanQuality flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.
If you are compressing to a fixed data rate, a high quality value means use all of the data rate, and a low quality value means you can use much lower than the data rate.

IAMVideoCompression::put_WindowSize

IAMVideoCompression Interface

Sets the number of frames over which the compressor must maintain an average data rate.

Syntax

HRESULT put_WindowSize(
    DWORDLONG WindowSize
    );

Parameters

WindowSize
[in] Window size, or number of frames, whose average size cannot exceed the data rate that the compressor has been asked to provide.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For a window of size n, the average frame size of any consecutive n frames will not exceed the stream's specified data rate, although individual frames can be larger or smaller. For example, if you have set a data rate of 100 kilobytes (KB) per second on a 10 frames per second (fps) movie, that will usually mean each frame must be less than or equal to 10 KB. However, by setting a window size of n, you are specifying that as long as the average length of those n frames is less than or equal to 10 KB, it doesn't matter how large the individual frames are. For example, some could be smaller and some could actually be larger than 10 KB, as long as the average is less than or equal to 10 KB.

See Also

IAMVideoCompression::get_WindowSize