chromasens GEN I CAM-SDK User manual

Chromasens GEN<i>CAM-SDK | Manual
R03 / 2021-04-15

GenICam_SDK.docx 2
Table of Contents
1General information 3
1.1 About Chromasens 3
1.1.1 Contact information 3
1.1.2 Support 3
1.2 Conventions used in this manual 4
1.2.1 Styles 4
1.2.2 Symbols 5
1.2.3 List of abbreviations 5
2General aspects of the API 7
3Getting started 8
3.1 Initialization of the SDK 8
3.2 Connecting to a camera 8
3.3 Getting and setting features 9
3.4 Acquiring images 10
3.5 Examples 11
3.5.1 Build examples 11
4List of SDK-functions 12
4.1 Init/Deinit-functions 12
4.2 Connecting and closing a device 12
4.3 Getting and setting device parameters 15
4.4 Functions related to image acquisition 22
4.5 File transfer functions 26
4.6 Memory transfer functions 27
4.7 Helper functions 28
4.8 Enumerations 29
4.9 Structures 32
5Installation 36
5.1 Windows installation 36
5.1.1 Installer Contents 36
5.2 Linux installation 36
5.2.1 Preparation 36
5.2.2 Step by Step Installation Ubuntu 18.04 36
5.2.3 Installer Contents 37

GenICam_SDK.docx 3
1 General information
1.1 About Chromasens
The name of our company, Chromasens, is a combination of 'Chroma' which means color, and
'Sens' which stands for sensor technology.
Chromasens designs, develops, and produces high-quality and user-friendly products:
◼Line scan cameras
◼Camera systems
◼Camera illumination systems
◼Image acquisition systems
◼Image processing solutions
Today, Chromasens GmbH is experiencing steady growth and is continually penetrating new
sales markets around the globe. The company's technologies are used, for example, in products
and for applications such as book and document scanners, sorting systems and inspection
systems for quality assurance monitoring.
Customers from all over the world of a wide range of industrial sectors have placed their trust in
the experience of Chromasens in the field of industrial image processing.
1.1.1Contact information
Chromasens GmbH
Max-Stromeyer-Str. 116
78467 Konstanz
Germany
Phone: [phone] / 876-0
Fax: [phone] / 876-303
Email: [e-mail]
HP: www.chromasens.de
1.1.2Support
Chromasens GmbH
Max-Stromeyer-Str. 116
D-78467 Konstanz
Germany
Phone: [phone] / 876-500
Fax: [phone] / 876-303
Email: [e-mail]
HP: http://www.chromasens.de/en/support
Visit our website at http://www.chromasens.de which features detailed information on our
company and products.

GenICam_SDK.docx 4
1.2 Conventions used in this manual
1.2.1Styles
Notification
To ease the use of the document and to clearly indicate the type of the used data different colors for the
different elements are used. Three different colors are used when displaying elements in tables:
Enumerations:
For example:
csiEventType
Defines events which can be received from the SDK
Definition
typedef enum csiEventType {
CSI_EVT_NEWIMAGEDATA = 0x00,
CSI_EVT_ERROR = 0x01,
CSI_EVT_MODULE = 0x02,
CSI_EVT_CUSTOM = 0x1000
} csiEventType;
Elements
CSI_EVT_NEWIMAGEDATA: New image data received
CSI_EVT_ERROR: Error occurred in the SDK
CSI_EVT_MODULE: General event notification
CSI_EVT_CUSTOM: A custom event was triggered
Structures:
For example:
Struct-name
csiDiscoveryInfo
Variable type
Element name
Description
uint32_t
numDevices
double
progress
bool
discoveryRunning
Functions:
For example:
csiDiscoverDevices
Searches for the devices currently connected to the system
Syntax
csiErr csiDiscoverDevices( csiDiscoveryInfo* discoveryInfoOut,
uint64_t timeoutMilliseconds,
csiDiscoveryInfoCallbackFunc discCallbackFunc = NULL,
const char* additionalSearchPaths = NULL,
bool overrideSearchPath CSI_DEFAULT_PARAM_FALSE);
Parameters:
In:
timeoutMilliseconds: The amount of time to search on a specific transport layer for a device
discCallBackFunc: pointer to a callback function which gets called when a result was received
AdditionalSearchPaths: as default only the paths given in the system variable “GENICAM_GENTL64_PATH” are being searched for the
used transport layers
overrideSearchPath: If set, only the given path is searched for transport layers to use.
Out:
discoveryInfoOut: The structure will be filled with the available devices
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:

