Grabber Class Reference

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

Classes
struct	StreamStatistics
	Contains statistics counters that can be used to analyze the stream behavior and identify possible bottlenecks. More...

Public Types
using	NotificationToken = void *
	Represents a registered callback.
using	DeviceLostHandler = std::function< void(Grabber &grabber)>
	Function prototype for device-lost event handlers.

Public Member Functions
	Grabber (Error &err=Error::Default())
	Creates a new grabber.
bool	is_valid () const noexcept
	Checks whether this grabber is a valid object.
bool	deviceOpen (const DeviceInfo &dev, Error &err=Error::Default())
	Opens the video capture device specified by the passed device information object.
bool	deviceOpen (const char *identifier, Error &err=Error::Default())
	Opens the video capture matching the specified identifier.
bool	deviceOpen (const std::string &identifier, Error &err=Error::Default())
	Opens the video capture matching the specified identifier.
bool	deviceOpenFromState (const std::vector< uint8_t > &device_state, Error &err=Error::Default())
	Restores the opened device and its settings from a memory buffer containing data that was previously written by Grabber::deviceSaveState(Error&).
bool	deviceOpenFromState (const char *file_path, Error &err=Error::Default())
	Restores the opened device and its settings from a file that was previously written by Grabber::deviceSaveState(const char*, Error&).
bool	deviceOpenFromState (const std::string &file_path, Error &err=Error::Default())
	Restores the opened device and its settings from a file that was previously written by Grabber::deviceSaveState(const std::string&, Error&).
bool	streamSetup (const std::shared_ptr< Sink > &sink, const std::shared_ptr< Display > &display, StreamSetupOption action=StreamSetupOption::AcquisitionStart, Error &err=Error::Default())
	Establishes the data stream from the device.
bool	streamSetup (const std::shared_ptr< Sink > &sink, StreamSetupOption action=StreamSetupOption::AcquisitionStart, Error &err=Error::Default())
	Establishes the data stream from the device.
bool	streamSetup (const std::shared_ptr< Display > &display, StreamSetupOption action=StreamSetupOption::AcquisitionStart, Error &err=Error::Default())
	Establishes the data stream from the device.
std::shared_ptr< Sink >	sink (Error &err=Error::Default()) const
	Returns a shared_ptr to the sink object that was passed to Grabber::streamSetup() when setting up the currently established data stream.
std::shared_ptr< Display >	display (Error &err=Error::Default()) const
	Returns a shared_ptr to the display object that was passed to Grabber::streamSetup() when setting up the currently established data stream.
bool	isStreaming () const
	Checks whethere there is a data stream established from this grabber's video capture device.
bool	acquisitionStart (Error &err=Error::Default())
	Starts the acquisition of images from the video capture device.
bool	acquisitionStop (Error &err=Error::Default())
	Stops the acquisition of images from the video capture device.
bool	streamStop (Error &err=Error::Default())
	Stops a data stream that was previously set up by a call to Grabber::streamSetup().
bool	isAcquisitionActive () const
	Checks whether image acquisition is currently enabled for this grabber's video capture device.
bool	isDeviceOpen () const
	Checks whether the grabber currently has an opened video capture device.
DeviceInfo	deviceInfo (Error &err=Error::Default()) const
	Returns information about the currently opened video capture device.
bool	isDeviceValid () const
	Checks whether the grabber's currently opened video capture device is ready to use.
bool	deviceClose (Error &err=Error::Default())
	Closes the video capture device currently opened by this grabber instance.
PropertyMap	devicePropertyMap (Error &err=Error::Default()) const
	Returns the property map for the currently opened video capture device.
PropertyMap	driverPropertyMap (Error &err=Error::Default()) const
	Returns the property map for the driver of the currently opened video capture device.
StreamStatistics	streamStatistics (Error &err=Error::Default())
	Query statistics counters from the currently running or previously stopped data stream.
std::vector< uint8_t >	deviceSaveState (Error &err=Error::Default())
	Saves the currently opened video capture device and all its settings into a memory buffer.
bool	deviceSaveState (const std::string &file_path, Error &err=Error::Default())
	Saves the currently opened video capture device and all its settings into a file.
