Grabber

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

Data Structures

struct   IC4_STREAM_STATS

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

struct   IC4_GRABBER

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

Typedefs

typedef void(*  ic4_grabber_device_lost_handler) (struct IC4_GRABBER *pGrabber, void *user_ptr)

Function pointer for the device-lost handler.

typedef void(* ic4_grabber_device_lost_deleter) (void *user_ptr)

Function pointer for cleanup of the device-lost user data.

typedef void *(* ic4_device_state_allocator) (size_t size)

Callback function called to allocate memory during the call of ic4_grabber_device_save_state.

Functions

bool  ic4_grabber_create (struct IC4_GRABBER **ppGrabber)

Creates a new grabber.

struct IC4_GRABBERic4_grabber_ref (struct IC4_GRABBER *pGrabber)

Increases the grabber's internal reference count by one.

void ic4_grabber_unref (struct IC4_GRABBER *pGrabber)

Decreases the grabber's internal reference count by one.

bool ic4_grabber_device_open (struct IC4_GRABBER *pGrabber, struct IC4_DEVICE_INFO *dev)

Opens the video capture device specified by the passed IC4_DEVICE_INFO.

bool ic4_grabber_device_open_by_identifier (struct IC4_GRABBER *pGrabber, const char *identifier)

Opens the video capture matching the specified identifier.

bool ic4_grabber_get_device (struct IC4_GRABBER *pGrabber, struct IC4_DEVICE_INFO **ppDev)

Returns information about the currently opened video capture device.

bool ic4_grabber_is_device_open (struct IC4_GRABBER *pGrabber)

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

bool ic4_grabber_is_device_valid (struct IC4_GRABBER *pGrabber)

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

bool ic4_grabber_device_close (struct IC4_GRABBER *pGrabber)

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

bool ic4_grabber_device_get_property_map (struct IC4_GRABBER *pGrabber, struct IC4_PROPERTY_MAP **ppPropertyMap)

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

bool ic4_grabber_driver_get_property_map (struct IC4_GRABBER *pGrabber, struct IC4_PROPERTY_MAP **ppPropertyMap)

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

bool ic4_grabber_stream_setup (struct IC4_GRABBER *pGrabber, struct IC4_SINK *sink, struct IC4_DISPLAY *display, bool start_acquisition)

Establishes the data stream from the device.

bool ic4_grabber_stream_stop (struct IC4_GRABBER *pGrabber)

Stops a data stream that was previously set up by a call to ic4_grabber_stream_setup().

bool ic4_grabber_is_streaming (struct IC4_GRABBER *pGrabber)

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

bool ic4_grabber_acquisition_start (struct IC4_GRABBER *pGrabber)

Starts the acquisition of images from the video capture device.

bool ic4_grabber_acquisition_stop (struct IC4_GRABBER *pGrabber)

Stops the acquisition of images from the video capture device.

bool ic4_grabber_is_acquisition_active (struct IC4_GRABBER *pGrabber)

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

bool ic4_grabber_get_sink (struct IC4_GRABBER *pGrabber, struct IC4_SINK **ppSink)

Returns a reference to the Sinks object that was passed to ic4_grabber_stream_setup() when setting up the currently established data stream.

bool ic4_grabber_get_display (struct IC4_GRABBER *pGrabber, struct IC4_DISPLAY **ppDisplay)

Returns a reference to the Display object that was passed to ic4_grabber_stream_setup() when setting up the currently established data stream.

bool ic4_grabber_event_add_device_lost (struct IC4_GRABBER *pGrabber, ic4_grabber_device_lost_handler handler, void *user_ptr, ic4_grabber_device_lost_deleter deleter)

Registers a function to be called when the currently opened video capture device was disconnected.

bool ic4_grabber_event_remove_device_lost (struct IC4_GRABBER *pGrabber, ic4_grabber_device_lost_handler handler, void *user_ptr)

Unregisters a device-lost handler that was previously registered using ic4_grabber_event_add_device_lost().

