Class Grabber

Represents an opened video capture device, allowing device configuration and stream setup.

Inheritance

Grabber

Implements

Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class Grabber : HandleObject, IDisposable
Remarks

The grabber object is the core component used when working with video capture devices.

Grabber objects are created using the constructor Grabber().

After creation, the most common operation on a grabber is to open a device. A device can be opened directly by

A device can also be selected and configured from a previously saved device state by

To establish a data stream from the opened video capture device, call StreamSetup(Sink, IDisplay, StreamSetupOption).

A Sink is required if the program needs to access, process, or store image data. There are several sink types available to choose from, which are useful depending on the application, e.g. QueueSink or SnapSink.

A IDisplay can be used to automatically display all images from the video capture device.

After the data stream has been set up, call AcquisitionStart() to begin the transfer of images.

See Grabber States for a discussion of the internal states of the grabber object during its lifetime.

Some object references, e.g. ImageBuffer, can keep the device and/or driver opened as long as they exist, since they point into device driver memory. To free all device-related resources, all objects references have to be released.

Constructors

Grabber()

Creates a new grabber.

Declaration

public Grabber()

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

Properties

DeviceInfo

Returns information about the currently opened video capture device.

Declaration

public DeviceInfo DeviceInfo { get; }
Property Value
Type Description
DeviceInfo

A DeviceInfo object for the currently opened video capture device.

Exceptions

Type Condition
InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

DevicePropertyMap

Returns the property map for the currently opened video capture device.

Declaration

public PropertyMap DevicePropertyMap { get; }
Property Value
Type Description
PropertyMap
Remarks

The property map returned from this function is the origin for all device feature manipulation operations.

Exceptions

Type Condition
InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

Display

Returns the display object that was passed to StreamSetup(IDisplay, StreamSetupOption) or StreamSetup(Sink, IDisplay, StreamSetupOption) when setting up the currently established data stream.

Declaration

public IDisplay Display { get; }
Property Value
Type Description
IDisplay

The current display, or null if no display was set.

DriverPropertyMap

Returns the property map for the driver of the currently opened video capture device.

Declaration

public PropertyMap DriverPropertyMap { get; }
Property Value
Type Description
PropertyMap
Remarks

The property map returned from this function is the origin for driver-related feature operations.

Exceptions

Type Condition
InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

IsAcquisitionActive

Checks whether image acquisition is currently enabled for this grabber's video capture device.

Declaration

public bool IsAcquisitionActive { get; }
Property Value
Type Description
bool

true, if image acquisition is currently active, otherwise false.

Remarks

In contrast to IsStreaming, this additionally checks whether the device was instructed to begin image acquisition.

See Grabber States for a discussion of the internal states of the grabber object during its lifetime.

IsDeviceOpen

Checks whether the grabber currently has an opened video capture device.

Declaration

public bool IsDeviceOpen { get; }
Property Value
Type Description
bool

true, if the grabber has an opened video capture device, otherwise false.

Remarks

See Grabber States for a discussion of the internal states of the grabber object during its lifetime.

IsDeviceValid

Checks whether the grabber's currently opened video capture device is ready to use.

Declaration

public bool IsDeviceValid { get; }
Property Value
Type Description
bool

true, if the grabber has an opened video capture device that is ready to use, otherwise false.

Remarks

There are multiple reasons for why this function may return false:

  • No device has been opened
  • The device was disconnected
  • There is a loose hardware connection
  • There was an internal error in the video capture device
  • There was a driver error

If the currently opened device becomes invalid, the DeviceLost event is raised.

See Grabber States for a discussion of the internal states of the grabber object during its lifetime.

IsStreaming

Checks whethere there is a data stream established from this grabber's video capture device.

Declaration

public bool IsStreaming { get; }
Property Value
Type Description
bool

true, if a data stream was previously established. Otherwise, or if the data stream was stopped again, false.

Remarks

See Grabber States for a discussion of the internal states of the grabber object during its lifetime.

Sink

Returns the sink object that was passed to StreamSetup(Sink, IDisplay, StreamSetupOption) or StreamSetup(Sink, StreamSetupOption) when setting up the currently established data stream.

Declaration

public Sink Sink { get; }
Property Value
Type Description
Sink

The current sink, or null if no sink was set.

StreamStatistics

Query statistics counters from the currently running or previously stopped data stream.

Declaration

public StreamStatistics StreamStatistics { get; }
Property Value
Type Description
StreamStatistics

