WMV参数设置学习笔记

WMV参数设置学习笔记 Video Codecs and Renderers The following table shows the video codecs and renderers available for Windows CE. All of these codecs and renderers are dependent on DirectShow. Codec or Renderer Sysgen variable DirectShow Video Renderer Filter SYSGEN_DSHOW_VIDREND MPEG-1 Video Codec SYSGEN_DSHOW_MPEGV MS RLE Video Codec SYSGEN_DSHOW_MSRLE Overlay Mixer SYSGEN_DSHOW_OVMIXER Video/Image Compression Manager SYSGEN_DSHOW_ICM WMV/MPEG-4 Video Codec SYSGEN_DSHOW_WMV The specific set of codecs and renderers supported by a Windows CE-based device is determined when the OS design is created. An OS design can contain all, some, or none of these codecs and renderers. See Also Media 1. DirectShow Interfaces The following table shows Microsoft? DirectShow? interfaces. Programming element PPC SP Description IAMBufferNegotiation X X Enables an application to request how many buffers a filter creates and the buffer size. IAMCameraControl X X Provides local or remote control over a camera. IAMDroppedFrames X X Retrieves performance information from a video capture filter, such as how many frames were dropped and how many frames were delivered. IAMExtendedSeeking X X Provides methods for seeking to Interface markers in a Windows Media stream and for modifying the playback speed. IAMFilterMiscFlags X X Indicates whether a filter is a source filter or a renderer. IAMStreamConfig X X Enables applications to query for the types of formats a filter supports on its output pin and to set the format that the pin will offer to its downstream connecting pin. IAMVideo Compression X X Sets and retrieves video compression properties. IAMVideoControl X X Enables you to flip a picture horizontally and/or vertically, set up a stream so it can capture from an external trigger (such as a camera button that the user pushes), simulate an external trigger in software, and list the available frame rates. IAMVideoProcAmp X X Enables an application to adjust the qualities of an incoming video signal, such as brightness, contrast, hue, saturation, gamma, and sharpness. IAMVideoRendererMode X X Manages the rendering mode used by the DirectShow Video Renderer Filter . IAudioRendererWaveOut X X Controls the Audio Renderer Interface (WaveOut) Filter , which uses the Waveform Audio API to render sound. IBaseFilter X X Abstracts an object that has typed input and output connections and can be aggregated dynamically. IBasicAudio X X Supports the filter graph's audio component. IBasicVideo X X Supports the video properties of a generic video window. IBuffering X X Allows you to control the size of the buffer filter in a capture graph. ICaptureGraphBuilder2 X X This interface provides methods for building capture graphs, and other custom filter graphs. The Capture Graph Builder object implements this interface. IDirectDrawVideo X X Allows an application to get details of the surface and any available hardware capabilities. IDMOWrapperFilter X X Enables applications to use DirectX Media Objects in a filter graph. IEnumMediaTypes X X Enumerates the preferred formats for a pin. IEnumPins X X Returns the enumerator interface for pins. IFileSinkFilter Interface X X The IFileSinkFilter2 Interface replaces this interface and inherits from it. IFileSinkFilter2 X X Writes media streams to a file. Interface IFileSourceFilter X X Sets the file name and media type of the media file that a source filter is to render. IFilterGraph X X Represents a graph of filters. IFilterGraph2 X X Adds new functionality to the IGraphBuilder and IFilterGraph interfaces. You should usually use IFilterGraph2 instead of the other two interfaces. IGraphBuilder X X Allows applications to call on the Filter Graph Manager to attempt to build a complete filter graph or parts of a filter graph given only partial information. IImageSinkFilter X X Sets the properties of the image sink filter. IKsPropertySet Interface X X Used to set and retrieve device properties on drivers, and also between software components. IMediaPosition X X It is recommended that you use the IMediaSeeking interface instead of IMediaPosition. This depreciated interface is no longer fully supported. IMediaSample X X Provides shared memory buffer functionality, holds some properties about the data, and holds a pointer to the data itself. IMediaSample2 X X Enables you to set and retrieve sample properties such as start and stop time that are defined in an AM_SAMPLE2_PROPERTIES structure with sample flags defined in the AM_SAMPLE_PROPERTY_FLAGS enumeration. IMediaSeeking X X Improves on the IMediaPosition interface by allowing arbitrary formats for seekable units, such as frames, bytes, and 100-second units of time. IMemAllocator X X Allocates IMediaSample blocks to be used for data transfer between pins. IMemInputPin X X Provides methods on an input pin to facilitate passing data and flush notifications from a connected output pin of an upstream filter. IOverlay X X Provides information so that a filter can write directly to video memory while placing the video in the correct window position. IOverlayNotify X X Provides an upstream filter, such as a decoder, with notifications of changes to the rendering window. IPin X X Represents a single, unidirectional connection point on a filter. IQualityControl X X Defines quality messages and allows a quality manager to install itself as the sink for these messages. IQualProp X X Returns information about the performance achieved — for example, the number of frames per second. IReferenceClock X X Represents a system reference clock to be implemented by a filter in the filter graph and used by other filters. ISmartTee X X Allows you to query for the presence of the Smart Tee Filter in the filter graph. IVideoWindow X X Supports the video window properties of a video renderer. 2. IAMCameraControl Interface This interface provides local or remote control over a camera. Applications can use this interface to control camera settings such as zoom, pan, aperture adjustment, or shutter speed. To obtain this interface, query the filter that controls the camera. In addition to the methods inherited from IUnknown , this interface exposes the following methods. Method Description Get Retrieves the current setting of a camera property. GetRange Rretrieves the range and default value of a specified camera property. Set Sets a specified property on the camera. Remarks Video capture filters automatically exposes this interface if their drivers support the PROPSETID_VIDCAP_CAMERACONTROL property set. CameraControlFlags This enumeration provides values that indicate whether a particular camera setting is controlled manually or automatically. typedef enum{ CameraControl_Flags_Auto = 0x0001, CameraControl_Flags_Manual = 0x0002 } CameraControlFlags; Elements CameraControl_Flags_Auto Indicates that the setting is controlled automatically. CameraControl_Flags_Manual Indicates that the setting is controlled manually. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. Windows CE 5.01 and later OS Versions: Header: IAMCameraControl::Get This method retrieves the current setting of a camera property. HRESULT Get ( long Property, long* lValue, long* Flags ); Parameters Property [in] A long value that specifies the property to retrieve, as a value from the CameraControlProperty enumeration. lValue [out] Pointer to a long variable that receives the value of the property. Flags [out] Pointer to a long variable that receives a member of the CameraControlFlags enumeration. The returned value indicates whether the setting is controlled manually or automatically. Return Values If the method succeeds, it returns S_OK. Otherwise it returns an HRESULT error code. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: CameraControlProperty This enumeration provides values that identify types of camera settings. typedef enum { CameraControl_Pan = 1, CameraControl_Tilt, CameraControl_Roll, CameraControl_Zoom, CameraControl_Exposure, CameraControl_Iris, CameraControl_Focus } CameraControlProperty; Elements CameraControl_Pan Identifies the camera's pan setting, in degrees. Values range from –180 to +180, with the default set to zero. Positive values are clockwise from the origin (the camera rotates clockwise when viewed from above), and negative values are counterclockwise from the origin. CameraControl_Tilt Identifies the camera's tilt setting, in degrees. Values range from –180 to +180, with the default set to zero. Positive values point the imaging plane up, and negative values point the imaging plane down. CameraControl_Roll Identifies the camera's roll setting, in degrees. Values range from –180 to +180, with the default set to zero. Positive values cause a clockwise rotation of the camera along the image-viewing axis, and negative values cause a counterclockwise rotation of the camera. CameraControl_Zoom Identifies the camera's zoom setting, in millimeters. Values range from 10 to 600, and the default is specific to the device. CameraControl_Exposure Identifies the exposure setting, in log base 2 seconds. In other words, for values less than zero, the exposure time is 1/2n seconds, and for values zero or above, the exposure time is 2n seconds. For example: Value Seconds -3 1/8 -2 1/4 -1 1/2 0 1 1 2 2 4 CameraControl_Iris Specifies the camera's iris setting, in units of fstop * 10. CameraControl_Focus Specifies the camera's focus setting, as the distance to the optimally focused target, in millimeters. The range and default value are specific to the device. Remarks For a given property, a particular device might implement only a subset of the listed range. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: IAMCameraControl::GetRange This method retrieves the range and default value of a specified camera property. HRESULT GetRange ( long property, long* pMin, long* pMax, long* pSteppingDelta, long* pDefault, long* pCapsFlags ); Parameters property [in] A long value that specifies the property to query, as a value from the CameraControlProperty enumeration. pMin [out] Pointer to a long variable that receives the minimum value of the property. pMax [out] Pointer to a long variable that receives the maximum value of the property. pSteppingDelta [out] Pointer to a long variable that receives the step size for the property. The step size is the smallest increment by which the property can change. pDefault [out] Pointer to a long variable that receives the default value of the property. pCapsFlags [out] Pointer to a long variable that receives an element of the CameraControlFlags enumeration, indicating whether the property is controlled automatically or manually. Return Values If the method succeeds, it returns S_OK. Otherwise it returns an HRESULT error code. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMCameraControl::Set This method sets a specified property on the camera. HRESULT Set ( long Property, long lValue, long Flags ); Parameters Property [in] A long value that specifies the property to set, as a value from the CameraControlProperty enumeration. lValue [in] A long value that specifes the new value of the property. Flags [in] A long value that specifies the desired control setting, as a member of the CameraControlFlags enumeration. Return Values If method succeeds, it returns S_OK. Otherwise it returns an HRESULT error code. Remarks If the Flags parameter is CameraControl_Flags_Auto, the method ignores the lValue parameter. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: 3. IAMVideoControl Interface This interface enables you to flip a picture horizontally and/or vertically, set up a stream so it can capture from an external trigger (such as a camera button that the user pushes), simulate an external trigger in software, and list the available frame rates. Use this interface when your application runs on hardware that is capable of flipping and external triggering. In addition to the methods inherited from IUnknown , this interface exposes the following methods. Method Description GetCaps Retrieves the capabilities of the underlying hardware. GetCurrentActualFrameRate Retrieves the actual frame rate at which the device is streaming. This method is used with devices, such as the Universal Serial Bus (USB) or cameras that use the IEEE 1394 serial standard, where the maximum frame rate can be limited by bandwidth availability. This is only available during video streaming. GetFrameRateList Retrieves a list of available frame rates. GetMaxAvailableFrameRate Retrieves the maximum frame rate currently available based on bus bandwidth usage for connections such as USB and IEEE 1394 camera devices where the maximum frame rate can be limited by bandwidth availability. GetMode Retrieves the video control mode of operation. SetMode Sets the video control mode of operation. Remarks Video capture filters automatically exposes this interface if the driver supports the PROPSETID_VIDCAP_VIDEOCONTROL property set. For more information, see Camera Drivers. VideoControlFlags This enumeration provides values that specify the video mode of operation for a video device. typedef enum tagVideoControlFlags { VideoControlFlag_FlipHorizontal = 0x0001, VideoControlFlag_FlipVertical = 0x0002, VideoControlFlag_ExternalTriggerEnable = 0x0004, VideoControlFlag_Trigger = 0x0008 } VideoControlFlags; Elements VideoControlFlag_FlipHorizontal Specifies that the picture is flipped horizontally. VideoControlFlag_FlipVertical Specifies that the picture is flipped vertically. VideoControlFlag_ExternalTriggerEnable Sets up a stream to capture a trigger from an external source, for example, a push button on a camera. Buffers can be queued to the driver but will not be passed up from the capture driver (for compression, display, or writing to a file) until the external event happens. See Remarks. VideoControlFlag_Trigger In software, simulates an external trigger when the stream has the VideoControlFlag_ExternalTriggerEnable flag set. Remarks The IAMVideoControl Interface uses the elements of this enumeration. Multiple capture buffers are queued to a capture driver and are filled at a fixed rate once the stream is put into the run state. If the VideoControlFlag_ExternalTriggerEnable flag is set, a filled buffer is not passed up from the WDM capture driver for compression, display, or writing to a file until the external event happens. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: VideoProcAmpFlags This enumeration indicates whether a particular video property is controlled manually or automatically. typedef enum tagVideoProcAmpFlags { VideoProcAmp_Flags_Auto = 0x0001, VideoProcAmp_Flags_Manual = 0x0002, } VideoProcAmpFlags; Elements VideoProcAmp_Flags_Auto Indicates that the property is controlled manually. VideoProcAmp_Flags_Manual Indicates that the property is controlled automatically. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: VideoProcAmpProperty This enumeration specifies video properties on a video capture device. typedef enum tagVideoProcAmpProperty { VideoProcAmp_Brightness, VideoProcAmp_Contrast, VideoProcAmp_Hue, VideoProcAmp_Saturation, VideoProcAmp_Sharpness, VideoProcAmp_Gamma, VideoProcAmp_ColorEnable, VideoProcAmp_WhiteBalance, VideoProcAmp_BacklightCompensation, VideoProcAmp_Gain } VideoProcAmpProperty; Elements VideoProcAmp_Brightness Specifies the brightness, also called the black level. For NTSC, the value is expressed in IRE units * 100. For non-NTSC sources, the units are arbitrary, with zero representing blanking and 10,000 representing pure white. Values range from –10,000 to 10,000. VideoProcAmp_Contrast Specifies the contrast, expressed as gain factor * 100. Values range from zero to 10,000. VideoProcAmp_Hue Specifies the hue, in degrees * 100. Values range from -180,000 to 180,000 (-180 to +180 degrees). VideoProcAmp_Saturation Specifies the saturation. Values range from 0 to 10,000. VideoProcAmp_Sharpness Specifies the sharpness. Values range from 0 to 100. VideoProcAmp_Gamma Specifies the gamma, as gamma * 100. Values range from 1 to 500. VideoProcAmp_ColorEnable Specifies the color enable setting. The possible values are 0 (off) and 1 (on). VideoProcAmp_WhiteBalance Specifies the white balance, as a color temperature in degrees Kelvin. The range of values depends on the device. VideoProcAmp_BacklightCompensation Specifies the backlight compensation setting. Possible values are 0 (off) and 1 (on). VideoProcAmp_Gain Specifies the gain adjustment. Zero is normal. Positive values are brighter and negative values are darker. The range of values depends on the device. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: IPin Interface This interface represents a single, unidirectional connection point on a filter. A pin connects to exactly one other pin on another filter. Other objects can use this interface on this pin. The interface between the filter and the pin is private to the implementation of a specific filter. During the connection process, one pin takes the lead. The base classes assume that this is the output pin of the upstream connecting filter. The filter graph manager calls the IPin::Connect method on this pin's IPin interface, passing the IPin pointer for the connecting pin. This connecting pin then calls the IPin::ReceiveConnection method located on the other pin, in addition to its format-enumeration, IUnknown::QueryInterface, and possibly IPin::QueryAccept methods, to establish whether the connection is possible. When to Implement All filters must implement this interface on each of its pins. Which methods are implemented depends on whether the pin is an input pin or an output pin. Use the CBasePin, CBaseInputPin, or CBaseOutputPin class, or classes derived from these classes, to implement this interface. When to Use This interface is used by other connecting pins and by the filter graph manager. Applications should not use this interface directly but should go through the filter graph manager. Connecting pins use the IPin interface on the opposite pin to negotiate a common media type and an agreed allocator to use for passing samples. Methods in Vtable Order The following table shows the methods that appear in the Vtable beneath the standard COM methods inherited from IUnknown. Method Description Connect Makes a connection to another pin. ReceiveConnection Makes a connection to this pin and is called by a connecting pin. Disconnect Breaks a connection. ConnectedTo Returns a pointer to the connecting pin. ConnectionMediaType Returns the media type of this pin's connection. QueryPinInfo Retrieves information about this pin (for example, the name, owning filter, and direction). QueryId Retrieves an identifier for the pin. QueryAccept Queries whether a given media type is acceptable by the pin. EnumMediaTypes Provides an enumerator for this pin's preferred media types. QueryInternalConnections Provides an array of the pins to which this pin internally connects. EndOfStream Informs the pin that no additional data is expected until a new run command is issued. BeginFlush Informs the pin to begin a flush operation. EndFlush Informs the pin to end a flush operation. NewSegment Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate. QueryDirection Retrieves the direction for this pin. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. IAMVideoControl::GetCaps This method retrieves the capabilities of the underlying hardware. HRESULT GetCaps ( IPin* pPin, long* pCapsFlags ); Parameters pPin IPin interface to query capabilities from. [in] Pointer to an pCapsFlags [out] Pointer to a value representing a combination of the flags from the VideoControlFlags enumeration. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks Possible capabilities include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoControl::GetCurrentActualFrameRate This method retrieves the actual frame rate, expressed as a frame duration in 100-nanosecond units. USB (Universal Serial Bus) and IEEE 1394 cameras may provide lower frame rates than requested because of bandwidth availability. This is only available during video streaming. HRESULT GetCurrentActualFrameRate ( IPin* pPin, LONGLONG* ActualFrameRate ); Parameters pPin [in] A pointer to the IPin interface to retrieve the frame rate from. ActualFrameRate [out] Pointer to a LONGLONG value that will contain the frame rate in terms of 100-nanosecond units. Return Values Returns an HRESULT value that depends on the implementation of the interface. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoControl::GetFrameRateList This method retrieves a list of available frame rates. HRESULT GetFrameRateList ( IPin* , pPin long iIndex, SIZE Dimensions, long* ListSize, LONGLONG** FrameRates ); Parameters pPin [in] Pointer to the IPin interface to query for the list of frame rates. iIndex [in] A long value that is the index of the format to query for frame rates. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps . The value must range between zero and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities ) minus one. Dimensions [in] A SIZE structure that specifies the frame image size (width and height) in pixels. ListSize [out] A pointer to a long value that is the number of elements in the list of frame rates. FrameRates [out] Address of a pointer to an array of LONGLONG values that are frame rates in 100-nanosecond units. Can be NULL if you only need ListSize. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks The caller is responsible for freeing the memory through a call to CoTaskMemFree . Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMStreamConfig::GetStreamCaps This method obtains audio, video, or other capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter. HRESULT GetStreamCaps( int iIndex, AM_MEDIA_TYPE** pmt, BYTE* pSCC ); Parameters iIndex [in] Index to the desired media type and capability pair. Use the IAMStreamConfig::GetNumberOfCapabilities method to retrieve the total number of these pairs. Possible index values range from zero to one less than the total number of pairs. pmt [out] Address of a pointer to an AM_MEDIA_TYPE structure. pSCC [out] Pointer to a stream configuration structure. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks This method enables you to get more information about accepted media types rather than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. Information such as media types, and sizes is returned by the VIDEO_STREAM_CONFIG_CAPS structure. Audio capabilities of the filter's output pin, including the number of inputs, sampling rate, and bit rate granularity, will be returned by an AUDIO_STREAM_CONFIG_CAPS structure. Call DeleteMediaType to free the pmt media type. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMStreamConfig::GetNumberOfCapabilities This method retrieves the number of stream capabilities structures for the compressor. HRESULT GetNumberOfCapabilities( int* piCount, int* piSize ); Parameters piCount [out] Pointer to the number of VIDEO_STREAM_CONFIG_CAPS and/or AUDIO_STREAM_CONFIG_CAPS structures supported. piSize [out] Pointer to the size of the configuration structure, either AUDIO_STREAM_CONFIG_CAPS or VIDEO_STREAM_CONFIG_CAPS. Return Values Returns an HRESULT value that depends on the implementation of the interface. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMVideoControl::GetMaxAvailableFrameRate This method retrieves the maximum frame rate currently available, based on bus bandwidth usage for connections, such as USB and IEEE 1394, where the maximum frame rate may be limited by bandwidth availability. HRESULT GetMaxAvailableFrameRate( IPin* pPin, long iIndex, SIZE , Dimensions LONGLONG* MaxAvailableFrameRate ); Parameters pPin [in] Pointer to the IPin Interface to retrieve the maximum frame rate from. iIndex [in] A long value that specifies the index of the format to query for maximum frame rate. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps . The value must range between zero and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities ) minus one. Dimensions [in] A SIZE structure that specifies the frame image size (width and height) in pixels. MaxAvailableFrameRate [out] Pointer to a LONGLONG value that is the maximum available frame rate. The frame rate is expressed as frame duration in 100-nanosecond units. Return Values Returns an HRESULT value that depends on the implementation of the interface. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoControl::GetMode This method retrieves the video control mode of operation. HRESULT GetMode ( IPin* pPin, long* Mode ); Parameters pPin [in] A pointer to the IPin interface to retrieve the video control mode from. Mode [out] Pointer to a long value representing a combination of the flags from the VideoControlFlags enumeration, which specify the video control mode. Return Values This method returns an HRESULT value that depends on the implementation of the interface. Remarks Possible modes of operation include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoControl::SetMode This method sets the video control mode of operation. HRESULT SetMode ( IPin* pPin, long Mode ); Parameters pPin [in] A point to the IPin interface to set the video control mode on. Mode [in] A long value specifying a combination of the flags from the VideoControlFlags enumeration to set the video control mode. Return Values This method returns an HRESULT value that depends on the implementation of the interface. Remarks Possible modes of operation include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: 4. IAMVideoCompression Interface This interface sets and retrieves video compression properties. It is supported by some video compression filters, and also by some video capture filters that output compressed video. Filters that support this interface expose it through their output pins. An application can use this interface to control how video is compressed, including characteristics such as the key-frame rate or the compression quality. A filter that supports this interface might not support every method. Use the IAMVideoCompression::GetInfo method to determine which methods the filter supports. Note To use this interface on a capture filter, you might need to connect the filter to another filter in the graph. In addition to the methods inherited from IUnknown , thisinterface exposes the following methods. Method Description get_KeyFrameRate Retrieves the key-frame rate. get_PFramesPerKeyFrame Retrieves the P frame frequency. get_Quality Retrieves the compression quality. get_WindowSize Retrieves the number of frames over which the compressor must maintain an average data rate. GetInfo Retrieves information about the filter's compression properties, including capabilities and default values. OverrideFrameSize Overrides a particular frame's data rate. OverrideKeyFrame Forces a particular frame to be a key frame. put_KeyFrameRate Sets the key-frame rate. put_PFramesPerKeyFrame Sets the predicted (P) frame frequency. put_Quality Sets the compression quality. put_WindowSize Sets the number of frames over which the compressor must maintain an average data rate. Remarks Video capture filters automatically exposes this interface if the driver supports the PROPSETID_VIDCAP_VIDEOCOMPRESSION property set. CompressionCaps Indicates video compression capabilities. typedef enum { CompressionCaps_CanQuality = 0x01, CompressionCaps_CanCrunch = 0x02, CompressionCaps_CanKeyFrame = 0x04, CompressionCaps_CanBFrame = 0x08, CompressionCaps_CanWindow = 0x10 } CompressionCaps; Elements CompressionCaps_CanQuality Video compressor supports the IAMVideoCompression::put_Quality and IAMVideoCompression::get_Quality methods. CompressionCaps_CanCrunch Video compressor can compress video to a specified data rate. If the compressor has this capability then the output pins media type will contain the data rate in the VIDEOINFOHEADER structure's dwBitRate member. The only way to set the data rate is to set dwBitRate. CompressionCaps_CanKeyFrame Video compressor supports the IAMVideoCompression::put_KeyFrameRate and IAMVideoCompression::get_KeyFrameRate methods. CompressionCaps_CanBFrame Video compressor supports the IAMVideoCompression::put_PFramesPerKeyFrame and IAMVideoCompression::get_PFramesPerKeyFrame methods. CompressionCaps_CanWindow Video compressor supports the IAMVideoCompression::put_WindowSize and IAMVideoCompression::get_WindowSize methods. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: VIDEOINFOHEADER This structure describes the bitmap and color information for a video image. typedef struct tagVIDEOINFOHEADER { RECT rcSource; RECT rcTarget; DWORD dwBitRate; DWORD dwBitErrorRate; REFERENCE_TIME AvgTimePerFrame; BITMAPINFOHEADER bmiHeader; } VIDEOINFOHEADER; Members rcSource RECT structure that specifies the source video window. This structure can be a clipping rectangle, to select a portion of the source video stream. See Source and Target Rectangles in Video Renderers for examples of how this member works. rcTarget RECT structure that specifies the destination video window. See Source and Target Rectangles in Video Renderers for examples of how this member works. dwBitRate DWORD value that specifies the video stream's approximate data rate, in bits per second. dwBitErrorRate DWORD value that specifies the video stream's data error rate, in bit errors per second. AvgTimePerFrame REFERENCE_TIME value that specifies the video frame's average display time, in 100-nanosecond units. bmiHeader Win32 BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. Setting Up the Build Environment. For more information, see OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: Dshow.h. IAMVideoCompression::get_KeyFrameRate This method retrieves the current key-frame rate. get_KeyFrameRate( long* pKeyFrameRate ); Parameters pKeyFrameRate [out] Pointer to a long variable that receives the current key-frame rate. If the value is negative, the filter will use the default key-frame rate. If the value is zero, only the first frame is a key frame. Return Values Returns an HRESULT value. Remarks The key-frame rate is the number of frames per key frame. For example, if the rate is 15, then a key frame occurs every 15 frames. To determine if the filter supports this method, call the IAMVideoCompression::GetInfo method and check for the CompressionCaps_CanKeyFrame (see CompressionCaps) flag in the pCapabilities parameter. The GetInfo method also returns the default key-frame rate. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoCompression::GetInfo This method retrieves information about the filter's compression properties, including capabilities and default values. 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 WCHAR buffer that receives a version string, such as "Version 2.1.0." pcbVersion [in, out] Pointer to an int variable that receives the size of the version string, in bytes. pszDescription [out] A LPWSTR buffer that receives a description string, such as "My Video Compressor." pcbDescription [in, out] Pointer to an int variable that receives the size of the description string. pDefaultKeyFrameRate [out] Pointer to a long variable that receives the default key-frame rate. pDefaultPFramesPerKey [out] Pointer to a long variable that receives the default rate of predicted (P) frames per key frame. pDefaultQuality [out] Pointer to a double variable that receives the default quality. pCapabilities [out] Pointer to a long variable that receives the compression capabilities, as a bitwise combination of zero or more CompressionCaps flags. Return Values Returns an HRESULT value. Remarks Any of the listed parameters can be NULL, in which case the method ignores that parameter. The application must allocate the buffers for the version and description strings. To determine the required size of the buffers, call this method with NULL for the pszVersion and pszDescription parameters. Use the values returned in pcbVersion and pcbDescription to allocate the buffers and then call the method again, as shown in the following code: int cbVersion, cbDesc; // Size in bytes, not characters! hr = pCompress->GetInfo(0, &cbVersion, 0, &cbDesc, 0, 0, 0, 0); if (SUCCEEDED(hr)) { WCHAR *pszVersion = new WCHAR[cbVersion/2]; // Wide character = 2 bytes WCHAR *pszDesc = new WCHAR[cbDesc/2]; if (pszVersion && pszDesc) { hr = pCompress->GetInfo(pszVersion, 0, pszDesc, 0, 0, 0, 0, 0); } delete [] pszVersion; delete [] pszDesc; } Note that the strings are wide-character strings, and the returned sizes are in bytes, not number of characters. Also, one or both strings might be zero-length. The parameter receives a set of flags indicating which pCapabilities compression properties are supported, and thus which IAMVideoCompression interface methods are supported. For example, if the CompressionCaps_CanKeyFrame flag is returned, the filter supports the IAMVideoCompression::get_KeyFrameRate and IAMVideoCompression::put_KeyFrameRate methods. The remaining parameters receive default values for the compression properties. For unsupported properties (as determined by the flags returned in ), you should ignore the corresponding default pCapabilities value, as it may not be correct or meaningful. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoCompression::get_PFramesPerKeyFrame Thsi method retrieves the rate of predicted (P) frames per key frame. HRESULT get_PFramesPerKeyFrame( long* pPFramesPerKeyFrame ); Parameters pPFramesPerKeyFrame [out] Pointer to a long variable that receives the number of P frames per key frame. If the value is negative, the filter will use the default rate. Return Values Returns an HRESULT value. IAMVideoCompression::get_Quality This method retrieves the current compression quality. HRESULT get_Quality( double* pQuality ); Parameters pQuality [out] Pointer to a double variable that receives the relative compression quality. The quality is expressed as a value between 0.0 and 1.0, where 1.0 indicates the best quality and 0.0 indicates the worst quality. If the value is negative, the filter will use the default quality. Return Values Returns an HRESULT value. IAMVideoCompression::get_WindowSize This method retrieves the number of frames over which the compressor will maintain the average data rate. For example, assuming a data rate of 100K/sec and a frame rate of 10 frames per second, if the window size is 1, then every frame will be 10K or less. If the window size is 5, then every five consecutive frames will average 10K per frame, but individual frames may exceed this size. The default window size is 1. HRESULT get_WindowSize( DWORDLONG* pWindowSize ); Parameters pWindowSize [out] Pointer to a DWORDLONG variable that receives the window size, expressed as a number of frames. Return Values Returns an HRESULT value. Possible values include the following. Value Description S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later. Header: IAMVideoCompression::OverrideFrame Size This method overrides the frame size of a specified frame. HRESULT OverrideFrameSize( long FrameNumber, long Size ); Parameters FrameNumber [in] A long value that specifies the frame number. The first frame that the filter delivers is numbered zero. Size [in] A long value that specifies the maximum size of the specified frame, in bytes. Return Values Returns an HRESULT value. The following table shows some of the possible return values. Value Description S_OK Success. E_NOTIMPL Not implemented. Remarks If the filter supports this method, the IAMVideoCompression::GetInfo method will return the CompressionCaps_CanCrunch flag (see CompressionCaps) in the pCapabilities parameter. However, this flag can also indicate that the filter supports setting the bit rate, so it does not guarantee that the OverrideFrameSize method is supported. IAMVideoCompression::OverrideKeyFrame This method instructs the filter to compress a particular frame as a key frame. HRESULT OverrideKeyFrame( long FrameNumber ); Parameters FrameNumber [in] A long value that specifies the frame number. The first frame that the filter delivers is numbered zero. Return Values Returns an HRESULT value. The following table shows some of the possible return values. Value Description S_OK Success. E_NOTIMPL Not implemented. Remarks If the filter supports this method, you can use it to override the normal key-frame distribution for a particular frame. After the filter creates a key frame, it might reset its count to determine when the next key frame should occur. For example, if the key-frame rate is 10, and an application uses this method to force frame 5 as a key frame, the filter might wait another 10 frames (until frame 15) before it creates the next key frame. IAMVideoCompression::put_KeyFrameRate This method sets the key-frame rate. HRESULT put_KeyFrameRate( long KeyFrameRate ); Parameters KeyFrameRate [in] A long value that identifies the desired key-frame rate. If the value is negative, the filter will use the default key-frame rate. If the value is zero, only the first frame will be a key frame. Return Values This method returns an HRESULT value. Remarks To determine if the filter supports this method, call the IAMVideoCompression::GetInfo method and check for the CompressionCaps_CanKeyFrame flag (see CompressionCaps) in the pCapabilities parameter. The GetInfo method also returns the default key-frame rate. IAMVideoCompression::put_PFramesPerKeyFrame This method sets the rate of predicted (P) frames per key frame. HRESULT put_PFramesPerKeyFrame( long PFramesPerKeyFrame ); Parameters PFramesPerKeyFrame [in] Specifies the number of P frames per key frame. If the value is negative, the filter will use the default rate. Return Values Returns an HRESULT value. Remarks To determine if the filter supports this method, call the IAMVideoCompression::GetInfo method and check for the CompressionCaps_CanBFrame flag (see CompressionCaps) in the pCapabilities parameter. The GetInfo method also returns the default P-frame rate. IAMVideoCompression::put_Quality This method sets the compression quality. HRESULT put_Quality( double Quality ); Parameters Quality [in] Specifies the quality as a value between 0.0 and 1.0, where 1.0 indicates the best quality and 0.0 indicates the worst quality. If the value is negative, the filter will use the default quality. Return Values This method returns an HRESULT value. Remarks To determine if the filter supports this method, call the IAMVideoCompression::GetInfo method and check for the CompressionCaps_CanQuality flag (see CompressionCaps) in the pCapabilities parameter. The GetInfo method also returns the default quality. IAMVideoCompression::put_WindowSize This method sets the number of frames over which the compressor must maintain an average data rate. For example, assuming a data rate of 100K/sec and a frame rate of 10 frames per second, if the window size is 1, then every frame will be 10K or less. If the window size is 5, then every five consecutive frames must average 10K per frame, but individual frames may exceed this size. HRESULT put_WindowSize( DWORDLONG WindowSize ); Parameters WindowSize [in] Specifies the window size, expressed as a number of frames. . Return Values This method returns an HRESULT value. 5. ICaptureGraphBuilder2 Interface This interface provides methods for building capture graphs, and other custom filter graphs. The Capture Graph Builder object implements this interface. The Capture Graph Builder is a helper object for building video and audio capture graphs. Capture and editing applications can use this component to construct filter graphs. The following code shows how to create this object using CoCreateInstance . CoCreateInstance( CLSID_CaptureGraphBuilder, NULL, CLSCTX_INPROC_SERVER, IID_ICaptureGraphBuilder2, (void**) &pCaptureGraphBuilder) In addition to the methods inherited from IUnknown , the ICaptureGraphBuilder2 interface exposes the methods shown in the following table. Method Description ControlStream Sets the start and stop times for one or more streams of captured data. FindInterface Searches the graph for a specified interface, starting from a specified filter. FindPin Retrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria. GetFiltergraph Retrieves the filter graph that the builder is using. RenderStream Connects an output pin on a source filter to a rendering filter, optionally through a compression filter. SetFiltergraph Specifies a filter graph for the capture graph builder to use. SetOutputFileName Creates the file writing section of the filter graph. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: ICaptureGraphBuilder2::ControlStream This method sets the start and stop times for one or more streams of captured data. HRESULT ControlStream( const GUID* pCategory, const GUID* pType, IBaseFilter* , pFilter REFERENCE_TIME* pstart, REFERENCE_TIME* pstop, WORD wStartCookie, WORD wStopCookie ); Parameters pCategory [in] Pointer to a GUID for a category of the AMPROPERTY_PIN_CATEGORY property (see Pin Property Set ). The value of this parameter cannot be NULL. pType [in] Pointer to a major type GUID that specifies the media type, or NULL. If this parameter is NULL, set the pFilter parameter to NULL as well. Otherwise, you might control the wrong pin and get unpredictable results. pFilter [in] Pointer to an IBaseFilter interface that specifies which filter to control. To control all the capture filters in the graph, set this parameter to NULL. pstart [in] Pointer to a variable that contains the start time. If the value is MAXLONGLONG (0x7FFFFFFFFFFFFFFF), the method cancels the previous start request. If the value is NULL, the pin starts immediately when the graph runs. pstop [in] Pointer to a variable that contains the stop time. If the value is MAXLONGLONG, the method cancels any previous stop request. If the value is NULL, the pin stops immediately. wStartCookie [in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STARTED event notification. See Remarks for more information. wStopCookie [in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STOPPED event notification. See Remarks for more information. Return Values Returns an HRESULT value. Possible values include the following. Return Code Description S_FALSE At least one downstream renderer will not send a stop notification. S_OK Success. E_FAIL Could not find a matching pin, or the pin did not support stream control. E_POINTER NULL pointer argument. Remarks This method locates output pins on capture filters, using search criteria that you supply in the method call. Then it calls the IAMStreamControl interface methods on those pins. This method enables an application to control streams without the application needing to enumerate the filters and pins in the graph. Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you can stop capturing to disk but leave video preview running. The first three parameters specify which pins to control. A capture graph can have more than one capture filter. For example, it might have filters for video, audio, and closed captioning data. Also, a capture filter can have more than one output pin. Some capture filters have separate pins for preview and capture, or separate pins for video-only data and audio-video interleaved data. To control video preview, for example, specify PIN_CATEGORY_PREVIEW for pCategory and MEDIATYPE_Video for pType. Note If the pin category is PIN_CATEGORY_PREVIEW, you cannot set specific start and stop times, because the samples delivered by a preview pin have no time stamps (see Time and Clocks in DirectShow ). Instead, use the values NULL and MAXLONGLONG to start and stop the pin at the desired times. Also, this method is not supported for preview if the device uses a video port pin, because in that case the device is delivering the preview samples directly over hardware. To control a pin, this method calls the IAMStreamControl::StartAt and IAMStreamControl::StopAt methods. Each pin sends an EC_STREAM_CONTROL_STARTED event notification when it starts. The second parameter of the event notification is the value given in wStartCookie. When the pin stops, it sends an EC_STREAM_CONTROL_STOPPED event notification. The second parameter of that event notification is the value given in wStopCookie. When this method locates a matching pin, it searches downstream for another filter that supports IAMStreamControl (typically a multiplexer). If it finds one, it also sets the start and stop times on that filter. This generates two pairs of stop notifications: one for the capture filter, and one for the downstream filter. Only the stop notification from the downstream filter uses the wStopCookie parameter. Waiting for this event guarantees that the downstream filter receives the last sample. If no downstream filter supports IAMStreamControl, the method returns S_FALSE. In that case, you might receive the stop notification before the last sample is rendered. MAXLONGLONG is the largest possible REFERENCE_TIME value. In the DirectShow base class library, it is also defined as the constant MAX_TIME. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: ICaptureGraphBuilder2::FindInterface This method searches the graph for a specified interface, starting from a specified filter. You can restrict the search to a section of the graph upstream or downstream of the filter, or restrict it to a particular pin category or media type. HRESULT FindInterface( const GUID* pCategory, const GUID* pType, IBaseFilter* pf, REFIID riid, void** ppint ); Parameters pCategory [in] Pointer to a GUID that specifies the search criteria. See Remarks for more information. The following values are possible: , &LOOK_UPSTREAM_ONLY , &LOOK_DOWNSTREAM_ONLY , A pin category from the AMPROPERTY_PIN_CATEGORY property set (see Pin Property Set ). , NULL See Remarks for more information. pType [in] Pointer to a GUID that specifies the major media type of an output pin, or NULL. pf [in] Pointer to the IBaseFilter interface of the filter. The method begins searching from this filter. riid [in] Interface identifier (IID) of the interface to locate. ppint [out] Address of a variable that receives the interface pointer. Be sure to release the retrieved interface pointer when you are done with the interface. Return Values Returns an HRESULT value. Possible values include the following. Return Code Description S_OK Success. E_FAIL Failure. E_NOINTERFACE No such interface supported. E_POINTER NULL pointer argument. Remarks In a capture graph, various filters and pins might expose interfaces for setting properties such as compression parameters (IAMVideoCompression interface) or stream formats (IAMStreamConfig interface ). You can use this method to find an interface, without writing special code that traverses the graph. Note Do not call this method to obtain an IVideoWindow Interface pointer. Always query the filter graph manager for this interface. Otherwise, the filter graph manager will not respond correctly to changes in screen resolution and other events. If the pCategory parameter is NULL, this method searches the entire graph for the requested interface. Starting from the filter specified by the pf parameter, it queries the following objects in the graph. , The filter , The filter's pins , All the downstream filters, including their pins , All the upstream filters, including their pins You can restrict the search by setting the pCategory and pType parameters, as follows: , If pCategory equals &LOOK_UPSTREAM_ONLY, the search starts from the filter's input pins and continues upstream. It does not include the filter or anything downstream from the filter. The pType parameter is ignored. , If pCategory equals &LOOK_DOWNSTREAM_ONLY, the search starts from the filter's output pins and continues downstream. It does not include the filter or anything upstream from the filter. The pType parameter is ignored. , If specifies a pin category, the downstream portion of pCategory the search is restricted to output pins on the filter that match both the pin category and the media type given in the parameter. pType In this case, the method also searches the filter and everything upstream from the filter. Pin categories are useful for finding pin interfaces on capture filters. For example, a capture filter might have separate pins for capture and preview. If you specify a pin category, you should also specify the media type, to make certain the method selects the correct filter and pin. Some video capture filters have a video port pin (PIN_CATEGORY_VIDEOPORT) instead of a preview pin. If you specify PIN_CATEGORY_PREVIEW and MEDIATYPE_Video (see Media Types ), the method treats any video port pins as preview pins. Your application does not have to test for this possibility. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: ICaptureGraphBuilder2::FindPin This method retrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria. HRESULT FindPin( IUnknown* pSource, PIN_DIRECTION pindir, const GUID* pCategory, const GUID* pType, BOOL fUnconnected, int num, IPin** ppPin ); Parameters pSource [in] Pointer to an interface on a filter, or to an interface on a pin. pindir [in] Member of the PIN_DIRECTION enumeration that specifies the pin direction (input or output). pCategory [in] A pointer to a pin category from the AMPROPERTY_PIN_CATEGORY property set (see Pin Property Set ). Use NULL to match any category. pType [in] Pointer to a major type GUID that specifies the media type. Use NULL to match any media type. fUnconnected [in] Boolean value that specifies whether the pin must be unconnected. If TRUE, the pin must be unconnected. If FALSE, the pin can be connected or unconnected. num [in] Zero-based index of the pin to retrieve, from the set of matching pins. If pSource is a pointer to a filter, and more than one pin matches the search criteria, this parameter specifies which pin to retrieve. If pSource is a pointer to a pin, this parameter is ignored. ppPin [out] Address of a pointer to receive the IPin interface of the matching pin. Return Values Returns S_OK if a matching pin is found, or E_FAIL otherwise. Remarks If pSource is a pointer to a filter, the method searches for the nth pin on that filter that matches the search criteria, where n is given by the num parameter. If the method finds a matching pin, it returns a pointer to the pin in the ppPin parameter. If pSource is a pointer to a pin, the method tests that pin against the search criteria. If the pin matches the criteria, the method returns S_OK, and returns a pointer to the pin's IPin interface in the ppPin parameter. Otherwise, it returns E_FAIL. In either case, if the method succeeds, the IPin interface returned in the ppPin parameter has an outstanding reference count. Be sure to release the interface when you are done using it. Typically, an application will not need to use this method. It is provided for unusually complex tasks, when the ICaptureGraphBuilder2::RenderStream method cannot build the filter graph. Use this method to retrieve a desired pin from a capture filter, and then build the rest of the graph manually. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: Pin Property Set Applies to: Devices based on Windows Mobile Version 5.0 and later The pin property set returns the pin category for a pin on a filter. The filter sets the category when it creates the pin; the category indicates what type of data the pin is delivered or receives by this pin. The GUID for the pin property set is AMPROPSETID_Pin. The following table shows the properties for the pin property set Property ID Description AMPROPERTY_PIN_CATEGORY The only property defined in this property set is the pin category property (AMPROPERTY_PIN_CATEGORY). The value of the property is a GUID data type. The following table shows the categories for the pin property set. Category GUID Description PIN_CATEGORY_ANALOGVIDEOIN Input pin of the capture filter that takes analog and digitizes it. PIN_CATEGORY_CAPTURE Capture pin. PIN_CATEGORY_CC Pin providing closed captioning data from Line 21. PIN_CATEGORY_EDS Pin providing Extended Data Services (Line 21, even fields). PIN_CATEGORY_NABTS Pin providing North American Videotext Standard data. PIN_CATEGORY_PREVIEW Preview pin. PIN_CATEGORY_STILL Pin that provides a still image. The filter's capture pin must be connected before the still-image pin is connected. PIN_CATEGORY_TELETEXT Pin providing teletext (a closed captioning variant). PIN_CATEGORY_TIMECODE Pin providing timecode data. PIN_CATEGORY_VBI Pin providing vertical blanking interval data. PIN_CATEGORY_VIDEOPORT Video output pin to be connected to input pin zero on the Overlay Mixer. PIN_CATEGORY_VIDEOPORT_VBI Pin to be connected to the VBI Surface Allocator, the VBI surface allocator filter that is needed to allocate the correct video memory for things like closed captioning overlays in scenarios where a video port is being used. PCI, IEEE 1394, and USB scenarios do not use this filter. PINNAME_VIDEO_CC_CAPTURE Hardware slicing closed-captioning pin This property is read-only. The following code shows how to check whether a pin supports this property set, and if so, how to obtain the pin category. HRESULT GetPinCategory(IPin *pPin, GUID *pPinCategory) { HRESULT hr; IKsPropertySet *pKs; hr = pPin->QueryInterface(IID_IKsPropertySet, (void **)&pKs); if (FAILED(hr)) { // The pin does not support IKsPropertySet. return hr; } // Try to retrieve the pin category. DWORD cbReturned; hr = pKs->Get(AMPROPSETID_Pin, AMPROPERTY_PIN_CATEGORY, NULL, 0, pPinCategory, sizeof(GUID), &cbReturned); // If this succeeded, pPinCategory now contains the category GUID. pKs->Release(); return hr; } ICaptureGraphBuilder2::GetFiltergraph This method retrieves the filter graph that the capture graph builder is using. HRESULT GetFiltergraph( IGraphBuilder** ppfg ); Parameters ppfg [out] Address of a variable that receives an IGraphBuilder interface pointer. Return Values Returns one of the following HRESULT values. Return Code Description S_OK Success. E_POINTER NULL pointer argument. E_UNEXPECTED No filter graph. Remarks Initially, the capture graph builder does not hold a pointer to a filter graph. This method returns E_UNEXPECTED until one of the following methods has been called: , ICaptureGraphBuilder2::RenderStream , ICaptureGraphBuilder2::SetFiltergraph , ICaptureGraphBuilder2::SetOutputFileName This method increments the reference count on the IGraphBuilder interface. Be sure to release the interface when you are done with it. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: ICaptureGraphBuilder2::RenderStream This method connects an output pin on a source filter to a sink filter, optionally through an intermediate filter. HRESULT RenderStream( const GUID* pCategory, const GUID* pType, IUnknown* pSource, IBaseFilter* pIntermediate, IBaseFilter* pSink ); Parameters pCategory [in] A pointer to a pin category from the AMPROPERTY_PIN_CATEGORY property set (see Pin Property Set ). Use NULL to match any category. The following list shows typical categories. , PIN_CATEGORY_CAPTURE , PIN_CATEGORY_PREVIEW , PIN_CATEGORY_CC pType [in] Pointer to a major-type GUID that specifies the media type of the output pin; or NULL to use any pin, regardless of media type. For a list of possible values, see Media Types . pSource [in] Specifies a pointer to the starting filter for the connection, or to an output pin. pIntermediate [in] Pointer to the IBaseFilter interface of an intermediate filter, such as a compression filter. Can be NULL. pSink [in] Pointer to the IBaseFilter interface of a sink filter, such as a renderer or mux filter. If the value is NULL, the method uses a default renderer (see Remarks). Return Values Returns an HRESULT value. Possible return values include the following. Return Code Description S_OK Success. VFW_S_NOPREVIEWPIN Preview was rendered through the Smart Tee Filter . E_FAIL Failure. E_INVALIDARG Invalid argument. E_POINTER NULL pointer argument. VFW_E_NOT_IN_GRAPH A filter is not in the filter graph. This error can occur if you did not call AddFilter to add pSource, pIntermediate, or pSink to the graph. It can also occur if you did not call SetFiltergraph to connect your graph to the Capture Graph Builder; in this case, the Capture Graph Builder object automatically creates its own filter graph. See Capture Graph Builder . Remarks This method renders a stream by connecting two or more filters together in a chain: , The pSource parameter specifies the start of the chain, either a filter or an output pin. , The pIntermediate parameter specifies an intermediate filter, typically a compression filter. This parameter can be NULL. , The pSink parameter specifies the filter at the end of the chain. Typically, this filter is either a renderer for preview, or a mux for file capture. The method connects pSource to pIntermediate, and then connects pIntermediate to pSink. If pIntermediate is NULL, the method just connects pSource to pSink. All of the filters specified by pSource, pIntermediate, and pSink must be added to the graph prior to calling the method. The method uses Intelligent Connect, so additional filters such as decoders might be added to the graph. If the pSink parameter is NULL, the method tries to use a default renderer. For video it uses the Video Renderer, and for audio it uses the Waveform Audio Renderer . If pSource is a filter, the method searches for an output pin on that filter. In that case, use the pCategory and pType parameters to narrow the search. For example, if a filter has separate pins for preview and capture, you can specify either PIN_CATEGORY_CAPTURE or PIN_CATEGORY_PREVIEW. If pSource is an output pin, set the pCategory and pType to NULL. In all cases, the method searches for unconnected pins. If more than one pin meets the specified criteria, the method uses the first such pin that it finds. Note that for DV capture, if the media type is MEDIATYPE_Interleaved and the pSink parameter is NULL, the method splits the interleaved stream into an audio stream and a video stream, and renders both of those streams. The RenderStream method handles many of the details required for capture graphs: Smart Tee. Some capture filters have a capture pin but no preview pin. To preview, the capture pin must be connected to the Smart Tee Filter . This filter splits the data into two streams, a capture stream and a preview stream. When you specify PIN_CATEGORY_PREVIEW or PIN_CATEGORY_CAPTURE, the method inserts a Smart Tee filter if one is needed. Then it renders the specified stream on the Smart Tee filter. If you render a preview stream and the method uses a Smart Tee filter, it returns VFW_S_NOPREVIEWPIN. Video Port Pins. Filters that work with video port extension (VPE) video capture hardware might have video port pins (PIN_CATEGORY_VIDEOPORT) instead of preview pins. For preview or capture to work, a video port pin must connect to the Overlay Mixer Filter. The method handles this detail. You do not have to specify PIN_CATEGORY_VIDEOPORT. Specify PIN_CATEGORY_PREVIEW or PIN_CATEGORY_CAPTURE, and the method will connect the pin correctly. In a similar way, some filters deliver VBI data using video port pins (PIN_CATEGORY_VIDEOPORT_VBI). As with PIN_CATEGORY_VIDEOPORT, the method handles this detail. You do not have to specify PIN_CATEGORY_VIDEOPORT_VBI. The following code shows a typical capture graph that connects the preview pin to the default renderer with no intermediate filter: // Video: pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video, pCaptureFilter, NULL, NULL); // Audio: pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio, pCaptureFilter, NULL, NULL); Connect the capture pin to a mux filter or file writer filter, depending on what type of file you wish to output. For AVI files, use the AVI Mux filter. For ASF files, use the WM ASF Writer filter. Typically, you will the parameter of the get a pointer to this filter from ppf ICaptureGraphBuilder2::SetOutputFileName method. pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", &ppf, &pSink); pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video, pCaptureFilter, NULL, ppf); For more examples, see Video Capture. File Sources. You can use this method to transcode or recompress a file. The following discussion assumes that the file has at most one video stream and one audio stream, or else a single interleaved stream. Otherwise, the method will not work correctly. A file source has one output pin, so set pCategory and pType to NULL. Call the method twice—once to render the video stream, and once to render the audio stream. The first call connects the source filter to a parser filter and renders one of the parser filter's output pins. The second call renders the parser's remaining output pin. If you are compressing one stream but not the other, make sure to specify the compressor filter in the first call. The method will automatically pick the correct stream based on the compression type. pBuilder->RenderStream(NULL, NULL, pSrc, pCompressor, pMux); pBuilder->RenderStream(NULL, NULL, pSrc, NULL, pMux); For a complete example, see Recompressing an AVI File. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: Smart Tee Filter Applies to: Devices based on Windows Mobile Version 5.0 and later The Smart Tee filter is used in video capture graphs to split the video stream into a preview stream and a capture stream. This is done without any additional data copying. The output pins support whatever media types are supported on the downstream connection. The Smart Tee filter is useful when a video capture filter does not provide separate pins for capture and preview. The Smart Tee filter delivers preview data only if doing so does not hurt capture performance. It also removes the time stamps from the preview stream. The capture graph builder automatically inserts the Smart Tee filter when needed. For more information, see Combining Video Capture and Preview. The following illustration shows a typical capture graph that uses the Smart Tee filter. The following table shows the filter properties. Filter property Description Filter Interfaces IBaseFilter Input Pin Media Types MEDIATYPE_Video, MEDIASUBTYPE_NULL Input Pin Interfaces IMemInputPin, IPin, IQualityControl Output Pin Media Types MEDIATYPE_Video, MEDIASUBTYPE_NULL Output Pin Interfaces IAMStreamControl, IPin, IQualityControl Filter CLSID CLSID_SmartTee Property Page CLSID No property page. Executable qcap.dll Merit MERIT_DO_NOT_USE Filter Category CLSID_LegacyAmFilterCategory ICaptureGraphBuilder2::SetFiltergr aph This method specifies a filter graph for the capture graph builder to use. HRESULT SetFiltergraph( IGraphBuilder* pfg ); Parameters pfg [in] Pointer to the filter graph's IGraphBuilder interface . Return Values Returns an HRESULT value. The following table shows some possible return values. Return code Description S_OK Success. E_POINTER NULL pointer argument. E_UNEXPECTED Unexpected error. Remarks If you do not call this method, the capture graph builder automatically creates a filter graph when it needs one. If the capture graph builder already has a filter graph, this method returns E_UNEXPECTED. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: ICaptureGraphBuilder2::SetOutputFileName This method creates the file writing section of the filter graph. HRESULT SetOutputFileName( const GUID* pType, LPCOLESTR lpwstrFile, IBaseFilter** ppf, IFileSinkFilter** pSink ); Parameters pType [in] Pointer to a GUID that represents either the media subtype of the output or the class identifier (CLSID) of a multiplexer filter or file writer filter. If you specify a media subtype, it must be one of the subtypes shown in the following table. Value Description MEDIASUBTYPE_Avi Audio-Video Interleaved (AVI) MEDIASUBTYPE_Asf Advanced Systems Format (ASF) lpwstrFile [in] Pointer to a wide-character string that contains the output file name. ppf [out] Address of a pointer that receives the multiplexer's IBaseFilter interface . pSink [out] Address of a pointer that receives the file writer's IFileSinkFilter2 interface. Can be NULL. Return Values Returns an HRESULT value. The following table shows some possible return values. Return code Description S_OK Success. E_FAIL Failure. E_POINTER Null pointer argument. Remarks This method creates a multiplexer filter based on the value of the pType parameter. For AVI, it creates the AVI Mux Filter. For ASF, it creates the WM ASF Writer. For other values, it creates the filter identified by the CLSID. It adds the multiplexer to the filter graph, and returns a pointer to its IBaseFilter interface in the ppf parameter. If the multiplexer supports the IFileSinkFilter2 interface, the method calls IFileSinkFilter2::SetFileName to set the output file name, using the value given in the lpwstrFile parameter. You can use the pointer to the multiplexer filter, returned in the ppf parameter, as the pSink parameter in the ICaptureGraphBuilder2::RenderStream method. For custom multiplexer filters, the method fails if the filter does not support a connection on its output pin before its input pins are connected. If the method succeeds, the IBaseFilter interface returned in the ppf parameter has an outstanding reference count. If the method succeeds and pSink is not NULL, the IFileSinkFilter interface also has an outstanding reference count. Be sure to release both interfaces when you are done using them. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: 6. IFileSinkFilter Interface Send Feedback on this topic to the authors See Also DirectShow Interfaces | IFileSinkFilter2 Interface The IFileSinkFilter2 Interface replaces this interface and inherits from it. This interface is implemented on filters that write media streams to a file. A file sink filter in a video capture filter graph, for instance, writes the output of the video compression filter to a file. Typically, the application running this filter graph should enable the user to enter the name of the file to be written to. This interface enables the communication of this information. If a filter needs the name of an output file, it should expose this interface to allow an application to set the file name. Note that there is currently no base class implementation of this interface. Any application that must set the name of the file into which the file sink filter will write should use this interface to get and set the file name. In addition to the methods inherited from IUnknown , the IFileSinkFilter interface exposes the following methods. Method Description IFileSinkFilter::GetCurFile Retrieves the name of the current file into which media samples will be written. IFileSinkFilter::SetFileName Sets the name of the file into which media samples will be written. IFileSinkFilter::GetCurFile This method retrieves the name and media type of the current file. HRESULT GetCurFile( LPOLESTR* , ppszFileName AM_MEDIA_TYPE* pmt ); Parameters ppszFileName [out] Address of a pointer that receives the name of the file, as an OLESTR type. pmt [out] Pointer to an AM_MEDIA_TYPE structure that receives the media type. This parameter can by NULL, in which case the method does not return the media type. Return Values Returns an HRESULT value. The following table shows some possible values. Value Description S_OK Success. E_FAIL No file is opened. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument in ppszFileName. Remarks If the filter has not opened a file, the method might succeed but return NULL in the ppszFileName parameter. Check the value when the method returns. The method allocates the memory for the string returned in ppszFileName, and the memory for the format block in the media type (if any). The caller must free them by calling CoTaskMemFree . For the media type, you can use the FreeMediaType function in the base class library. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: IFileSinkFilter::SetFileName This method sets the name of the file into which media samples will be written. HRESULT SetFileName( LPCOLESTR pszFileName, const AM_MEDIA_TYPE* pmt ); Parameters pszFileName [in] Pointer to the name of the file to receive the media samples. pmt [in] Pointer to and AM_MEDIA_TYPE structure that describes the type of media samples to be written to the file, and the media type of the sink filter's input pin. Return Values Returns an HRESULT value. Remarks If the pszFileName parameter names a nonexistent file, the file will be created. If it names an existing file, the sink filter will overwrite the file without first deleting it. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. For more information, see Setting Up the Build Environment . Pocket PC Platforms: Windows Mobile 5.0 and later Smartphone Platforms: Windows Mobile 5.0 and later OS Versions: Windows CE 5.01 and later Header: 7. IAMStreamConfig Interface This interface is implemented on the output pins of audio/video compression filters, including the ACM Wrapper and the AVI Compressor. Filter developers can implement this interface on any output pin that handles audio or video data. This interface enables applications to query what types of formats a filter supports on its output pin and to set the format that the pin will offer to its downstream connecting pin. This in turn enables an application to simply call IGraphBuilder::Render on the pin, and the graph builder will create a graph appropriate to the desired format. If an application attempts to use IPin::EnumMediaTypes to enumerate a pin's supported media types after calling IAMStreamConfig::SetFormat, only the one media type will be returned. The IAMStreamConfig::GetStreamCaps method retrieves the AM_MEDIA_TYPE structure associated with the stream, as well as a VIDEO_STREAM_CONFIG_CAPS or an AUDIO_STREAM_CONFIG_CAPS structure that further describes the stream's characteristics. For video, this includes information on cropping, stretching, alignment, granularity, and data rates. Filter developers: Implement this interface on the video output pin when you are writing a video compression filter. Methods in Vtable Order The following table shows the methods that appear in the Vtable beneath the standard COM methods inherited from IUnknown. Method Description GetFormat Retrieves the audio or video stream's format. GetNumberOfCapabilities Retrieves the number of stream capabilities structures for the compressor. GetStreamCaps Obtains audio or video capabilities of a stream. SetFormat Sets the audio or video stream's format. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMStreamConfig::GetFormat This method retrieves the audio or video stream's format. HRESULT GetFormat( AM_MEDIA_TYPE** pmt ); Parameters pmt [out] Address of a pointer to an AM_MEDIA_TYPE structure. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks To be safe, set pmt to NULL before passing it in this method call. When you are done using the media DeleteMediaType function to free the structure. type structure, call the Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMStreamConfig::GetNumberOfCapabilities This method retrieves the number of stream capabilities structures for the compressor. HRESULT GetNumberOfCapabilities( int* , piCount int* piSize ); Parameters piCount [out] Pointer to the number of VIDEO_STREAM_CONFIG_CAPS and/or AUDIO_STREAM_CONFIG_CAPS structures supported. piSize [out] Pointer to the size of the configuration structure, either AUDIO_STREAM_CONFIG_CAPS or VIDEO_STREAM_CONFIG_CAPS. Return Values Returns an HRESULT value that depends on the implementation of the interface. Requirements DirectShow applications and DirectShow filters have different include file and link library Setting Up the Build Environment for more information. requirements. See Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMStreamConfig::GetStreamCaps This method obtains audio, video, or other capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter. HRESULT GetStreamCaps( int iIndex, AM_MEDIA_TYPE** pmt, BYTE* pSCC ); Parameters iIndex [in] Index to the desired media type and capability pair. Use the IAMStreamConfig::GetNumberOfCapabilities method to retrieve the total number of these pairs. Possible index values range from zero to one less than the total number of pairs. pmt [out] Address of a pointer to an AM_MEDIA_TYPE structure. pSCC [out] Pointer to a stream configuration structure. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks This method enables you to get more information about accepted media types rather than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. Information such as media types, and sizes is returned by the VIDEO_STREAM_CONFIG_CAPS structure. Audio capabilities of the filter's output pin, including the number of inputs, sampling rate, and bit rate granularity, will be returned by an AUDIO_STREAM_CONFIG_CAPS structure. Call DeleteMediaType to free the pmt media type. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: IAMStreamConfig::SetFormat This method sets the audio or video stream's format. HRESULT SetFormat( AM_MEDIA_TYPE* pmt ); Parameters pmt [in] Pointer to an AM_MEDIA_TYPE structure. Return Values Returns an HRESULT value that depends on the implementation of the interface. Remarks A call to this method will fail if the pin is streaming. If your output pin is not connected and you can connect it with this media type, return S_OK from this method and start enumerating the specified media type as follows. Specify this format as format number zero in the CTransformOutputPin::GetMediaType function's iPosition parameter. You can offer and accept only this type to ensure that the pins will use this format for the connection when it occurs. If your output pin is already connected and you can provide this type, then reconnect your pin. If the other pin cannot accept the media type, fail this call and leave your connection alone. Passing in NULL as a parameter value can cause some filters to set their default format and forget a previous format you have given it with this method. The frame rate at which your filter should produce data is determined by the AvgTimePerFrame field of VIDEOINFOHEADER of the media type your output pin is connected with. You may not be able to capture at any arbitrary frame rate, but only certain rates. If your pin is connected with a media type that asks for a frame rate you cannot provide, you should provide frames at the next lowest frame rate possible. For example, if your media type has AvgTimePerFrame=333333 (approximately 1/30 of a second, meaning 30 frames per second) and you can only capture 29.97 or 35 frames per second, you should provide frames at 29.97 frames per second, because that is the closest value lower than 30 that you can provide. You can provide a higher frame rate than asked if the frame rate you provide does not create frame durations more than 1 microsecond shorter than requested, because AvgTimePerFrame may simply have rounding errors. If the AvgTimePerFrame field is 0, you can supply frames at any default frame rate that you want. Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: 8. AM_MEDIA_TYPE This structure describes a media sample type. typedef struct _MediaType{ GUID majortype; GUID subtype; BOOL bFixedSizeSamples; BOOL bTemporalCompression; ULONG lSampleSize; GUID formattype; IUnknown* pUnk; ULONG cbFormat; /* [size_is] */ BYTE __RPC_FAR* pbFormat; } AM_MEDIA_TYPE; Members majortype Major type of the media sample. subtype Subtype of the media sample. bFixedSizeSamples If TRUE, samples are of a fixed size. bTemporalCompression If TRUE, samples are compressed. lSampleSize Size of the sample in bytes. formattype Registered (GUID) format type. pUnk IUnknown interface. Pointer to the cbFormat Size of the format section of the media type. pbFormat Pointer to the format section of the media type. The layout of this is determined by the format type GUID. Format types include the following. Format type Structure pointed to FORMAT_MPEGVideo MPEG1VIDEOINFO FORMAT_VideoInfo VIDEOINFOHEADER FORMAT_WaveFormatEx WAVEFORMATEX FORMAT_MPEG2Video MPEG2VIDEOINFO FORMAT_VideoInfo2 VIDEOINFOHEADER2 Remarks Media Types In any function that receives an AM_MEDIA_TYPE parameter, always validate the values of cbFormat and formattype before dereferencing the pbFormat member. The following code is incorrect: if (pmt->formattype == FORMAT_VideoInfo) { VIDEOINFOHEADER *pVIH = (VIDEOINFOHEADER*)pmt->pbFormat; // **** Wrong! **** } The following code is correct: if ((pmt->formattype == FORMAT_VideoInfo) && (pmt->cbFormat > sizeof(VIDEOINFOHEADER) && (pbFormat != NULL)) { VIDEOINFOHEADER *pVIH = (VIDEOINFOHEADER*)pmt->pbFormat; // Now you can use pVIH. } Requirements DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information. Pocket PC: Windows Mobile 5.0 and later Smartphone: Windows Mobile 5.0 and later OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: Dshow.h. Media Type Functions The Mtype.h header file in the DirectShow base classes provides helper functions for handling media types. These general-purpose functions create, copy and delete a task-allocated AM_MEDIA_TYPE structure. This is useful when using the IEnumMediaTypes interface, because the implementation allocates the structures that must be deleted later. The functions are paired as follows: , CreateMediaType is the opposite of DeleteMediaType. , FreeMediaType is the opposite of CopyMediaType. Programming element Description AreEqualVideoTypes Compares the format, height, and width of two video sources. CopyMediaType Copies a task-allocated AM_MEDIA_TYPE structure. CreateAudioMediaType Initializes a media type structure given a wave format structure. CreateMediaType Allocates and initializes an AM_MEDIA_TYPE structure. DeleteMediaType Deletes a task-allocated AM_MEDIA_TYPE structure. FreeMediaType Frees a task-allocated AM_MEDIA_TYPE structure from memory. 9. VIDEO_STREAM_CONFIG_CAPS介绍 This structure contains information about possible connections. typedef struct _VIDEO_STREAM_CONFIG_CAPS { GUID guid; ULONG VideoStandard; SIZE InputSize; SIZE MinCroppingSize; SIZE MaxCroppingSize; int CropGranularityX; int CropGranularityY; int CropAlignX; int CropAlignY; SIZE MinOutputSize; SIZE MaxOutputSize; int OutputGranularityX; int OutputGranularityY; int StretchTapsX; int StretchTapsY; int ShrinkTapsX; int ShrinkTapsY; LONGLONG MinFrameInterval; LONGLONG MaxFrameInterval; LONG MinBitsPerSecond; LONG MaxBitsPerSecond; } VIDEO_STREAM_CONFIG_CAPS; Members guid :Will set MEDIATYPE_Video to indicate a video sample. VideoStandard :The analog video standard supported. Set in the AnalogVideoStandard enumeration type (0 if not supported). InputSize :Size of the incoming signal, expressed through the Win32 SIZE structure as the image rectangle's width and height in pixels. For a compressor, the size is taken from the width and height members of the Win32 BITMAPINFOHEADER structure in the input pin's AM_MEDIA_TYPE structure. For a capture filter, the size is the largest signal the filter can digitize with every pixel remaining unique. MinCroppingSize :Smallest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member. MaxCroppingSize :Largest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member. CropGranularityX :Granularity of the cropping size. For example, you could specify that the only valid widths are an even multiple of four. CropGranularityY :Granularity of the cropping size. For example, you could specify that the only valid heights are an even multiple of four. CropAlignX :Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four. CropAlignY :Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four. MinOutputSize :Smallest bitmap this pin can produce. MaxOutputSize :Largest bitmap this pin can produce. OutputGranularityX Granularity of output bitmap width. OutputGranularityY :Granularity of output bitmap height. StretchTapsX :Value indicating how well the filter can stretch the image's width. 0 means the filter cannot stretch. 1 means it uses pixel doubling. 2 means it uses interpolation (2 taps). 3 and higher indicate it implements better interpolation. StretchTapsY :Value indicating how well the filter can stretch the image's height. 0 means the filter cannot stretch. 1 means it uses pixel doubling. 2 means it uses interpolation (2 taps). 3 and higher indicate it implements better interpolation. ShrinkTapsX :Value indicating how well the filter can shrink the image's width. 0 means the filter cannot shrink. 1 means it just eliminates some rows of pixels. 2 means it uses interpolation (2 taps). 3 and higher indicate it implements better interpolation. ShrinkTapsY :Value indicating how well the filter can shrink the image's height. 0 means the filter cannot shrink. 1 means it just eliminates some rows of pixels. 2 means it uses interpolation (2 taps). 3 and higher indicate it implements better interpolation. MinFrameInterval :Minimum frame rate allowed. This applies to the capture filter only. MaxFrameInterval :Maximum frame rate allowed. This applies to the capture filter only. MinBitsPerSecond :Minimum data rate this pin can produce. MaxBitsPerSecond :Maximum data rate this pin can produce. Remarks For example, assume the following values for some of the structure members: , MinCroppingSize = (160, 120) , MaxCroppingSize = (320, 240) , CropGranularityX = 4 , CropGranularityY = 8 These values indicate that valid cropping sizes begin at MinCroppingSize and increase in steps in the x-direction by CropGranularityX and in the y-direction by CropGranularityY. In this case the x-value can be anywhere from 160 to 320 pixels in steps of 4 and the y-value can be anywhere from 120 to 240 pixels in steps of 8. In this scenario a few of the valid sizes are as follows: , 160 x 120, 164 x 120, 168 x 120, 172 x 120, and so on , 160 x 128, 164 x 128, 168 x 128, 172 x 128, and so on , 160 x 136, 164 x 136, 168 x 136, 172 x 136, and so on CropAlignX and CropAlignY indicate where the cropping rectangle can be inside the input size rectangle. Given a 160 × 120 sized cropping rectangle and the following: , CropAlignX = 2 , CropAlignY = 4 Some valid values for the VIDEOINFOHEADER structure's rcSource member are as follows: , (0, 0, 160, 120) , (2, 0, 162, 120) , (2, 4, 162, 124) , (2, 8, 162, 128) For a 320 × 240 cropping rectangle and the same cropping alignment values, (2, 4, 322, 244) is one example of the many legal rectangles. The structure members discussed in this section work together to specify what values of rcSource are valid for the VIDEOINFOHEADER structure that describes the output pin's media type. Of the remaining structure members, MinOutputSize, MaxOutputSize, OutputGranularityX, and OutputGranularityY describe the biWidth and biHeight members of the BITMAPINFOHEADER structure contained in the output pin's media type VIDEOINFOHEADER structure. Requirements OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later. Header: Dshow.h. 10. IPersistPropertyBag:IPersist This interface works in conjunction with IPropertyBag to define an individual property-based persistence mechanism. Methods The following tables show the methods for this interface in alphabetical order. This interface inherits the methods for the IUnknown and IPersist. Method Description InitNew Informs the object that it is being initialized as a newly created object. Load Instructs the object to initialize itself using the properties available in the property bag, and notifies the provided error log object when errors occur. Save Instructs the object to save its properties to the given property bag, and optionally to clear the object's dirty flag. Remarks A mechanism such as IPersistStream gives an object an IStream in which to store its binary data, while IPersistPropertyBag provides an object with an IPropertyBag interface through which it can save and load individual properties. The object that implements IPropertyBag can then save those properties in various ways, such as in name and value pairs in a text file. Errors encountered in the process on either side are recorded in an error log through IErrorlog. This error reporting mechanism works on a per-property basis instead of on all properties at once. IPropertyBag and IPersistPropertyBag optimize "Save as Text" mechanisms, and therefore are recommended for ActiveX Control containers that implement a "Save as Text" mechanism. IPropertyBag is implemented by a container, and is roughly analogous to IStream. IPersistPropertyBag is implemented by controls, and is roughly analogous to IPersistStream. Requirements OS Versions: Windows CE .NET 4.0 and later. Header: Ocidl.h, Ocidl.idl. Link Library: Ole32.lib, Uuid.lib. 11. IPropertyBag:IUnknown This interface provides an object with a property bag in which the object can persistently save its properties. Methods The following table shows the methods for this interface in alphabetical order. Like all COM interfaces, this interface inherits the methods for the IUnknown interface. Method Description Read Asks the property bag to read the named property into a caller-initialized VARIANT. Write Asks the property bag to save the named property in a caller-initialized VARIANT. Remarks To read a property in IPersistPropertyBag::Load, the object calls IPropertyBag::Read. When the object is saving properties in IPersistPropertyBag::Save, it calls IPropertyBag::Write. Each property is described with a name whose value is stored in a VARIANT. This information allows a client to save the property values as text. This is the primary reason why a client might choose to support IPersistPropertyBag. The client records errors that occur during Read into the supplied error log. IPropertyBag and IPersistPropertyBag optimize "Save as Text" mechanisms, and are therefore recommended for ActiveX Control containers that implement a "Save as Text" mechanism. IPropertyBag is implemented by a container, and is roughly analogous to IStream. IPersistPropertyBag is implemented by controls, and is roughly analogous to IPersistStream. Requirements OS Versions: Windows CE .NET 4.0 and later. Header: Ocidl.h, Ocidl.idl. Link Library: Ole32.lib, Uuid.lib.