Baumer-GAPI2 SDK Programmer's Guide - Site ftp Elvitec

Baumer-GAPI2 SDK
Programmer‘s Guide

Table of Contents
1. Introduction .............................................................................................................. 5
2. Baumer-GAPI2 .......................................................................................................... 5
2.1 Baumer-GAPI2 Stack Components ........................................................................ 5
2.1.1 Hardware ......................................................................................................... 5
2.1.2 Baumer GenICam-API...................................................................................... 5
2.2 Software Components ............................................................................................ 6
2.2.1 Baumer-GAPI2 Modules .................................................................................. 6
2.3 Gerneral System Requirements .............................................................................. 6
3. Central Idea Behind BGAPI2 ................................................................................... 8
3.1 Interface Classes ................................................................................................... 9
3.1.1 INode, NodeMap, Node .................................................................................... 9
3.1.2 EventControl ................................................................................................... 12
3.2 Main Classes ........................................................................................................ 14
3.2.1 System............................................................................................................ 14
3.2.2 Interface.......................................................................................................... 15
3.2.3 Device............................................................................................................. 15
3.2.4 DataStream .................................................................................................... 16
3.2.5 Buffer .............................................................................................................. 17
3.3 List Classes ........................................................................................................... 18
3.3.1 SystemList ...................................................................................................... 19
3.3.2 InterfaceList .................................................................................................... 19
3.3.3 DeviceList ....................................................................................................... 19
3.3.4 DataStreamList ............................................................................................... 19
3.3.5 BufferList ........................................................................................................ 20
3.4 Additional Classes ................................................................................................. 22
3.4.1 Image.............................................................................................................. 22
3.4.2 Image Processor ............................................................................................ 23
3.4.3 Trace............................................................................................................... 24
3.5 IException ............................................................................................................ 25
4. Programming Basics in Baumer-GAPI2 ............................................................... 26
4.1 Setting System variables ...................................................................................... 27
4.2 Implementation ..................................................................................................... 28
4.2.1 Implementation C++ ....................................................................................... 28
4.2.2 Implementation in C# ..................................................................................... 30
5. Application development with Baumer-GAPI ..................................................... 33
5.1 First steps ............................................................................................................. 33
5.1.1 Preparation ..................................................................................................... 34
5.1.2 SystemList ...................................................................................................... 35
5.1.3 Open a System ............................................................................................... 35
5.1.4 Get the InterfaceList and fill it ......................................................................... 36
5.1.5 Open an Interface ........................................................................................... 36
5.1.6 Get the DeviceList and fill it ............................................................................ 36
5.1.7 Open a Device ................................................................................................ 37
5.1.8 Get DataStreamList and fill it .......................................................................... 37
5.1.9 Open a DataStream ....................................................................................... 38
5.1.10 Create the BufferList and allocate Buffer memory ........................................ 38
5.1.11 Allocate Image Buffer to the DataStream ..................................................... 39
5.1.12 Start Camera and fill the Image Buffer ......................................................... 40
5.1.13 Releasing the resources ............................................................................... 41
3

Application (image processing interface written by the customer)
Customer
C# module
C# Component
Framework (OS module)
Operating
system
Framework:
Baumer-GAPI 2 is tested
with Windows ® : .NET
4.0
Image Library
Image
process ng
Co or
management
Algorithms
C++ API
Baumer GAPI2 Library
Baumer-GAPI2
GenTL Consumer
interface X
Plug in
Gigabit Ethernet
Plug in
USB 3 0
Plug in
GenTL Producer
TCP/IP
stack
Baumer
Driver X
Baumer Filter Driver
(optional)
Baumer USB 3 0
Device Driver
Hardware
Driver X
Hardware
Driver NIC
Bus Driver
Hardware Driver
Figure 1 ►
BGAPI 2 stack
Hardware X
Network Inte face
Card (NIC)
USB 3 0 Host Con roller
Hardware
4

