C# Class DirectX.Capture.Capture

Use the Capture class to capture audio and video to AVI files.
This is the core class of the Capture Class Library. The following sections introduce the Capture class and how to use this library.

Basic Usage

The Capture class only requires a video device and/or audio device to begin capturing. The Filters class provides lists of the installed video and audio devices.

// Remember to add a reference to DirectX.Capture.dll using DirectX.Capture ... Capture capture = new Capture( Filters.VideoInputDevices[0], Filters.AudioInputDevices[0] ); capture.Start(); ... capture.Stop();

This will capture video and audio using the first video and audio devices installed on the system. To capture video only, pass a null as the second parameter of the constructor.

The class is initialized to a valid temporary file in the Windows temp folder. To capture to a different file, set the Capture.Filename property before you begin capturing. Remember to add DirectX.Capture.dll to your project references.


Setting Common Properties

The example below shows how to change video and audio settings. Properties such as Capture.FrameRate and AudioSampleSize allow you to programmatically adjust the capture. Use Capture.VideoCaps and Capture.AudioCaps to determine valid values for these properties.

Capture capture = new Capture( Filters.VideoInputDevices[0], Filters.AudioInputDevices[1] ); capture.VideoCompressor = Filters.VideoCompressors[0]; capture.AudioCompressor = Filters.AudioCompressors[0]; capture.FrameRate = 29.997; capture.FrameSize = new Size( 640, 480 ); capture.AudioSamplingRate = 44100; capture.AudioSampleSize = 16; capture.Filename = "C:\MyVideo.avi"; capture.Start(); ... capture.Stop();

The example above also shows the use of video and audio compressors. In most cases you will want to use compressors. Uncompressed video can easily consume over a 1GB of disk space per minute. Whenever possible, set the Capture.VideoCompressor and Capture.AudioCompressor properties as early as possible. Changing them requires the internal filter graph to be rebuilt which often causes most of the other properties to be reset to default values.


Listing Devices

Use the Filters.VideoInputDevices collection to list video capture devices installed on the system.

foreach ( Filter f in Filters.VideoInputDevices ) { Debug.WriteLine( f.Name ); }
The Filters class also provides collections for audio capture devices, video compressors and audio compressors.

Preview

Video preview is controled with the Capture.PreviewWindow property. Setting this property to a visible control will immediately begin preview. Set to null to stop the preview.

// Enable preview capture.PreviewWindow = myPanel; // Disable preview capture.PreviewWindow = null;

The control used must have a window handle (HWND), good controls to use are the Panel or the form itself.

Retrieving or changing video/audio settings such as FrameRate, FrameSize, AudioSamplingRate, and AudioSampleSize will cause the preview window to flash. This is beacuse the preview must be temporarily stopped. Disable the preview if you need to access several properties at the same time.


Property Pages

Property pages exposed by the devices and compressors are available through the Capture.PropertyPages collection.

// Display the first property page capture.PropertyPages[0].Show();

The property pages will often expose more settings than the Capture class does directly. Some examples are brightness, color space, audio balance and bass boost. The disadvantage to using the property pages is the user's choices cannot be saved and later restored. The exception to this is the video and audio compressor property pages. Most compressors support the saving and restoring state, see the PropertyPage.State property for more information.

Changes made in the property page will be reflected immediately in the Capture class properties (e.g. Capture.FrameSize). However, the reverse is not always true. A change made directly to FrameSize, for example, may not be reflected in the associated property page. Fortunately, the filter will use requested FrameSize even though the property page shows otherwise.


Saving and Restoring Settings

To save the user's choice of devices and compressors, save Filter.MonikerString and user it later to recreate the Filter object.

To save a user's choices from a property page use PropertyPage.State. However, only the audio and video compressor property pages support this.

The last items to save are the video and audio settings such as FrameSize and AudioSamplingRate. When restoring, remember to restore these properties after setting the video and audio compressors.