GenICam_SDK.docx 5
1.2.2Symbols
CAUTION
Indicates a potentially hazardous situation or task, which, if not
avoided, may result in minor or moderate injury.
Indicates a potentially hazardous situation or task, which, if not avoided, could
result in damage to the product or the surrounding environment.
Indicates a helpful tip.
More detailed information can be retrieved online.
1.2.3List of abbreviations
Abbreviation
Meaning
Explanation
CCM
Color conversion matrix
The CCM supports the conversion from for
example RGB to sRGB or any user-defined
conversion
Corona II
LED illumination
Chromasens product
DSNU
Dark signal non-
uniformity
Irregularity in the dark image
GenICam
Generic interface for
cameras
Generic programming interface for industrial
cameras administered by the European
Machine Vision Association
www.emva.org
CTI
Common Transport
Interface
A GenTL Producer implementation as
dynamic loadable platform dependent library
GCT
GenICam Control Tool
Graphical user interface using the SDK.
Provides a graphical way to configure devices
using different TLs.

GenICam_SDK.docx 6
GenApi
GenICam Module
-
GenTL
Generic Transport Layer
-
GenTL
Consumer
A library or application
using an implementation
of a Transport Layer
Interface
-
GenTL
Producer
Transport Layer Interface
implementation
-
LED
Light emitting diode
-
PRNU
Photo response non-
uniformity
Difference in sensitivity of the individual pixels
ROI
Region of interest
-
RS485
ANSI standard defining the electrical
characteristics of drivers and receivers for use
in serial communications systems.
SFNC
Standard Feature Naming
Convention
Document of the GenICam standard, which
provides feature names for common camera
features.
VSync
Vertical synchronization
Frame signal for an image (corresponds to
FVAL: frame valid)

GenICam_SDK.docx 7
2 General aspects of the API
The purpose of the Chromasens Gen<I>Cam-SDK is to provide a user friendly and easy way to
handle all Chromasens cameras regardless of the physical interface.
Requirements:
Supported operating systems:
Windows: Windows 10 Version 2
Linux: Ubuntu >= 18.X
Supported compiler:
Visual Studio >= 2015
GCC

GenICam_SDK.docx 8
3 Getting started
This chapter will describe the basic functions/sequences needed to handle the basic
functionality of the camera.
Ready to use-Examples are also shipped with the SDK in order to demonstrate the usage of the
SDK regarding getting/setting features and acquiring images.
3.1 Initialization of the SDK
Before accessing any other functions of the SDK, an initialization needs to be done.
Please refer to 4.1 Init/Deinit-functions for the detailed description of the function csiInit.
After finishing the work with the SDK make sure to call the csiClose function. This makes
sure that all memory is freed again, and all connections/interfaces are properly closed again
3.2 Connecting to a camera
The use of the Chromasens Gen<I>CAM-SDK enables the user to use different transport layers
and interfaces for the available devices.
Depending on the requirements for your application these transport layers can be selected
during the device discovery process.
It is possible to use the standard search paths for the already installed transport layers.
These paths are set in the environmental variable “GENICAM_GENTL64_PATH”or for 32Bit-
applications: “GENICAM_GENTL32_PATH”.
This is the default behavior. To reduce the time needed for the discovery process a specific path
can be given. The search can also be limited to this single path when the
overrideSearchPath is set.
To establish a connection, you will need to call 2 functions:
csiDiscoverDevices and csiOpenDevice. Detailed information regarding the functions
can be found here: 3.2 Connecting to a camera

GenICam_SDK.docx 9
3.3 Getting and setting features
To configure the camera, so called features can be set and read by using the feature names
provided by the device-xml-file.
All features are of a specific type. The following different types exist:
- Boolean
- Integer
- Floating point
- String
- Command
- Register
- Enumeration
For each type, a “Get”- and “Set”-function does exist in the API. For example use
“csiGetFeatureFloat” to get a float parameter.
To retrieve additional information the function “csiGetFeatureParameter” exists. This function
will fill a csiFeatureParameter-structure which provides information about the display name,
minimum and maximum values, etc. This function is especially useful if you do not know the
valid thresholds of a parameter.
Please be careful when treating string features. You must not exceed the maximum length! This
can also be retrieved with the function “csiGetFeatureParameter”. The parameter
“maximumStringLength” of the csiFeatureParameter-structure will indicate the maximum string
length to set in the feature.
If the complete list of the device features needs to be retrieved, it is recommended to use the
function “csiIterateFeatureTree”. An example is shipped with the SDK to demonstrate the
usage of it.
To set the values please use the type-specific set-functions. For example, use
“csiSetFeatureInt” for an integer value.
These functions are described in detail in the chapter “3.3 Getting and setting features”.

