ArvDevice: Aravis Reference Manual

ArvDevice

ArvDevice — Abstract base class for device handling

Functions

ArvStream *	arv_device_create_stream ()
ArvChunkParser *	arv_device_create_chunk_parser ()
gboolean	arv_device_read_memory ()
gboolean	arv_device_write_memory ()
gboolean	arv_device_read_register ()
gboolean	arv_device_write_register ()
const char *	arv_device_get_genicam_xml ()
ArvGc *	arv_device_get_genicam ()
ArvGcNode *	arv_device_get_feature ()
gboolean	arv_device_is_feature_available ()
void	arv_device_execute_command ()
gboolean	arv_device_get_boolean_feature_value ()
void	arv_device_set_boolean_feature_value ()
void	arv_device_set_string_feature_value ()
const char *	arv_device_get_string_feature_value ()
void	arv_device_set_integer_feature_value ()
gint64	arv_device_get_integer_feature_value ()
void	arv_device_get_integer_feature_bounds ()
gint64	arv_device_get_integer_feature_increment ()
void	arv_device_set_float_feature_value ()
double	arv_device_get_float_feature_value ()
void	arv_device_get_float_feature_bounds ()
double	arv_device_get_float_feature_increment ()
gboolean	arv_device_is_enumeration_entry_available ()
gint64 *	arv_device_dup_available_enumeration_feature_values ()
const char **	arv_device_dup_available_enumeration_feature_values_as_strings ()
const char **	arv_device_dup_available_enumeration_feature_values_as_display_names ()
gboolean	arv_device_set_features_from_string ()
void	arv_device_set_range_check_policy ()
void	arv_device_set_register_cache_policy ()

Signals

void

control-lost

Run Last

Types and Values

#define	ARV_DEVICE_ERROR
enum	ArvDeviceError
	ArvDevice

Object Hierarchy

    GObject
    ╰── ArvDevice
        ├── ArvFakeDevice
        ├── ArvGvDevice
        ╰── ArvUvDevice

Implemented Interfaces

ArvDevice implements GInitable.

Description

ArvDevice is an abstract base class for the control of cameras. It provides an easy access to the camera settings, and to its genicam interface for more advanced uses.

Functions

arv_device_create_stream ()

ArvStream *
arv_device_create_stream (ArvDevice *device,
                          ArvStreamCallback callback,
                          void *user_data,
                          GError **error);

Creates a new ArvStream for video stream handling. See ArvStreamCallback for details regarding the callback function.

Parameters

device	a ArvDevice
callback	a frame processing callback.	[scope call]
user_data	user data for `callback` .	[allow-none][closure]
error	a GError placeholder, `NULL` to ignore

Returns

a new ArvStream.

[transfer full]

Since: 0.2.0

arv_device_create_chunk_parser ()

ArvChunkParser *
arv_device_create_chunk_parser (ArvDevice *device);

Create a ArvChunkParser object, to be used for chunk data extraction from ArvBuffer.

Parameters

device

a ArvDevice

Returns

a new ArvChunkParser object, NULL on error.

[transfer full]

Since: 0.4.0

arv_device_read_memory ()

gboolean
arv_device_read_memory (ArvDevice *device,
                        guint64 address,
                        guint32 size,
                        void *buffer,
                        GError **error);

Reads size bytes from the device memory.

Parameters

device	a ArvDevice
address	memory address
size	number of bytes to read
buffer	a buffer for the storage of the read data
error	a GError placeholder.	[out][allow-none]

Returns

TRUE on success.

[skip]

Since: 0.2.0

arv_device_write_memory ()

gboolean
arv_device_write_memory (ArvDevice *device,
                         guint64 address,
                         guint32 size,
                         void *buffer,
                         GError **error);

Writes size bytes to the device memory.

Parameters

device	a ArvDevice
address	memory address
size	size of the returned buffer
buffer	the buffer read from memory.	[transfer full]
error	a GError placeholder.	[out][allow-none]

Returns

TRUE on success.

[skip]

Since: 0.2.0

arv_device_read_register ()

gboolean
arv_device_read_register (ArvDevice *device,
                          guint64 address,
                          guint32 *value,
                          GError **error);

Reads the value of a device register.

Parameters

device	a ArvDevice
address	register address
value	a placeholder for the read value.	[out]
error	a GError placeholder.	[out][allow-none]

Returns

TRUE on success.

[skip]

Since: 0.2.0

arv_device_write_register ()

gboolean
arv_device_write_register (ArvDevice *device,
                           guint64 address,
                           guint32 value,
                           GError **error);

Writes value to a device register.

Parameters

device	a ArvDevice
address	the register address
value	value to write
error	a GError placeholder.	[out][allow-none]

Returns

TRUE on success.

[skip]

Since: 0.2.0

arv_device_get_genicam_xml ()

const char *
arv_device_get_genicam_xml (ArvDevice *device,
                            size_t *size);

Gets the Genicam XML data stored in the device memory.

Parameters

device	a ArvDevice
size	placeholder for the returned data size (bytes).	[out][allow-none]

Returns