1. Introduction
This programmer’s guide is addressed to programmers who need to integrate Baumer
cameras into their own software. It corresponds to the GenICam API of Baumer-GAPI2
and the use of Microsoft ® Visual Studio ® from version 2005 (C++) and version 2010 (C#).
2. Baumer-GAPI2
Baumer-GAPI2 is the abbreviation for Baumer “Generic Application Programming Interface”
in version 2. With this API Baumer provides an interface for optimal integration and
control of Baumer cameras.
The fundamental basis for BGAPI2 is the GenICam (Generic Interface for Cameras) standard
and the employment of GenTL as standardized interface.
BGAPI2 provides interfaces to several programming languages as C++ and to the .NET
Framework on Windows ® operating systems, which in turn allow the use of other languages
such as C# or VB.NET.
2.1 Baumer-GAPI2 Stack Components
2.1.1
Hardware
2.1.1.1 Gigabit Ethernet
Working with Baumer Gigabit Ethernet cameras requires the installation of appropriate
hardware – such as a NIC (Network Interface Card) on your PC.
Notice
For Gigabit Ethernet Baumer recommends the employment of NICs with an Intel ® chipset.
The hardware is delivered with a hardware driver which is required in order to establish
communications between hardware and software.
Installation:
For further information on
installing the Baumer-GAPI
SDK refer to the appropriate
Installation Guide for
your operating system and
hardware interface.
API:
API stands for “Application
Programming Interface”.
An API is a software
interface between two
programs, usually between
operating system and an
application.
GenICam:
GenICam stands for
Generic Interface for
Cameras and is a generic
programming interface
for industrial cameras. It’s
goal is to decouple industrial
camera interfaces
from the user application
programming interface
(API).
2.1.2
Baumer GenICam-API
Programmer
2.1.2.1
Producer
Within the GenICam Producer a complete camera system is mapped to the software. The
Producer provides the 5 main classes that are used in any BGAPI2 application.
2.1.2.2
Consumer
CameraL nk®
GigE Vis on®
(GEV)
USB3Vision
▲ Figure 2
The GenICam vision
The consumer is the counterpart of the producer mentioned above. Here all the available
producers are managed (loading, opening, closing).
Furthermore the consumer provides all additional classes and enables the exception handling.
2.1.2.3
Framework
A Framework represents a software platform, which provides a runtime environment, an
API and several services to the programmer. It is required, for example, when programming
in C# or VB.NET.
5

2.2
Software Components
The BGAPI2 is package of several libraries in form of dynamic link libraries (dll's). Thereat
previously mentioned GenTL producer represents an exception. The producer is delivered
as a common transport interface (.cti-file).
2.2.1 Baumer-GAPI2 Modules
The Baumer-GAPI2 is partitioned into several modules. Depending on your chosen programming
language, either more or fewer of these may be used.
2.2.1.1 Baumer-GAPI2 Library
As previously stated, Baumer-GAPI2 supports several programming languages to create
an application. Therefore the Baumer-GAPI2 Library represents a uniform API for the
cross-interface camera control. Here, global camera control functions are defined.
2.2.1.2 Image Library
This library includes several functions for image processing and image editing.
2.2.1.3
Programming Languages
This means that the C++ API and C# API resorts directly to the BGAPI2 library.
2.3
Gerneral System Requirements
Single-camera system
Recommended
Multi-camera system
Recommended
CPU DUAL-Core, Intel ® Xeon ® W3503 DUAL-Core, Intel ® Xeon ® W3503
Clock 2.4 GHz 2.4 GHz
RAM 4 GB 4 GB
Operating
system
(OS)
Compiler
As shown in Figure 1, the implementation of C++ and C# is partially realized hierarchically.
Framework
(optional)
Microsoft ® Windows ® 7 32 / 64 bit systems (required for USB 3.0)
Microsoft ® Windows ® 8 32 / 64 bit systems (required for USB 3.0)
Microsoft Compiler only
(included in Microsoft ® Visual Studio)
Windows ® OS: .NET Framework 4.0 or higher for C# implementation
6

Namespace: BGAPI2
INODE
NODEMAP
Interface
Classes
NODE
Main
Classes
List
Classes
SystemList
Additional
Classes
Image
Namespace: Exceptions
Exception
Classes
ErrorException
NotInitializedException
NotImplementedException
Classes of BGAPI2
Namespace: Events
EventControl
Interface
EventControl
Device
EventControl
DataStream
EventControl
PnPEvent DeviceEvent
System Interface Device DataStream Buffer
InterfaceList
DeviceList DataStreamList BufferList
Image
Processor
Trace
IException
ResourceInUseException
InvalidIdException
IOException
NotAvailableException
AccessDeniedException
NoDataException
AbortException
SysVarMissingException
InvalidHandleException
InvalidParameterException
InvalidBufferException
▲ Figure 3
Classes of BGAPI2
7

3. Central Idea Behind BGAPI2
The fundamental idea behind the Baumer SDK was to free the programmer from need of
defining and instantiating all the required and usable objects and to transfer these tasks
to the BGAPI2.
The API bases on five main classes (System, Interface, Device, DataStream, Buffer) and
the use of the GenTL interface.
On BGAPI2 there are two entry points for the user. On one hand, application programming
can be started by using the system list. On the other hand BGAPI2 offers the possibility
to use the image processor separately.
BGAPI2
Entry point
Programmer
GenAPI
GenTL
Third Party To ols
Consumer
Producer 1
Producer 2
e g GigE S andard e g bgapi gige
Producer
Customer
Application
Consumer
Producer 3
e g bgapi2 usb c i
Baumer
GenICam API
SystemList
System 0
System 1
...
NodeList
NodeTree
Node 0
Node 1
...
Node n
System
InterfaceList
Interface 0
Interface 1
...
Interface n
Image
Processor
Image
▲ Figure 3
Fundamental Approach
of GenAPI and GenTL
NodeList
NodeTree
Node 0
Node 1
...
Node n
Interface
DeviceList
Device 0
Device 1
...
Device n
(Remote-)
NodeList
(Remote-)
NodeTree
Node 0
Node 1
...
Node n
Device
DataStreamList
Data Stream 0
Data Stream 1
...
Data Stream n
DataStream
NodeList
NodeTree
Node 0
Node 1
...
Node n
BufferList
Buffer 0
Buffer 1
...
Buffer n
Buffer
NodeList
NodeTree
Figure 4 ►
Interaction diagram
Node 0
Node 1
...
Node n
8

3.1
Interface Classes
The major part of the functionality of BGAPI2 is provided by the two interface classes
NodeInterface and EventInterface. For instance the main classes inhertit functionalities
from INode.
3.1.1
INode, NodeMap, Node
INode
The INode class allows the direct access to all components
of the xml-file.
Parent class for:
System
Interface
Device DataStream
Buffer
Functions of the class INode
BGAPI2::INode:: ...
GetNode(String name);
GetNodeTree();
GetNodeList();
Returns a pointer to a specified object of the Node
class.
Returns the tree view of all nodes of the XML file.
Returns a one-dimensional list of the nodes of the XML
file.
NodeMap
NodeMap is the collection class for nodes.
Member of INode
Functions of the class NodeMap
BGAPI2::NodeMap:: ...
GetNode(String name);
GetNodeTree();
GetNodeList();
Returns a pointer to a specified object of the Node
class.
Returns the tree view of all nodes of the XML file
Returns a one-dimensional list of the nodes of the XML
file.
9

NODE
Member of INode
A Node presents one feature from the XML description
file.
Functions of the class Node
BGAPI2::Node:: ...
10
GetInterface();
GetExtension();
GetToolTip();
GetDescription();
GetName();
GetDisplayName();
GetVisibility();
GetImplemented();
GetAvailable();
GetLocked();
GetImposedAccessMode();
GetCurrentAccessMode();
GetAlias();
GetRepresentation();
GetUnit();
HasUnit();
GetEventID();
Enumeration value
GetEnumNodeList();
Returns the inferface of the respective Node.
Returns custom specific data from the XML-file.
Returns a Tool-Tip.
Returns the the description of the feature.
Returns the name of the feature.
Returns a meaningful for displaying in Graphical User
Inferfaces (GUI).
Returns the visibility of the node (Invisible, Beginner,
Expert, Guru).
Returns the status of implementation of the feature.
Returns the availability of the feature.
Returns information whether the feature is locked
(read only) or not.
Returns the the startup behavior of the feature
Returns the current access mode
Returns the name of another node which decribes the
same feature in a different manner
Gives a hint how to display the feature within the application
(GUI).
Returns the unit of the feature [e.g. ms, Hz].
Query whether the feature has a unit.
Returns the ID of an event.
Returns a list of Enum Entries of the feature.
Set value in string format (General purpose function)
GetValue();
Retrieving values ​as a converted string.
SetValue( String
Value );
Setting a value as string, regardless of the interface
type (it will be converted from string).
Integer functions (only for Integer Interface)
GetInt();
Retrieving of values.
SetInt( bo_int64
Setting values as an integer.
value );
GetIntMin();
Returns the minimum value.
GetIntMax();
Returns the maximum value.
GetIntInc();
Returns the step size for setting a value.
Float functions (only for Float Interface)
GetDouble();
Retrieving of value.
SetDouble( bo_double Setting values as an float.
value );
GetDoubleMin();
Returns the minimum value.
GetDoubleMax();
Returns the maximum value.
String functions (only for String interface)

GetMaxStringLength(); Retrieving the maximum length of the string.
GetString();
Retrieving of values.
SetString( String Setting values as an string.
value );
Command value (only for Command Interface)
Execute();
One-time exexution of a command.
IsDone();
Query, whether the command has been executed.
Boolean value (only for Bool Interface)
GetBool();
Retrieving of the values (true / false).
SetBool( bo_bool value Setting boolean values.
);
Access type (only for Category interface)
GetNodeTree();
Returns the tree view of all nodes.
GetNodeList();
Returns a one-dimensional list of the nodes.
Selectors
IsSelector();
Query, whether the feature is a selector.
GetSelectedNodeList(); Returns a list of features that are influenced by the
Selector.
Register access (only for Register Interface)
getLength();
Read a length of an address.
getAdress();
Read an address.
get( void *pBuffer, Read a register.
bo_unint64 len);
set(void *pBuffer, Write a register.
bo_uint64 len);
11

3.1.2
EventControl
This class provides access to custom events as well as the event node.
3.1.2.1
InterfaceEventControl
Interface EventControl
Inherits from:
EventControl
InterfaceEventControl provides the Plug´n Play
event.
Parent class for:
Interface
Functions of the class InterfaceEventControl
BGAPI2::InterfaceEventControl:: ...
RegisterPnPEvent(EventMode
eventMode);
UnregisterPnPEvent();
GetPnPEvent(PnPEvent * pPnPEvent,
bo_using64 iTimeout);
Enables the P´n´P Eventhandling.
Disables the P´n´P Eventhandling.
Polling function for the P´n´P Events.
3.1.2.2
DeviceEventControl
Device EventControl
This class provides access to standard events.
Inherits from:
Eventcontrol
Parent class for:
Device
Functions of the class Device EventControl
BGAPI2::DeviceEventControl:: ...
RegisterDeviceEvent(Event
eventMode);
UnregisterDeviceEvent();
GetDeviceEvent(DeviceEvent
* pDeviceEvent, bo_uint64
iTimeout);
Enables standard compliant device events, specified
within the xml description file.
Disable standard compliant device events, specified
within the xml description file.
Polling function for event devices.
12

3.1.2.3
DataStreamEventControl
DataStreamEventControl
Inherits from:
EventControl
DataStreamEventControl provices "new Bufferevent",
which is used a image notification.
Parent class for:
DataStream
Functions of the class DataStream EventControl
BGAPI2::DataStreamEventControl:: ...
RegisterNewBufferEvent();
UnregisterNewBuffer-
Event();
GetFilledBuffer(bo_uint64
iTimeout);
CancelGetFilledBuffer();
Enables standard compliant buffer events specified
within the xml description file.
Disables tandard compliant buffer events specified
within the xml description file.
Polling with timeout.
Cancellation routine for GetfilledBuffer.
13

3.2
Main Classes
The main classes represent the fundamental logical and physical components of the image
processing system.
The main classes are: System, Interface, Device, DataStream and Buffer.
3.2.1
System
System
Inherits from:
EventControl
INode
The System is the abstraction of the Producer and previously
mentioned producer.
Functions of the class System
BGAPI2::System:: ...
System(String filepath);
Open();
Close();
GetInterfaces();
GetID();
GetVendor();
GetModel();
GetVersion();
Setting the path to the producer file.
Open a System (producer file).
Close the System (producer file).
Returns a list of all available interfaces (InterfaceList).
Returns the unique string identifier of the System, which is
used in the SystemList.
Returns the name of the producer vendor.
Returns the model name of the producer.
Returns the version number of system file.
GetTLType(); Returns type of System (GEV, USB3, ...) .
GetName();
GetPathName();
GetDisplayName();
Returns the name of system file.
Retrieving the filepath.
Returns a meaningful name of the System for display only.
14

3.2.2
Interface
Interface
Inherits from:
Interface EventControl
INode
The class Interface represents a physical interface, e.g.
GEV or a logical interface, such as USB.
Functions of the class Interface
BGAPI2::Interface:: ...
Open();
Close();
GetDevices();
GetID();
GetDisplayName();
Open an Interface.
Close the Interface.
Returns the list of available devices for this interface (DeviceList).
Returns the unique string ID which is used in InterfaceList.
Returns a meaningful name of the Interface for display only.
GetTLType(); Returns interface type (GEV, USB, ...).
3.2.3
Device
Device
Inherits from:
Device EventControl
INode
The main class Device is used to retrieve information
(e.g. model, manufacturer, access modes) of the device
(camera) and also to control the device.
Functions of the class Device
BGAPI2::Device:: ...
OpenReadOnly();
Open();
OpenExclusive();
Close();
IsOpen();
StartStacking();
WriteStack();
GetDataStreams();
GetID();
GetVendor();
Open as read only, no parameters can be changed.
Open a device with read and write access.
Open a device exclusively with read and write access, the
device is blocked for other software tools.
Close the device.
Open a device with read only access, changing parameters
is denied.
Start command for parameter stacking (parameters will be
queued).
Single write command to transmit all stacked parameters
at once.
Returns a list of available DataStreams.
Returns the unique string ID of device (such as MAC address
on GEV).
Returns the vendor of the camera.
15

GetModel();
GetTLType();
GetDisplayName();
GetAccessStatus();
GetPayloadSize();
GetRemoteNode
(String name);
GetRemoteNode-
Tree();
GetRemoteNodeList();
GetRemoteConfigurationFile();
Returns the camera model (e.g. MXGC20c).
Returns the device type of system (such as GEV,
USB3, ...).
Returns a meaningful name, for display only.
Returns how the device is / can be opened:
Open();
OpenReadOnly();
OpenExclusive();
Returns the Payloadsize.
Returns a pointer to a specified object of the connected
device.
Returns the tree view of all nodes of the XML file of the
connected device.
Returns a one-dimensional list of the nodes of the XML file
of the connected devices.
Returns the XML description file of the connected device.
3.2.4
DataStream
DataStream
This class is responsable for the buffer handling.
Inherits from:
DataStream EventControl
Node
Functions of the class DataStream
BGAPI2::DataStream:: ...
Open();
Close();
GetBufferList();
GetID();
GetPayloadSize();
GetDefinesPayload-
Size();
GetIsGrabbing();
GetTLType();
StartAcquisition
(bo_uint64
iNumToAcquire);
StopAcquisition();
AbortAcquisition();
Open a DataStream.
Close the DataStream.
Returns a list of already created buffers (BufferList).
Returns the unique string identifier of the DataStream.
Returns the size Payloadsize.
Checks if Datastream can provide Payloadsize.
Returns whether the DataStream is already started or not.
Returns the type of the DataStream.
Starts the acquisition of a specified number of images.
Stops the image acquisition.
Aborts the image acquisition immediately.
16

3.2.5
Buffer
Buffer
Inherits from:
EventControl
This class realizes the data access to the memory. It contains
information about the received data (e.g. image size,
pixel format) too.
The Buffer module encapsulates a single memory buffer.
Its purpose is to act as the target for the image acquisition.
Buffers can be allocated automatically by the producer or
by the user.
Notice
On activated Chunk mode, there is no access to some
features of the buffer object (e.g. GetHeight, GetWidth
or GetPixelFormat). Please use the GetChunkNodeTree
function instead.
Functions of the class Buffer
BGAPI2::Buffer:: ...
Buffer();
Buffer( void * pUserObj
);
Buffer( void *pUserBuffer,
bo_uint64
uUserBufferSize,
void *pUserObj);
GetID();
QueueBuffer();
GetMemPtr();
GetMemSize();
GetUserObj();
GetTimestamp();
GetNewData();
GetIsQueued();
Creates a buffer object.
Creates a buffer object including user specific data.
Creates a buffer object with using user allocated memory.
Returns the unique ID of buffer (e.g. Buffer_01f94fb), not
the memory address of the buffer.
Allocates the buffer to the input queue of a DataStream.
Returns the memory address of the buffer.
Returns the memory size of the buffer.
Returns the user specific data of the buffer.
Returns the buffer´s timestamp.
Returns "true" if the buffer is filled until GetFilledBuffer is
performed.
Returns "true" as long as the buffer is allocated to the input
queue of a DataStream.
Returns "true", if buffer being filled.
Returns "true" on defect image data.
GetIsAcquiring();
GetIsIncomplete();
GetTLType(); Returns the type of buffer (GEV, USB3, ...).
GetSizeFilled(); Returns the current fill level of the buffer [Bytes].
GetWidth();
Returns the image width.
GetHeight();
Returns the image height.
GetXOffset(); Returns the offset in x-direction.
GetYOffset(); Returns the offset in y-direction.
GetFrameID(); Returns a hardware generated counter (1...65535).
GetImagePresent(); Returns the availability of the image within the buffer.
GetImageOffset(); Returns the position of the first byte of image data within
the buffer.
GetPayloadType(); Returns whether the payload is chunck or image data .
GetPixelFormat(); Returns the pixel format of the image.
17

GetDeliveredImage-
Height();
GetDelivered-
ChunkPayloadSize();
GetChunkLayoutID();
GetChunkNodeTree();
Returns the number of lines of a transmitted image.
Returns the delivered chunk payload size.
Returns the ID of the layout.
Returns the tree view of all chunk nodes.
3.3
List Classes
This classes aim to the discovery and listing of the main objects.
The list classes are: SystemList, InterfaceList, DeviceList, DataStreamList and Buffer-
List.
In any list class there are three different ways to handle the objects within a list. The first
of them is the iterator, which can be used for interating through the lists using begin
and end functions.
The second approach is the access by using the subscript operator. And the third way of
object handling is realized by the find function.
Each list entry consists of an ID, which is used as key value and a pointer to an object of
the main classes.
This functions are availalble for all List Classes.
BGAPI2::[respective List Class]:: ...
iterator
begin();
end();
Refresh(bo_uint64 iTimeout);
size();
operator[](const String& val)
find(const String& _keyval);
erase(iterator& _where);
erase(const String& _keyval);
clear();
This is the iterator class.
Retrieving the iterator that points to the first
list entry.
Retrieving the iterator that points to the last
list entry (+1).
Refresh with timout.
(not available for the BufferList)
Returns the number of found list entries.
This is the subscript operator for the access
to a free selectable point of a list.
Returns the iterator for the desired list entry,
that is defined by the unique ...
Erases a list entry, using the iterator.
Erases a list entry, using the unique string
identifier.
Clears the list.
18

3.3.1
SystemList
SystemList
This class is used to list objects of the System class.
Special feature of the SystemList: This object is a Singleton.
It is not possible to create other objects of this class. It always
accesses to the same object. Therefore, a release function is necessary.
Functions of the class SystemList
BGAPI2::SystemList:: ...
GetInstance();
ReleaseInstance();
CreateInstanceFromPath (String
producerpath);
Add(System * pSystem);
Refresh();
Create the instance of the SystemList.
Release the instance of the SystemList.
Forces the usage of only one producer for
the listing.
Adds a producer to the list.
Refreshes the SystemList.
3.3.2
InterfaceList
InterfaceList
This class is used to list objects of the Interface class.
3.3.3
DeviceList
DeviceList
This class is used to list objects of the Device class.
3.3.4
DataStreamList
DataStreamList
This class is used to list objects of the DataStream class.
19

3.3.5
BufferList
BufferList
This class is used to list objects of the Buffer class.
Special feature of the BufferList: With this list class the programmer
can add buffers to the buffer list. Therefore there is no
refresh function.
Functions of the class BufferList
BGAPI2::BufferList:: ...
Add(Buffer *pBuffer);
RevokeBuffer(Buffer
*pBuffer);
FlushInputToOutput-
Queue();
FlushAllToInputQueue();
FlushUnqueuedToInput-
Queue();
DiscardOutputBuffers();
DiscardAllBuffers();
GetDeliveredCount();
GetUnderrunCount();
GetAnnouncedCount();
GetQueuedCount();
GetAwaitDeliveryCount();
Adds a new Butter to the BufferList.
Revokes the buffer from the BufferList.
Flushing all buffers form the input queue to the output
queue.
Flushing all available buffers to the input queue.
Flushing all announced buffer to the input queue.
Discarding all buffers from the output queue to announced
status.
Discarding all buffers form any queue to announced
status.
Returns the number of buffers that are retrieved from
the output queue by using GetFilledBuffer.
Returns the number of buffer underruns.
Returns the number of announced buffers.
Returns the number of queued buffer (input queue).
Returns the number of queued buffer (output
queue).
20

Memory
delete & free
create & allocate
Buffer
RevokeBuffer
Add
Announce
DiscardAllBuffers
QueueBuffer/
FlushAllToInputQueue
GetFilledBuffer/
DiscardAllBuffers/
DiscardOutputBuffers
Queued
------------
Inpuf Buffer
Pool
FlushInputToOutputQueue
FlushAllToInputQueue
Pending
------------
Output Buffer
Pool
Start of new Frame
Frame Acquisition complete
Fill
◄ Figure 6
Buffer handling
21

3.4
Additional Classes
Beside the previously mentioned classes, the BGAPI2 also contains three additional
classes.
The first two of them (Image & ImageProcessor) are used for image handling and manipulation
and are encapsulated in the bgapi2_img.dll. The third class (Trace) aims to
the tracing functionality.
3.4.1
Image
Image
This class provides the ability of image transformation.
Functions of the class Image
BGAPI2::Image:: ...
GetWidth();
GetHeight();
GetPixelFormat();
TransformImage( String sPixelFormat,
Image** ppOutputImage );
GetBuffer();
GetTransformBufferLength(String
sPixelFormat);
TransformImageToBuffer( String sPixelFormat,
void* pBuffer, bo_uint64
uBufferSize );
His-
GetHistogram(bo_tHistRecords
togram);
Release();
Returns the buffer of the image.
Returns the required buffer length of
the image, after tranformation to a
specified pixel format.
Performs the image transformation
using user allocated buffer of the previously
determined length (GetTransformBufferLength).
Returns the histogramm array of the
image
Releases the occupied resources (except
the user allocated buffer).
Returns the width of the image.
Returns the height of the image.
Returns the pixel format of the image.
Performs the image transformation.
22

3.4.2
Image Processor
Image Processor
The task of this class is the creation of image objects
Functions of the class Image Processor
BGAPI2::ImageProcessor:: ...
GetInstance();
ReleaseInstance();
GetVersion();
CreateImage(bo_uint width, bo_
uint height, String pixelformat,
void* pBuffer, bo_uint64 uBuffer-
Size);
CreateTransformedImage(Image*
pInputImage, const char* szDestinationPixelformat);
SetDestinationFlip( bool vertical,
bool horicontal );
GetDestinationFlip( bool *vertical,
bool *horicontal );
Creates a singleton instance of the
class.
Releases the image processor instance.
Returns the version of the Image processor.
Creates a BGAPI Image object based
on a filled buffer.
Creates an image object and performes
a pixel format transformation.
Flips the image in the specified direction.
Returns the direction of the image flipping.
23

3.4.3
Trace
Trace
BGAPI2 Trace offers the possibility to monitor the program flow
and detect errors.
Functions of the class Trace
BGAPI2::Trace:: ...
Enable( bo_bool benable );
ActivateOutputToFile( bo_bool bactive,
String tracefilename );
ActivateOutputToDebugger( bo_bool
vactive );
ActivateMaskError( bool vactive );
ActivateMaskWarning( bo_bool bactive
);
ActivateMaskInformation( bo_bool
bactive );
ActivateOutputOptionTimestamp( bo_
bool bactive );
ActivateOutputOptionTimestampDiff(
bo_bool bactive);
ActivateOutputOptionPrefix( bo_bool
bactive );
Enables or disables of the tracing.
Provides the possibility to print trace
outputs to the specified file.
Provides the possibility to print trace
outputs to the debugger.
Activates error tracing
Activates warning tracing.
Activates information tracing.
Includes the timestamp to the trace
output.
Includes the time lag from the last to
the current trace output.
Includes the module, that created the
trace output (such as producer, consumer
...)
24

3.5
IException
IException
This class is responable for the exception handling and represents
the parent class of all exception classes.
Functions of the IException
BGAPI2::IException:: ...
GetErrorDescription();
GetFunctionName();
GetType();
Exception Class
NotInitializedException
NotImplementedException
ResourceInUseException
AccessDeniedException
InvalidHandleException
InvalidIdException
NoDataException
Returns a description of the error.
Returns the function name, where the error occured.
Returns the type of the error.
InvalidParameterException
IOException
AbortException
InvalidBufferException
NotAvailableException
SysVarMissingException
ErrorException
Description
The requested object is not initialized.
The requested function/feature is not implemented.
The requested object is already used.
Requested operation is not allowed.
Given handle does not support the operation.
ID could not be connected to a resource.
The function has no data to work on.
One of the parameter given was not valid or out of
range and none of the error codes above fits.
Communication error has occurred.
An operation has been aborted before it could be
completed.
No Buffer announced or one or more buffers with
invalid buffer size.
Resource or information is not available at a given
time in a current state.
System variable is not available or specified (see
section 4.1).
General purpose exception
25

4. Programming Basics in Baumer-GAPI2
During the installation process, all required files were copied to your system.
Default path Windows ® 32 bit / 64 bit:
C:\Program Files\Baumer\Baumer GAPI SDK
In the following, these folders are refered to as
Notice
Location of the Runtime Modules
All Baumer-GAPI2 DLL's must be provided within the same directory as the calling
application. This accounts for the fact, that the BGAPI2_genicam.dll tries to find its
modules within the directory in which it finds itself.
Further searches the BGAPI2_genicam.dll in the GENTL PATH for producers.
Please take care to refer to the correct directory (Win32 = 32bit / x64 = 64 bit).
This mainly should be considered for the employment of Microsoft ® Visual Studio –
here the working directory needs to be suitable adjusted.
26

4.1
Setting System variables
Microsoft ® Windows ® 7
Notice
The path to the system variable is set already during the installation process of the SDK.
Follow the instructions to change the path to the system variables (bgapi2_xxx.cti).
1. Click Start, then choose Computer.
2. Click Properties.
3. Select the tab Advanced.
4. Click Environment Variables.
5. Control whether in the System
variables the entry GENICAM_GEN-
TL32_PATH exists.
If the entry does not exist continue
with step 6.
If the entry exists continue with
step 8.
6. Click New at System variables.
7. Adjust the following.
Variable name:
GENICAM_GENTL32_PATH
Variables value:
32-bit systems
\Components\Bin\Win32
64-bit systems
\Components\Bin\x64
Continue with step 9.
8. Select the Variable GENICAM_
GENTL32_PATH and click Edit.
Add the Baumer path to the Variable
value. Separate it with a semicolon
to existing entries.
Variables value:
32-bit systems
\Components\Bin\Win32
64-bit systems
\Components\Bin\x64
27

4.2 Implementation
Depending on the programming language you have chosen, you will need to include
different header files and libraries. See the respective precaution of your employed programming
language.
4.2.1
Implementation C++
Header files:
Files required for the
compiler and containing
forwarded declarations for
subroutines, variables and
other identifiers.
4.2.1.1 Header Files
\Components\Dev\C++\Inc
bgapi2_genicam.hpp
bgapi2_def.h
bgapi2_featurenames.h
Interface definition for Baumer-GAPI2, including classes,
functions and function pointer for callbacks.
Definitions for Baumer-GAPI2, including defines, enumerations
and typedefs.
Summary of the features from the GenICam Standard Features
Naming Convention.
To include the necessary header file for C++ write the following code:
#include "bgapi2_genicam.hpp"
4.2.1.2 Libraries
Library:
Collection of recurrent
routines.
Notice
The files required for 32 bit and 64 bit operating systems are totally different. Please
include the correct folder. Including the wrong files may lead to problems!
Default path Windows ® 32bit:
\Components\Dev\C++\Lib\Win32
Default path Windows ® 64bit:
\Components\Dev\C++\Lib\x64
bgapi2_genicam.lib
This is where all function names and their implementations
are filed.
28

4.2.1.3
Precaution
Create a new project by generating a *.cpp file, then open the project properties from the
context menu. Some required information such as the header files directory will need to
be set here.
Please set the following values in “ Properties”:
▪▪
“ C++” → “General”: “Additional Include Directories”:
\Dev\C++\Inc
▪▪
“Linker” → “General”: “ Additional Library Directories”:
\Dev\C++\Lib\Win32
▪▪ “Linker” → “Input”: “Additional Dependencies”:
bgapi2_genicam.lib
▪▪ “Build Events” → “Post-Build-Event”: “Command Line”:
absolute path:
copy "\Components\Bin\Win32"\*.* .\
or the relative path (which is used in the examples):
copy ..\..\..\..\..\Bin\Win32\*.* .\
Notice
32-Bit:
\Components\Bin\Win32
bgapi2_genicam.dll
bgapi2_img.dll
BO_GigEFilterDrv.dll
MathParser.dll
64-Bit
\Components\Bin\x64
bgapi2_genicam.dll
bgapi2_img.dll
BO_GigEFilterDrv.dll
MathParser.dll
4.2.1.4 Using Namespace
In order to employ the BGAPI2 namespace for C++ as default, please enter the following
code:
using namespace BGAPI2;
29

4.2.2 Implementation in C#
4.2.2.1
.NET Component
Create a new project, open its properties via
the context menu and select:
"Add Reference...".
Integrate the respective bgapi2_genicam_
dotnet.dll.
Now you can see under References the integrated
bgapi2_genicam_dotnet.dll.
Build Events (C#
The reason for the
command is that
compiled .exe mu
contain all require
bgapi2.dll files in
same directory.
Notice
32-Bit:
\Components\Dev\C_Sharp\Win32
bgapi2_genicam_dotnet.dll
64-Bit
\Components\Dev\C_Sharp\x64
bgapi2_genicam_dotnet.dll
Then go to the added bgapi2_genicam_dotnet.dll
Properties and set "Copy Local" to
"True".
30

4.2.2.2
Precaution
The first method is applied with the provided examples.
Please set the following values under
“ Properties”:
▪▪ “Build Events” → “Post-Build-Event”: “Command Line”:
absolute path:
copy "\Components\Bin\Win32"\*.* .\
or relative path:
relative path: copy "..\..\..\..\..\..\..\Bin\Win32"\*.* .\
Alternatively you can use this method:
Open the properties via the context menu
and select:
):
copy
he
st
d
the
"Add → Existing Item...".
Add the respective DLL files.
31

Notice
32-Bit:
\Components\Bin\Win32
bgapi2_genicam.dll
bgapi2_img.dll
BO_GigEFilterDrv.dll
MathParser.dll
64-Bit
\Components\Bin\x64
bgapi2_genicam.dll
bgapi2_img.dll
BO_GigEFilterDrv.dll
MathParser.dll
At each of the included files you must set "Copy
to Output Directory" to "Copy always".
4.2.2.3 Using Namespace
In order to employ the BGAPI2 namespace for C# as a default, please enter the following
code:
using BGAPI2;
or put BGAPI2 to all calls at the head, e.g.:
BGAPI2.Interface
BGAPI2.Device
BGAPI2.Image
BGAPI2.Exception
32

5. Application development with Baumer-GAPI
Notice
In order to ensure a smooth flow of your application, it is not recommended to perform
function calls during the image acquisition on high system load. If parallel processing
is necessary, Baumer suggests the processing of these function calls in a separate
thread.
5.1 First steps
In this chapter, we will guide you on your way to the first image.
This tutorial relates to working with one interface and one camera in C++ and C#.
Instances
Baumer-GAPI2
entry point
Programmer
DataStream
Device
Interface
System
SystemList
◄ Figure 7
Steps to the first image
33

5.1.1
Preparation
5.1.1.1
Includes
First, please create a new project and set the “Configuration Properties”.
Header files C++
Header file of the default
input/output library: This
library includes macro
definitions, constants,
declarations of functions
and types.
For more information look
into the documentation for
standard library.
C++ C#
and include the necessary header file
#include "bgapi2_genicam.hpp"
using namespace BGAPI2;
The standard library and the standard input/output
header also need to be included:
#include
using System;
#include
using System.Collections.Generic;
#include
using System.Linq;
using System.Text;
using BGAPI2;
5.1.1.2
Declaration of Variables
We also need to declare several variables and pointers for the main function:
C++ C#
int main()
{
static void Main(string[] args)
{
Variable for SystemList and System
BGAPI2::SystemList * systemList = NULL;
BGAPI2.SystemList systemList = null;
BGAPI2::System * pSystem = NULL;
BGAPI2.System mSystem = null;
BGAPI2::String sSystemID; string sSystemID = "";
Variables for InterfaceList and Interface:
BGAPI2::InterfaceList * interfaceList =
NULL;
BGAPI2.InterfaceList interfaceList = null;
BGAPI2::Interface * pInterface = NULL;
BGAPI2.Interface mInterface = null;
BGAPI2::String sInterfaceID; string sInterfaceID = "";
Variable for DeviceList and Device
BGAPI2::DeviceList * deviceList = NULL;
BGAPI2.DeviceList deviceList = null;
BGAPI2::Device * pDevice = NULL;
BGAPI2.Device mDevice = null;
BGAPI2::String sDeviceID; string sDeviceID = "";
Variables for DataStreamList and DataStream
BGAPI2::DataStreamList * datastreamList =
NULL;
DataStreamList datastreamList = null;
BGAPI2::DataStream * pDataStream = NULL;
BGAPI2.DataStream mDataStream = null;
BGAPI2::String sDataStreamID; string sDataStreamID = "";
Variables for BufferList and Buffer
BGAPI2::BufferList * bufferList = NULL;
BufferList bufferList = null;
BGAPI2::Buffer * pBuffer = NULL;
BGAPI2.Buffer mBuffer = null;
34

5.1.2
SystemList
C++ C#
instantiating and updating SystemList
try
try
{ {
systemList = SystemList::GetInstance();
systemList = SystemList.Instance;
systemList->Refresh();
systemList.Refresh();
std::cout

5.1.4
Get the InterfaceList and fill it
Get the the InterfaceList of the selected System and update that list. For this example we
used a timeout of 100 ms.
C++ C#
interfaceList = pSystem->GetInterfaces(); interfaceList = mSystem.Interfaces;
interfaceList->Refresh(100);
interfaceList.Refresh(100);
std::cout end(); ifc++)
foreach (KeyValuePair
ifc_pair in interfaceList)
{ {
ifc->second->Open(); ifc_pair.Value.Open();
sInterfaceID = ifc->first; sInterfaceID = ifc_pair.Key;
break; break;
} }
Check whether the InterfaceID is filled and assign the interface pointer:
if (sInterfaceID == "") if (sInterfaceID == "")
return 0; // no interface found return; // no interface found
else
else
pInterface = (*interfaceList)[sInter
faceID];
mInterface =
interfaceList[sInterfaceID];
5.1.6
Get the DeviceList and fill it
Get the the DeviceList of the selected Interface and update that list. Using a timeout of
100 ms.
C++ C#
deviceList = pInterface->GetDevices();
deviceList = mInterface.Devices;
deviceList->Refresh(100);
deviceList.Refresh(100);
std::cout

5.1.7
Open a Device
Now you search for the device in the list (here open the first device in the list):
C++ C#
for (DeviceList::iterator dev = deviceList->begin();
dev != deviceList-
>end(); dev++)
foreach (KeyValuePair
dev_pair in deviceList)
{ {
dev->second->Open(); dev_pair:Value.Open();
sDeviceID = dev->first; sDeviceID = dev_pair.Key;
break; break;
} }
Check the DeviceID is filled and assign the device pointer:
if (sDeviceID == "") if (sDeviceID == "")
return 0; // no device found return; // no device found
else
else
pDevice = (*deviceList)[sDeviceID]; mDevice = deviceList[sDeviceID];
5.1.8
Get DataStreamList and fill it
Get the the DataStreamList of the selected Device and update that list. Using a timeout
of 100 ms.
C++ C#
datastreamList = pDevice-
datastreamList = mDevice.DataStreams;
>GetDataStreams();
datastreamList->Refresh(100);
datastreamList.Refresh(100);
std::cout

5.1.9
Open a DataStream
Now you search for the data stream in the list (here open the first datastream in the list):
C++ C#
for(DataStreamList::iterator dst=
datastreamList->begin();dst != datastream-
List->end();dst++)
foreach (KeyValuePair dst_pair in datastreamList)
{ {
dst->second->Open(); dst_pair.Value.Open();
sDataStreamID = dst->first; sDataStreamID = dst_pair.Key;
break; break;
} }
Check the DataStreamID is filled and assign the data stream pointer:
if (sDataStreamID == "") if (sDataStreamID == "")
return 0; // no datastream found return; // no datastream found
else
else
pDataStream = (*datastreamList)
[sDataStreamID];
Now the datastream is opened.
mDataStream =
datastreamList[sDataStreamID];
5.1.10
Create the BufferList and allocate Buffer memory
The created BufferList is empty and needs to be filled with buffers.
C++ C#
bufferList = pDataStream->GetBufferList(); bufferList = mDataStream.BufferList;
for(int i=0; i

5.1.11
Allocate Image Buffer to the DataStream
C++ C#
for (BufferList::iterator buf = bufferList->begin();
buf != bufferList->end();
buf++)
foreach (KeyValuePair
buf_pair in bufferList)
{ {
buf->second->QueueBuffer(); buf_pair.Value.QueueBuffer();
} }
std::cout

5.1.12
Start Camera and fill the Image Buffer
Start the data stream.
40
C++ C#
pDataStream->StartAcquisitionContinuous(); mDataStream.StartAcquisition();
pDevice->GetRemoteNode("AcquisitionStart")-
>Execute();
Start of the camera:
mDevice.RemoteNodeList["AcquisitionStart"]
.Execute();
Fill the image buffer using a timeout of 1000 milliseconds. The memory pointer to the
image data is displayed.
BGAPI2::Buffer * pBufferFilled = NULL;
BGAPI2.Buffer mBufferFilled = null;
try
try
{ {
pBufferFilled = pDataStream-
>GetFilledBuffer(1000);
mBufferFilled = mDataStream.Get
FilledBuffer(1000);
if(pBufferFilled == NULL) if(mBufferFilled == null)
{ {
std::cout

ufferList->DiscardAllBuffers();
bufferList.DiscardAllBuffers();
while( bufferList->size() > 0) while (bufferList.Count > 0)
{ {
pBuffer = bufferList->begin()-
>second;
mBuffer = bufferList.Values.First();
bufferList->RevokeBuffer(pBuffer); bufferList.RevokeBuffer(mBuffer);
delete pBuffer; }
5.1.13
Releasing the resources
C++ C#
pDataStream->Close();
mDataStream.Close();
pDevice->Close();
mDevice.Close();
pInterface->Close();
mInterface.Close();
pSystem->Close();
mSystem.Close();
BGAPI2::SystemList::ReleaseInstance();
int endKey = 0;
To prevent the application from closing use the following code:
std::cout > endKey;
return 0;
} // end of main
System.Console.Write("Input any number to
close the program:\n");
Console.Read();
return;
} //end of Main
41

Baumer Optronic GmbH
Badstrasse 30
DE-01454 Radeberg, Germany
Phone +49 (0)3528 4386 0 · Fax +49 (0)3528 4386 86
sales@baumeroptronic.com · www.baumer.com
Technical data has been fully checked, but accuracy of printed matter not guaranteed.
Subject to change without notice. Printed in Germany 01/13. v1.0 11099008