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.

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.

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

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.