GenICam_SDK.docx 10
3.4 Acquiring images
To get images from the device, it must be opened first by calling the appropriate functions.
The diagram below provides an overview of the functions which should be called during an
acquisition process.
Depending on the type of the device it is possible to retrieve multiple data streams in parallel
from the same device. This capability can be checked by using the
“csiGetNumberOfDataStreams”-function which is described in the chapter 4.4 Functions related
to image acquisition.
In general, two different ways in acquiring the images can be used:
1. Using Events (Events must be registered by the “csiRegisterEvent”-function prior to the
usage of the event.
2. Directly calling the csiGetNextImage-function
Independent of these two ways, the Acquisition from the device must be started first by calling
csiStartAcquisition.
If enough images have been processed this needs to be stopped again by calling
csiStopAcquisition.
After a received image is processed it must be released back into the receive buffer of the
acquisition engine by calling csiReleaseImage.
By failing to do so the user will cause an error as soon as all receive buffers have been filled by
the incoming data.
Tograb images continuously the processing part needs to keep up with the speed of the camera.
Otherwise, images might be lost.

GenICam_SDK.docx 11
3.5 Examples
The SDK software package comes with a set of programming examples for C++. Currently there are
two examples included:
acquisition_basics
Demonstrates how to discover and open a device and how to acquire images.
Locations:
Windows:
C:\Users\Public\Documents\Chromasens\GCT2\examples\basic
Linux: /usr/share/csgenicam/examples/basic
feature_iteration
Demonstrates how to iterate through the feature tree of a device and how to set / get
features.
Locations:
Windows:
C:\Users\Public\Documents\Chromasens\GCT2\examples\feature_iteration
Linux: /usr/share/csgenicam/examples/feature_iteration
3.5.1Build examples
To build the examples requires CMake version > v3.14 and a build environment. The steps to build the
examples are the same for both Windows and Linux:
1) Open the CMake GUI and select the examples root directory as the source folder of your project.
(“Where is the source code”)
2) Next select a directory where to generate the project files, should be somewhere outside the
source tree.
(“Where to build the binaries”)
3) Press the “Configure”button. After the first configuration it is required to manually set the path
to the CSGenICam CMake configuration files:
4) Press “Configure”again and “Generate”afterwards. The project is now configured and can be
opened and built from the directory selected in “Where to build the binaries”.

GenICam_SDK.docx 12
4 List of SDK-functions
4.1 Init/Deinit-functions
csiInit
Initializes the SDK. Needs to be called first before any other function of the SDK is called!
Syntax
csiErr csiInit(csiLogLevel logLvl = CSI_LOGLEVEL_WARN, , csiLogSinkCallbackFunc logCallbackFunc = NULL,
csiLogUserData* userdata = NULL)
Parameters:
In: logLvl: Defines the loglevel for the SDK. This will enable a closer debugging of the SDK. Use
the enum csiLogLevel for setting the desired loglevel
logCallbackFunc: An optional callback function for log messages coming from the SDK.
userData: Optional user data that will be passed as parameter when the log callback function is
called.
Out:Nothing
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
After the usage of the SDK make sure to call csiClose in order to free all memory again and not leaving any interfaces open.
csiClose
Closes the SDK and frees all allocated memory and interfaces.
Syntax
csiErr csiClose();
Parameters:
In: Nothing
Out:Nothing
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
4.2 Connecting and closing a device
csiDiscoverDevices
This function will look for attached GenICAM-devices on the available transport layers.
Syntax
csiErr csiDiscoverDevices(csiDiscoveryInfo* discoveryInfoOut, uint64_t timeoutMilliseconds,
csiDiscoveryInfoCallbackFunc discCallbackFunc = NULL,
const char* additionalSearchPaths = NULL, bool overrideSearchPath = false)
Parameters:
In: timeoutMilliseconds The time until when a response from a device needs to be received when doing a discovery
discCallbackFunc Pointer to a callback function which receives information about the discovery progress.
The callback function receives the current progress in %, number and names of the found
devices Also a flag if the discovery is running is provided.
additionalSearchPaths You can specify additional paths to search for transport layers. If you want to specify multiple
paths, you need to divide the paths by using a “;”-sign
overrideSearchPath If this flag is set, only the path(s) provided in “additionalSearchPaths” will be searched for the
cti-files to load
Out: discoveryInfoOut pointer to a structure which will contain the information about the found devices. The
information is the same provided to the callback function
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
By default, this function tries to use all available transport layers in the system. The search paths for the cti-files are set in the
environmental variable GENICAM_GENTL64_PATH (64 bit) or GENICAM_GENTL32_PATH(32 bit applications).