// Disable preview capture.PreviewWindow = null; // Save settings string videoDevice = capture.VideoDevice.MonikerString; string audioDevice = capture.AudioDevice.MonikerString; string videoCompressor = capture.VideoCompressor.MonikerString; string audioCompressor = capture.AudioCompressor.MonikerString; double frameRate = capture.FrameRate; Size frameSize = capture.FrameSize; short audioChannels = capture.AudioChannels; short audioSampleSize = capture.AudioSampleSize; int audioSamplingRate = capture.AudioSamplingRate; ArrayList pages = new ArrayList(); foreach ( PropertyPage p in capture.PropertyPages ) { if ( p.SupportsPersisting ) pages.Add( p.State ); } // Restore settings Capture capture = new Capture( new Filter( videoDevice), new Filter( audioDevice) ); capture.VideoCompressor = new Filter( videoCompressor ); capture.AudioCompressor = new Filter( audioCompressor ); capture.FrameRate = frameRate; capture.FrameSize = frameSize; capture.AudioChannels = audioChannels; capture.AudioSampleSize = audioSampleSize; capture.AudioSamplingRate = audioSamplingRate; foreach ( PropertyPage p in capture.PropertyPages ) { if ( p.SupportsPersisting ) { p.State = (byte[]) pages[0] pages.RemoveAt( 0 ); } } // Enable preview capture.PreviewWindow = myPanel;

TV Tuner

To access the TV Tuner, use the Capture.Tuner property. If the device does not have a TV tuner, this property will be null. See DirectX.Capture.Tuner.Channel, DirectX.Capture.Tuner.InputType and DirectX.Capture.Tuner.SignalPresent for more information.

// Change to channel 5 capture.Tuner.Channel = 5;

Troubleshooting

This class library uses COM Interop to access the full capabilities of DirectShow, so if there is another application that can successfully use a hardware device then it should be possible to modify this class library to use the device.

Try the AMCap sample from the DirectX SDK (DX9\Samples\C++\DirectShow\Bin\AMCap.exe) or Virtual VCR from http://www.DigTV.ws


Credits

This class library would not be possible without the DShowNET project by NETMaster: http://www.codeproject.com/useritems/directshownet.asp

Documentation is generated by nDoc available at http://ndoc.sourceforge.net


Feedback

Feel free to send comments and questions to me at [email protected]. If the the topic may be of interest to others, post your question on the www.codeproject.com page for DirectX.Capture.
Inheritance: ISampleGrabberCB
Afficher le fichier Open project: parhansson/KMotionX Class Usage Examples

Méthodes publiques

Свойство Type Description
dxUtils DirectX.Capture.DxUtils

Protected Properties

Свойство Type Description
audioCaps AudioCapabilities
audioCompressor Filter
audioCompressorFilter IBaseFilter
audioDevice Filter
audioDeviceFilter IBaseFilter
audioSources SourceCollection
audioStreamConfig IAMStreamConfig
captureGraphBuilder ICaptureGraphBuilder2
fileWriterFilter IFileSinkFilter
filename string
graphBuilder IGraphBuilder
graphState GraphState
isCaptureRendered bool
isPreviewRendered bool
mediaControl IMediaControl
muxFilter IBaseFilter
previewCaps DirectX.Capture.VideoCapabilities
previewStreamConfig IAMStreamConfig
previewWindow System.Windows.Forms.Control
propertyPages PropertyPageCollection
recFileMode RecFileModeType
rotCookie DsROTEntry
rotCookie int
sampGrabber ISampleGrabber
tuner Tuner
tvAudio IAMTVAudio
videoCaps DirectX.Capture.VideoCapabilities
videoCompressor Filter
videoCompressorFilter IBaseFilter
videoDevice Filter
videoDeviceFilter IBaseFilter
videoSources SourceCollection
videoStreamConfig IAMStreamConfig
videoWindow IVideoWindow
wantCaptureRendered bool
wantPreviewRendered bool

Méthodes publiques

Méthode Description
Capture ( Filter videoDevice, Filter audioDevice, bool audioViaPci ) : System

Create a new Capture object. videoDevice and audioDevice can be null if you do not wish to capture both audio and video. However at least one must be a valid device. Use the Filters class to list available devices.
Cue ( ) : void

Prepare for capturing. Use this method when capturing must begin as quickly as possible.

This will create/overwrite a zero byte file with the name set in the Filename property.

This will disable preview. Preview will resume once capture begins. This problem can be fixed if someone is willing to make the change.

This method is optional. If Cue() is not called, Start() will call it before capturing. This method cannot be called while capturing.

