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< Sinksink (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]grabberThe 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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]identifierThe model name, unique name, serial, user id, IPV4 address or MAC address of a connected video capture device
[out]errReference 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]devA device information object representing the video capture device to be opened
[out]errReference 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]identifierThe model name, unique name or serial of a connected video capture device
[out]errReference 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_pathPath to a file containing device state information
[out]errReference 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_pathPath to a file containing device state information
[out]errReference 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_stateA buffer containing data that was written by Grabber::deviceSaveState(Error&).
[out]errReference 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]errReference 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_pathPath to a file that the device stats is written to
[out]errReference 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_pathPath to a file that the device stats is written to
[out]errReference 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]errReference 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]errReference 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]errReference 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]cbCallback function to be called when the connection to the currently opened device ist lost.
[out]errReference 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]tokenA token that was returned when registering an event handler using Grabber::eventAddDeviceLost().
[out]errReference 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]errReference 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]displayA display to display images
[in]actionSpecifies whether to immediately start acquisition after the data stream was set up successfully
[out]errReference 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]sinkA sink to receive the images
[in]displayA display to display images
[in]actionSpecifies whether to immediately start acquisition after the data stream was set up successfully
[out]errReference 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]sinkA sink to receive the images
[in]actionSpecifies whether to immediately start acquisition after the data stream was set up successfully
[out]errReference 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]errReference 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]errReference 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.