A StreamStatistics object containing the stream statistics counters.

Remarks

This operation is only valid after a data stream was established once.

Exceptions

Type Condition
InvalidOperationException

A data stream has not been setup yet

IC4Exception

Check ErrorCode and ToString() for details.

Methods

AcquisitionStart()

Starts the acquisition of images from the video capture device.

Declaration

public void AcquisitionStart()
Remarks

A data stream has to be established before calling this function by calling StreamSetup(Sink, IDisplay, StreamSetupOption) or one of its overloads.

This operation is equivalent to executing the AcquisitionStart command on the device's PropertyMap.

Exceptions

Type Condition
InvalidOperationException

A data stream was not setup yet, or acquisition is already active

IC4Exception

Check ErrorCode and ToString() for details.

AcquisitionStop()

Stops the acquisition of images from the video capture device.

Declaration

public void AcquisitionStop()
Remarks

The acquisition of images has to be started, for example by calling AcquisitionStart() or passing AcquisitionStart during stream setup, before calling this function.

This operation is equivalent to executing the AcquisitionStop command on the device's PropertyMap.

Exceptions

Type Condition
InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

DeviceClose()

Closes the video capture device currently opened by this grabber instance

Declaration

public void DeviceClose()
Remarks

If the device is closed, all its resouces are released:

  • If image acquisition is active, it is stopped.
  • If a data stream was set up, it is stopped.
  • References to data stream-related objects are released, possibly destroying the sink and/or display.
  • Property objects retrieved from the DevicePropertyMap become invalid.

ImageBuffer objects and their memory stay allocated until they are disposed. References to image buffers can keep the video capture device open, if they point into driver memory.

Exceptions

Type Condition
InvalidOperationException

The function was called from a thread that cannot perform the operation, e.g. a device callback.

IC4Exception

Check ErrorCode and ToString() for details.

DeviceOpen(string)

Opens the video capture matching the specified identifier.

Declaration

public void DeviceOpen(string identifier)

Parameters

Type Name Description
string identifier

The model name, unique name or serial of a connected video capture device

Remarks

If there are multiple devices matching the specified model name, unique name or serial, the function will fail and throw a IC4Exception with the error code set to Ambiguous.

If there is no device with the specified model name, unique name or serial, the function will fail and throw a IC4Exception with the error code set to DeviceNotFound.

Exceptions

Type Condition
ArgumentNullException

identifier is null

InvalidOperationException

The grabber already has an opened device

IC4Exception

Check ErrorCode and ToString() for details.

DeviceOpen(DeviceInfo)

Opens the video capture device specified by the passed device information object.

Declaration

public void DeviceOpen(DeviceInfo deviceInfo)

Parameters

Type Name Description
DeviceInfo deviceInfo

A device information object representing the video capture device to be opened

Exceptions

Type Condition
ArgumentNullException

deviceInfo is null

InvalidOperationException

The grabber already has an opened device

IC4Exception

Check ErrorCode and ToString() for details.

DeviceOpenFromState(byte[])

Restores the opened device and its settings from a memory buffer containing data that was previously written by DeviceSaveState().

Declaration

public void DeviceOpenFromState(byte[] deviceState)

Parameters

Type Name Description
byte[] deviceState

A buffer containing data that was written by DeviceSaveState().

Remarks

If the memory buffer contains settings for properties that could not be written, the function will fail and throw a IC4Exception with the error code set to Incomplete.

Exceptions

Type Condition
ArgumentNullException

deviceState is null.

InvalidOperationException

A device was already opened.

IC4Exception

Check ErrorCode and ToString() for details.

DeviceOpenFromState(Stream)

Restores the opened device and its settings from a Stream containing device state data.

Declaration

public void DeviceOpenFromState(Stream strm)

Parameters

Type Name Description
Stream strm

A Stream containing device state data.

Exceptions

Type Condition
ArgumentNullException

strm is null

InvalidOperationException

A device was already opened.

IC4Exception

Check ErrorCode and ToString() for details.

DeviceOpenFromState(string)

Restores the opened device and its settings from a file that was previously written by DeviceSaveState(string).

Declaration

public void DeviceOpenFromState(string fileName)

Parameters

Type Name Description
string fileName

Path to a file containing device state information

Exceptions

Type Condition
ArgumentNullException

fileName is null

InvalidOperationException

A device was already opened.

IC4Exception

Check ErrorCode and ToString() for details.

DeviceSaveState()