bool ic4_grabber_get_stream_stats (struct IC4_GRABBER *pGrabber, struct IC4_STREAM_STATS *stats)

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

bool ic4_grabber_device_save_state (struct IC4_GRABBER *pGrabber, ic4_device_state_allocator alloc, void **ppData, size_t *data_size)

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

 
bool ic4_grabber_device_save_state_to_file (struct IC4_GRABBER *pGrabber, const char *file_path)

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

bool ic4_grabber_device_open_from_state (struct IC4_GRABBER *pGrabber, const void *data, size_t data_size)

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

bool ic4_grabber_device_open_from_state_file (struct IC4_GRABBER *pGrabber, const char *file_path)

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

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.

To create a grabber object, call ic4_grabber_create().

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

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

One of the Sinks 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. Queue Sink or Snap Sink.

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 ic4_grabber_acquisition_start() to begin the transfer of images.

When the grabber object is no longer needed, call ic4_grabber_unref(). Please note that some other object references, e.g. IC4_IMAGE_BUFFER, can keep the device opened as long as they exist, since they point into device driver memory.

Typedef Documentation

◆ ic4_device_state_allocator

typedef void *(* ic4_device_state_allocator) (size_t size)

Callback function called to allocate memory during the call of ic4_grabber_device_save_state.

Parameters
[in]sizeSize of the memory buffer to be allocated.
Returns
The pointer to the allocated memory buffer, or NULL if the allocation was not possible.
Note
If this function returns NULL, the call to ic4_grabber_device_save_state will fail.
See also
ic4_grabber_device_save_state

◆ ic4_grabber_device_lost_deleter

typedef void(* ic4_grabber_device_lost_deleter) (void *user_ptr)

Function pointer for cleanup of the device-lost user data.

Parameters
[in]user_ptrUser data that was specified when calling ic4_grabber_event_add_device_lost()

◆ ic4_grabber_device_lost_handler

typedef void(* ic4_grabber_device_lost_handler) (struct IC4_GRABBER *pGrabber, void *user_ptr)

Function pointer for the device-lost handler.

Parameters
[in]pGrabberPointer to the grabber whose device was lost
[in]user_ptrUser data that was specified when calling ic4_grabber_event_add_device_lost()

Function Documentation

◆ ic4_grabber_acquisition_start()

bool ic4_grabber_acquisition_start ( struct IC4_GRABBER pGrabber)

Starts the acquisition of images from the video capture device.

Parameters
[in]pGrabberA grabber with an established data stream
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Precondition
A data stream has was previously established using ic4_grabber_stream_setup().
Note
This operation is equivalent to executing the AcquisitionStart command on the video capture device's property map.
See also
ic4_grabber_acquisition_stop
ic4_grabber_stream_setup

◆ ic4_grabber_acquisition_stop()

bool ic4_grabber_acquisition_stop ( struct IC4_GRABBER pGrabber)

Stops the acquisition of images from the video capture device.

Parameters
[in]pGrabberA grabber with acquisition active
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
This operation is equivalent to executing the AcquisitionStop command on the video capture device's property map.
See also
ic4_grabber_acquisition_start

◆ ic4_grabber_create()

bool ic4_grabber_create ( struct IC4_GRABBER **  ppGrabber)

Creates a new grabber.

Parameters
[out]ppGrabberPointer to receive the handle to the new grabber object.
When the grabber is no longer required, release the object reference using ic4_grabber_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
See also
ic4_grabber_unref

◆ ic4_grabber_device_close()

bool ic4_grabber_device_close ( struct IC4_GRABBER pGrabber)

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

Parameters
[in]pGrabberA grabber with an opened video capture device
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
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.
  • Properties objects become invalid.

◆ ic4_grabber_device_get_property_map()

bool ic4_grabber_device_get_property_map ( struct IC4_GRABBER pGrabber,
struct IC4_PROPERTY_MAP **  ppPropertyMap 
)

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
[in]pGrabberA grabber with an opened video capture device
[out]ppPropertyMapPointer to a handle that receives the property map.
When the property map is longer required, call ic4_propmap_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Remarks
The property map handle and dependent objects retrieved from it will not keep the device in an opened state. If the device is closed, all future operations on the property map will result in an error.
See also
ic4_propmap_unref

