Table of Contents

Class VideoCaptureSource

Namespace
VisioForge.Core.Types.VideoCapture
Assembly
VisioForge.Core.dll

Represents a video capture source device configuration for DirectShow-based video capture operations.

public class VideoCaptureSource

Inheritance

Inherited Members

Examples

// Create a capture source with automatic format detection
var captureSource = new VideoCaptureSource("Logitech HD Webcam");

// Or create from device info
var deviceInfo = GetVideoCaptureDeviceInfo();
var captureSource = new VideoCaptureSource(deviceInfo);

// Configure additional options
captureSource.UseClosedCaptions = true;
captureSource.UseRAWSampleGrabber = true;

Remarks

This class encapsulates the configuration settings for a video capture device, including format selection, frame rate control, and special features like closed captions and raw sample grabbing. It automatically detects and selects optimal capture formats based on device capabilities.

The class supports various capture scenarios including:

  • Standard video capture devices (webcams, capture cards)
  • TV tuners with internal MPEG encoders
  • Devices that can also serve as audio sources
  • Professional capture devices with multiple output pins

Constructors

VideoCaptureSource(string)

Initializes a new instance of the VisioForge.Core.Types.VideoCapture.VideoCaptureSource class with automatic format detection.

public VideoCaptureSource(string name)

Parameters

name string

The name of the video capture device.

Remarks

This constructor automatically enumerates available devices, finds the matching device by name, and attempts to detect the best capture format. The format selection prioritizes:

  1. 4K resolution (3840x2160) if available
  2. 1080p resolution (1920x1080) as second choice
  3. 720p resolution (1280x720) as third choice
  4. MJPEG codec over uncompressed formats

Exceptions

ArgumentNullException

Thrown when name is null.

VideoCaptureSource(VideoCaptureDeviceInfo)

Initializes a new instance of the VisioForge.Core.Types.VideoCapture.VideoCaptureSource class from device information.

public VideoCaptureSource(VideoCaptureDeviceInfo info)

Parameters

info VideoCaptureDeviceInfo

The video capture device information containing capabilities and supported formats.

Examples

// Get device info from enumeration
var devices = mediaPlayer.GetVideoCaptureDevices();
var webcam = devices.FirstOrDefault(d => d.Name.Contains("HD"));

// Create capture source from device info
var captureSource = new VideoCaptureSource(webcam);

Remarks

This constructor uses the provided device information to configure the capture source, automatically selecting the best available format based on the device's capabilities. Unlike the name-based constructor, this avoids the need to re-enumerate devices.

The format detection follows the same prioritization as the name-based constructor, favoring higher resolutions and MJPEG compression when available.

Exceptions

ArgumentNullException

Thrown when info is null.

VideoCaptureSource(MediaFoundationCaptureDevice)

Initializes a new instance of the VisioForge.Core.Types.VideoCapture.VideoCaptureSource class from a Media Foundation camera.

public VideoCaptureSource(MediaFoundationCaptureDevice device)

Parameters

device MediaFoundationCaptureDevice

The camera returned by VideoCaptureCore.Video_MediaFoundationCaptureDevices.

Remarks

Sets VisioForge.Core.Types.VideoCapture.VideoCaptureSource.UseMediaFoundation and does not read the DirectShow format list. The default size is the largest listed size that fits in 1920x1080, or the largest listed size when every size is larger. VisioForge.Core.Types.VideoCapture.VideoCaptureSource.Format is that size (1280x960), VisioForge.Core.Types.VideoCapture.VideoCaptureSource.Format_UseBest is false, and VisioForge.Core.Types.VideoCapture.VideoCaptureSource.FrameRate is the fastest listed rate at or below 100 fps. The capture source rejects a faster rate.

To use another listed size, assign VisioForge.Core.Types.VideoCapture.MediaFoundationCaptureFormat.Name to VisioForge.Core.Types.VideoCapture.VideoCaptureSource.Format and one of its VisioForge.Core.Types.VideoCapture.MediaFoundationCaptureFormat.FrameRates to VisioForge.Core.Types.VideoCapture.VideoCaptureSource.FrameRate. Audio, crossbar, tuner and direct capture stay off.

Exceptions

ArgumentNullException

Thrown when device is null.

Properties

CustomPinName

Gets or sets the custom pin name for devices with multiple output pins.

public string CustomPinName { get; set; }

Property Value

string

Remarks

Professional capture devices may expose multiple output pins, each potentially offering different formats or processing paths. Use the VideoFormatsAllPins property of VisioForge.Core.Types.VideoCapture.VideoCaptureDeviceInfo to enumerate available pins and their formats.

Common pin names include:

  • "Capture" - Main capture pin
  • "Preview" - Lower resolution preview pin
  • "Still" - High resolution still image pin

Format

Gets or sets the specific video format string for capture operations.

public string Format { get; set; }

Property Value

string

Remarks

The format string typically includes the codec type and resolution, such as:

  • "MJPG 1920x1080" - Motion JPEG at 1080p
  • "YUY2 1280x720" - Uncompressed YUV at 720p
  • "RGB24 640x480" - RGB at VGA resolution