DisableEvent ( ) : void

Disable grabbing next frame
Dispose ( ) : void

Calls Stop, releases all references. If a capture is in progress it will be stopped, but the CaptureComplete event will NOT fire.
DisposeSampleGrabber ( ) : void

Dispose Sample Grabber specific data
GrapImg ( ) : void

Allocate memory space and set SetCallBack
ShowPropertyPage ( int filter, Control o ) : bool

Show property page of object
Start ( ) : void

Begin capturing.
Stop ( ) : void

Stop the current capture capture. If there is no current capture, this method will succeed.

Méthodes protégées

Méthode Description
assertStopped ( ) : void

Assert that the class is in a Stopped state.
createGraph ( ) : void

Create a new filter graph and add filters (devices, compressors, misc), but leave the filters unconnected. Call renderGraph() to connect the filters.
derenderGraph ( ) : void

Disconnect and remove all filters except the device and compressor filters. This is the opposite of renderGraph(). Soem properties such as FrameRate can only be set when the device output pins are not connected.
destroyGraph ( ) : void

Completely tear down a filter graph and release all associated resources.
getStreamConfigSetting ( IAMStreamConfig streamConfig, string fieldName ) : object

Retrieves the value of one member of the IAMStreamConfig format block. Helper function for several properties that expose video/audio settings from IAMStreamConfig.GetFormat(). IAMStreamConfig.GetFormat() returns a AMMediaType struct. AMMediaType.formatPtr points to a format block structure. This format block structure may be one of several types, the type being determined by AMMediaType.formatType.
getTempFilename ( ) : string

Get a valid temporary filename (with path). We aren't using Path.GetTempFileName() because it creates a 0-byte file
onPreviewWindowResize ( object sender, EventArgs e ) : void

Resize the preview when the PreviewWindow is resized
removeDownstream ( IBaseFilter filter, bool removeFirstFilter ) : void

Removes all filters downstream from a filter from the graph. This is called only by derenderGraph() to remove everything from the graph except the devices and compressors. The parameter "removeFirstFilter" is used to keep a compressor (that should be immediately downstream of the device) if one is begin used.
renderGraph ( ) : void

Connects the filters of a previously created graph (created by createGraph()). Once rendered the graph is ready to be used. This method may also destroy streams if we have streams we no longer want.
setStreamConfigSetting ( IAMStreamConfig streamConfig, string fieldName, object newValue ) : object

Set the value of one member of the IAMStreamConfig format block. Helper function for several properties that expose video/audio settings from IAMStreamConfig.GetFormat(). IAMStreamConfig.GetFormat() returns a AMMediaType struct. AMMediaType.formatPtr points to a format block structure. This format block structure may be one of several types, the type being determined by AMMediaType.formatType.
startPreviewIfNeeded ( ) : void

Setup and start the preview window if the user has requested it (by setting PreviewWindow).

Private Methods

Méthode Description
AddDeInterlaceFilter ( ) : bool
ISampleGrabberCB ( double SampleTime, IMediaSample pSample ) : int
ISampleGrabberCB ( double SampleTime, IntPtr pBuffer, int BufferLen ) : int
InitSampleGrabber ( ) : bool
InitVideoRenderer ( ) : bool
SetMediaSampleGrabber ( ) : void
getMediaSubType ( IAMStreamConfig streamConfig ) : DxUtils.ColorSpaceEnum
setMediaSubType ( IAMStreamConfig streamConfig, DirectX.Capture.DxUtils newValue ) : void

Method Details

Capture() public méthode

Create a new Capture object. videoDevice and audioDevice can be null if you do not wish to capture both audio and video. However at least one must be a valid device. Use the Filters class to list available devices.
public Capture ( Filter videoDevice, Filter audioDevice, bool audioViaPci ) : System
videoDevice Filter
audioDevice Filter
audioViaPci bool
Résultat System

Cue() public méthode

Prepare for capturing. Use this method when capturing must begin as quickly as possible.
This will create/overwrite a zero byte file with the name set in the Filename property.

This will disable preview. Preview will resume once capture begins. This problem can be fixed if someone is willing to make the change.

This method is optional. If Cue() is not called, Start() will call it before capturing. This method cannot be called while capturing.