◆ ic4_grabber_device_open()

bool ic4_grabber_device_open ( struct IC4_GRABBER pGrabber,
struct IC4_DEVICE_INFO dev 
)

Opens the video capture device specified by the passed IC4_DEVICE_INFO.

Parameters
[in]pGrabberA grabber instance that does not have an opened video capture device
[in]devA IC4_DEVICE_INFO representing the video capture device to be opened
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Remarks
If the grabber already has a device open, the function will fail and the error value is set to IC4_ERROR_INVALID_OPERATION.
See also
ic4_grabber_open_dev_by_name
ic4_grabber_device_close
ic4_grabber_is_device_open
ic4_grabber_is_device_valid

◆ ic4_grabber_device_open_by_identifier()

bool ic4_grabber_device_open_by_identifier ( struct IC4_GRABBER pGrabber,
const char *  identifier 
)

Opens the video capture matching the specified identifier.

Parameters
[in]pGrabberA grabber instance that does not have an opened video capture device
[in]identifierThe model name, unique name, serial, user id, IPV4 address or MAC address of a connected video capture device
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Remarks
If the grabber already has a device open, the function will fail and the error value is set to IC4_ERROR_INVALID_OPERATION.
If there are multiple devices matching the specified identifier, the function will fail and the error value is set to IC4_ERROR_AMBIGUOUS.
If there is no device with the specified identifier, the function will fail and the error value is set to IC4_ERROR_DEVICE_NOT_FOUND.
See also
ic4_grabber_device_open
ic4_grabber_device_close
ic4_grabber_is_device_open
ic4_grabber_is_device_valid

◆ ic4_grabber_device_open_from_state()

bool ic4_grabber_device_open_from_state ( struct IC4_GRABBER pGrabber,
const void *  data,
size_t  data_size 
)

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

Parameters
[in]pGrabberA grabber object without an opened device
[in]dataPointer to a memory buffer containing data that was written by ic4_grabber_device_save_state
[in]data_sizeSize of the memory buffer pointed to by pData
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
If the memory buffer contains settings for properties that could not be written, the function fails and the error value is set to IC4_ERROR_INCOMPLETE.
See also
ic4_grabber_device_save_state

◆ ic4_grabber_device_open_from_state_file()

bool ic4_grabber_device_open_from_state_file ( struct IC4_GRABBER pGrabber,
const char *  file_path 
)

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

Parameters
[in]pGrabberA grabber object without an opened device
[in]file_pathPath to a file containing device state information
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
If the file contains settings for properties that could not be written, the function fails and the error value is set to IC4_ERROR_INCOMPLETE.
See also
ic4_grabber_device_save_state_to_file
ic4_grabber_device_open_from_state

◆ ic4_grabber_device_save_state()

bool ic4_grabber_device_save_state ( struct IC4_GRABBER pGrabber,
ic4_device_state_allocator  alloc,
void **  ppData,
size_t *  data_size 
)

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

Parameters
[in]pGrabberA grabber object with an opened device
[in]allocPointer to a function that allocates the memory buffer.
For example, malloc can be passed here.
[out]ppDataPointer to a pointer to receive the newly-allocated memory buffer containing the device state.
The caller is responsible for releasing the memory, using a function that can free memory returned by alloc.
[out]data_sizePointer to size_t to receive the size of the memory buffer allocated by the call
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
To restore the device state at a later time, use ic4_grabber_device_open_from_state.
In addition to serializing the device's properties (like ic4_propmap_serialize_to_memory() 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
ic4_grabber_load_device_state
ic4_grabber_save_device_state_to_file

◆ ic4_grabber_device_save_state_to_file()

bool ic4_grabber_device_save_state_to_file ( struct IC4_GRABBER pGrabber,
const char *  file_path 
)

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

