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.

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.

If you are using a WDM video capture or compression filter, you can only query for this interface if the 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.

---

IAMVideoCompression::GetInfo

IAMVideoCompression Interface

Retrieves compressor information.

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 Values

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

---

IAMVideoCompression::get_KeyFrameRate

IAMVideoCompression Interface

Retrieves the current key frame rate.

get_KeyFrameRate(
  long * pKeyFrameRate
  ) PURE;

Parameters

pKeyFrameRate

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

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.

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 Values

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.

HRESULT get_Quality(
  double * pQuality
  ) PURE;

Parameters

pQuality

[out] Current quality setting.

Return Values

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.

HRESULT get_WindowSize(
  DWORDLONG * pWindowSize
  );

Parameters

pWindowSize

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

Return Values

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.

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 Values

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.

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 Values

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

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.

---

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression Interface

Sets the key frame rate.

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 Values

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.

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 Values

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.

HRESULT put_Quality(
  double Quality
  ) PURE;

Parameters

Quality

[in] Desired quality.

Return Values

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.

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 Values

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

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

Top of Page