Represents an opened video capture device, allowing device configuration and stream setup.
More...
|
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...
|
|
|
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().
|
|
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.
◆ ic4_device_state_allocator
typedef void *(* ic4_device_state_allocator) (size_t size) |
◆ 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
-
◆ 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
-
◆ 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.
◆ ic4_grabber_device_get_property_map()
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.
- See also
- ic4_propmap_unref
◆ ic4_grabber_device_open()
◆ ic4_grabber_device_open_by_identifier()
bool ic4_grabber_device_open_by_identifier |
( |
struct IC4_GRABBER * |
pGrabber, |
|
|
const char * |
identifier |
|
) |
| |
◆ 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 |
|
) |
| |
◆ ic4_grabber_device_save_state()
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 |
|
) |
| |
◆ ic4_grabber_driver_get_property_map()
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.
- See also
- ic4_propmap_unref
◆ ic4_grabber_event_add_device_lost()
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()
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()
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.
- See also
- ic4_grabber_is_device_open
◆ ic4_grabber_get_display()
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()
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()
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 | ) |
|
◆ 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
.
- 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
.
◆ ic4_grabber_is_streaming()
bool ic4_grabber_is_streaming |
( |
struct IC4_GRABBER * |
pGrabber | ) |
|
◆ ic4_grabber_ref()
Increases the grabber's internal reference count by one.
- Parameters
-
[in] | pGrabber | A pointer to a grabber |
- Returns
- The pointer passed via pGrabber
- See also
- ic4_grabber_unref
◆ ic4_grabber_stream_setup()
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 |
- See also
- ic4_grabber_ref