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_GRABBER *	ic4_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] size Size 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_ptr User 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]	pGrabber	Pointer to the grabber whose device was lost
[in]	user_ptr	User 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] pGrabber A 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] pGrabber A 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] ppGrabber Pointer 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] pGrabber A 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]	pGrabber	A grabber with an opened video capture device
[out]	ppPropertyMap	Pointer 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]	pGrabber	A grabber instance that does not have an opened video capture device
[in]	dev	A 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]	pGrabber	A grabber instance that does not have an opened video capture device
[in]	identifier	The 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]	pGrabber	A grabber object without an opened device
[in]	data	Pointer to a memory buffer containing data that was written by ic4_grabber_device_save_state
[in]	data_size	Size 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]	pGrabber	A grabber object without an opened device
[in]	file_path	Path 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]	pGrabber	A grabber object with an opened device
[in]	alloc	Pointer to a function that allocates the memory buffer. For example, `malloc` can be passed here.
[out]	ppData	Pointer 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_size	Pointer 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]	pGrabber	A grabber object with an opened device
[in]	file_path	Path 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]	pGrabber	A grabber with an opened video capture device
[out]	ppPropertyMap	Pointer 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]	pGrabber	The grabber for which the callback is registered
[in]	handler	The function to be called when the device is lost
[in]	user_ptr	User data to be passed in calls to handler.
[in]	deleter	A 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]	pGrabber	The grabber on which the callback is currently registered
[in]	handler	Pointer to the function to be unregistered
[in]	user_ptr	User 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]	pGrabber	A grabber instance with an opened video capture device
[out]	ppDev	A 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]	pGrabber	A grabber with an established data stream
[out]	ppDisplay	A 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]	pGrabber	A grabber with an established data stream
[out]	ppSink	A 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]	pGrabber	A grabber object
[out]	stats	A 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] pGrabber A 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] pGrabber A 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] pGrabber A 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] pGrabber A 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] pGrabber A 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]	pGrabber	A grabber object that has opened a video capture device
[in]	sink	A sink (Sinks) to receive the images
[in]	display	A Display to display images
[in]	start_acquisition	If `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] pGrabber A 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] pGrabber A 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