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.
When to Implement
Implement this interface on the output pin of a video capture or video compressor filter that provides compressed video data.
When to Use
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.
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. |
Retrieves compressor information.
HRESULT GetInfo(
WCHAR * pszVersion,
int *pcbVersion,
LPWSTR pszDescription,
int *pcbDescription,
long *pDefaultKeyFrameRate,
long *pDefaultPFramesPerKey,
double *pDefaultQuality,
long *pCapabilities
) PURE;
Returns an HRESULT value that depends on the implementation of the interface.
Retrieves the number of frames over which the compressor must maintain an average data rate.
HRESULT get_WindowSize(
DWORDLONG * pWindowSize
);
Returns an HRESULT value that depends on the implementation of the interface.
IAMVideoCompression::put_WindowSize
Retrieves the current key frame rate.
get_KeyFrameRate(
long * pKeyFrameRate
) PURE;
Returns an HRESULT value that depends on the implementation of the interface.
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_KeyFrameRate
Retrieves the predicted (P) frame interval.
HRESULT get_PFramesPerKeyFrame(
long * pPFramesPerKeyFrame
) PURE;
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.
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_KeyFrameRate
Retrieves the current image quality setting.
HRESULT get_Quality(
double * pQuality
) PURE;
Returns an HRESULT value that depends on the implementation of the interface.
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.
Overrides a frame's data rate.
HRESULT OverrideFrameSize(
long FrameNumber,
long Size
) PURE;
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.
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.
Forces a frame to be a key frame.
HRESULT OverrideKeyFrame(
long FrameNumber
) PURE;
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.
Once 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.
Sets the key frame rate.
HRESULT put_KeyFrameRate(
long KeyFrameRate
) PURE;
Returns an HRESULT value that depends on the implementation of the interface.
To determine if the compressor supports this method, check for the CompressionCaps_CanKeyFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.
Sets predicted (P) frame interval.
HRESULT put_PFramesPerKeyFrame(
long PFramesPerKeyFrame
) PURE;
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.
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.
Sets the quality of the video image.
HRESULT put_Quality(
double Quality
) PURE;
Returns an HRESULT value that depends on the implementation of the interface.
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.
Sets the number of frames over which the compressor must maintain an average data rate.
HRESULT put_WindowSize(
DWORDLONG WindowSize
);
Returns an HRESULT value that depends on the implementation of the interface.
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.
IAMVideoCompression::get_WindowSize
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.