a pointer to the Genicam XML data, owned by the device.

[transfer none]

Since: 0.2.0

arv_device_get_genicam ()

ArvGc *
arv_device_get_genicam (ArvDevice *device);

Retrieves the genicam interface of the given device.

Parameters

device

a ArvDevice

Returns

the genicam interface.

[transfer none]

Since: 0.2.0

arv_device_get_feature ()

ArvGcNode *
arv_device_get_feature (ArvDevice *device,
                        const char *feature);

Parameters

device	a ArvDevice
feature	feature name

Returns

the genicam node corresponding to the feature name, NULL if not found.

[transfer none]

Since: 0.2.0

arv_device_is_feature_available ()

gboolean
arv_device_is_feature_available (ArvDevice *device,
                                 const char *feature,
                                 GError **error);

Return: TRUE if feature is available, FALSE if not or on error.

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder, `NULL` to ignore

Since: 0.8.0

arv_device_execute_command ()

void
arv_device_execute_command (ArvDevice *device,
                            const char *feature,
                            GError **error);

Execute a genicam command.

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Since: 0.8.0

arv_device_get_boolean_feature_value ()

gboolean
arv_device_get_boolean_feature_value (ArvDevice *device,
                                      const char *feature,
                                      GError **error);

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

the feature value, FALSE on error.

Since: 0.8.0

arv_device_set_boolean_feature_value ()

void
arv_device_set_boolean_feature_value (ArvDevice *device,
                                      const char *feature,
                                      gboolean value,
                                      GError **error);

Set the value of a boolean feature.

Parameters

device	a ArvDevice
feature	feature name
value	feature value
error	a GError placeholder

Since: 0.8.0

arv_device_set_string_feature_value ()

void
arv_device_set_string_feature_value (ArvDevice *device,
                                     const char *feature,
                                     const char *value,
                                     GError **error);

Set the string feature value.

Parameters

device	a ArvDevice
feature	feature name
value	new feature value
error	a GError placeholder

Since: 0.8.0

arv_device_get_string_feature_value ()

const char *
arv_device_get_string_feature_value (ArvDevice *device,
                                     const char *feature,
                                     GError **error);

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

the string feature value, NULL on error.

Since: 0.8.0

arv_device_set_integer_feature_value ()

void
arv_device_set_integer_feature_value (ArvDevice *device,
                                      const char *feature,
                                      gint64 value,
                                      GError **error);

Set the integer feature value.

Parameters

device	a ArvDevice
feature	feature name
value	new feature value
error	a GError placeholder

Since: 0.8.0

arv_device_get_integer_feature_value ()

gint64
arv_device_get_integer_feature_value (ArvDevice *device,
                                      const char *feature,
                                      GError **error);

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

the integer feature value, 0 on error.

Since: 0.8.0

arv_device_get_integer_feature_bounds ()

void
arv_device_get_integer_feature_bounds (ArvDevice *device,
                                       const char *feature,
                                       gint64 *min,
                                       gint64 *max,
                                       GError **error);

Retrieves feature bounds.

Parameters

device	a ArvDevice
feature	feature name
min	minimum feature value.	[out]
max	maximum feature value.	[out]
error	a GError placeholder

Since: 0.8.0

arv_device_get_integer_feature_increment ()

gint64
arv_device_get_integer_feature_increment
                               (ArvDevice *device,
                                const char *feature,
                                GError **error);

Not all integer features have evenly distributed allowed values, which means the returned increment may not reflect the allowed value set.

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

feature value increment, or 1 on error.

Since: 0.8.0

arv_device_set_float_feature_value ()

void
arv_device_set_float_feature_value (ArvDevice *device,
                                    const char *feature,
                                    double value,
                                    GError **error);

Set the float feature value.

Parameters

device	a ArvDevice
feature	feature name
value	new feature value
error	a GError placeholder

Since: 0.8.0

arv_device_get_float_feature_value ()

double
arv_device_get_float_feature_value (ArvDevice *device,
                                    const char *feature,
                                    GError **error);

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

the float feature value, 0.0 on error.

Since: 0.8.0

arv_device_get_float_feature_bounds ()

void
arv_device_get_float_feature_bounds (ArvDevice *device,
                                     const char *feature,
                                     double *min,
                                     double *max,
                                     GError **error);

Retrieves feature bounds.

Parameters

device	a ArvDevice
feature	feature name
min	minimum feature value.	[out]
max	maximum feature value.	[out]
error	a GError placeholder

Since: 0.8.0

arv_device_get_float_feature_increment ()

double
arv_device_get_float_feature_increment
                               (ArvDevice *device,
                                const char *feature,
                                GError **error);

Not all float features have evenly distributed allowed values, which means the returned increment may not reflect the allowed value set.

Parameters

device	a ArvDevice
feature	feature name
error	a GError placeholder

Returns

feature value increment, or G_MINDOUBLE on error.

Since: 0.8.16

arv_device_is_enumeration_entry_available ()

gboolean
arv_device_is_enumeration_entry_available
                               (ArvDevice *device,
                                const char *feature,
                                const char *entry,
                                GError **error);