Saves the currently opened video capture device and all its settings into a memory buffer.

Declaration

public byte[] DeviceSaveState()

Returns

Type Description
byte[]

A byte array containing the device state data

Remarks

To restore the device state at a later time, use DeviceOpenFromState(byte[]).

In addition to serializing the device's properties (like Serialize() would), this function also saves the currently opened video capture device so that it can be re-opened at a later time with all settings restored.

Exceptions

Type Condition
InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

DeviceSaveState(string)

Saves the currently opened video capture device and all its settings into a file.

Declaration

public void DeviceSaveState(string fileName)

Parameters

Type Name Description
string fileName

Path to a file that the device stats is written to

Remarks

To restore the device state at a later time, use DeviceOpenFromState(string).

In addition to serializing the device's properties (like Serialize(string) would), this function also saves the currently opened video capture device so that it can be re-opened at a later time with all settings restored.

Exceptions

Type Condition
ArgumentNullException

fileName is null

InvalidOperationException

No device opened

IC4Exception

Check ErrorCode and ToString() for details.

StreamSetup(IDisplay, StreamSetupOption)

Establishes the data stream from the device.

Declaration

public void StreamSetup(IDisplay display, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

Parameters

Type Name Description
IDisplay display

A display to display the images

StreamSetupOption setupOption

Specifies whether to immediately start acquisition after the data stream was set up successfully

Remarks

A device has to be opened before calling this function.

The grabber takes references to the passed display, tying its lifetime to the grabber until the data stream is stopped.

To stop the data stream at a later time, call StreamStop()

Exceptions

Type Condition
ArgumentNullException

display is null

InvalidOperationException

The operation could not be performed. Possible reasons can be

  • No device opened
  • Data stream is already active
  • The function was called from a thread that cannot perform the operation, e.g. a sink callback.
IC4Exception

Check ErrorCode and ToString() for details.

StreamSetup(Sink, IDisplay, StreamSetupOption)

Establishes the data stream from the device.

Declaration

public void StreamSetup(Sink sink, IDisplay display, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

Parameters

Type Name Description
Sink sink

A sink to receive the images

IDisplay display

A display to display the images

StreamSetupOption setupOption

Specifies whether to immediately start acquisition after the data stream was set up successfully

Remarks

A device has to be opened before calling this function.

The grabber takes references to the passed sink and display, tying their lifetime to the grabber until the data stream is stopped.

To stop the data stream at a later time, call StreamStop()

Exceptions

Type Condition
ArgumentNullException

sink is null or display is null

InvalidOperationException

The operation could not be performed. Possible reasons can be

  • No device opened
  • Data stream is already active
  • The function was called from a thread that cannot perform the operation, e.g. a sink callback.
IC4Exception

Check ErrorCode and ToString() for details.

StreamSetup(Sink, StreamSetupOption)

Establishes the data stream from the device.

Declaration

public void StreamSetup(Sink sink, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

Parameters

Type Name Description
Sink sink

A sink to receive the images

StreamSetupOption setupOption

Specifies whether to immediately start acquisition after the data stream was set up successfully

Remarks

A device has to be opened before calling this function.

The grabber takes references to the passed sink, tying its lifetime to the grabber until the data stream is stopped.

To stop the data stream at a later time, call StreamStop()

Exceptions

Type Condition
ArgumentNullException

sink is null

InvalidOperationException

The operation could not be performed. Possible reasons can be

  • No device opened
  • Data stream is already active
  • The function was called from a thread that cannot perform the operation, e.g. a sink callback.
IC4Exception

Check ErrorCode and ToString() for details.

StreamStop()

Stops a data stream that was previously set up by a call to StreamSetup(Sink, IDisplay, StreamSetupOption) or one of its overloads.

Declaration

public void StreamStop()
Remarks

This function releases the sink and/or display references that were used to setup the data stream. If there are no additional references to the sink or display, the sink or display is destroyed.

Exceptions

Type Condition
InvalidOperationException

The function was called from a thread that cannot perform the operation, e.g. a sink callback.

IC4Exception

Check ErrorCode and ToString() for details.

Events

DeviceLost

Occurs then the currently opened video capture device becomes invalid.

Declaration

public event EventHandler DeviceLost
Event Type
Type Description
EventHandler
Remarks

There are multiple reasons for why event may happen:

  • The device was disconnected
  • There is a loose hardware connection
  • There was an internal error in the video capture device
  • There was a driver error

Implements