bool	deviceSaveState (const char *file_path, Error &err=Error::Default())
	Saves the currently opened video capture device and all its settings into a file.
NotificationToken	eventAddDeviceLost (DeviceLostHandler cb, Error &err=Error::Default())
	Registers a new device-lost event handler.
bool	eventRemoveDeviceLost (NotificationToken token, Error &err=Error::Default())
	Unregisters a device-lost event handler.

Detailed Description

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

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

Grabber objects are created using the constructor Grabber::Grabber(Error&).

After creation, the most common operation on a grabber is to open a device. Call Grabber::deviceOpen() or one of its siblings. A device can also be selected and configured by calling Grabber::deviceOpenFromState().

To establish a data stream from the opened video capture device, call Grabber::streamSetup(), specifying a sink and/or a display.

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 Display can be used to automatically display all images received from a video capture device.

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

Graber objects are movable.

Note

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.

Member Typedef Documentation

DeviceLostHandler

using DeviceLostHandler = std::function<void(Grabber& grabber)>

Function prototype for device-lost event handlers.

Parameters

[in]

grabber

The grabber on which the event handler was registered.

NotificationToken

using NotificationToken = void*

Represents a registered callback.

When a callback function is registered using Grabber::eventAddDeviceLost, a token is returned.

The token can then be used to remove the callback using Grabber::eventRemoveDeviceLost at a later time.

Constructor & Destructor Documentation

Grabber()

Grabber ( Error &  err = Error::Default() )

inline

Creates a new grabber.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Note

If the constructor fails, the grabber object is in an invalid state. All member function calls will fail.

See also

Grabber::is_valid

Member Function Documentation

acquisitionStart()

bool acquisitionStart ( Error &  err = Error::Default() )

inline

Starts the acquisition of images from the video capture device.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Precondition

A data stream has was previously established using Grabber::streamSetup().

Note

This operation is equivalent to executing the AcquisitionStart command on the video capture device's property map.

See also

Grabber::acquisitionStop()

Grabber::streamSetup()

acquisitionStop()

bool acquisitionStop ( Error &  err = Error::Default() )

inline

Stops the acquisition of images from the video capture device.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Precondition

The image acquisition was previously started.

Note

This operation is equivalent to executing the AcquisitionStop command on the video capture device's property map.

See also

Grabber::acquisitionStart()

Grabber::isAcquisitionActive()

deviceClose()

bool deviceClose ( Error &  err = Error::Default() )

inline

Closes the video capture device currently opened by this grabber instance.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Remarks

If the device is closed, all its resources 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 device's PropertyMap objects become invalid.

deviceInfo()

DeviceInfo deviceInfo ( Error &  err = Error::Default() ) const

inline

Returns information about the currently opened video capture device.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

A device information object for the currently opened video capture device.
If an error occurs, an invalid object is returned. Check the err output parameter or PropertyMap::is_valid().

deviceOpen() [1/3]

bool deviceOpen ( const char *  identifier, Error &  err = Error::Default()  )

inline

Opens the video capture matching the specified identifier.

Parameters

[in]	identifier	The model name, unique name or serial of a connected video capture device
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Remarks

If the grabber already has a device open, the function will fail and the error value is set to ErrorCode::InvalidOperation.
If there are multiple devices matching the specified model name, unique name or serial, the function will fail and the error value is set to ErrorCode::Ambiguous.
If there is no device with the specified model name, unique name or serial, the function will fail and the error value is set to ErrorCode::DeviceNotFound.

deviceOpen() [2/3]

bool deviceOpen ( const DeviceInfo &  dev, Error &  err = Error::Default()  )

inline

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

Parameters

[in]	dev	A device information object representing the video capture device to be opened
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

deviceOpen() [3/3]

bool deviceOpen ( const std::string &  identifier, Error &  err = Error::Default()  )

inline

Opens the video capture matching the specified identifier.

Parameters

[in]	identifier	The model name, unique name or serial of a connected video capture device
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Remarks

If the grabber already has a device open, the function will fail and the error value is set to ErrorCode::InvalidOperation.
If there are multiple devices matching the specified model name, unique name or serial, the function will fail and the error value is set to ErrorCode::Ambiguous.
If there is no device with the specified model name, unique name or serial, the function will fail and the error value is set to ErrorCode::DeviceNotFound.