Parameters

device	an ArvDevice instance
feature	enumeration feature name
entry	entry name
error	a GError placeholder

Returns

TRUE if the feature and the feature entry are available

Since: 0.8.17

arv_device_dup_available_enumeration_feature_values ()

gint64 *
arv_device_dup_available_enumeration_feature_values
                               (ArvDevice *device,
                                const char *feature,
                                guint *n_values,
                                GError **error);

Get all the available values of feature , as integers.

Parameters

device	an ArvDevice
feature	feature name
n_values	placeholder for the number of returned values
error	a GError placeholder

Returns

a newly created array of 64 bit integers, which must freed after use using g_free, or NULL on error.

[array length=n_values][transfer container]

Since: 0.8.0

arv_device_dup_available_enumeration_feature_values_as_strings ()

const char **
arv_device_dup_available_enumeration_feature_values_as_strings
                               (ArvDevice *device,
                                const char *feature,
                                guint *n_values,
                                GError **error);

Get all the available values of feature , as strings.

Parameters

device	an ArvDevice
feature	feature name
n_values	placeholder for the number of returned values
error	a GError placeholder

Returns

a newly created array of const strings, which must freed after use using g_free, or NULL on error.

[array length=n_values][transfer container]

Since: 0.8.0

arv_device_dup_available_enumeration_feature_values_as_display_names ()

const char **
arv_device_dup_available_enumeration_feature_values_as_display_names
                               (ArvDevice *device,
                                const char *feature,
                                guint *n_values,
                                GError **error);

Get display names of all the available entries of feature .

Parameters

device	an ArvDevice
feature	feature name
n_values	placeholder for the number of returned values
error	a GError placeholder

Returns

a newly created array of const strings, to be freed after use using g_free, or NULL on error.

[array length=n_values][transfer container]

Since: 0.8.0

arv_device_set_features_from_string ()

gboolean
arv_device_set_features_from_string (ArvDevice *device,
                                     const char *string,
                                     GError **error);

Set features from a string containing a list of space separated feature assignments or command names. For example:

1	arv_device_set_features_from_string (device, "Width=256 Height=256 PixelFormat='Mono8' TriggerStart", &error);

Parameters

device	a ArvDevice
string	a space separated list of features assignments
error	a GError placeholder, `NULL` to ignore

Since: 0.8.0

arv_device_set_range_check_policy ()

void
arv_device_set_range_check_policy (ArvDevice *device,
                                   ArvRangeCheckPolicy policy);

Sets the range check policy. When enabled, before being set, the value of all nodes with an ArvGcFloat or ArvGcInteger interface will be checked against their Min and Max properties.

Be aware that some camera may have wrong definition of Min and Max, as this check is defined as not mandatory in the Genicam specification. If this is the case, it will not possible to set the value of the features with faulty Min or Max definition. Range check is disabled by default.

Parameters

device	a ArvDevice
policy	range check policy

Since: 0.8.6

arv_device_set_register_cache_policy ()

void
arv_device_set_register_cache_policy (ArvDevice *device,
                                      ArvRegisterCachePolicy policy);

Sets the register cache policy.

Be aware that some camera may have wrong Cachable properties defined in their Genicam metadata, which may lead to incorrect readouts. Using the debug cache policy, and activating genicam debug output (export ARV_DEBUG=genicam), can help you to check the cache validity. In this mode, every time the cache content is not in sync with the actual register value, a debug message is printed on the console.

Parameters

device	a ArvDevice
policy	cache policy

Since: 0.8.0

Types and Values

ARV_DEVICE_ERROR

#define ARV_DEVICE_ERROR arv_device_error_quark()

enum ArvDeviceError

Members

ARV_DEVICE_ERROR_WRONG_FEATURE	Wrong feature type
ARV_DEVICE_ERROR_FEATURE_NOT_FOUND	Feature node not found
ARV_DEVICE_ERROR_NOT_CONNECTED	Device is not connected
ARV_DEVICE_ERROR_PROTOCOL_ERROR	Protocol error
ARV_DEVICE_ERROR_TRANSFER_ERROR	Transfer error
ARV_DEVICE_ERROR_TIMEOUT	Timeout detected
ARV_DEVICE_ERROR_NOT_FOUND	Device not found
ARV_DEVICE_ERROR_INVALID_PARAMETER	Invalid construction parameter
ARV_DEVICE_ERROR_GENICAM_NOT_FOUND	Missing Genicam data
ARV_DEVICE_ERROR_NO_STREAM_CHANNEL	No stream channel found
ARV_DEVICE_ERROR_NOT_CONTROLLER	Controller privilege required
ARV_DEVICE_ERROR_UNKNOWN	Unknown error

ArvDevice

typedef struct _ArvDevice ArvDevice;

Signal Details

The `“control-lost”` signal

void
user_function (ArvDevice *device,
               gpointer   user_data)

Signal that the control of the device is lost.

This signal may be emited from a thread different than the main one, so please take care to shared data access from the callback.

Parameters

device	a ArvDevice
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 0.2.0