Parameters
[in]pGrabberA grabber object with an opened device
[in]file_pathPath to a file that the device state is written to.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
To restore the device state at a later time, use ic4_grabber_device_open_from_state_file().
In addition to serializing the device's properties (like ic4_propmap_serialize_to_file() 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
ic4_grabber_device_open_from_state_file
ic4_grabber_device_save_state

◆ ic4_grabber_driver_get_property_map()

bool ic4_grabber_driver_get_property_map ( struct IC4_GRABBER pGrabber,
struct IC4_PROPERTY_MAP **  ppPropertyMap 
)

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
[in]pGrabberA grabber with an opened video capture device
[out]ppPropertyMapPointer to a handle that receives the property map.
When the property map is longer required, call ic4_propmap_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Remarks
The property map handle and dependent objects retrieved from it will not keep the device in an opened state. If the device is closed, all future operations on the property map will result in an error.
See also
ic4_propmap_unref

◆ ic4_grabber_event_add_device_lost()

bool ic4_grabber_event_add_device_lost ( struct IC4_GRABBER pGrabber,
ic4_grabber_device_lost_handler  handler,
void *  user_ptr,
ic4_grabber_device_lost_deleter  deleter 
)

Registers a function to be called when the currently opened video capture device was disconnected.

Parameters
[in]pGrabberThe grabber for which the callback is registered
[in]handlerThe function to be called when the device is lost
[in]user_ptrUser data to be passed in calls to handler.
[in]deleterA function to be called when the handler was unregistered and the user_ptr will no longer be required.
The deleter function can be used to release data associated with user_ptr.
The deleter function will be called when the device-lost handler is unregistered, or the grabber object itself is destroyed.
Note
To unregister a device-lost handler, call ic4_grabber_event_remove_device_lost().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_grabber_event_remove_device_lost()

bool ic4_grabber_event_remove_device_lost ( struct IC4_GRABBER pGrabber,
ic4_grabber_device_lost_handler  handler,
void *  user_ptr 
)

Unregisters a device-lost handler that was previously registered using ic4_grabber_event_add_device_lost().

Parameters
[in]pGrabberThe grabber on which the callback is currently registered
[in]handlerPointer to the function to be unregistered
[in]user_ptrUser data that the function was previously registered with
Note
The pair of handler and user_ptr has to be an exact match to the parameters used in the call to ic4_grabber_event_add_device_lost().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_grabber_get_device()

bool ic4_grabber_get_device ( struct IC4_GRABBER pGrabber,
struct IC4_DEVICE_INFO **  ppDev 
)

Returns information about the currently opened video capture device.

Parameters
[in]pGrabberA grabber instance with an opened video capture device
[out]ppDevA pointer to a handle to receive the device information.
When the device information is no longer required, release the object reference using ic4_devinfo_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Remarks
If the grabber does not have an opened video capture device, the function will fail and the error value is set to IC4_ERROR_INVALID_OPERATION.
See also
ic4_grabber_is_device_open

◆ ic4_grabber_get_display()

bool ic4_grabber_get_display ( struct IC4_GRABBER pGrabber,
struct IC4_DISPLAY **  ppDisplay 
)

Returns a reference to the Display object that was passed to ic4_grabber_stream_setup() when setting up the currently established data stream.

Parameters
[in]pGrabberA grabber with an established data stream
[out]ppDisplayA pointer to a sink handle to receive the currently connected display.
This is a new reference. If it is no longer in use, it must be released using ic4_display_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
See also
ic4_grabber_stream_setup

◆ ic4_grabber_get_sink()

bool ic4_grabber_get_sink ( struct IC4_GRABBER pGrabber,
struct IC4_SINK **  ppSink 
)

Returns a reference to the Sinks object that was passed to ic4_grabber_stream_setup() when setting up the currently established data stream.

Parameters
[in]pGrabberA grabber with an established data stream
[out]ppSinkA pointer to a sink handle to receive the currently connected sink.
This is a new reference. If it is no longer in use, it must be released using ic4_sink_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
See also
ic4_grabber_stream_setup