public Cue ( ) : void
Résultat void

DisableEvent() public méthode

Disable grabbing next frame
public DisableEvent ( ) : void
Résultat void

Dispose() public méthode

Calls Stop, releases all references. If a capture is in progress it will be stopped, but the CaptureComplete event will NOT fire.
public Dispose ( ) : void
Résultat void

DisposeSampleGrabber() public méthode

Dispose Sample Grabber specific data
public DisposeSampleGrabber ( ) : void
Résultat void

GrapImg() public méthode

Allocate memory space and set SetCallBack
public GrapImg ( ) : void
Résultat void

ShowPropertyPage() public méthode

Show property page of object
public ShowPropertyPage ( int filter, Control o ) : bool
filter int
o System.Windows.Forms.Control
Résultat bool

Start() public méthode

Begin capturing.
public Start ( ) : void
Résultat void

Stop() public méthode

Stop the current capture capture. If there is no current capture, this method will succeed.
public Stop ( ) : void
Résultat void

assertStopped() protected méthode

Assert that the class is in a Stopped state.
protected assertStopped ( ) : void
Résultat void

createGraph() protected méthode

Create a new filter graph and add filters (devices, compressors, misc), but leave the filters unconnected. Call renderGraph() to connect the filters.
protected createGraph ( ) : void
Résultat void

derenderGraph() protected méthode

Disconnect and remove all filters except the device and compressor filters. This is the opposite of renderGraph(). Soem properties such as FrameRate can only be set when the device output pins are not connected.
protected derenderGraph ( ) : void
Résultat void

destroyGraph() protected méthode

Completely tear down a filter graph and release all associated resources.
protected destroyGraph ( ) : void
Résultat void

getStreamConfigSetting() protected méthode

Retrieves the value of one member of the IAMStreamConfig format block. Helper function for several properties that expose video/audio settings from IAMStreamConfig.GetFormat(). IAMStreamConfig.GetFormat() returns a AMMediaType struct. AMMediaType.formatPtr points to a format block structure. This format block structure may be one of several types, the type being determined by AMMediaType.formatType.
protected getStreamConfigSetting ( IAMStreamConfig streamConfig, string fieldName ) : object
streamConfig IAMStreamConfig
fieldName string
Résultat object

getTempFilename() protected méthode

Get a valid temporary filename (with path). We aren't using Path.GetTempFileName() because it creates a 0-byte file
protected getTempFilename ( ) : string
Résultat string

onPreviewWindowResize() protected méthode

Resize the preview when the PreviewWindow is resized
protected onPreviewWindowResize ( object sender, EventArgs e ) : void
sender object
e System.EventArgs
Résultat void

removeDownstream() protected méthode

Removes all filters downstream from a filter from the graph. This is called only by derenderGraph() to remove everything from the graph except the devices and compressors. The parameter "removeFirstFilter" is used to keep a compressor (that should be immediately downstream of the device) if one is begin used.
protected removeDownstream ( IBaseFilter filter, bool removeFirstFilter ) : void
filter IBaseFilter
removeFirstFilter bool
Résultat void

renderGraph() protected méthode

Connects the filters of a previously created graph (created by createGraph()). Once rendered the graph is ready to be used. This method may also destroy streams if we have streams we no longer want.
protected renderGraph ( ) : void
Résultat void

setStreamConfigSetting() protected méthode

Set the value of one member of the IAMStreamConfig format block. Helper function for several properties that expose video/audio settings from IAMStreamConfig.GetFormat(). IAMStreamConfig.GetFormat() returns a AMMediaType struct. AMMediaType.formatPtr points to a format block structure. This format block structure may be one of several types, the type being determined by AMMediaType.formatType.
protected setStreamConfigSetting ( IAMStreamConfig streamConfig, string fieldName, object newValue ) : object
streamConfig IAMStreamConfig
fieldName string
newValue object
Résultat object

startPreviewIfNeeded() protected méthode

Setup and start the preview window if the user has requested it (by setting PreviewWindow).
protected startPreviewIfNeeded ( ) : void
Résultat void

Property Details

audioCaps protected_oe property

protected AudioCapabilities,DirectX.Capture audioCaps
Résultat AudioCapabilities

audioCompressor protected_oe property

