Grabber States

During its lifetime, the IC4_GRABBER object transitions through multiple states.

The current grabber state can be observed through a collection state query functions:

Initial State

Initially, the grabber has not opened a video capture device.

Property Value
ic4_grabber_is_device_open false
ic4_grabber_is_device_valid false
ic4_grabber_is_streaming false
ic4_grabber_is_acquisition_active false

Calling ic4_grabber_device_close always brings the grabber back to the Initial state.

Opening a device using ic4_grabber_device_open or one of its sibling functions puts the grabber into the Device Opened state.

Device Opened

In this state, a device was opened, but streaming has not been started yet. Once opened, the device should be configured to prepare the required settings for streaming.

Property Value
ic4_grabber_is_device_open true
ic4_grabber_is_device_valid true
ic4_grabber_is_streaming false
ic4_grabber_is_acquisition_active false

Calling ic4_grabber_device_close brings the grabber back to the Initial state.

Calling ic4_grabber_stream_setup elevates the grabber state to Streaming. If the start_acquisition parameter of the call is set to true. acquisition is started immediately and the grabber state moves to Acquisition Active.

If the connection to the device is lost (e.g. it is unplugged), the grabber moves into the Device Invalid state. Additionally, the device-lost event (see ic4_grabber_event_add_device_lost) is raised.

Streaming

In this state, a streaming connection between the device and the host has been established. Everything is prepared for the device to send and the host to receive image data.

Property Value
ic4_grabber_is_device_open true
ic4_grabber_is_device_valid true
ic4_grabber_is_streaming true
ic4_grabber_is_acquisition_active false

To start acquisition, call ic4_grabber_acquisition_start or execute the IC4_PROPID_ACQUISITION_START command in the device's property map. After that, the grabber is in the Acquisition Active state.

Calling ic4_grabber_stream_stop stops the data stream and moves the grabber back to the Device Opened state.

Calling ic4_grabber_device_close stops the data stream, closes the device and puts the grabber back to the Initial state.

If the connection to the device is lost (e.g. it is unplugged), the grabber moves into the Device Invalid state. Additionally, the device-lost event (see ic4_grabber_event_add_device_lost) is raised.

Acquisition Active

In this state, the device is sending images to the host.

Property Value
ic4_grabber_is_device_open true
ic4_grabber_is_device_valid true
ic4_grabber_is_streaming true
ic4_grabber_is_acquisition_active true

Please note that the device may pause transmission because of certain device settings, e.g. IC4_PROPID_TRIGGER_MODE.

To stop acquisition, call ic4_grabber_acquisition_stop or execute the IC4_PROPID_ACQUISITION_STOP command in the device's property map. After that, the grabber is in the Streaming state.

Calling ic4_grabber_stream_stop stops acquisition in the device, stops the data stream and moves the grabber back to the Device Opened state.

Calling ic4_grabber_device_close stops the data stream, closes the device and puts the grabber back to the Initial state.

If the connection to the device is lost (e.g. it is unplugged), the grabber moves into the Device Invalid state. Additionally, the device-lost event (see ic4_grabber_event_add_device_lost) is raised.

Device Invalid

In this state, the connection to the device was lost. ic4_grabber_is_device_valid returns false.

Property Value
ic4_grabber_is_device_open true
ic4_grabber_is_device_valid false

Calling DeviceClose puts the grabber back to the Initial state.