GenICam_SDK.docx 13
csiGetDeviceInfo
A function to get information about the found devices in the system
Syntax
csiErr csiGetDeviceInfo(uint32_t deviceIndex, csiDeviceInfo* deviceInfoOut)
Parameters:
In: deviceIndex Index of the found device from the csiDiscoverDevices-function
Out: deviceInfoOut Detailed information of the found device. The information will be provided in this structure.
The structure must be allocated on the caller side.
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
This function provides in more detailed information about the found devices such as device identifier, name, model, vendor,
serial number, interface description, interface-ID, username, version, consistency of camera package, TL-Producer-information,
access status
csiGetNumberOfTLProducers
Returns the number of available transport layers in the system
Syntax
csiErr csiGetNumberOfTLProducers(int32_t *numTLProducers);
Parameters:
In: Nothing
Out: numTLProducers The number of transport layers detected in the environment.
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
The SDK uses the environment variable GENICAM_GENTL64_PATH to search for available transport layers. This function
allows to request the number of transport layers available through that environment variable.
csiGetTLProducerInfoByIndex
Returns additional information about a transport layer.
Syntax
CSI_DLL_EXPORT csiErr csiGetTLProducerInfoByIndex(csiTLProducerInfos *tlProducerInfos, int32_t indexTL);
Parameters:
In: intexTL: The index of the transport layer in the list.
Out: tlProdcrInfos: The structure holding additional information about the transport layer.
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
The index must be within 0 and the number of transport layer returned by csiGetNumberOfTLProducers.
csiGetTLProducerInfoByName
Returns additional information about a transport layer.
Syntax
CSI_DLL_EXPORT csiErr csiGetTLProducerInfoByName(csiTLProducerInfos *tlProdecrrInfos, const char* producerName);
Parameters:
In: producerName: The name of the producer (usually the file path to the producer *.cti file)
Out: tlProdcrInfos: The structure holding additional information about the transport layer.
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
Similar to csiGetTLProducerInfoByIndex but using the name (file path) of the producer.