deviceOpenFromState() [1/3]

bool deviceOpenFromState ( const char *  file_path, Error &  err = Error::Default()  )

inline

Restores the opened device and its settings from a file that was previously written by Grabber::deviceSaveState(const char*, Error&).

Parameters

[in]	file_path	Path to a file containing device state information
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

If the memory buffer contains settings for properties that could not be written, the function fails and the error value is set to ErrorCode::Incomplete.

See also

Grabber::deviceSaveState(const char*, Error&)

deviceOpenFromState() [2/3]

bool deviceOpenFromState ( const std::string &  file_path, Error &  err = Error::Default()  )

inline

Restores the opened device and its settings from a file that was previously written by Grabber::deviceSaveState(const std::string&, Error&).

Parameters

[in]	file_path	Path to a file containing device state information
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

If the memory buffer contains settings for properties that could not be written, the function fails and the error value is set to ErrorCode::Incomplete.

See also

Grabber::deviceSaveState(const std::string&, Error&)

deviceOpenFromState() [3/3]

bool deviceOpenFromState ( const std::vector< uint8_t > &  device_state, Error &  err = Error::Default()  )

inline

Restores the opened device and its settings from a memory buffer containing data that was previously written by Grabber::deviceSaveState(Error&).

Parameters

[in]	device_state	A buffer containing data that was written by Grabber::deviceSaveState(Error&).
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

If the memory buffer contains settings for properties that could not be written, the function fails and the error value is set to ErrorCode::Incomplete.

See also

Grabber::deviceSaveState(std::vector<uint8_t>&, Error&)

devicePropertyMap()

PropertyMap devicePropertyMap ( Error &  err = Error::Default() ) const

inline

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

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

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

A PropertyMap object.
If an error occurs, an invalid object is returned. Check the err output parameter or PropertyMap::is_valid().

deviceSaveState() [1/3]

bool deviceSaveState ( const char *  file_path, Error &  err = Error::Default()  )

inline

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

Parameters

	file_path	Path to a file that the device stats is written to
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

To restore the device state at a later time, use Grabber::deviceOpenFromState(const char*, Error&).
In addition to serializing the device's properties (like PropertyMap::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.

See also

Grabber::deviceOpenFromState(const char*, Error&)

Grabber::deviceSaveState(std::vector<uint8_t>&, Error&)

deviceSaveState() [2/3]

bool deviceSaveState ( const std::string &  file_path, Error &  err = Error::Default()  )

inline

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

Parameters

	file_path	Path to a file that the device stats is written to
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

To restore the device state at a later time, use Grabber::deviceOpenFromState(const std::string&, Error&).
In addition to serializing the device's properties (like PropertyMap::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.

See also

Grabber::deviceOpenFromState(const std::string&, Error&)

Grabber::deviceSaveState(std::vector<uint8_t>&, Error&)

deviceSaveState() [3/3]

std::vector< uint8_t > deviceSaveState ( Error &  err = Error::Default() )

inline

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

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

A vector of bytes containing the device state data.

Note

To restore the device state at a later time, use Grabber::deviceOpenFromState(const std::vector<uint8_t>&, Error&).
In addition to serializing the device's properties (like PropertyMap::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.

See also

Grabber::deviceOpenFromState(const std::vector<uint8_t>&, Error&)

Grabber::deviceSaveState(const std::string&, Error&)

display()

std::shared_ptr< Display > display ( Error &  err = Error::Default() ) const

inline

Returns a shared_ptr to the display object that was passed to Grabber::streamSetup() when setting up the currently established data stream.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

shared_ptr to the display object, or nullptr if an error occurred.
Check the err output parameter for details.

driverPropertyMap()

PropertyMap driverPropertyMap ( Error &  err = Error::Default() ) const

inline

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

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

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

A PropertyMap object.
If an error occurs, an invalid object is returned. Check the err output parameter or PropertyMap::is_valid().

eventAddDeviceLost()

NotificationToken eventAddDeviceLost ( DeviceLostHandler  cb, Error &  err = Error::Default()  )

inline

Registers a new device-lost event handler.

Parameters

[in]	cb	Callback function to be called when the connection to the currently opened device ist lost.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