If left empty and VisioForge.Core.Types.VideoCapture.VideoCaptureSource.Format_UseBest is true, the framework will automatically select an appropriate format.

Format_UseBest

Gets or sets a value indicating whether automatic format selection should be used.

public bool Format_UseBest { get; set; }

Property Value

bool

Remarks

When enabled, the framework analyzes available formats and selects the optimal one based on resolution (preferring 4K > 1080p > 720p) and codec (preferring MJPEG for better quality and lower CPU usage).

FrameRate

Gets or sets the target frame rate for video capture.

public VideoFrameRate FrameRate { get; set; }

Property Value

VideoFrameRate

Remarks

The actual frame rate achieved depends on device capabilities and the selected format. Not all combinations of resolution and frame rate may be supported by the device.

Common frame rates include:

  • 30 fps - Standard video
  • 60 fps - Smooth motion
  • 25 fps - PAL standard
  • 24 fps - Film standard

InternalMPEGEncoder_Name

Gets or sets the name of the internal MPEG encoder for devices with hardware encoding capabilities.

public string InternalMPEGEncoder_Name { get; set; }

Property Value

string

Remarks

Some capture devices, particularly TV tuner cards, include built-in MPEG encoders that can perform hardware compression directly on the device, reducing CPU usage.

IsAudioSource

Gets or sets a value indicating whether this video capture device should also be used as an audio source.

public bool IsAudioSource { get; set; }

Property Value

bool

Remarks

Most modern video capture devices include audio capture capabilities. However, some older TV tuners require a separate audio connection to the sound card and do not support direct audio capture through the video device.

When set to true, the framework will attempt to capture both audio and video from the same device, simplifying synchronization.

Name

Gets or sets the display name of the video capture device.

public string Name { get; set; }

Property Value

string

Remarks

This is the human-readable name of the device, such as "Logitech HD Webcam" or "USB Video Device".

Path

Gets or sets the DirectShow device path for unique device identification.

public string Path { get; set; }

Property Value

string

Remarks

This property is optional but recommended when multiple devices with the same name exist in the system. The device path provides a unique identifier that persists across system restarts.

Use the Video_CaptureDevice_GetDevicePath method to obtain the device path for a specific device.

UseClosedCaptions

Gets or sets a value indicating whether to capture closed captions if available.

public bool UseClosedCaptions { get; set; }

Property Value

bool

Remarks

Closed captions are typically available from TV tuner devices capturing broadcast content. When enabled, caption data will be embedded in the output stream or made available through appropriate events.

UseMediaFoundation

Gets or sets a value indicating whether the camera is opened with Media Foundation instead of the DirectShow capture filter.

public bool UseMediaFoundation { get; set; }

Property Value

bool

Remarks

When enabled, frames enter the capture graph as RGB24. The Windows DirectShow camera bridge is not used, so a frame-server camera does not keep that bridge's capture-buffer pool across Stop and Start.

The flag does nothing until the application sets it. Call VisioForge.Core.Types.VideoCapture.VideoCaptureSource.IsMediaFoundationCaptureAvailable first: when that returns false, or the device cannot be opened, starting capture fails and does not fall back to DirectShow.

Audio from the same device, direct capture, closed captions, a raw sample grabber on the capture filter, a custom pin, an internal MPEG encoder and crossbar routing are not available in this mode. Recording receives RGB24 rather than the camera's native format.

Take the camera from VideoCaptureCore.Video_MediaFoundationCaptureDevices. A size that is only in the DirectShow device list is not a size this mode can open.

UseRAWSampleGrabber

Gets or sets a value indicating whether raw sample grabbing is enabled for frame-level access.

public bool UseRAWSampleGrabber { get; set; }

Property Value

bool

Remarks

When enabled, the framework inserts a sample grabber filter in the DirectShow graph, allowing direct access to video frames through the OnVideoFrameBufferRAW event. This is useful for custom processing, analysis, or frame capture scenarios.

Note that enabling this feature may impact performance due to the additional memory copies required for frame access.

Methods

IsMediaFoundationCaptureAvailable()

Returns whether Media Foundation camera capture can be used in this process.

public static bool IsMediaFoundationCaptureAvailable()

Returns

bool

true when the operating system is Windows 10 version 1607 or later and the camera frame server is not turned off; otherwise, false.

Remarks

The frame server is off only when HKLM\SOFTWARE\Microsoft\Windows Media Foundation\Platform\EnableFrameServerMode is 0 in the registry view of this process. A missing value means the feature is on. This method does not change the registry.

ToString()

Returns a string representation of this video capture source.

public override string ToString()

Returns

string

The device name as specified by the VisioForge.Core.Types.VideoCapture.VideoCaptureSource.Name property.

Examples

var captureSource = new VideoCaptureSource("Logitech HD Webcam");
Console.WriteLine(captureSource.ToString()); // Output: "Logitech HD Webcam"

Remarks

This override provides a human-readable representation of the capture source, making it suitable for display in user interfaces, logging, and debugging. The returned value is simply the device name without any additional formatting.