Grabber Class Reference

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

Classes

struct

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, serial, user id, IPV4 address or MAC address 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 identifier, the function will fail and the error value is set to ErrorCode::Ambiguous.
If there is no device with the specified identifier, 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.