A token that can be used to unregister the callback using .\n If an error occurrs, the function returns nullptr.

See also

Grabber::eventRemoveDeviceLost

eventRemoveDeviceLost()

bool eventRemoveDeviceLost ( NotificationToken  token, Error &  err = Error::Default()  )

inline

Unregisters a device-lost event handler.

Parameters

[in]	token	A token that was returned when registering an event handler using Grabber::eventAddDeviceLost().
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

See also

Grabber::eventAddDeviceLost

is_valid()

bool is_valid ( ) const

inlinenoexcept

Checks whether this grabber is a valid object.

If there is an error in the constructor, and function was not configured to throw on error, an invalid object is created. All member function calls will fail.

Returns

true, if this grabber was constructed successfully, otherwise false.
In case of an error, check the constructor's error parameter for details.

See also

Error Handling

isAcquisitionActive()

bool isAcquisitionActive ( ) const

inline

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

Returns

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.

isDeviceOpen()

bool isDeviceOpen ( ) const

inline

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

Returns

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

isDeviceValid()

bool isDeviceValid ( ) const

inline

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

Returns

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

isStreaming()

bool isStreaming ( ) const

inline

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

Returns

true, if a data stream was previously established by calling Grabber::streamSetup().
Otherwise, or if the data stream was stopped again, false.

sink()

std::shared_ptr< Sink > sink ( Error &  err = Error::Default() ) const

inline

Returns a shared_ptr to the sink object that was passed to Grabber::streamSetup() when setting up the currently established data stream.

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

shared_ptr to the sink object, or nullptr if an error occurred.
Check the err output parameter for details.

streamSetup() [1/3]

bool streamSetup ( const std::shared_ptr< Display > &  display, StreamSetupOption  action = StreamSetupOption::AcquisitionStart, Error &  err = Error::Default()  )

inline

Establishes the data stream from the device.

A data stream is required for image acquisition from the video capture device, and must include a Sink, a Display, or both.

Parameters

[in]	display	A display to display images
[in]	action	Specifies whether to immediately start acquisition after the data stream was set up successfully
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Precondition

A device was previously opened using Grabber::deviceOpen() or one of its sibling functions.

Note

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

See also

Grabber::streamStop()

Grabber::acquisitionStart()

streamSetup() [2/3]

bool streamSetup ( const std::shared_ptr< Sink > &  sink, const std::shared_ptr< Display > &  display, StreamSetupOption  action = StreamSetupOption::AcquisitionStart, Error &  err = Error::Default()  )

inline

Establishes the data stream from the device.

A data stream is required for image acquisition from the video capture device, and must include a Sink, a Display, or both.

Parameters

[in]	sink	A sink to receive the images
[in]	display	A display to display images
[in]	action	Specifies whether to immediately start acquisition after the data stream was set up successfully
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Precondition

A device was previously opened using Grabber::deviceOpen() or one of its sibling functions.

Note

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

See also

Grabber::streamStop()

Grabber::acquisitionStart()

streamSetup() [3/3]

bool streamSetup ( const std::shared_ptr< Sink > &  sink, StreamSetupOption  action = StreamSetupOption::AcquisitionStart, Error &  err = Error::Default()  )

inline

Establishes the data stream from the device.

A data stream is required for image acquisition from the video capture device, and must include a Sink, a Display, or both.

Parameters

[in]	sink	A sink to receive the images
[in]	action	Specifies whether to immediately start acquisition after the data stream was set up successfully
[out]	err	Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Precondition

A device was previously opened using Grabber::deviceOpen() or one of its sibling functions.

Note

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

See also

Grabber::streamStop()

Grabber::acquisitionStart()

streamStatistics()

StreamStatistics streamStatistics ( Error &  err = Error::Default() )

inline

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

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

A StreamStatistics structure containing statistics counters.

Precondition

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

streamStop()

bool streamStop ( Error &  err = Error::Default() )

inline

Stops a data stream that was previously set up by a call to Grabber::streamSetup().

Parameters

[out]

err

Reference to an error handler. See Error Handling for details.

Returns

true on success, otherwise false.

Note

This function releases the sink and/or display references that were passed to .\n If there are no external references to the sink or display, the sink or display is destroyed.