Configuring a Video Capture Device

This section contains a small example program showing how to configure a video capture device through the IC4_PROPERTY_MAP interface.

The article Accessing Device Properties explains the capabilities of the property interface in detail.

Open a Device

For demonstration purposes, we open the first available video capture device:

// Create a grabber object
struct IC4_GRABBER* grabber = NULL;
ic4_grabber_create(&grabber);
 
// Find the first available video capture device
struct IC4_DEVICE_ENUM* enumerator = NULL;
ic4_devenum_create(&enumerator);
ic4_devenum_update_device_list(enumerator);
struct IC4_DEVICE_INFO* info = NULL;
ic4_devenum_get_devinfo(enumerator, 0, &info);
ic4_devenum_unref(enumerator);
 
// Open it
ic4_grabber_device_open(grabber, info);
ic4_devinfo_unref(info);
void ic4_devenum_unref(struct IC4_DEVICE_ENUM *pEnumerator)
Decreases the device enumerator's internal reference count by one.
bool ic4_devenum_update_device_list(struct IC4_DEVICE_ENUM *pEnumerator)
Searches for video capture devices and populates the enumerator's internal device list.
bool ic4_devenum_get_devinfo(const struct IC4_DEVICE_ENUM *pEnumerator, int index, struct IC4_DEVICE_INFO **ppInfo)
Returns a IC4_DEVICE_INFO object describing one of the discovered video capture devices.
bool ic4_devenum_create(struct IC4_DEVICE_ENUM **ppEnumerator)
Creates a new device enumerator.
void ic4_devinfo_unref(struct IC4_DEVICE_INFO *pInfo)
Decreases the device information's internal reference count by one.
bool ic4_grabber_create(struct IC4_GRABBER **ppGrabber)
Creates a new grabber.
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.
Device enumerator type.
Device information type.
Represents an opened video capture device, allowing device configuration and stream setup.

Configure the Resolution

Next, we configure the device to output Mono8 data with a ROI of 640x480:

IC4_PROPERTY_MAP* map = NULL;
ic4_grabber_device_get_property_map(grabber, &map);
 
// Configure the device to output images in the Mono8 pixel format
ic4_propmap_set_value_int64(map, IC4_PROPID_PIXELFORMAT, IC4_PIXELFORMAT_Mono8);
 
// Set the resolution to 640x480
ic4_propmap_set_value_int64(map, IC4_PROPID_WIDTH, 640);
ic4_propmap_set_value_int64(map, IC4_PROPID_HEIGHT, 480);
#define IC4_PROPID_HEIGHT
Height of the image provided by the device (in pixels).
Definition C_PropertyConstants.h:699
#define IC4_PROPID_WIDTH
Width of the image provided by the device (in pixels).
Definition C_PropertyConstants.h:1099
bool ic4_propmap_set_value_int64(struct IC4_PROPERTY_MAP *map, const char *prop_name, int64_t value)
Set the value of a property with a known name to the passed integer value.
Represents the property interface of a component, usually a video capture device.

Define ROI Origin

Then, the origin of the ROI is moved to the top left corner of the sensor:

// Set the origin of the ROI to the top-left corner of the sensor
ic4_propmap_set_value_string(map, IC4_PROPID_OFFSET_AUTO_CENTER, "Off");
ic4_propmap_set_value_int64(map, IC4_PROPID_OFFSET_X, 0);
ic4_propmap_set_value_int64(map, IC4_PROPID_OFFSET_Y, 0);
#define IC4_PROPID_OFFSET_X
Horizontal offset from the origin to the region of interest (in pixels).
Definition C_PropertyConstants.h:854
#define IC4_PROPID_OFFSET_Y
Vertical offset from the origin to the region of interest (in pixels).
Definition C_PropertyConstants.h:859
bool ic4_propmap_set_value_string(struct IC4_PROPERTY_MAP *map, const char *prop_name, const char *value)
Set the value of a property with a known name to the passed string value.

Set an Exposure Time

Finally, we configure the device to a fixed exposure time of 5ms and enable automatic gain control:

// Configure the exposure time to 5ms (5000�s)
ic4_propmap_set_value_string(map, IC4_PROPID_EXPOSURE_AUTO, "Off");
ic4_propmap_set_value_double(map, IC4_PROPID_EXPOSURE_TIME, 5000.0);
 
// Enable GainAuto
ic4_propmap_set_value_string(map, IC4_PROPID_GAIN_AUTO, "Continuous");
#define IC4_PROPID_GAIN_AUTO
Sets the automatic gain control mode.
Definition C_PropertyConstants.h:649
#define IC4_PROPID_EXPOSURE_AUTO
Sets the automatic exposure mode when ExposureMode is Timed.
Definition C_PropertyConstants.h:544
#define IC4_PROPID_EXPOSURE_TIME
Sets the Exposure time when ExposureMode is Timed and ExposureAuto is Off.
Definition C_PropertyConstants.h:579
bool ic4_propmap_set_value_double(struct IC4_PROPERTY_MAP *map, const char *prop_name, double value)
Set the value of a property with a known name to the passed double value.

At the end of the program, references to objects have to be released:

// Clean up property map and grabber objects
ic4_propmap_unref(map);
ic4_grabber_unref(grabber);
void ic4_grabber_unref(struct IC4_GRABBER *pGrabber)
Decreases the grabber's internal reference count by one.
void ic4_propmap_unref(struct IC4_PROPERTY_MAP *map)
Decreases the property map's internal reference count by one.