GenICam_SDK.docx 14
csiOpenDevice
Open the device given by the index. The TL of this index is used
Syntax
csiErr csiOpenDevice(const char* deviceIdentifier, csiHandle* deviceHandleOut, uint64_t timeoutMilliseconds,
csiDeviceAccessMode openMode)
Parameters:
In: deviceIdentifier Index of the found device from the csiDiscoverDevices-function
timeoutMilliseconds Timeout in milliseconds until the device needs to be opened successfully
openMode The device can be opened in different modes to enable/hinder concurrent access to
the device.
The following modes might be used:
CSI_DEV_MODE_EXCLUSIVE: Only this process can communicate with the camera
CSI_DEV_MODE_READ: Camera-parameters can be read and images can be
acquired
CSI_DEV_MODE_CONTROL: Camera-parameters can be read and written. Read-
access by another process to the device is still possible
Out: deviceHandleOut: Handle to the device. This handle needs to be used to any successive call.
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
Depending on the used transport layer it might be necessary to use a longer timeout. Please refer to the information provided
with the specific TL.
csiCloseDevice
Close the connection to the specific device
Syntax
csiErr csiCloseDevice(csiHandle device
Parameters:
In: device: Handle provided by the csiOpenDevice-function
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To grant access to the device for other applications, the connection should be closed when it is not needed anymore.
The API will cleanup no longer needed memory when this command is executed.

GenICam_SDK.docx 15
4.3 Getting and setting device parameters
It is possible to retrieve and set parameters on the device/camera. The SDK additionally
provides the possibility to set parameters for other involved components such as the transport
layer module.
Therefore, it is possible to indicate this by changing the module parameter from the default
setting (CSI_DEVICE_MODULE) to the other components such as transport layer, stream, or
buffer module.
Please note that the parameters available for the different modules will differ significantly!
csiGetFeatureBool
Retrieve a boolean feature from the device
Syntax
csiErr csiGetFeatureBool (csiHandle device, const char* parameterName, bool* valueOut,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name of the feature to get (Not the display name!)
module: Module for which the parameter should be get. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: valueOut: Pointer to a bool-value where the current value of the feature will be written to
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiSetFeatureBool
Set a boolean feature on the device
Syntax
csiErr csiSetFeatureBool(csiHandle device, const char* parameterName, bool value,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set
value: Boolean value to set the feature to (true or false)
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be set on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiGetFeatureInt
Retrieve an integer feature from the device
Syntax
csiErr csiGetFeatureInt(csiHandle device, const char* parameterName, int64_t* valueOut,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to get
module: Module for which the parameter should be get. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: valueOut: Pointer to an in64_t-value where the current value of the feature will be written to
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:

GenICam_SDK.docx 16
csiSetFeatureInt
Set an integer feature on the device
Syntax
csiErr csiSetFeatureInt(csiHandle device, const char* parameterName, int64_t value,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set
value: integer value to set the feature to
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be set on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiGetFeatureFloat
Retrieve a floating point feature from the device
Syntax
csiErr csiGetFeatureFloat(csiHandle device, const char* parameterName, double* valueOut,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to get
module: Module for which the parameter should be get. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: valueOut: Pointer to a double-value where the current value of the feature will be written to
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiSetFeatureFloat
Set a floating point value feature on the device
Syntax
csiErr csiSetFeatureFloat(csiHandle device, const char* parameterName, double value,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set
value: floating point value to set
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be set on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:

GenICam_SDK.docx 17
csiGetFeatureString
Retrieve a string feature from the device
Syntax
csiErr csiGetFeatureString(csiHandle device, const char* parameterName, char* valueOut, size_t* sizeOut, csiModuleLevel
module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to get
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or
buffer-module
Out: valueOut: Pointer to a char-value where the current value of the feature will be written to
sizeOut: size of the read string
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To avoid unexpected behavior, you should first retrieve the length of the string to be received!
1. Call the function with valueOut set to NULL. The function will return the current size of the string parameter.
This enables the user to provide sufficient space to return the desired string.
Alternative: Call the function “csiGetFeatureParameter”. This function will provide all necessary information
about the parameter (including min and max values).
The maximum string length to be retrieved can be read from from the “maximumStringLength”-parameter
2. Call the function as described by providing a pointer to the string buffer with the sufficient length
csiSetFeatureString
Set a string feature on the device
Syntax
csiErr csiSetFeatureString(csiHandle device, const char* parameterName,const char* value,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set
value: pointer to a character array which contains the string to set
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be set on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To avoid unexpected behavior, it is recommended to retrieve the maximum string length before setting it to the device.
This can be achieved by using the function “csiGetFeatureParameter”. This function will provide all necessary information
about the parameter (including min and max values).
The string length must not exceed the length given in the “maximumStringLength”-parameter
csiExecuteCommand
Execute a command on the device
Syntax
csiErr csiExecuteCommand(csiHandle device, const char* parameterName,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set.
module: Module for which the parameter should be executed. Please use the enum csiModuleLevel to select.
Determines if the parameter should be executed on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
The function will return immediately. Even if the triggered function is still active. To check if the command is still running,
please use the function “csiIsCommandActive”.

GenICam_SDK.docx 18
csiIsCommandActive
Check if a command is still active
Syntax
csiErr csiIsCommandActive(csiHandle device, const char* parameterName, bool *isActive,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the command to execute
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: isActive: Pointer to a bool-value where the current state of the command is written to (true: active, false: inactive)
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
If a lengthy operation is triggered, it is possible to check the current status by calling this command.
csiGetFeatureReg
Retrieve a register value from the device
Syntax
csiErr csiGetFeatureReg(csiHandle device, const char* parameterName, char* buffer, size_t* length,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to get
value:
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: buffer: Pointer to a char-array where the current value of the feature will be written to
length: Current length of the retrieved data
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To avoid unexpected behavior, it is recommended to retrieve the maximum buffer length before getting it from the device.
This can be achieved by using the function “csiGetFeatureParameter”. This function will provide all necessary information
about the parameter (including min and max values).
The register length must not exceed the length given in the “featureRegLength”-parameter
csiSetFeatureReg
Set a register value on the device
Syntax
csiErr csiSetFeatureReg(csiHandle device, const char* parameterName,
const char* buffer, size_t length, csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to set
buffer: pointer to the data which will be written to the r egister
length: number of bytes to write to the register
module: Module for which the register should be set. Please use the enum csiModuleLevel to select.
Determines if the register should be set on the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To avoid unexpected behavior, it is recommended to retrieve the maximum buffer length before setting it to the device.
This can be achieved by using the function “csiGetFeatureParameter”. This function will provide all necessary information
about the parameter (including min and max values).
The register length must not exceed the length given in the “featureRegLength”-parameter

GenICam_SDK.docx 19
csiGetFeatureParameter
Retrieve a specific feature from the device. Detailed information about this feature will be returned
Syntax
csiErr csiGetFeatureParameter(csiHandle device, const char* parameterName, csiFeatureParameter* featureParamOut,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the feature to get
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: featureParamOut
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiIterateFeatureTree
Provides a possibility to iterate through all available features on the camera
Syntax
csiErr csiIterateFeatureTree(csiHandle device, const char* rootFeatureName, uint32_t index, char* featureNameOut,
size_t nameBuffSize, csiFeatureType* type, csiModuleLevel module =
CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
rootFeatureName: name of the feature to start from. To start from the very beginning use “root”
index: This will indicate the number of the child element of the rootFeature to retrieve
nameBuffSize: size of the provided buffer for the featureNameOut
module: Module for which the feature tree should be iterated. Please use the enum csiModuleLevel to select.
Determines if the feature tree on the device-, transport layer-, interface- stream- or buffer-
module should be used
Out: featureNameOut: name of the retrieved feature
type: type of the retrieved feature
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
If starting from the very beginning, use “Root” as rootFeatureName. From there call this function for each returned feature in
order to get all features of the device.
Please check the provided example “feature_iteration” for a template of usage.
csiGetFeatureEnum
Retrieve an enumeration feature from the device
Syntax
csiErr csiGetFeatureEnum(csiHandle device, const char* parameterName, csiFeatureParameter *featureParamOut,
csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the enumeration to get
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: featureParamOut: Structure which contains all necessary information about the requested feature:
the relevant entries of the csiFeatureParameter-structure:
enumCounter: Number of different enum-entries for the enumeration
enumIndex: Currently selected enumeration index
valueStr: name of the enum-entry
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:

GenICam_SDK.docx 20
csiSetFeatureEnum
Set an enumeration feature on the device
Syntax
csiSetFeatureEnum(csiHandle device, const char* parameterName, const char* value, csiModuleLevel module =
CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the enumeration to get
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out:
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
To retrieve the possible values for this enumeration, two functions need to be called:
1. csiGetFeatureEnum: in the returned structure, the element “enumCounter” indicates the number of available
entries
2. The different entries can be retrieved by using the function “csiGetFeatureEnumEntryByIndex” simply by iterating
from 0 until the “enumCounter”-1
csiGetFeatureEnumEntryByIndex
Retrieve an enumeration feature from the device by using its index
Syntax
csiErr csiGetFeatureEnumEntryByIndex(csiHandle device, const char* parameterName, int32_t enumIndex,
csiFeatureParameter *featureParamOut, csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the enumeration to get
enumIndex: the index of the enumeration to get
module: Module for which the parameter should be retrieved. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: featureParamOut: Name of the enumeration of the requested index
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
The enumeration string will be given in the csiFeatureParameter-structure: valueStr
csiGetFeatureEnumEntryByName
Syntax
csiErr csiGetFeatureEnumEntryByName(csiHandle device, const char* parameterName, const char* enumValue,
csiFeatureParameter *featureParamOut, csiModuleLevel module = CSI_DEVICE_MODULE)
Parameters:
In: device: Handle provided by the csiOpenDevice-function
parameterName: name (Not the display name!) of the enumeration to get
enumValue:
module: Module for which the parameter should be set. Please use the enum csiModuleLevel to select.
Determines if the parameter should be retrieved from the device-, transport layer-, interface- stream- or buffer-
module
Out: featureParamOut
Return value:
Returns csiSuccess or an error defined in the csiErr-Enum.
Comment:
csiRegisterInvalidateCB
Register an invalidation callback function to a specific feature by name
Syntax
csiErr csiRegisterInvalidateCB(csiHandle device, const char *featureName, CB_OBJECT objCB,
CB_FEATURE_INVALIDATED_PFN pfnFeatureInvalidateCB, csiModuleLevel module =
CSI_DEVICE_MODULE);
Parameters:
In: device: Handle provided by the csiOpenDevice-function
featureName: Name of the feature register the callback to
objCB: An user object that is passed as parameter to the callback function
pfnFeatureInvalidateCB: The callback function
module: Module for which the feature invalidation callback should be registered. Please use the enum
csiModuleLevel to select.