protected Filter,DirectX.Capture audioCompressor
Résultat Filter

audioCompressorFilter protected_oe property

protected IBaseFilter audioCompressorFilter
Résultat IBaseFilter

audioDevice protected_oe property

protected Filter,DirectX.Capture audioDevice
Résultat Filter

audioDeviceFilter protected_oe property

protected IBaseFilter audioDeviceFilter
Résultat IBaseFilter

audioSources protected_oe property

protected SourceCollection,DirectX.Capture audioSources
Résultat SourceCollection

audioStreamConfig protected_oe property

protected IAMStreamConfig audioStreamConfig
Résultat IAMStreamConfig

captureGraphBuilder protected_oe property

protected ICaptureGraphBuilder2 captureGraphBuilder
Résultat ICaptureGraphBuilder2

dxUtils public_oe property

Interface to DirectShow utilities for controlling video
public DxUtils,DirectX.Capture dxUtils
Résultat DirectX.Capture.DxUtils

fileWriterFilter protected_oe property

protected IFileSinkFilter fileWriterFilter
Résultat IFileSinkFilter

filename protected_oe property

protected string filename
Résultat string

graphBuilder protected_oe property

protected IGraphBuilder graphBuilder
Résultat IGraphBuilder

graphState protected_oe property

protected GraphState graphState
Résultat GraphState

isCaptureRendered protected_oe property

protected bool isCaptureRendered
Résultat bool

isPreviewRendered protected_oe property

protected bool isPreviewRendered
Résultat bool

mediaControl protected_oe property

protected IMediaControl mediaControl
Résultat IMediaControl

muxFilter protected_oe property

protected IBaseFilter muxFilter
Résultat IBaseFilter

previewCaps protected_oe property

Property Backer: preview capabilities of video device
protected VideoCapabilities,DirectX.Capture previewCaps
Résultat DirectX.Capture.VideoCapabilities

previewStreamConfig protected_oe property

IAMStreamConfig interface of preview pin. It is not really common that the preview has such interface, but if it has such interface it can be used "independent" from the capture pin interface.
protected IAMStreamConfig previewStreamConfig
Résultat IAMStreamConfig

previewWindow protected_oe property

protected Control,System.Windows.Forms previewWindow
Résultat System.Windows.Forms.Control

propertyPages protected_oe property

protected PropertyPageCollection,DirectX.Capture propertyPages
Résultat PropertyPageCollection

recFileMode protected_oe property

Recording file mode (e.g. Windows Media Audio)
protected RecFileModeType recFileMode
Résultat RecFileModeType

rotCookie protected_oe property

Special variable for debugging purposes Cookie into the Running Object Table
protected DsROTEntry rotCookie
Résultat DsROTEntry

rotCookie protected_oe property

protected int rotCookie
Résultat int

sampGrabber protected_oe property

Sample Grabber interface
protected ISampleGrabber sampGrabber
Résultat ISampleGrabber

tuner protected_oe property

protected Tuner,DirectX.Capture tuner
Résultat Tuner

tvAudio protected_oe property

IAMTVAudio property
protected IAMTVAudio tvAudio
Résultat IAMTVAudio

videoCaps protected_oe property

protected VideoCapabilities,DirectX.Capture videoCaps
Résultat DirectX.Capture.VideoCapabilities

videoCompressor protected_oe property

protected Filter,DirectX.Capture videoCompressor
Résultat Filter

videoCompressorFilter protected_oe property

protected IBaseFilter videoCompressorFilter
Résultat IBaseFilter

videoDevice protected_oe property

protected Filter,DirectX.Capture videoDevice
Résultat Filter

videoDeviceFilter protected_oe property

protected IBaseFilter videoDeviceFilter
Résultat IBaseFilter

videoSources protected_oe property

protected SourceCollection,DirectX.Capture videoSources
Résultat SourceCollection

videoStreamConfig protected_oe property

protected IAMStreamConfig videoStreamConfig
Résultat IAMStreamConfig

videoWindow protected_oe property

protected IVideoWindow videoWindow
Résultat IVideoWindow

wantCaptureRendered protected_oe property

protected bool wantCaptureRendered
Résultat bool

wantPreviewRendered protected_oe property

protected bool wantPreviewRendered
Résultat bool