◆ ic4_grabber_get_stream_stats()

bool ic4_grabber_get_stream_stats ( struct IC4_GRABBER pGrabber,
struct IC4_STREAM_STATS stats 
)

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

Parameters
[in]pGrabberA grabber object
[out]statsA pointer to a structure to receive the stream statistics
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Precondition
This operation is only valid after a data stream was established once.

◆ ic4_grabber_is_acquisition_active()

bool ic4_grabber_is_acquisition_active ( struct IC4_GRABBER pGrabber)

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

Parameters
[in]pGrabberA grabber object
Returns
true, if image acquisition is currently active, otherwise false.
Remarks
This function neither clears nor sets the error status returned by ic4_get_last_error.
See also
ic4_grabber_acquisition_start
ic4_grabber_acquisition_stop

◆ ic4_grabber_is_device_open()

bool ic4_grabber_is_device_open ( struct IC4_GRABBER pGrabber)

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

Parameters
[in]pGrabberA grabber object
Returns
true, if the grabber has an opened video capture device, otherwise false.
Remarks
This function neither clears nor sets the error status returned by ic4_get_last_error().
See also
ic4_grabber_device_open

◆ ic4_grabber_is_device_valid()

bool ic4_grabber_is_device_valid ( struct IC4_GRABBER pGrabber)

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

Parameters
[in]pGrabberA grabber object
Returns
true, if the grabber has an opened video capture device that is ready to use, otherwise false.
Remarks
This function neither clears nor sets the error status returned by ic4_get_last_error().
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

◆ ic4_grabber_is_streaming()

bool ic4_grabber_is_streaming ( struct IC4_GRABBER pGrabber)

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

Parameters
[in]pGrabberA grabber object
Returns
true, if a data stream was previously established by calling ic4_grabber_stream_setup().
Otherwise, or if the data stream was stopped again, false.
Remarks
This function neither clears nor sets the error status returned by ic4_get_last_error().
See also
ic4_grabber_stream_setup
ic4_grabber_stream_stop

◆ ic4_grabber_ref()

struct IC4_GRABBER * ic4_grabber_ref ( struct IC4_GRABBER pGrabber)

Increases the grabber's internal reference count by one.

Parameters
[in]pGrabberA pointer to a grabber
Returns
The pointer passed via pGrabber
Remarks
If pGrabber is NULL, the function returns NULL. An error value is not set.
See also
ic4_grabber_unref

◆ ic4_grabber_stream_setup()

bool ic4_grabber_stream_setup ( struct IC4_GRABBER pGrabber,
struct IC4_SINK sink,
struct IC4_DISPLAY display,
bool  start_acquisition 
)

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 (Sinks), a Display, or both.

Parameters
[in]pGrabberA grabber object that has opened a video capture device
[in]sinkA sink (Sinks) to receive the images
[in]displayA Display to display images
[in]start_acquisitionIf true, immediately start image acquisition after the data stream was set up.
Otherwise, a call to ic4_grabber_acquisition_start() is required to start image acquisition later.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Precondition
A device was previously opened using ic4_grabber_device_open() 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
ic4_grabber_stream_stop
ic4_grabber_acquisition_start

◆ ic4_grabber_stream_stop()

bool ic4_grabber_stream_stop ( struct IC4_GRABBER pGrabber)

Stops a data stream that was previously set up by a call to ic4_grabber_stream_setup().

Parameters
[in]pGrabberA grabber with an established data stream
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Note
This function releases the sink and display references that were passed to ic4_grabber_stream_setup().
If there are no external references to the sink or display, the sind or display is destroyed.
See also
ic4_grabber_stream_setup

◆ ic4_grabber_unref()

void ic4_grabber_unref ( struct IC4_GRABBER pGrabber)

Decreases the grabber's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters
[in]pGrabberA pointer to a grabber
Remarks
If pGrabber is NULL, the function does nothing. An error value is not set.
If the grabber object is destroyed, 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.
  • The device is closed. Properties objects become invalid.
See also
ic4_grabber_ref