Class Grabber

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

Inheritance

object

HandleObject

Grabber

Implements

IDisposable

Inherited Members

HandleObject.Dispose(bool)

HandleObject.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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 one of the constructors Grabber(), Grabber(DeviceInfo) or Grabber(string).

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

• passing string identifying a device to DeviceOpen(string)
• passing a DeviceInfo object to DeviceOpen(DeviceInfo)

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

• passing the file name of a device state file to DeviceOpenFromState(string)
• passing a byte array contains device state data to DeviceOpenFromState(byte[])
• passing a Stream containing device state data to DeviceOpenFromState(Stream)

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.

Grabber(string)

Creates a new grabber and immediately opens the video capture device matching the specified identifier.

Declaration

public Grabber(string identifier)

Parameters

Type	Name	Description
string	identifier	The model name, unique name, serial, user id, IPV4 address or MAC address of a connected video capture device to be opened immediately

Remarks

If there are multiple devices matching the specified identifier, the constructor will fail and throw a IC4Exception with the error code set to Ambiguous.

If there is no device matching the specified identifier, the constructor will fail and throw a IC4Exception with the error code set to DeviceNotFound.

Exceptions

Type	Condition
ArgumentNullException	deviceInfo is null
IC4Exception	Check ErrorCode and ToString() for details.

Grabber(DeviceInfo)

Creates a new grabber and immediately opens the video capture device represented by the passed DeviceInfo object.

Declaration

public Grabber(DeviceInfo deviceInfo)

Parameters

Type	Name	Description
DeviceInfo	deviceInfo	A device information object representing a video capture device to be opened immediately

Exceptions

Type	Condition
ArgumentNullException	deviceInfo is null
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 device matching the specified identifier.

Declaration

public void DeviceOpen(string identifier)

Parameters

Type	Name	Description
string	identifier	The model name, unique name, serial, user id, IPV4 address or MAC address of a connected video capture device

Remarks

If there are multiple devices matching the specified identifier, the function will fail and throw a IC4Exception with the error code set to Ambiguous.

If there is no device matching the specified identifier, 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

IDisposable