Software Development Kit (SDK)


.

Table of Content

1

Introduction

1.1
Overview
1.2
'hello world' for a free running camera
2

Initialization and Parameterization

2.1
Overview
2.2
Initialization and Release
2.2.1
Initializing without Configuration File
2.2.2
Initializing with configuration file
2.2.3
Releasing frame grabber resources
2.2.4
Specfic initializations according to advanced frame grabber usage
2.3
Configuration files
2.3.1
Loading a frame grabber configuration
2.3.2
Saving a frame grabber configuration
2.4
Parameter interface of the frame grabber
2.4.1
Setting the frame grabber parameters
2.4.2
Getting special parameter settings
2.5
Parameter interface of the frame grabber
2.5.1
Setting the frame grabber parameters
2.5.2
Getting special parameter settings
2.5.3
Parameter ID
2.5.3.1
Getting the parameter ID
2.5.3.2
Parameter ID by name
2.5.4
Name of a parameter
2.5.5
Number of parameters
3

Memory management

3.1
Overview
3.1.1
Memory buffer layout
3.1.2
Memory management functions
3.2
Grabber allocated frame memory
3.2.1
Anonymous grabber allocated frame memory
3.2.1.1
Allocating a frame buffer
3.2.1.2
Releasing a frame buffer
3.2.2
Explicit grabber allocated frame memory
3.2.2.1
Allocating one frame buffer out of several
3.2.2.2
Releasing frame buffers
3.3
User allocated frame memory
3.3.1
Overview
3.3.2
Memory management settings
3.3.3
Adding user memory
3.3.4
Deleting user memory
3.3.5
Releasing memory
3.4
General memory limitations
4

Acquisition

4.1
Overview
4.2
Acquisition modes
4.3
Start and stop image grabbing
4.3.1
Starting image grabbing
4.3.2
Stopping image grabbing
4.3.3
Example Non Blockin Mode
4.3.4
Example blocking mode
4.4
Controlling Transfer Status
4.4.1
Default mode
4.4.1.1
Getting the image
4.4.1.2
Requesting the current image number
4.4.1.2.1
Requesting the current image number (Non-Blocking Function Call)
4.4.1.2.2
Requesting the current image number (Blocking Function Call)
4.4.2
Acquisition with blocked frame buffers
4.5
Access on frame buffer
4.6
Status information on frame buffer
4.6.1
Reading the status of frame buffer
4.6.2
Setting the status of frame buffer
4.6.3
Reading the image tag information
4.6.4
Reading the DMA transfer length
4.6.5
Reading the time stamp as integer
4.6.6
Reading the time stamp as unsigned integer 64
4.7
Settings during acquisition
4.8
Timeout configuration
4.9
Sequence recording
4.10
Access on pixel data
5

Features

5.1
Operation modes of the trigger system
5.1.1
Overview (Acquisition Applets / VA Applets)
5.1.2
Using Trigger Modes Based On Acquisition Applets
5.1.2.1
Free Run Mode
5.1.2.2
Acquisition is Controlled by the Frame Grabber - Grabber Controlled Mode
5.1.2.2.1
Grabber Controlled Mode for one Camera Port
5.1.2.2.2
Grabber Controlled Synchron for Two Cameras
5.1.2.3
Acquisition is Triggered by Software - Software Trigger Mode
5.1.2.4
Acquisition is Controlled by External Signal - External Trigger
5.1.2.5
Strobe
5.1.2.5.1
Setting the Exposure Time
5.1.2.5.2
Strobe Delay
5.1.2.5.3
Activating and Deactivating the Strobe
5.1.2.6
Activating and Deactivating the Exsync
5.1.3
Using Trigger Modes Based On VA Applets
5.1.3.1
FreeRun mode
5.1.3.2
Acquisition is controlled by the frame grabber - Grabber controlled mode
5.1.3.3
Acquisition is controlled by external signal - External trigger
5.1.3.4
Acquisition is triggered by software - Software trigger mode
5.2
Coprocessor functionality (VisualApplets)
5.3
Shading Interface with Defective Pixel Interpolation (Acquisition Applets)
5.3.1
Overview
5.3.2
Allocating Buffer for Shading Feature
5.3.3
Freeing Buffer
5.3.4
Getting Access to Shading Interface
5.3.5
Closing the Access
5.3.6
Getting the Line Number of the Current Image
5.3.7
Setting Parameters for Shading Calculation and Defective Pixel Interpolation
5.3.8
Writing the Currently Corrected Line
5.4
PixelPlant
6

Asynchronous Grabbing (APC)

6.1
Registering a callback handler
6.2
Callback notifications
6.3
Termination of APC / Stopping the acquisition
7

Serial interface (CL frame grabber)

8

Error functions

8.1
Description of last error message
8.2
Getting the last error code
8.3
Obtaining Error Messages From Error Codes
8.4
Error Messages
9

Further Functions For Information Retrieval

9.1
Software Version Number
9.2
Board Type
9.3
Serial Number
9.4
Applet ID
9.5
Applet Version
9.6
Global Write Access Flag
9.7
Using The Type ENUM
10

Event management

10.1
Event system<
10.2
Query available events
10.3
Example: List of Camera Link based events
10.4
Controlling event notifications
10.5
Event notification
10.6
Event information
10.7
Example for waiting on an event
10.8
Example for asynchronous event handling
11

Image Display

11.1
Overview
11.2
Create Display()
11.3
SetBufferWidth()
11.4
DrawBuffer()
11.5
CloseDisplay()
11.6
SetDisplayDepth()
12

Compiler settings

12.1
WindowsTM
12.2
Linux
12.3
QNXTM
13

File Formats

13.1
File Formats for Lookup-Tables
13.1.1
General Properties
13.1.2
Header
13.1.3
Main Section
13.1.4
LUT format for color image format
13.2
File Formats for Knee-Lookup-Tables
13.2.1
Header
13.2.2
Main Section
13.3
File format for VisualApplets field parameters and tables
13.3.1
General properties
13.3.2
Example for a table of integer values
13.3.3
Examples for field parameter types
14

Index

The Software Development Kit (SDK) - Manual

Runtime 5
June 2018


Supported Frame Grabbers

The SDK supports all Basler frame grabbers of the following generations:

  • microEnable IV (Camera Link and GigE Vision)
  • microEnable 5 marathon (Camera Link, CXP, CLHS)
  • microEnable 5 ironman (Camera Link, CXP)

Supported Operating Systems

Windows (with Virtual Studio 2017, 2015, 2013, 2012, 2010, 2008):

  • Windows 10 (32bit/64bit)
  • Windows 8 (32bit/64bit)
  • Windows 7 (32bit/64bit)
  • Windows Server 2012
  • Windows Server 2010
  • Windows Server 2008 R2

Linux (with gcc version 4 or higher):

  • Linux 32bit
  • Linux 64bit

1 Introduction

1.1 Overview

This chapter is intended to introduce you to the powerfull and flexible microEnable Frame Grabber Series Software Development Kit (SDK). The concept and elementary functions of the SDK will be described and enhanced by code examples.

Please note: There exists an additional SDK documentation (SDK Manual - GigE Extensions) , covering GigE specific functions.

This document describes the general software interface of the microEnable Frame Grabber Series. It is a review on the main functions. In certain cases different parameters will be used for different frame grabber setups (i.e. color or gray scale grabber). These differences can be found in the software manuals of the according camera manufacturers.

Concerning information on microEnable Series hardware, please take a look at corresponding manuals more.

The microEnable frame grabber series is a modern frame grabber family which is based on the FPGA technology. It gives the user the advantage of an individual setting concerning different use cases by the reason of different FPGA configurations (applets) for area or line scan cameras, gray or color processing or special functions as real-time bayer correction or 2D shading functionality. The possibility in choosing the needed functions is a central concept and is realized in software interface by choosing the corresponding FPGA functionality.

There are basically 3 possibilities to use a certain set of functions (represented through an applet) on a Basler frame grabber. You can either load and access predefined applets - termed Acquisition Applet or SmartApplets, or you can create and access a custom applet with a certain functionality by using VisualApplets - termed VA Applet. One major difference is, that in case of AcquisitionApplets / SmartApplets we are handling .dll-files, in case of VA Applets we are handling .hap-files. Within this documentation you will get information which and how functions can be used for Acquisition Applets / SmartApplets, which and how functions can be used in the context of VA Applets and which and how functions can be applied for both types of applets

Calling Fg_Init() for initializing the grabber and sending a special FPGA functionality library will choose the wished library and FPGA functionality and the grabber will be configured.

Each configuration is parameterizable in a big range. Typical parameters are i. e. the image size, setting the DMA channel or the trigger mode. The SDK enables two different concepts for parameter setting. Either all parameters will be saved and loaded in a loadable parameter file (*.mcf) or it can be modified by a selective access with Fg_setParameter().

Initialization and configuration are described in chapter 2.

Central element of the SDK is the memory management which is described in chapter 3. It enables an acquisition with maximum speed within main memory of the PC. The memory management is completely dynamic and can be given by the system as well as by the frame grabber for further usage. In each case the defined image buffer within the PC will be devided in image packages (subbuffers) for storing image data.

The acquisition functionality of microEnable frame grabber series is explained in chapter 4. It is optimized to maximum speed also at small image sizes and very high frame rates. It allows the linear acquisition mode which transfers the images periodically into a ring buffer. Besides the linear acquisition mode, it exists a blocking mode which only overwrites an acquired image, if it has been released explicitly.

There are different possibilities to check the status of image transfer:

  • Asking for current image number
  • Waiting for a corresponding image
  • Fetching the next image

In cases that you like to send trigger signals to your camera to get images in extern or grabber controlled configured cycles, you will need to set your grabber to a special acquisition and trigger mode. How to handle it is described in chapter 5.1.

How to improve your acquisition concerning shading is described in chapter 5.2. Shading is a special preprocessing on your images.

The serial connection to a camera is implemented according to the CameraLink specification. More information about serial communication can be found in chapter 6.

Some error functions are noted in chapter 7. It lets you get an error code and a corresponding error description in case of an application problem.

Further functions are described in chapter 8. I. e. the serial number could be read out of your grabber to identify it.

Managing frame grabber events are described in chapter 9.

How to display images with some simple functions is explained in chapter 10.

Chapter 11 shows neccessary compiler settings for working with this software development kit.

An index is appended in chapter 12.




1.2 'hello world' for a free running camera

The easiest way to create a SDK example is the use of a microEnable configuration file. It can be created by the help of the Basler tool microDisplay.

1. Selection of an applet

microEnable frame grabber operates in various system configurations (area-, line-, color-, monochrome-cameras, with or without preprocessing). First, the right applet has to be created and selected before configuring special parameters. The applet has to be loaded to initialize the grabber. An overview of available applets will be displayed by starting the microDisplay program. Besides, one of several possibly available frame grabber cards can be chosen by a logical number. For each grabber which should be used for acquisition, an applet has to be loaded. The variable number must be 0 for grabber 1 and 1 for grabber 2 and so on. Please note, the same applet will be loaded for both physical ports of a Camera Link frame grabber and 4 physical ports of a GigE frame grabber ! It is not possible to load different applets for different ports of a frame grabber.

Visual Applets example: myVAdesign for the operation of a custom application based on ViusalApplets.

fg = Fg_Init("myVAdesign.hap", 0);

Acquistion Applet example: DualAreaGray for the operation of up to two monochrome area cameras.

fg = Fg_Init("DualAreaGray16.dll", 1);

2. Setting parameters

Parameters can be set concerning your specific setup (camera, trigger and so on) and concerning the features of the applet. The following example shows how to set a certain image width and height. The parameter width and height have to contain the image size in pixels.

Visual Applets example: myVAdesign for the operation of a custom application based on ViusalApplets.

Acquisition Applet example:

unsigned int width = 1024;
unsigned int height = 1024;
Fg_setParameter(fg, FG_WIDTH, &width, 1);
Fg_setParameter(fg, FG_HEIGHT, &height, 1);

3. Allocating memory

Before grabbing images, memory has to be allocated to create a frame buffer for acquisition where the images will be stored in. The frame buffer will be allocated dynamically. It is placed within main memory of your PC. You can set the number of subbuffers and calculate the buffer size. The buffer size is depending on the image format. Monochrome cameras have a format of 8bit, 10bit, 12bit, 14bit or 16bit.

dma_mem *memhdr = Fg_AllocMemEx(fg, Size, BufCnt);

4. Grabbing

The grabbing starts with:

Fg_AcquireEx(fg, DmaIndex, PicCount, 0, memhdr);

The grabbing continues until the number of PicCount is reached or with explicit call of the function Fg_stopAcquire().

5. Releasing resources

The resources have to be freed at the end of your application.

Fg_FreeMemEx(fg, memhdr);
Fg_FreeGrabber(fg);




2 Initialization and Parameterization

2.1 Overview

The microEnable Frame Grabber Series are modern frame grabber which are based on FPGA technology. It gives the user the advantage that the frame grabber can be set individually concerning different use cases by the reason of different FPGA configurations for area or line scan cameras, gray or color processing or special functions as real-time bayer correction or 2D shading functionality. The possibility in choosing neccessary functions is a central concept and is realized in software interface by choosing the corresponding FPGA functionality. Calling Fg_Init() for initializing the grabber with a special FPGA functionality library will choose the wished library and FPGA functionality and the grabber will be configured.

Each configuration is parameterizable in a big range. Typical parameters are i. e. image size, CameraLink settings or the trigger mode. The SDK enables two different concepts for parameter setting. Either all parameters will be saved (Fg_saveConfig()) and loaded (Fg_loadConfig()) in a loadable parameter file (*.mcf) or it can be modified by a selective access with Fg_setParameter().

Before using the microEnable, the frame grabber must be initialized. The initialization has to be handled by starting the program. When initializing a connection to the device, the driver will be build up and all necessary internal data structures will be initialized.

To configure the frame grabber to the current setup, either a camera parameter file (microEnable configuration file *.mcf) can be created in microDisplay and loaded by the program. Then, you would call Fg_InitConfig().Otherwise after initialization with Fg_Init(), a manual parameterization of the function Fg_setParameter() can handle the frame grabber. Fg_getParameter() or Fg_getParameterEx() informs you about special values that have been set.

After finishing the acquisition or on occurrence of errors, frame grabber resources have to be released with Fg_FreeGrabber().

Functions for initialization and configuration are following:

1. Initialization and Release of the Frame Grabber Resource

Function

Description

Fg_Init(), Fg_InitEx()

Initializing the frame grabber.

Fg_InitConfig()

Initializing the frame grabber by the help of a configuration file.

Fg_FreeGrabber()

Release of frame grabber resources.

2. Configuration of grabbing parameters

Function

Description

Fg_loadConfig()

Loading the camera configuration file.

Fg_saveConfig()

Saving the camera configuration file.

Fg_setParameter()

Setting parameters manually to the frame grabber.

Fg_getParameter()

Reading the current value of a parameter from a frame grabber.

Fg_getParameterEx()

Reading the current value of a parameter from a
frame grabber via giving additional information.




2.2 Initialization and Release

2.2.1 Initializing without Configuration File

Description

The function Fg_InitEx() initializes the frame grabber. If the initialization succeeds, an initialized pointer will be returned on data structure Fg_Struct, if not, the result is NULL.

If more than one microEnable frame grabber is available in the PC system, each hardware card will differ by a logical number, which is distributed by initialization.

Attention: Each frame grabber card will be handled uniquely by a separate data structure Fg_Struct, after initialization. The selection of frame grabbers is sorted by the increasing number of slots in the PC. Please note, that the unique ID can differ from PC to PC.

Besides, each grabber has a unique ID, the serial number which is printed on each board. It can be displayed by microDiagnosis and microDisplay. An additional possibility for identifying several grabbers is to use the function Fg_getSerialNumber() to ask for serial number via SDK.

A grabber that is initialized in "master" mode will configure the FPGA. A grabber initialized as slave will not configure the FPGA. In fact, it checks if the FPGA is already configured with the same design as requested. Not all applets and platforms support slave configurations, e.g., currently VA generated HAPs and BaseX1 applets do not support slave mode. A call to Fg_Init() is just an abbreviation for call Fg_InitEx() with 0 as last argument (i.e., master mode).

A frame grabber resource initialized by Fg_Init() or Fg_InitEx() will be released by Fg_FreeGrabber().



Syntax

Fg_Struct *Fg_Init(const char *FileName, unsigned int BoardIndex)

Fg_Struct *Fg_InitEx(const char *FileName, unsigned int BoardIndex, int isSlave)


Parameters

Parameter

Type

Description

FileName

const char*

Applet name for initialization.

BoardIndex

const unsigned int

Logical number of the board.

isSlave int if board should be opened in slave mode.


Return values

Return value

Description

pointer != NULL

Frame grabber has been initialized successfully.

NULL

Frame grabber could not be initialized correctly.
Reason for failing is a hardware or applet that hasn't been found.





2.2.2 Initializing with configuration file

Description

The function Fg_InitConfig() initializes the frame grabber and loads a parameter file (microEnable configuration file *.mcf). If the initialization succeeds, an initialized pointer will be returned on data structure Fg_Struct, if not, the result is NULL.

If more than one microEnable frame grabber is available in the PC system, each hardware card will differ by a logical number, which is distributed by initialization.

Attention: Each frame grabber card will be handled uniquely by a separate data structure Fg_Struct, after initialization. The selection of frame grabbers is sorted by the increasing number of slots in the PC. Please note, that the unique ID can differ from PC to PC.

Besides, each grabber has a unique ID, the serial number which is printed on each board. It can be displayed with microDiagnosis / microDiagnosis mE4 or microDisplay. An additional possibility for identifying several grabbers is to use the function Fg_getSerialNumber() to ask for serial number via SDK.

A frame grabber resource initialized by Fg_InitConfig() will be released by Fg_FreeGrabber().



Syntax

Fg_Struct *Fg_InitConfig(char *ConfigName, unsigned int BoardIndex)


Parameters

Parameter

Type

Description

ConfigName

char*

Applet name for initialization.

BoardIndex

int

Logical number of the board.


Return values

Return value

Description

pointer != NULL

Frame grabber has been initialized successfully.

NULL

Frame grabber could not be initialized correctly.
Reason for failing is a hardware, configuration file or applet that hasn't been found.




2.2.3 Releasing frame grabber resources

Description

The function Fg_FreeGrabber() stops the operating frame grabber and releases the resources. Also all DMA buffers allocated by Fg_AllocMem() will be released. The function Fg_FreeMem() will be executed internally. Otherwise, an allocated frame buffer by Fg_AllocMemEx() will be released. In this case, the function Fg_FreeMemEx() will be executed internally. All internal resources will be released.



Syntax

int Fg_FreeGrabber(Fg_Struct *Fg)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.


Return values

Return value

Description

FG_OK

The operating frame grabber has been stopped successfully.

FG_NOT_INIT

The frame grabber was not initialized.


2.2.4 Specific initializations according to advanced frame grabber usage


This chapter describes some special aspects when using the frame grabbers under specific cicumstances.


2.2.4.1 Master/Slave Mode


Sometimes it's reasonable, that an application controls the framegrabber from different software processes. Especially when using the functionality of Dual-Applets, which have independent processing for image data streams for each camera port, an application's architecture might be designed in this way. Too allow such a kind of software architecture in order to interact completely independent for each stream on the Framegrabber, the so called master / slave mode is created for. The following scheme shows this type of controlling the Framegrabber and the applet:

In this type of architecture, the components are having the following tasks:

  • Master:
    • Primary load of the applet (configuring the FPGA)
    • Global / Initial parametrization of the applet
  • Slave:
    • Control of acquisition on one particular image stream / processing chain on the framegrabber
    • Parametrization of the specific parameters belonging to that stream




Each box in the figure above represents a software process inside the user's application, each one holding it's own instance of the Framegrabber handle (Fg_struct) on which it interacts furtheron. Fg_InitEx() SDK function allows this type of interactivity by using the additional parameter "IsSlave". One Framegrabber handle (Fg_struct) acts as a master, while the other grabber handles are initialized in slave mode. Note, that always the same applet name has to be used in that case.

Due to this tasks, the control sequence of SDK calls looks like the following:

  1. General Initialization of the master structure by calling FG_INITEX(<AppletName>, IsSlave= false). When this call is done, the FPGA gets configured by the according data inside the applet.
  2. Initializing the slave structures by calling FG_InitEx(isSlave=true), each time using the same applet name as it was done by initializing the master and each slave before.
  3. Repeat the intialization for each slave.
  4. Do the global applet initialization by setting the according applet parameters. This is done by the SDK-function Fg_setParameter() and using the master handle.
  5. Do the slave specific initilization by calling the Fg_setParameter() function and the according slave handle.
  6. Start/Stop the acquisition on the different slaves.

Important Note: If working in master / slave mode, the initialization of the frame grabber has to be synchronized over all processes, i.e., call FG_INITEX(<AppletName>, IsSlave= false) and all calls FG_INITEX(<AppletName>, IsSlave= true) must be completed before the master and slave processes can continue with other calls of the frame grabber API like Fg_setParameter(), Fg_Acquire() etc.. A call of Fg_InitEx() without synchronization might stop a running acquisition or change a previously done parametrization of the applet on the other processes.


General remarks:

  • The master/slave mode needn't to be done from different processes, but it could.
  • Each handle has to be created by using the Fg_InitEx() function by using the same applet name
  • Only Dual-Applets are currently supporting this feature.


2.2.4.1 Using multiple frame grabbes within one system (multi- grabber systems)


High performance systems may use multiple Basler framegrabbers in one computer system. Usually multiple framegrabber of the same time are in use, but different types of framegrabber can be combined as well.

In such cases, the Basler Framegrabber SDK offers an independent access to each Framegrabber:

  • Each Framegrabber has to be initialized by a call to Fg_Init() / Fg_InitEx() function by addressing the framegrabber by using an numerical index (“boardNo”)
  • For each framegrabber an independent handle will be created by Fg_Init() / Fg_InitEx()
  • Each Framegrabber can be controlled independently (parametrization of the applet, starting an stopping the acquisition)

2.2.4.1.1 Frame grabber adressing modes

When calling the Fg_Init() function, a kind of address for the target framegrabber has to be passed to the SDK function call. This parameter is calle “Boardindex” (see declaration of Fg_Init()) and therefore the address is represented by an index (starting with 0). The indices are created from the SDK automatically in form of consecutive numbers. They can be seen, when starting the microDiagnostics application. Here the association between board indices and the board serial numbers can be seen as well.

Usually these indices are created automatically and are not necessarily linked to PCI slots of the PC. If there is a need, to influence the addressing the Framegrabber, the SDK offers some possibilities:

  • Assigning board indices according to increasing board serial numbers,

This mode is done by setting an environment variable “SISO_SORT_BOARDS_BY_SERIAL” to “1”

  • Manual assignment of indices for each board according to board serial numbers


Assigning board indices according to increasing board serial numbers,
This mode is done by setting an environment variable SISO_SORT_BOARDS_BY_SERIAL to 1

Manual assignment of indices for each board according to board serial numbers

  1. When using this mode, the assignment is read from an ASCII file named board_order.cfg
  2. The file is located at the <INSTALLDIR>\BIN directory
  3. For detailed description of the file see chapter Format of board indices configuration file

Manual assignment of indices for each board according to PCI Bus IDs

  1. When using this mode, the assignment is read from an ASCII file named board_order.cfg.
  2. The file is located at the <INSTALLDIR>\BIN directory
  3. For detailed description of the file see chapter Format of board indices configuration file


These possibilities can be used in situations, when there is a need to identify the boards in a repeatable way. When using the explicit assignment by creating the configuration file, gaps at the assignment of board indices are allowed. The manual assignment for board indices to serial numbers ca easily be done by using the MicroDiagnostics application.

Format of board indices configuration file

By using this file, the association between board indices and physical boards can be modified.

The file is a flat ASCII file, describing line by line the logical board index for the present boards.

Example 1:

sortkey = serialnumber

a4490001 = 0

a4490001 = 1


Example 2:

sortkey = pciaddress

4:0.0 = 0

3:9.0 = 1

Description:

Each line consists of the identifier for the board according to the scheme <BOARDIDENTIFIER> = <BOARDINDEX>

BOARDIDENTIFIER: this can currently be

  1. the board's serial number, which ist a 8 digit alphanumerical value
  2. the board's PCI bus identifier, which is an entry according to the format:

<PCIBusNo>, <DeviceNo>, <FunctionNo>

Example:

4:0.0 = 1

This information can be seen at the Device manager for each device.

BOARDINDEX: the numerical value for the according index (first board starting with 0), which will be used to address the board when calling the FG_INIT function.

SORTKEY: valid values are "serialnumber" and "pciaddress". The default is automatic detection according to the first entry. This entry should be at the first line of the file to indicate the type of sorting

Location of the file
The expected location is the binary directory of the SiliconSoftware Runtime installation
Filename
The filename has to be board_order.cfg


2.3 Configuration files

2.3.1 Loading a frame grabber configuration

Description

Having initialized the frame grabber, an existing camera configuration file can be loaded with the function Fg_loadConfig(). There must already be a valid pointer to frame grabber structure.

A configuration file can also be saved with Fg_saveConfig().

The extension of the microEnable configuration file is always *.mcf.



Syntax

int Fg_loadConfig(Fg_Struct *Fg, const char *Filename)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Filename

const char*

Name and path to microEnable configuration file.


Return values

Return value

Description

FG_OK

Transmission has been finished successfully.

FG_NOT_INIT

Frame grabber hasn't been initialized correctly.

FG_INVALID_FILENAME

Filename hasn't been found.

FG_INVALID_CONFIGFILE

Configuration file is invalid.




2.3.2 Saving a frame grabber configuration

Description

The frame grabber's configuration can be saved into a file by Fg_saveConfig(). Parameterization will be handled by loading this file. The frame grabber has to be initialized first!

A configuration file can also be loaded with Fg_loadConfig().

The extension of the microEnable configuration file is always *.mcf.



Syntax

int Fg_saveConfig(Fg_Struct *Fg, const char *Filename)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Filename

const char*

Name and path to the frame grabber configuration file.


Return values

Return value

Description

FG_OK

Transmission has been finished successfully.

FG_NOT_INIT

Frame grabber hasn't been initialized correctly.

FG_INVALID_FILENAME

Filename hasn't been found.




2.4 Parameter Interface of the Frame Grabber

2.4.1 Setting the Frame Grabber Parameters

Description

Each DLL, loaded by Fg_Init or Fg_InitConfig, has a set of parameters to change and control the applets operation. Each frame grabber setup has general, ever valid parameters, as described above. Moreover each frame grabber configuration has configuration dependent parameters. The number of available parameters, their names and functions are depending on the applet.

The function Fg_setParameter() enables to set a parameter value concerning a loaded applet by Fg_Init or Fg_InitConfig. The parameter values can be read with Fg_getParameter().

In some applets you could set the path to a file for shading correction or defective pixel interpolation. Therefore you would need the parameters FG_SHADING_SUBFILE0, FG_SHADING_MULTFILE0 or FG_SHADING_FPNFILE0.

The Fg_setParameterWithType() function allows to specify which type the variable passed as value has. This way you can tell the grabber library if the values is e.g. a signed or unsigned integer or if it is 32 or 64 bits wide. If you use C++ the fgrab_prototyp.h file offers some handy function overloads that omit the last parameter and automatically set the type based on the variable type passed as value.


Syntax

int Fg_setParameter(Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex)

int Fg_setParameterWithType(Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex, const enum FgParamTypes type)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter

int

As argument, a identification number is needed.
If the identification number is unknown, the parameter name has to be given.
For more information on possible parameter names, see table below ...

Value void* Pointer to required value.
DmaIndex unsigned int Logical number of used Dma port. The camera associated with the DMA port is depending on the applet. All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 is associated with PORT B and so on.
type FgParamTypes Identification of the type of the variable passed as value.


General and for each applet available parameters

Parameter Name

Values

Description

Expected
input type

Default value

FG_PORT

PORT_A = 0;
PORT_B = 1

Logical number of the used
frame grabber port.

int

0

FG_WIDTH

Applet depending [*1]

Width of the image
clipping.

int

Applet depending [*1]

FG_HEIGHT

Applet depending [*1]

Height of the image
clipping.

int

Applet depending [*1]

FG_XOFFSET

Applet depending [*1]

X-offset from the left top
corner in pixel.

int

0 pixels

FG_YOFFSET

Applet depending [*1]

Y-offset from the left top
corner in pixel.

int

0 pixels

FG_XSHIFT

Applet depending [*1]

Number of invalid words at
the beginning of a row
(in a multiplication of the
width of the interface).

int

0

FG_TIMEOUT

Applet depending [*1]

Global Timeout. Time in seconds until device
driver displays a timeout of
the frame grabber and stops the aquisition.

int

1000000s

FG_FRAMESPERSEC

Applet depending [*1]

Numbers of images per
seconds.

Double

8.0fps

FG_FORMAT

FG_GRAY = 8bit
FG_GRAY16 = 16bit;
FG_COL24 = 24bit
FG_COL32 = 32bit

Color format of
transferred image.

int

Applet depending [*1]

FG_EXPOSURE

Applet depending [*1]

Exposure depending on
f/s in µs.

int

2000µs

FG_TRIGGERMODE

FREE_RUN
GRABBER_CONTROLLED,
GRABBER_CONTROLLED_SYNC,
ASYNC_SOFTWARE_TIGGER
ASYNC_TRIGGER

Five available trigger modes.

int

FREE_RUN

FG_STROBEPULSEDELAY

0-2^10

Pulse delay in µs
for the strobe.

int

0µs

FG_GLOBAL_ACCESS Auto = 0
Read = 1,
Read Write = 3
Read Write Change = 7
Parameter for
access plausibilities.
int 0

[*1] See parameter descriptions for microEnable IV-Base x1, for microEnable IV-Full x1, for microEnable IV-Full x4.


Return Values

Return Value

Description

FG_OK

The parameter was set correctly.

FG_NOT_INIT

Initialization failed.

FG_INVALID_PARAMETER

An invalid parameter has been entered.

FG_VALUE_OUT_OF_RANGE

Value is besides valid ranges.


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error, width;
const char* str1, str2;
Fg_Struct *fg;

// Initialization of frame grabber 0
if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...

// Setting of the width of the image on 1024
width = 1024;
if(Fg_setParameter(fg, FG_WIDTH, &width,PORT_A)<0){ // CameraLink port A

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}

// Setting of the width of the image on 1024
uint32_t height = 1024;
Fg_setParameterWithType(fg, FG_WIDTH, &height, PORT_A, FG_PARAM_TYPE_UINT32_T);

...

}




2.4.2 Getting Special Parameter Settings

Description

Parameters can be read with Fg_getParameter(), Fg_getParameterWithType(), and Fg_getParameterEx(). The usage of these functions is similar to Fg_setParameter(). Again parameters are accessed by their ID or its name which can be determined in the way described above.


Syntax

int Fg_getParameter(Fg_Struct *Fg, int Parameter, void *Value, const unsigned int DmaIndex)

int Fg_getParameterWithType(Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex,
const enum FgParamTypes type)

int Fg_getParameterEx(Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter

int

As argument, a identification number is needed.
If the identification number is unknown, the parameter name has to be given.
For more information on possible parameter names, see table below ...

Value void* Pointer to required value.
DmaIndex unsigned int Logical number of used Dma port. The camera associated with the DMA port is depending on the applet. All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 is associated with PORT B and so on.

pMem

dma_mem*

Handle on memory area which has been reserved.

ImgNr

frameindex_t

Image number.


General and for each camera available parameters

Parameter Name Output type Description

FG_CAMSTAUS

int

If a camera signal is on CameraLink port value is 1 else 0.

FG_REVNR

double

Current revision version of camera DLL.

FG_TIMEOUT

int

Time in seconds until device driver displays a timeout of the frame grabber.

FG_WIDTH

int

Width of the clipping image.

FG_MAXWIDTH

int

Maximum width of the clipping image.

FG_HEIGHT

int

Height of the clipping image.

FG_MAXHEIGHT

int

Maximum height of the clipping image.

FG_XSHIFT

int

Number of invalid words at the beginning of a row
(modulo of the width of the interface).

FG_XOFFSET

int

X-offset from the left top corner in pixel.

FG_YOFFSET

int

Y-offset from the left top corner in pixel.

FG_FRAMESPERSEC

double

Number of images per second.

FG_EXPOSURE

int

Exposure time in µs.

FG_FORMAT

int

Color format of the transferred image
8bit gray (FG_GRAY)
16bit color (FG_GRAY16) or
24bit color (FG_COL24).
See color management of the according frame grabber design.

FG_PORT

int

Logical number of the active CameraLink port.

FG_PIXELDEPTH

int

Returns the depth of color of the pixel.

FG_LINEALIGNMENT

int

Returns the alignment of a line (in bits).

FG_TRANSFER_LEN

size_t

Returns the length of the last DMA transfer.

FG_TRIGGERMODE

int

Trigger modes
FREE_RUN
GRABBER_CONTROLLED
GRABBER_CONTROLLED_SYNCRON
ASYNC_SOFTWARE_TRIGGER
ASYNC_TRIGGER.

FG_STROBPULSEDELAY

int

Strobe delay to the trigger in µs.

FG_TWOCAMMODEL

int

Returns the value, if the loaded camera applet
is a dual (1) or a single applet (0).

FG_HDSYNC

double

Returns the HDSYNC value.

FG_GLOBAL_ACCESS int Returns the value for the set plausibility access.
FG_BOARD_INFORMATION uint

Information on the board type:

BINFO_BOARD_TYPE:
0xa40 for microEnable IV-Base x1
0xa41 for microEnable IV-Full x1
0xa44 for microEnable IV-Full x4

BINFO_POCL:
0 for microEnable IV-Base x1
1 for microEnable IV-Base x1 PoCL


Return Values

Return Value

Description

FG_OK

Parameter was read correctly.

FG_NOT_INIT

Initialization failed.

FG_INVALID_PARAMETER

An invalid parameter has been entered.




2.5 Parameter interface of the frame grabber (VA Applets)

Each applet (VA Applets and AcquisitionApplets), loaded by Fg_Init or Fg_InitConfig, has a set of parameters to control and change the applet fuctionality. The number of available parameters, their names and functions depend on the VA design created with VisualApplets and and the feature set of a certain Acquisition Applet, respectively. The available parameters in a VA Applet are determined by the VisualApplets operators used within the VA design.

  Please keep in mind that VA applets have a different set of parameters available compared to the AcquisitionApplets shipped with the runtime installation. To get information for the parameters available in VA applets please refer to the Visual Applets operator manual.

2.5.1 Setting frame grabber parameters (VA Applets)

Description

Each applet (VA Applets/Acquisition Applets), loaded by Fg_Init or Fg_InitConfig, has a set of parameters to change and control the applets operation. The number of available parameters, their names and functions depend on the VA design created with VisualApplets and and the feature set of a certain Acquisition Applet, respectively The available parameters in a VA Applet are determined by the VisualApplets operators used within the VA design.

Applet parameters are accessed by their ID. The ID is an integer value, which can be determined using two SDK functions. These functions are: Fg_getParameterId() and Fg_getParameterIdByName(). Having the parameter ID, enables to set the parameter value inside the applet with Fg_setParameter() or to read the parameter value with Fg_getParameter(). The number of available parameters within the applet can be determined by calling Fg_getNrOfParameter(), the name of each parameter with Fg_getParameterName().

Setting applet parameters is done with Fg_setParameter(). This function takes the Fg_Struct pointer, as it has been returned by Fg_Init or Fg_InitConfig, the parameter ID, the new value, and the associated DMA number.



Syntax

int Fg_setParameter(Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter

int

The parameter ID. Can be either the value returned by
Fg_getParameterId() or Fg_getParameterIdByName()
or the ID of a generally available parameter.

See table below for generally available parameters ...

Value
void*
Pointer to required value.
DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending
on the applet. All acquisition applets, delivered with the Silicon-Software Runtime, have
a direct mapping between DMA ports and camera ports. This means DmaIndex 0 is associated
with PORT A and DmaIndex 1 is associated with PORT B and so on.


Return values

Return value

Description

FG_OK

The parameter has been set correctly.

FG_NOT_INIT

Initialization has been failed.

FG_INVALID_PARAMETER

An invalid parameter has been entered.

FG_VALUE_OUT_OF_RANGE

The entered value is besides valid ranges.


A number of parameter IDs are already pre-defined and generally available. They can be accessed with pre-defined constants. These parameters are summarized in the following table:

General and for each design / applet available parameters

Expected
Input Type

Define

Value

Description

int
FG_FORMAT
8 = FG_BINARY = 1bit,
3 = FG_GRAY = 8bit,
1 = FG_GRAY16 = 16bit,
2 = FG_COL24 = 24bit,
5 = FG_COL30 = 30bit,
4 = FG_COL32 = 32bit,
6 = FG_COL48 = 48bit.
Pixel output format.
int
FG_GLOBAL_ACCESS
0 = auto,
1 = read,
3 = read write,
7 = read write change.
Access flag for plausibilities.

int

FG_HEIGHT

Depending on design.

Image height in pixels.

int

FG_LINEALIGNMENT

0 = MSB = right,
1 = LSB = left.

Alignment of bits for output format.

int

FG_PORT

0 = PORT_A (base config.),
1 = PORT_B (base config.),
2 = PORT_AB (medium / full config.).

Active port of the grabber.

int

FG_TIMEOUT

min: 1 sec.
max: 2,147,483,646 sec.

Time in seconds until the
device driver displays a timeout.

int
FG_WIDTH
Depending on design.
Image width in pixels




2.5.2 Getting special parameter settings (VA Applets)

Description

Parameters can be read with Fg_getParameter() and Fg_getParameterEx(). The usage of these functions is similar to Fg_setParameter(). Again parameters are accessed by their ID which can be determined in the way described above.

Syntax

int Fg_getParameter(Fg_Struct *Fg, int Parameter, void *Value, const unsigned int DmaIndex)

int Fg_getParameterEx(Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter

int

The parameter ID. Can be either the value returned by
Fg_getParameterId() or Fg_getParameterIdByName()
or the ID of a generally available parameter.

See table below for generally available parameters ...

Value
void*
Pointer to required value.
DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between DMA
ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 is associated
with PORT B and so on.

pMem

void*

Handle on memory area which has been reserved.

ImgNr

frameindex_t

Image number.


Return values

Return value

Description

FG_OK

The parameter value has been read correctly.

FG_NOT_INIT

Initialization has been failed.

FG_INVALID_PARAMETER

An invalid parameter has been entered.


In addition to the general available parameters described in Fg_setParameter() , number of read only parameters can be always accessed with Fg_getParameter() and Fg_getParameterEx(). These parameters are summarized in the following table:

General and for each design / applet available parameters

Output type
Define
Value
Description

int

FG_APPLET_REVISION

Depending.

Version number of the loaded applet.

int

FG_APPLET_VERSION

Depending.

Version number of the loaded applet.

int

FG_CAMSTATUS

0 = no camera connected to this grabber.
1 = one camera connected.
2 = two cameras connected to the board.

If no camera is connected, the result is 0.
If a camera signal is on microEnable's physical port, the result is 1.
If there are two pixel clocks recognized, the result is 2 ...

int

FG_CAMSTATUS_EXTENDED

0 = CameraClk
1 = CameraLval
2 = CameraFval
3 = CameraExsync
4 = ExTrg
5 = BufferOverflow
6 = BufStatus
7 = BufStatus

Extended information on the pixel clock from the camera, LVAL and FVAL,
as well as the ExSync signals, external trigger signals,
buffer overflow status and buffer status.

int
FG_FORMAT
8 = FG_BINARY = 1bit,
3 = FG_GRAY = 8bit,
1 = FG_GRAY16 = 16bit,
2 = FG_COL24 = 24bit,
5 = FG_COL30 = 30bit,
4 = FG_COL32 = 32bit,
6 = FG_COL48 = 48bit.
Pixel output format.
int
FG_GLOBAL_ACCESS
0 = auto,
1 = read,
3 = read write,
7 = read write change.
Access flag for plausibilities.

int

FG_HEIGHT

Depending on design.

Image height in pixels.

int
FG_IMAGE_TAG
Depending.
Tag to a corresponding image on a buffer.
The information is for reference, for lost image checks respectively.
See here for further information on this parameter.

int

FG_MAXHEIGHT

Depending on design.

Maximum image height in pixels.

int
FG_MAXWIDTH
Depending on design.
Maximum image width in pixels.

int

FG_LINEALIGNMENT

0 = MSB = right,
1 = LSB = left.

Alignment of bits for output format.

int

FG_PORT

0 = PORT_A (base config.),
1 = PORT_B (base config.),
2 = PORT_AB (medium / full config.).

Active port of the grabber.

double

FG_REVNR

Depending.

Revision number of this release version.

int

FG_TIMEOUT

min: 1 sec.
max: 2,147,483,646 sec.

Time in seconds until the device driver displays a timeout.
See here for further information on this parameter.

int
FG_TIMESTAMP
Depending.
Gets the timestamp of an image. See here for a return of an integer.
uint64
FG_TIMESTAMP_LONG
Depending.
Gets the timestamp of an image.
See here for a return of an unsigned integer 64.

size_t

FG_TRANSFER_LEN

Depending.

Returns the length of the last DMA transfer.
See here for further information on this parameter.

int
FG_WIDTH
Depending on design.
Image width in pixels.




2.5.3 Parameter ID (VA Applets)

2.5.3.1 Getting the parameter ID (VA Applets)

Description

The function Fg_getParameterId() returns the parameter ID of the parameter referenced by paramIndex. The value paramIndex is the index of the parameter. Its range is from 0 up to the value returned by Fg_getNrOfParameter().


Syntax

int Fg_getParameterId(Fg_Struct *fg, int index)


Parameter

Parameter

Type

Description

fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

index
int
Logical Parameter index.


Return values

Return value

Description

0

The parameter couldn't be found.

> 0

The parameter ID.




2.5.3.2 Parameter ID by name (VA Applets)

Description

The function Fg_getParameterIdByName() searchs for the ID of the parameter referenced by the string paramName.


Syntax

int Fg_getParameterIdByName(Fg_Struct *fg, const char *name)


Parameter

Parameter

Type

Description

fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

name
char*
Full Parameter name.


Return values

Return value

Description

0

The parameter couldn't be found.

> 0

The parameter ID.


The string "name" is the full name of the parameter. The full name of the parameters is determined by VisualApplets during Applet creation. It consists out of the process name, the module name in which the parameter has been defined, and the simple parameter name. Each part of the full name is separated by an underscore ('_'). Example: The parameter XOffset in module Buffer1 in process 0 is accessed by the full name "Process0_Buffer1_XOffset".

When hierarchical boxes are used, the name the name(s) of the boxes have to be added in front of the module name in which the parameter has been defined. Example: The parameter XOffset in module Buffer1 inside hierarchical box HBox1 in process 0 is accessed by the full name "Process0_HBox1_Buffer1_XOffset"

Important: Parameters in microEnable IV applets get an additional prefix "Device1". The full name of the above example is on a microEnable IV board is "Device1_Process0_Buffer1_XOffset". Furthermore, for PixelPlant applets the prefix changes to "Device2".

To get information about the parameters available inside the applet and their names, please use the SDK example created by VisualApplets. It contains source code to access and initialize all parameters of the applet.


2.5.4 Name of a parameter (VA Applets)

Description

The function Fg_getParameterName() informs about the name of a special parameter by index.


Syntax

char *Fg_getParameterName(Fg_Struct *fg, int index)


Parameter

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

paramIndex
int
Parameter index.


Return values

Return value

Description

char*

A char pointer to the parameter full name string.




2.5.5 Number of parameters (VA Applets)

Description

The function Fg_getNrOfParameter() returns the number of parameters available within the loaded applet.


Syntax

int Fg_getNrOfParameter(Fg_Struct *Fg)


Parameter

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.


Return values

Return value

Description

< 0

An error occured.
Use Fg_getLastErrorDescription() for more information.

> 0

The number of parameters.




3 Memory management

3.1 Overview

The memory management enables making the acquired images available with maximum speed within main memory of the PC. It is neccessary for acquiring images. The memory management is completely dynamic. There are two general modes to allocate frame buffers:

  1. User allocated frame memory: data is stored into memory locations specified by user application
  2. Grabber allocated frame memory: the frame grabber library manages the memory buffers

The first mode (often described as "user memory model") offers maximum flexibilty with the disadvantage of slightly more complicated setup.

The second mode is more constrained regarding the available memory sizes and buffers but is a bit easier to setup. This mode is sometimes called "kernel memory model" because in older versions of the framegrabber SDK (before version 4.2.18 and only using microEnable III grabbers) this memory has been allocated by the driver and was then passed to the userspace program. Since version 4.2.18 this memory is allocated by the framegrabber libraries as it has always been using microEnable IV cards. The behaviour for image grabbing and memory constraints did not change between kernel and library allocated memory.

3.1.1 Memory buffer layout

Memory buffers consist of a control structure (the so called "buffer head") which is only used for internal purposes of the grabber system and the subbuffer which receive the transferred data. The buffer head is represented by the dma_mem type used as input and output of several memory management functions. User applications should treat these objects as opaque. The subbuffers are associated with the buffer heads and can be either specified by the user application or be allocated by the frame grabber library.

The number of subbuffers and their size must be specified when the buffer head is created. All subbuffers need to be of the same size. Every subbuffer is a continuous area in the memory space of the user application. The beginning of the buffer needs to be aligned to a 4 byte boundary (32 bit). Before a DMA operation can be started all subbuffers in a buffer head must be allocated. This will automatically be taken care of with grabber allocated frame memory. For every device (i.e. physical frame grabber board) up to 256 buffer heads can be active at the same time. This limit is a driver limit and is shared by all system processes that work with this grabber device.

Buffer heads are attached to DMA channels when the DMA channel starts either explicitely using Fg_AcquireEx() or implicitely using Fg_Acquire() (see next sections for details). Once a DMA channel is started the buffer head of this channel can not be changed nor can this buffer head be used on a different DMA channel.

After each frame transfer the timestamp when this frame was received as well as the transfer length and an image tag are stored for the used subbuffer. These information can later be queried using Fg_getParameter() and Fg_getParameterEx() using the FG_IMAGE_TAG, FG_TIMESTAMP, FG_TIMESTAMP_LONG, and FG_TRANSFER_LENGTH parameters. All information stored for this subbuffer will be overwritten when the next image is stored in this subbuffer. If a DMA head is no longer attached to a DMA channel these information remain intact and can still be queried using Fg_getParameterEx().

As long as the subbuffer memory is attached to a DMA head the memory is "pinned" in memory, i.e. it cannot be swapped out. This means that it can not be used any longer by other applications or the operating system. Since the operating system as well as your application need some memory to run you can not use your complete physical memory as DMA memory. Some more memory is needed by the driver to allocate the control structures for the DMA buffer, the amount of memory depends on the number of subbuffers and their size. See the memory limits chapter for details.

Additional details about memory managment and memory usage during the acquisition process can be found at the application note "High perfromance image acquisition" .

3.1.2 Memory management functions

Function

Description

Allocation of a frame buffer (old version).

Release of a frame buffer (old version).

Allocation of a frame buffer (new version).

Release of a frame buffer (new version).

Allocation of buffer management for usage of user memory as frame buffer.

Adding user memory to frame buffer.

Deletion of user memory from frame buffer.

Release user memory control structure.




3.2 Grabber allocated frame memory

Technically grabber allocated frame memory is the same as user allocated, i.e. it is allocated more or less the same way inside the grabber library as discussed int the chapter User allocated frame memory.

For historical reasons all memory is allocated as a single continuous memory region which is later split into subbuffers, so the first byte of the second buffer follows directly after the last byte of the first buffer. A severe constraint for the amount of memory that can be allocated arises from this behaviour: there must be enough continuous memory space in the virtual address space of the user application to allow all frame memory to be allocated as a single large region. Since shared libraries, previous memory allocations, and other factors will also use the same address space inside your process this limit may be hit even if enough physical memory is available to create the requested buffer. If you cannot allocate your requested memory using grabber allocated frame memory even if you think that enough memory is available try switching to user allocated frame memory. The greatest available memory region within a processes address space can be less than 1 GB on Windows (32 bit), even if much more physical memory is installed.

You must not rely on the continous layout of the subbuffer memory as this may change in future versions of the SDK.

3.2.1 Anonymous grabber allocated frame memory

This mode moves the management of the buffer head inside the frame grabber library. Fg_AllocMem() takes an additional parameter to specify the DMA channel to which the allocated DMA head will be assigned. Afterwards you can call Fg_Acquire() instead of Fg_AcquireEx() as the memory is already assigned to the DMA channel. On the other side you can not keep this memory around while another DMA head is used with this DMA channel as this would make this memory inaccessible until the frame grabber is freed. You also cannot use most other "Ex" functions from the frame grabber library as you don't have the needed dma_mem pointer.

A memory buffer allocated with Fg_AllocMem() must be freed with Fg_FreeMem().

In general you should avoid to use these functions whereever possible. Fg_AllocMemEx() and Fg_FreeMemEx() provide much greater flexibility with very little more complexity in your application.

Fg_AllocMem() will return the pointer to the beginning of the DMA subbuffer memory as result. This is the reason for the continuous allocation of this memory mode.

3.2.1.1 Allocating a frame buffer

Description

The function Fg_AllocMem() reserves a defined area of the user memory as frame grabber memory and blocks it in the system memory. The frame buffer can be subdivided in several subbuffers.

The frame buffer is organized as a ring buffer. It means, if an image is written in the last subbuffer of the frame buffer, the next image will be transferred in the first subbuffer of the frame buffer. Existant images will be overwritten.

Allocated memory can be released with Fg_FreeMem().

Please note, that there are memory limits existing!




Syntax

void *Fg_AllocMem(Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Size

size_t

Size of all image memory in byte.

BufCnt
frameindex_t

Number of subbuffers. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the
applet. All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping
between DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and
DmaIndex 1 is associated with PORT B and so on.


Return values

Return value

Description

NULL

An error has been occured.
Use Fg_getLastErrorDescription() for more information.

void*

Pointer to a valid image buffer.




3.2.1.2 Releasing a frame buffer

Description

The function Fg_FreeMem() releases the used memory which has been allocated with Fg_AllocMem(), before. This function will fail if the DMA channel is active.

Syntax

int Fg_FreeMem(Fg_Struct *Fg, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the
applet. All acquisition applets, delivered with the Silicon-Software Runtime, have a direct
mapping between DMA ports and camera ports. This means DmaIndex 0 is associated with
PORT A and DmaIndex 1 is associated with PORT B and so on.


Return values

Return value

Description

FG_OK

Image memory has been released successfully.

FG_NOT_INIT

A failed try to release. Although, frame grabber has not been initialized correctly.

FG_STILL_ACTIVE

Transfer of an image is still active.
The transfer has to be stopped before releasing the frame grabber buffer.




3.2.2 Explicit grabber allocated frame memory

In this mode the allocation of the frame memory and subbuffers are handled by the frame grabber library in Fg_AllocMemEx() function. Afterwards the DMA head is returned and you can work as if it were user memory.

The only difference to user allocated frame memory is that you must not call Fg_FreeMemHead() to release that buffer as this would leak the subbuffer memory. A DMA head allocated by Fg_AllocMemEx() must always be freed by Fg_FreeMemEx().

3.2.2.1 Allocating a frame buffer out of several

Description

The function Fg_AllocMemEx() reserves an area of the main memory as frame buffer, blocks it and makes it available for the user. The frame buffer is organized as a ring buffer which is subdivided in several subbuffers. It is possible to allocate up to 256 different frame buffers as long as the maximum size of the configurable frame buffer is not exceeded.

The assignment between acquired images and subbuffers, which contain the images within PC memory, depends on the acquisition mode.

Allocated memory can be released with Fg_FreeMemEx() or Fg_FreeMemHead().

Please note, that there are memory limits existing!





Syntax

dma_mem *Fg_AllocMemEx(Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Size
size_t
Size of all image memory in byte.
BufCnt
frameindex_t
Number of subbuffers. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.


Return values

Return value

Description

NULL

An error has been occured.
Use Fg_getLastErrorDescription() for more information.

dma_mem*

Pointer to a valid image buffer.




3.2.2.2 Releasing frame buffers

Description

The function Fg_FreeMemEx() releases the used memory which has been reserved with Fg_AllocMemEx() before. If the acquisition and access on the memory is still active, the function can not releases the memory area and returns with an error message.



Syntax

int Fg_FreeMemEx(Fg_Struct *Fg, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

pMem
dma_mem*

Handle on memory area, which has already been reserved with
with Fg_AllocMemEx().


Return values

Return value

Description

FG_OK

Image memory has been released successfully.

FG_NOT_INIT

Frame grabber has not been initialized correctly.

FG_STILL_ACTIVE

Transfer of an image is still active.
The transfer has to be stopped before releasing the frame grabber buffer.




3.3 User allocated frame memory

3.3.1 Overview

In most cases it is helpful to use an already by the user allocated (already allocated i. e. by malloc() or new) memory area as frame buffer. Two steps are required. As first step a memory management is initialized (Fg_AllocMemHead()), which prepares the driver for usage of user memory and its size. As second step, subbuffers are added to the memory management (Fg_AddMem()). Later, they will be deleted from memory management (Fg_DelMem()). If the memory management is not necessary any longer, it will be erased by the function Fg_FreeMemHead().

Please make sure that you always check the return codes of both Fg_AllocMemHead() and Fg_AddMem(). Fg_AllocMemHead() will return a NULL pointer in case of failure, Fg_AddMem() will return an error code. If any of these functions fail starting the DMA channel later will not work. Common problems here are passing NULL pointers to Fg_AddMem() or memory ranges that are not owned by the user application.




3.3.2 Memory management settings

Description

To use an allocated user memory as frame buffer, a handle on the frame buffer must be created with the function Fg_AllocMemHead(). The image memory is organized as a ring buffer, which is subdivided in several subbuffers.

The assignment between acquired images and subbuffers, which contain the images within PC memory, depends on the acquisition mode.

Allocated memory can be released with Fg_FreeMemHead().

Please note, that there are memory limits existing!




Syntax

dma_mem *Fg_AllocMemHead(Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Size
size_t
Size of all image memory in byte.
BufCnt
frameindex_t
Number of subbuffers. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.


Return values

Return value

Description

NULL

An error has been occured.
Use Fg_getLastErrorDescription() for more information.

dma_mem*

A valid handle on frame buffer.




3.3.3 Adding user memory

Description

To use an allocated user memory as subbuffer, a handle on the frame buffer must have been created with the function Fg_AllocMemHead(), before. Then, the function Fg_AddMem() adds an allocated memory area to the frame buffer management.

The assignment between acquired images and subbuffers, which contain the images within PC memory, depends on the acquisition mode.

Please note, that there are memory limits existing!




Syntax

int Fg_AddMem(Fg_Struct *Fg, void *pBuffer, const size_t Size, const frameindex_t BufCnt, dma_mem *memHandle)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

pBuffer
void*
Pointer to user memory to be added.
Size
size_t
Size of user memory in byte.
BufCnt
frameindex_t
Index of subbuffers, the user memory should be added. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.
pMem
dma_mem*
Pointer to the handle on frame buffer.


Return values

Return value

Description

int

Index of subbuffer.

FG_INVALID_PARAMETER

An invalid parameter has been used.




3.3.4 Deleting user memory

Description

With the function Fg_DelMem() a user memory area of the image memory management can be deleted which has been created with Fg_AllocMemHead() and added with Fg_AddMem(), before. The deleted memory area won't be released. It has to be decided by the user.




Syntax

int Fg_DelMem(Fg_Struct *Fg, dma_mem *memHandle, const frameindex_t bufferIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

memhandle
dma_mem*
Pointer to the handle on frame buffer.
bufIndex
frameindex_t
Index of subbuffers, the user memory should be added to. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.


Return values

Return value

Description

FG_OK

User memory has been deleted correctly.

FG_INVALID_PARAMETER

An invalid parameter has been used.




3.3.5 Releasing memory

Description

The function Fg_FreeMemHead() releases a handle on a frame buffer that has been added with Fg_AllocMemHead(), before. If the acquisition and access to the memory is still active, the function is not able to release the memory area and returns with an error message. You do not need to explicitely remove the subbuffers before calling Fg_FreeMemHead() as this will be done automatically.




Syntax

int Fg_FreeMemHead(Fg_Struct *Fg, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

pMem
dma_mem*

Handle on memory area, which has been reserved by
Fg_AllocMemEx() or Fg_AllocMemHead().


Return values

Return value

Description

FG_OK

Handle on frame buffer has been released correctly.

FG_NOT_INIT

Frame grabber has not been initialized correctly.

FG_STILL_ACTIVE

The transmission of an image still is active.
The transmission has to be stopped first, before image memory can be released.

3.3.6 User allocated frame memory example

The error handling in this example is not complete to avoid code obfuscation. This would leak for example the memory buffers allocated by malloc().

Example

size_t buflen = 1024 * 1024;
frameindex_t bufcnt = 8;

dma_mem *head = Fg_AllocMemHead(Fg, buflen * bufcnt, bufcnt);

if (head == NULL) {
fprintf(stderr, "allocating buffer head failed: %s\n", Fg_getLastErrorDescription(Fg));
return -1;
}

for (frameindex_t i = 0; i < bufcnt; i++) {
void *newbuf = malloc(buflen);
if (Fg_AddMem(Fg, bufmem[i], buflen, i, head) != FG_OK)
return -1;
}

// now we replace the second buffer with a different one

Fg_DelMem(Fg, head, 1);

void *different_buffer = malloc(buflen);

if (Fg_AddMem(Fg, different_buffer, buflen, 1, head) < 0)

return -1;

// now acquire one image per subbuffer

Fg_AcquireEx(Fg, PORT_A, bufcnt, ACQ_STANDARD, head);

...

// get the image tag of the last image

unsigned int imageTag;
Fg_getParameterEx(Fg, FG_IMAGE_TAG, &imageTag, head, bufcnt);

// get the transfer length of the first image. This uses a different way to get that information only to show both ways.

size_t imageLen = bufcnt;
Fg_getParameterWithType(Fg, FG_TRANSFER_LEN, &imageLen, PORT_A, FG_PARAM_TYPE_SIZE_T);

// release the memory, DMA needs to be stopped at this point

Fg_FreeMemHead(Fg, head);



3.4 General Memory Limits

32 bit Operating Systems: Under standard Windows® 32 bit systems it is possible to allocate up to 1.6 GB of frame buffer per process (at minimal 2 GB main memory). Please note that the allocation depends on the available RAM and the operating system. Under a server version like, e.g., Windows® Server 2003, it is possible to allocate 2.4 GB per process.

64 bit Operating Systems: 64 bit applications don't underly the limits stated above. Successful operation has been verified on configurations with up to 32 GB main memory.

Note: With a rising number of subbuffers, the available memory will decrease because memory is needed for administative structures. It is possible to allocate up to 256 different frame buffers per grabber, as long as the sum of the frame buffers doesn't exceed the maximum size.


4 Acquisition

4.1 Overview

The microEnable acquisition functions are optimated for maximum data transfer speed. It allows the linear acquisition mode which transfers the images periodically into a ring buffer. Besides the linear acquisition mode, it exists a blocking mode which only overwrites an acquired image, if it has been released explicitly.

Besides starting and stopping the image acquisition, in this chapter the functions for checking the status of transfer are described.

The function of the grabbing control is sorted in three groups:

1. Starting and stopping the grabbing

Function

Description

Starts the image acquisition.

Stops the image acquisition.


2. The request of the current transferred image

Function

Description

Transfers an image from the frame buffer.

Returns the number of the last grabbed image.

Returns the number of the picture of the last grabbed image.
When the preselected picture is reached, the function blocks
the image grabbing.


3. Frame buffer calculation for an image number

Function

Description

Calculation of the frame buffer, according to an image number.


4. Reading and setting of the status information of the frame buffer

Function

Description

Reading of the status information of the frame buffer.

Setting of the status information of the frame buffer.




4.2 Acquisition modes

There are three different acquiring modes, which differ in the release of the acquired frame buffer. The acquiring modes are settable by Fg_AcquireEx().

  1. Default mode (ACQ_STANDARD): In this grabbing mode all subbuffers of a frame buffer are overwritten with new images as long as acquiring is active.

  2. Blocked mode (ACQ_BLOCK): In this grabbing mode an acquired image is blocked as long as it is released explicitely. In contrary to the standard mode, a blocked image will not be overwriten by the acquiring process.




4.3 Starting and stopping of image grabbing

4.3.1 Starting image grabbing

Description

The functions Fg_Acquire() and Fg_AquireEx() start a continuous grabbing. Having started, the exact number of images will be grabbed (maxPic). If a timeout occurs, the grabbing will be stopped. If a continuous grabbing with manual stopping is needed (explicit stopping of the grabbing with Fg_stopAcquire() or Fg_stopAcquireEx()), the maximum image number has to be set to GRAB_INFINITE.

In a multi DMA configuration the image grabbing can be started and stopped independently for each DMA channel.

The grabbing mode is set by a flag. You can choose between ACQ_STANDARD and ACQ_BLOCK. Is the mode ACQ_STANDARD set, the image memory is used as a ring buffer and all subbuffer will be overwritten cyclicly. Is the mode ACQ_BLOCK choosen, the acquired frame buffer is blocked as long as it is explicitely released by the user. If all subbuffers are blocked, the acquired images will be stored in an additional, optional buffer (DummyBuffer), which is not blockable. There is no unique assignment between image number and subbuffer number in this grabbing model.

Timeouts

Having started the Acquisition by using the function Fg_Acquire() or Fg_AquireEx(), the process of image grabbing runs, until a call to Fg_stopAcquire() or Fg_stopAcquireEx() is done. The grabbing process keeps on running, even if no image data is present until a certain timeout is reached. This timeout can be set individually for each grabbing process (identified by DMA channel) by using the Fg_setParameterXXX() functions. The parameter therfore is named FG_TIMEOUT and is represented by an integer value in the dimension of seconds. The default value for this parameter is 1000000 seconds. Pleases note, that this parameter (FG_TIMEOUT) has to be distinguished from the timeout when waiting for images by calling the Fg_getLastPicNrXXX(), which doesn't stop the acquisition, but indicates that within the given time the given image number hasn't been transferred to the memory/RAM.

Please note that for operation of GigE applets additional functions need to be called in order to start the grabbing at the camera's side. Please refer to the GigE SDK documentation for further information or see the SDK example for GigE Vision.



Syntax

int Fg_Acquire(Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount)

int Fg_AcquireEx(Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount, const int nFlag, dma_mem *memHandle)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
PicCount
frameindex_t

Maximum number of images to be grabbed. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.
GRAB_INFINITE, means infinite grabbing.

nFlag
int
ACQ_STANDARD, ACQ_BLOCK
memHandle
dma_mem*
Pointer to handle of frame buffer.


Return values

Return value

Description

FG_OK

Grabbing has been started correctly.
(when grabbing synchronously also finished correctly).

FG_NOT_INIT

Frame grabber has not been initialised correctly.

FG_NO_VALID_DESIGN

No valid design has been loaded.

FG_INVALID_MEMORY

Image memory has not been allocated.

FG_NOT_ENOUGH_MEMORY

Insufficient image memory has been allocated for specified image parameter.

FG_ALREADY_STARTED

Grabbing is already started and can't be started twice.

FG_INVALID_PARAMETER

An invalid parameter has been set.




4.3.2 Stopping image grabbing

Description

The function Fg_stopAcquire()and Fg_stopAcquireEx()stops the running image grabbing that has been started with Fg_Acquire() or Fg_AquireEx() respectively. In a dual grabber configuration, each port can be stopped separately. In a single grabber configuration only the active port.

The function Fg_stopAcquire() stopps the acquiring of images asynchronous, that means, running image transfer won't be finished in every case.

The function Fg_stopAcquireEx() stopps the image acquiring asynchronous or synchronous. The parameter ID indicates the stop mode and also the duration of timeout in seconds. Timeout is the maximum time, the function will wait in synchronous mode to stop the acquisition.




Syntax

int Fg_stopAcquire(Fg_Struct *Fg, const unsigned int DmaIndex)

int Fg_stopAcquireEx(Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *memHandle, const int nFlag)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 is associated
with PORT B and so on.
pMem
dma_mem*

Pointer to handle of frame buffer.

nFlag
int

Selecting stopping mode and timeout in seconds
(STOP_SYNC, STOP_ASYNC, STOP_SYNC_TO_APC) .


Return values

Return value

Description

FG_OK

Transmission has been finished successfully.

FG_NOT_INIT

Frame grabber has not been initialised correctly.

FG_TRANSFER_NOT_ACTIVE

Transmission has not been started.

FG_INVALID_PARAMETER

An invalid parameter has been set.

FG_CANNOT_STOP

The frame grabber could not been stopped.


4.3.3 Example for Non-Blocked Frame Buffer (Acquisition Applets)

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
const char* str1, str2;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...
// Starts the grabbing of 100000 pictures

if(Fg_Acquire(fg,PORT_A,100000)){

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}

}




4.3.4 Example for blocked frame buffer (Acquisition Applet)

#include <stdio.h>
#include "fgrab_Struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
const char* str1, str2;
dma_mem *pMem0;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...
// Starts the grabbing of 100000 pictures

if(Fg_AcquireEx(fg,PORT_A,100000,ACQ_BLOCK,pMem0)){

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}

}





4.4 Controlling Transfer Status

4.4.1 Default mode

4.4.1.1 Getting the image

Description

After image acquisition, the buffer number of an image can be explicitely determined by the help of the function int Fg_getImage() or Fg_getImageEx(). It is needed for blocking acquisition mode. But it can also be used for standard acquisition mode.

The first buffer has the number 0.

Depending on the parameter, the internal image counters for the last gotten image will be updated or not. A pointer to the image will be gotten by the function Fg_getImagePtr() or Fg_getImagePtrEx().




Syntax

frameindex_t Fg_getImage(Fg_Struct *Fg, const int Param, const frameindex_t PicNr, const unsigned int DmaIndex, const int Timeout)

frameindex_t Fg_getImageEx(Fg_Struct *Fg, const int Param, const frameindex_t PicNr, const unsigned int DmaIndex,
const int Timeout, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Param
int

See table below ...

PicNr
frameindex_t
0 in blocking mode, 32 bit image number on 32 bit systems, a 64 bit image number on 64 bit systems in default grabbing mode.
DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 i
s associated with PORT B and so on.
Timeout
int
Duration of timeout in seconds.
pMem
dma_mem*
Pointer to variable buffer.

Flag

Description

SEL_NEW_IMAGE

Selection of current acquired image (running process).

SEL_ACT_IMAGE

Selection of last acquired image.

SEL_NEXT_IMAGE

Selection of next image after last get image.

SEL_NUMBER

Selection of an image by image number,
not available in blocking mode!


Return values

Return value

Description

>= 0

Buffer number, beginning with 0. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

FG_TIMEOUT_ERR

Timeout occurs.

FG_INVALID_PARAMETER
This error occurs, either if the image number is <= 0 or
if the blocking mode has been chosen in case of flag SEL_NUMBER.



4.4.1.2 Requesting the current image number

4.4.1.2.1 Requesting the current image number (Non-blocking Function Call)

Description

The number of the last, completely transferred image can be requested with a non-blocking call of Fg_getLastPicNumber() or Fg_getLastPicNumberEx(). The first completely transferred image has the image number 1. An image number 0 means, that a complete image is still not transferred.

Using the user memory management, the function Fg_getLastPicNumberEx() is to be used.


Syntax

frameindex_t Fg_getLastPicNumber(Fg_Struct *Fg, const unsigned int DmaIndex)

frameindex_t Fg_getLastPicNumberEx(Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
pMem
dma_mem*
Pointer to variable buffer.


Return values

Return value

Description

= 0

Transmission is running, no image has been completely transfered, yet.

> 0
Number of the last completely transferred image, transmission is running. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

FG_TIMEOUT_ERR

An error occured.
Use Fg_getLastErrorDescription() for more information.

FG_INVALID_PARAMETER
An invalid parameter has been given to the function.


Example (Acquisition Applet)

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
const char* str1, str2;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...
// Starts the grabbing of 100000 images

if(Fg_Acquire(fg,PORT_A,100000)){

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...
frameindex_t LastPicNr;
LastPicNr = Fg_getLastPicNumber(fg,PORT_A);

}



4.4.1.2.2 Requesting The Current Image Number (Blocking Function Call)

Description

The number of the last, completely transferred image can be requested with a blocking call of Fg_getLastPicNumberBlocking() or Fg_getLastPicNumberBlockingEx(),

In contrary to Fg_getLastPicNumber() or Fg_getLastPicNumberEx() the function waits, until the transmission of the preselected image number is successfully finished or a maximum time is elapsed. If the image number is obtained before, the function returns immediately. The first image number value will be1, if no error occurs.

Attention: When working with extreme high framerates, the returned value of the function can be bigger then the preselected image number. In this case it is important to allocate enough frame buffers.




Syntax

frameindex_t Fg_getLastPicNumberBlocking(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, const int Timeout)

frameindex_t Fg_getLastPicNumberBlockingEx(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex,
const int Timeout, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

PicNr
frameindex_t

Requested image number. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
Timeout
int
Timeout in seconds.
pMem
dma_mem*
Pointer to variable buffer.


Return values

Return value

Description

> 0

Current image number, beginning with 1. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

FG_TIMEOUT_ERR
An error occured.
Use Fg_getLastErrorDescription() for more information.
FG_INVALID_PARAMETER
An invalid parameter has been given to the function.


Example (Acquisition Applets)

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error,i;
const char* str1, str2;
Fg_Struct *fg;
int nr_of_buffer,pic_size,buf_size;
frameindex_t pic_draw, pic_nr;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...

if((Fg_Acquire(fg,PORT_A,1000)) < 0){

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
....
// Blocking request of the current image transmission
while(pic_draw < 300){

pic_nr = Fg_getLastPicNumberBlocking(fg,pic_draw,PORT_A,15);
if(pic_nr<0){

Fg_FreeGrabber(fg);
return -1;

}
if(pic_draw<pic_nr){

DrawBuffer(nId0,Fg_getImagePtr(fg,pic_nr, camPort),pic_nr,"");
pic_draw=pic_nr;

}

}
....

}



4.4.2 Acquisition with blocked frame buffers

If acquistion takes place with blocked frame buffers, the images can be transferred only by the functions Fg_getImage() or Fg_getImageEx().

In this case following parameters are defined:

Flag

Description

SEL_NEW_IMAGE

Selection of current acquired image (running process).

SEL_ACT_IMAGE

Selection of last acquired image.

SEL_NEXT_IMAGE

Selection of next image after last get image.




4.5 Access on frame buffer

Description

With the function Fg_getImagePtr() or Fg_getImagePtrEx() a pointer to an image in the frame buffer is created.

Reference: The function will return only the correct image, if it still exists in the frame buffer.

Example:

Framebuffer = 2;

Fg_getImagePtr(Fg, 3, dma0) // returns a pointer of the third frame buffer;
// by the use of two frame buffers,
// the pointer to frame buffer 1 is identical with the third.


Syntax

void *Fg_getImagePtr(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex)

void *Fg_getImagePtrEx(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

PicNr
frameindex_t

Number of frame buffer or picture number. A 32 bit integer on 32 bit systems, a 64 bit number on 64 bit systems.

DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
pMem
dma_mem*
Pointer to variable buffer.


Return values

Return value

Description

void*

Pointer to current image position.


Example (Acquisition Applets)

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
const char* str1, str2, str3, str4;
Fg_Struct *fg;
frameindex_t nr_of_buffer;
size_t pic_size,buf_size;
frameindex_t pic_draw,pic_nr;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

str1=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
...

// Allocation of memory

nr_of_buffer = 2;

// Framebuffer size

pic_size = (width*height);
buf_size = pic_size * nr_of_buffer;

if((image_ptr =Fg_AllocMem(fg,buf_size,nr_of_buffer,PORT_A))==NULL){

str2=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}

// image grabbing of 1.000 pictures
pic_draw=0;

if((Fg_Acquire(fg,PORT_A,1000)) < 0){

str3=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}

fprintf(stdout,"Aufnahme gestartet\n");

while(pic_draw < 1000){

pic_nr = Fg_getLastPicNumber(fg, PORT_A);
if(pic_nr<0){

str4=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;

}
if(pic_draw<pic_nr){

// Display of the image with the function DrawBuffer
DrawBuffer(nId0,Fg_getImagePtr(fg,pic_nr, PORT_A),pic_nr,"");
pic_draw=pic_nr;

}

}

}



4.6 Status information on frame buffer

4.6.1 Reading the status of frame buffer

Description

With the functions Fg_getStatus() or Fg_getStatusEx() you are getting information about the acquisition status. The parameter data depends on the chosen flag. For details, please see tables below.

By the help of Fg_setStatus() or Fg_setStatusEx() buffers can be blocked or unblocked.




Syntax

frameindex_t Fg_getStatus(Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex)

frameindex_t Fg_getStatusEx(Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Param
int

See table below ...

Data
frameindex_t
Optional data. For carrying image counts or buffer indices, this parameter has a size of 32bit on
32 bit systems and a 64 bit on 64bit systems.
DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
pMem
dma_mem*
Pointer to variable buffer.

Param

Bedeutung

NUMBER_OF_GRABBED_IMAGES

Sum of all acquired images.
The parameter data will be ignored.

NUMBER_OF_LOST_IMAGES

Sum of lost images.
The parameter Data will be ignored.

NUMBER_OF_BLOCK_LOST_IMAGES

Sum of all images, which are lost by blocking of the frame buffer.
The parameter Data will be ignored.

NUMBER_OF_BLOCKED_IMAGES

Sum of blocked images.
The parameter Data will be ignored.

NUMBER_OF_ACT_IMAGE

Number of last acquired image.
The parameter Data requires the timeout value.

NUMBER_OF_LAST_IMAGE

Number of last get image.
The parameter Data will be ignored.

NUMBER_OF_NEXT_IMAGE

Number of next image after last get image.
The parameter Data will be ignored.

NUMBER_OF_IMAGES_IN_PROGRESS

Sum of all images which aren't gotten, yet.
The parameter Data will be ignored.

BUFFER_STATUS
1 if the buffer is locked, otherwise 0.
The parameter Data requires the image number.
GRAB_ACTIVE_X
Tells whether the commad is active (1) at the moment (otherwise 0).
The parameter Data will be ignored.


Return values

Return value

Description

frameindex_t

Return depends on given parameter, see table above ...

FG_INVALID_PARAMETER
An error occurs, if an invalid parameter has been given to the function.




4.6.2 Setting the status of frame buffer

Description

The function int Fg_setStatus() or Fg_setStatusEx() explicitely allow, blocking or releasing a blocked buffer (see table below ...).

By the help of Fg_getStatus() or Fg_getStatusEx() the acquisition status can be gotten.




Syntax

int Fg_setStatus(Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex)

int Fg_setStatusEx(Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex, dma_mem *pMem)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Param
int

See table below ...

Data
frameindex_t
Optional data. For carrying image counts or buffer indices, this parameter has a size of 32bit on
32 bit systems and a 64 bit on 64bit systems.
DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.
pMem
dma_mem*
Pointer to variable buffer.

Parameter

Bedeutung

FG_UNBLOCK_ALL

Explicite release of all buffers.

FG_UNBLOCK

Explicite release of one buffer.

FG_BLOCK

Release of one blocking buffer.

FG_PULSE_NEXT_BUFFER

Switch to the next buffer in ACQ_PULSE mode.


Return values

Return value

Description

FG_OK

The operation succeeded

FG_INVALID_PARAMETER
Error occurs, if an invalid parameter has been given to the function.

Example (VA Applets)

#include <stdio.h>

#include <stdlib.h>

#include "os_type.h"

#include "vasFgProject.h"

// ---------------------------------------------------------------------------

int main () {

// ---------------------------------------------------------------------------

Fg_Struct* fg = Fg_Init("DualGrayAreaBase.hap",0);

...

// ---------------------------------------------------------------------------

int id0 = CreateDisplay(8 * byteWidth0, width0, height0);

SetBufferWidth(id0, width0, height0);

// ---------------------------------------------------------------------------

frameindex_t maxPic = 10;

i = Fg_AcquireEx(fg, 0, maxPic ACQ_BLOCK, pmem0);

...

// ---------------------------------------------------------------------------

for(i = 1;i<=maxPic;i++){

...

int status;

status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);

if(status <0){

fprintf(stdout,"Error: %d\n",status);

} else {

fprintf(stdout,"grabbed image %d\n",status);

};

void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);

DrawBuffer(id0,iPtr0,i,0);

}

// ---------------------------------------------------------------------------

fprintf(stdout,"Releasing buffer no.: %d\n",i);

Fg_setStatusEx(fg, FG_UNBLOCK, i, 0, pmem0);

// ---------------------------------------------------------------------------

Fg_stopAcquireEx(fg,0,pmem0,0);

Fg_FreeGrabber(fg);

return (0);

}




4.6.3 Reading The Image Tag Information

Description

By using the generic function Fg_getParameter() or Fg_getParameterEx() with the define FG_IMAGE_TAG as parameter, you can get the image tag of a buffer for reference. You can use the information for lost image checks if you compare it to the image number. Please note, that the image tag begins with 0, but the image number begins with 1.

The Fg_getParameterEx() version has slightly less overhead but can only be used if you have the direct handle to the DMA control structure for the used memory, i.e. you created your memory using Fg_AllocMemEx() or Fg_AllocMemHead().




Syntax

unsigned int imageTag;

imageTag = bufNum;
int Fg_getParameterEx(Fg_Struct *Fg, FG_IMAGE_TAG, &imageTag, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)

imageTag = bufNum;
int Fg_getParameter(Fg_Struct *Fg, FG_IMAGE_TAG, &imageTag, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter
int

Parameter defines FG_IMAGE_TAG.

imageTag [*1]
int
Input: Buffer number.
Output: Image tag.
DmaIndex
unsigned int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.

[*1]Important: This parameter is used as input and as output when using Fg_getParameter().




4.6.4 Reading The DMA Transfer Length

Description

By using the generic function Fg_getParameter() or Fg_getParameterEx() with the define FG_TRANSFER_LEN as parameter, you can get the DMA transfer length of an image of the buffer. It can be used for lost data checks in case of buffer overflows, in example.


Syntax

size_t dmaLength;

dmaLength = bufNum;
int Fg_getParameterEx(Fg_Struct *Fg, FG_TRANSFER_LEN, &dmaLength, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)

dmaLength = bufNum;
int Fg_getParameter(Fg_Struct *Fg, FG_TRANSFER_LEN, &dmaLength, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter
int

Parameter defines FG_TRANSFER_LEN.

dmaLength [*1]
size_t
Input: Buffer number.
Output:Transfer length.
DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.

[*1] Important: This parameter is used as input and as output when using Fg_getParameter().




4.6.5 Reading The Time Stamp As Integer

Description

By using the generic function Fg_getParameter() or Fg_getParameterEx() with the define FG_TIMESTAMP as parameter, you can get the timestamp of an image buffer in microseconds as an integer value.




Syntax

unsigned int timeStamp;

timeStamp = bufNum;
int Fg_getParameterEx(Fg_Struct *Fg, FG_TIMESTAMP, &timeStamp, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)

timeStamp = bufNum;
int Fg_getParameter(Fg_Struct *Fg, FG_TIMESTAMP, &timeStamp, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Parameter
int

Parameter defines FG_TIMESTAMP.

timeStamp (1)
unsigned int
Input: Buffer number.
Output: Time stamp.
DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.

(1) Important: This parameter is used as input and as output when using Fg_getParameter().




4.6.6 Reading The Time Stamp As 64 Bit Integerd

Description

By using the generic function Fg_getParameter() or Fg_getParameterEx() with the define FG_TIMESTAMP_LONG as parameter, you can get the timestamp of an image of the buffer as a 64 bit integer value. It is a high-performance query counter and related to Microsoft's query performance counter for Windows®.


Syntax

uint64_t timeStamp;

timeStampLong = bufNum;
int Fg_getParameterEx(Fg_Struct *Fg, FG_TIMESTAMP_LONG, &timeStamp, const unsigned int DmaIndex, dma_mem *pMem,
const frameindex_t ImgNr)

timeStampLong = bufNum;
int Fg_getParameter(Fg_Struct *Fg, FG_TIMESTAMP_LONG, &timeStampLong, const unsigned int DmaIndex)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

flag
int

Parameter defines FG_TIMESTAMP_LONG.

timeStampLong (1)
uint64_t
Input: Buffer number.
Output: Query performance counter.
DmaIndex
int
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
is associated with PORT B and so on.

(1) Important: This parameter is used as input and as output when using Fg_getParameter().




4.7 Settings during acquisition

Special care has to be taken about settings that will be done during acquisition. In some cases it is affordable to deactivate some parameters, in other cases it is affordable to stop the acquisition.

For changing the values width or height i. e., it is affordable to stop the acquisition, before and restart it again, afterwards.

For exposure time settings, the ExsyncEnable parameter must be deactivated, before and activated again, afterwards.




4.8 Timeout configuration

Description

The acquisition can automatically be interrupted after a time, which can be setup. This helps to identify require a wrong parameterization or defect cable connection to the camera. The timeout settings can be individually parameterised for each camera port and are indicated in seconds. The timeout setting is adjustable be the parameter function Fg_setParameter().




Parameter

Values

Description

Expected
input type

Default value

FG_TIMEOUT

2-2ˆ31

Time until a running grabbing
transmission is stopped;
unit in seconds.

int

1000000


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting of the TIMEOUTS in seconds
int nTimeoutInSekunden = 15;
Fg_setParameter(fg,FG_TIMEOUT,&nTimeoutInSekunden, camPort);

}



4.9 Sequence Recording

Description

Using high framerates and small image sizes it is desirable to grab a complete sequence.

If the image grabbing is started with exactly the same number of images, which are available in the frame buffer, a sequence of up to 1.000.000 images can be recorded and temporarily stored.




4.10 Access On Pixel Data

Description

In some cases it is neccessary to get access on acquired pixel data. It is possible to work with the data of each single pixel.

The function Fg_getImagePtr() returns a pointer to the first value of a long array. The content of this array is depending on the output format that you choose (GRAY, GRAY16, COL24, ...).

If you like to get access on the array byte for byte, you can cast the returned pointer:
unsigned char *bytePtr = (unsigned char*)Fg_getImagePtr();

If you are using the FG_GRAY format:
bytePtr[0] // first pixel
bytePtr[1] // second pixel
...

If you are using the format FG_COL24:
bytePtr[0] // first pixel blue component
bytePtr[1] // first pixel green component
bytePtr[2] // first pixel red component

bytePtr[3] // second pixel blue component
bytePtr[4] // second pixel green component
bytePtr[5] // second pixel red component
...

If you want to work with FG_GRAY16 or FG_COL48 you should use a unsigned short pointer.




5 Features

5.1 Operation modes of the trigger system

For an optimal adaptation in industrial operation, microEnable offers four trigger modes and a special synchronizing mode. For hardware understanding, please take a look at following documents: microEnable III, TTL trigger for microEnable III, opto trigger for microEnable III, microEnable IV with CameraLink interface, microEnable IV with GigabitEthernet interface, TTL trigger for microEnable IV or opto trigger for microEnable IV. Moreover, we have an additional documentation for understanding the trigger system.

Please note, that using VisualApplets for generating a VA Applet allows to create custom trigger functions. Therefor the section 5.1.3 describes only in short possible base configurations and how it is controlled via the SDK.

5.1.1 Overview

Default trigger configuration is Free Run. In this operation mode, the camera works self sufficient and doesn't need any trigger signal. The speed of the image grabbing is defined by the camera. See image below ...

In the operation mode Grabber Controlled Mode, the frame grabber defines the speed of image grabbing. The grabber controls the camera with the signal image trigger which will be transfered over CC signals via CameraLink interface to the camera. With this function the grabber controls the frequency, the pulse width as well as the polarity. See image below ...

In operation mode External Trigger the grabbing of images is controlled by an external signal (i.e. a light barrier). One edge of the trigger signal initiates an image trigger and hereby the grabbing of an image. Synchronously a pulse is generated, optionally delayed by software, for using i.e. as impulse for strobe control. The external signal has to be connected to a trigger module and generates a trigger signal for the camera which will be transfered over CC signals via CameraLink to the camera. With this function the grabber controls the pulse width as well as the polarity. See image below ...

The operation mode Softwaretrigger works similar to the External Trigger. In this case, grabbing images is not initiated by an external signal, but by a software access. The camera works external triggered. However, the grabber defines trigger signals which are transfered over CC signals via CameraLink to acquire images. The trigger signals are sent to camera via software access by the user. With this function the grabber controls the frequency, the pulse width as well as the polarity. See image below ...

The trigger modes Free Run, Grabber Controlled and Softwaretrigger can be realized with a single VisualApplets operator. Therefore, the setting handling under the SDK is nearly identical. Just some parameters are differing in their values, but the parameters itself are the same.

In External Trigger Mode the realization within VisualApplets is completely different. There is not only one operator, but several. That's the reason for several different settings that have to be done for aquisition in External Trigger Mode. It will be shown some chapters later.

The following sections contains one description and example for realizing a certain trigger mode based on Acquisition Applets and based on VA Applets.




5.1.2 Using Trigger Modes Based On AcquisitionApplets

5.1.2.1 Free Run Mode

Description

The configuration of the operation mode of the frame grabber on Free Run is made by the parametric function Fg_setParameter(). The operation mode can be configured separately for each CameraLink port.

Parameter

Value

Description

Expected
input type

Default value

FG_TRIGGERMODE

FREE_RUN

Setting of the operation mode of
the frame grabber on Free Run.

int

FREE_RUN


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting of the operation mode
int trigger_mode = FREE_RUN;

if(Fg_setParameter(fg, FG_TRIGGERMODE, &trigger_mode, camPort)<0){

...

}

}




5.1.2.2 Acquisition is Controlled by the Frame Grabber - Grabber Controlled Mode

5.1.2.2.1 Grabber Controlled Mode for one Camera Port

Description

In the operation mode Grabber Controlled mode, the frame grabber defines the speed of image grabbing. The grabber controls the camera with the signal image trigger which will be transfered over CC signals via CameraLink interface to the camera. With this function the grabber controls the frequency, the pulse width as well as the polarity.

The configuration of the operation mode of the frame grabber on Grabber Controlled is made by the parametric function Fg_setParameter(). In this case, the trigger mode, the time of exposure and the framerate is to be set.

The operation mode can be configured separately for each CameraLink port.

Parameter

Value

Description

Expected
input type

Default value

FG_TRIGGERMODE

GRABBER_CONTROLED

Setting of the operation mode
of the frame grabber on
Grabber Controlled.

int

FREE_RUN

FG_EXPOSURE

Applet depending [*1]

Setting of the exposure
time in µs.

int

2000µs

FG_FRAMESPERSEC

Applet depending [*1]

Setting of the framerate.

double

8.0fps


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting the operation mode
int trigger_mode = GRABBER_CONTROLLED;

if(Fg_setParameter(fg, FG_TRIGGERMODE, &trigger_mode, camPort)<0){

Fg_Error();
return error;

}

if(Fg_setParameter(fg, FG_EXPOSURE, &nExposureInMicroSec, camPort)<0){

Fg_Error();
return error;

}
if(Fg_setParameter(fg, FG_FRAMESPERSEC, &dFps, camPort)<0){

Fg_Error();
return error;

}

}




5.1.2.2.2 Grabber Controlled Synchron for Two Cameras

Description

In the operation mode Grabber Controlled Synchron mode, the frame grabber defines the speed of image grabbing for both ports synchronously. The grabber controls the camera with the signal image trigger which will be transfered over CC signals via CameraLink interface to the camera. With this function the grabber controls the frequency, the pulse width as well as the polarity.

The configuration of the operation mode of the frame grabber on Grabber Controlled Synchron is made by the parametric function Fg_setParameter(). In this case, the trigger mode, the time of exposure and the framerate have to be set.

Attention: The operation mode can be configured only for CameraLink port A. CameraLink port B works in slave mode and doesn't need to be parametrizised.

Parameter

Value

Description

Expected
input type

Default value

FG_TRIGGERMODE

GRABBER_CONTROLED_SYNCHRON

Setting of the operation mode
of the frame grabber on
Grabber Controlled Synchon.

int

FREE_RUN

FG_EXPOSURE

Applet depending [*1]

Setting of the exposure
time in µs.

int

2000µs

FG_FRAMESPERSEC

Applet depending [*1]

Setting of the framerate.

double

8.0fps


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting of the operation mode
int trigger_mode = GRABBER_CONTROLLED;

if(Fg_setParameter(fg, FG_TRIGGERMODE, &trigger_mode, camPort)<0){

Fg_Error();
return error;

}

if(Fg_setParameter(fg, FG_EXPOSURE, &nExposureInMicroSec, camPort)<0){

Fg_Error();
return error;

}
if(Fg_setParameter(fg, FG_FRAMESPERSEC, &dFps, camPort)<0){

Fg_Error();
return error;

}

}




5.1.2.3 Acquisition is Triggered by Software - Software Trigger Mode

Description

The operation mode Softwaretrigger operates similar to the External Trigger. In this case the grabbing of the images is not initiated by an external signal, but by a software access. The camera operates external triggered. However, the grabber defines trigger signals which are transfered over CC signals via CameraLink to acquire images. The trigger signals are sent to camera via software access by the user. The call of the function Fg_sendSoftwareTrigger() initiates immediately a single trigger signal to the camera.

Two different Softwaretrigger modes exist: SoftwareTrigger and SoftwareTriggerQueued. In SoftwareTrigger mode after sending a trigger a busy will be returned until complete frame is transfered from camera onto frame grabber. A new trigger to the camera can not be sent before busy isn't set. In SoftwareTriggerQueued mode it is possible to add several triggers to the queue. Triggers in queue will be processed as soon as possible.

The specific Softwaretrigger mode is activated by the parametric function Fg_setParameter() via parameter FG_TRIGGERMODE. In this case, the trigger mode and the time of exposure have to be set. The frame grabber controls the length and the polarity of the trigger signal to camera. Three different ways exist to send a software trigger to the camera.

  • Fg_sendSoftwareTrigger (send a single pulse)
  • Fg_sendSoftwareTriggerEx (possibility to send multiple pulses)
  • Via parameter FG_SENDSOFTWARETRIGGER

The operation mode can be configured separately for each CameraLink port.

Parameter

Value

Description

Expected
input type

Default value

FG_TRIGGERMODE

ASYNC_SOFTWARE_TRIGGER

ASYNC_SOFTWARE_TRIGGER_QUEUED

Setting of the operation mode
of the frame grabber on
software trigger.

int

FREE_RUN

FG_EXPOSURE

Applet depending [*1]

Setting of the exposure
time in µs.

int

2000µs


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if ((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL) {

// error handling

}

// Setting of the operation mode
int trigger_mode = ASYNC_SOFTWARE_TRIGGER;
if (Fg_setParameter(fg, FG_TRIGGERMODE, &trigger_mode, camPort) < 0) {

// error handling

}

// set width of trigger signal to camera
if(Fg_setParameter(fg, FG_EXPOSURE, &nExposureInMicroSec, camPort)<0){

// error handling

}

// Generates a software trigger
if (Fg_sendSoftwareTrigger(fg, PORT_A) {

// error handling

}

}




5.1.2.4 Acquisition is Controlled by External Signal - External Trigger

Description

In the operation mode External Trigger the grabbing of images is controlled by an external signal (i.e. a light barrier). At the edge of the trigger signal an image trigger will be initiated and hereby the grabbing of an image. Synchronously, a pulse will be generated, optionally delayed by software, for using as impulse for strobe control e. g. The external signal has to be connected to a trigger module and generates a trigger signal for the camera which will be transfered over CC signals via CameraLink to the camera. With this function the grabber controls the pulse width as well as the polarity.

The configuration of the operation mode of the frame grabber on External Trigger is made by the parametric function Fg_setParameter(). In this case, the trigger mode and the time of exposure have to be set.

The operation mode can be configured separately for each CameraLink port.

Parameter

Value

Description

Expected
input type

Default value

FG_TRIGGERMODE

ASYNC_TRIGGER

The operation mode of
the frame grabber is set
on External Trigger.

int

FREE_RUN

FG_EXPOSURE

Applet depending [*1]

The exposure time in µs is set.

int

2000µs

FG_TRIGGERINSRC

0-3 in case of TTL trigger board,
0-7 in case of opto trigger board

The channel of the trigger
input signal is selectable.

int

0

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting of the operation mode
int trigger_mode = ASYNC_TRIGGER;

if(Fg_setParameter(fg, FG_TRIGGERMODE, &trigger_mode, camPort)<0){

Fg_Error();
return error;

}
if(Fg_setParameter(fg, FG_EXPOSURE, &nExposureInMicroSec, camPort)<0){

Fg_Error();
return error;

}
if(Fg_setParameter(fg, FG_TRIGGERINSRC, &nTrgSource, camPort)<0){

Fg_Error();
return error;

}

}




5.1.2.5 Strobe

5.1.2.5.1 Setting the Exposure Time

Description

For controlling the values of the exposure time in a larger scale, the image trigger signal is generated with a configurable prescaler, which is also used as line trigger (see trigger manual). The resolution of the prescaler is configurable.


Parameter

Value

Description

Expected
input type

Default value

FG_PRESCALER,
FG_LINETRIGGERTIME

Applet depending [*1]

Configuration of the
granularity of the exposure
time, respectively
the line trigger time.

int

0




5.1.2.5.2 Strobe Delay

Description

In the operation mode Softwaretrigger and External Trigger, a signal for flash light controlling is generated, which is deduced by the trigger signal. This signal is set with delay.

Attention: The resolution of the flash light signal depends on the values of the prescaler, which is configurable as parameter FG_PRESCALER in µs by using the function Fg_setParameter().

See also

Resolution exposure time

Parameter

Value

Description

Expected
input type

Default value

FG_STROBEPULSDELAY

Applet depending [*1]

Flash light will be delayed
for the chosen value
in microseconds.

int

0µs


Example

#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"

int main(){

int error;
char* str;
Fg_Struct *fg;

// Initialization of frame grabber 0

if((fg = Fg_Init("DualAreaGray16.dll",0)) == NULL){

...

}

// Setting of flash light delay in µs
Fg_setParameter(fg,FG_STROBEPULSEDELAY,&nStrobePulseDelayInMicroSec, camPort);

}




5.1.2.5.3 Activating and Deactivating the Strobe

Description

The function int Fg_setFlash() explicitly allows a switch to on and off of the strobe signal. The parameter name FG_ON activates the strobe signal, FG_OFF deactivates it.


Syntax

int Fg_setFlash(Fg_Struct *Fg, int Flag, const unsigned int CamPort)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Flag int Activate the strobe signal with the FG_ON (ID = 1)
or deactivate it with FG_OFF (ID = 0).
CamPort int Logical number of used CameraLink port.
CameraLink port A = 0 and CameraLink port B = 1.


Return Values

Return Value

Description

FG_INVALID_PARAMETER

An invalid parameter has been set.

FG_OK

The function finished correctly.




5.1.2.6 Activating and Deactivating the Exsync

Description

The function int Fg_setExsync() explicitly allows a switch to on and off of the exsync signal to the camera. The parameter name FG_ON activates the exsync signal, FG_OFF deactivates it.


Syntax

int Fg_setExsync(Fg_Struct *Fg, int Flag, const unsigned int CamPort)


Parameters

Parameter

Type

Description

Fg

Fg_Struct*

Pointer to frame grabber structure Fg_Struct.

Flag int Activate the exsync signal with FG_ON (ID = 1)
or deactivate it with FG_OFF (ID = 0.
CamPort int Logical number of used CameraLink port.
CameraLink port A = 0 and CameraLink port B = 1.


Return Values

Return Value

Description

FG_INVALID_PARAMETER

An invalid parameter has been set.

FG_OK

The function finished correctly.




5.1.3 Using Trigger Modes Based On VA Applets

5.1.3.1 FreeRun mode

Description

The operation mode configuration FreeRun can be set by the parametric function Fg_setParameter(). The operation mode must be configured separately for each DMA. It is affordable that the camera is in FreeRun mode, too.

Basis for the following example code is the VisualApplets example DualGrayAreaBase.va (see VisualApplets installation ../examples)

Example

#include <stdio.h>

#include <stdlib.h>

#include "os_type.h"

#include "vasFgProject.h"

// ---------------------------------------------------------------------------

int main () {

// ---------------------------------------------------------------------------

Fg_Struct* fg = Fg_Init("DualGrayAreaBase.hap",0);

...

// ---------------------------------------------------------------------------

int id0 = CreateDisplay(8 * byteWidth0, width0, height0);

SetBufferWidth(id0, width0, height0);

int id1 = CreateDisplay(8 * byteWidth1, width1, height1);

SetBufferWidth(id1, width1, height1);

// ---------------------------------------------------------------------------

i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);

...

i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);

...

// ---------------------------------------------------------------------------

for(i = 1;i<=100;i++){

...

frameindex_t status;

status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);

...

status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);

...

void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);

DrawBuffer(id0,iPtr0,i,0);

void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);

DrawBuffer(id1,iPtr1,i,0);

}

// ---------------------------------------------------------------------------

Fg_stopAcquireEx(fg,0,pmem0,0);

Fg_stopAcquireEx(fg,1,pmem1,0);

Fg_FreeGrabber(fg);

return (0);

}




5.1.3.2 Acquisition is controlled by the frame grabber - Grabber controlled mode

Description

In the operation mode Grabber Controlled Mode, the frame grabber defines the speed of image grabbing. The grabber controls the camera with the signal image trigger which will be transfered over CC signals via CameraLink interface to the camera. With this function the grabber controls the frequency, the pulse width as well as the polarity.

Basis for the following example code is the VisualApplets example DualGrayAreaBase.va (see VisualApplets installation ../examples)

Example

#include <stdio.h>

#include <stdlib.h>

#include "os_type.h"

#include "vasFgProject.h"

// ---------------------------------------------------------------------------

int main () {

// ---------------------------------------------------------------------------

Fg_Struct* fg = Fg_Init("DualGrayAreaBase.hap",0);

...

int timeout = 5;

Fg_setParameter(fg, FG_TIMEOUT, &timeout, 0);

/*============ TrgPortArea : Trigger ============== */

...

Device1_Process0_Trigger_TriggerMode = TrgPortArea::ExternSw_Trigger;

Fg_setParameter(fg, Device1_Process0_Trigger_TriggerMode_Id, &Device1_Process0_Trigger_TriggerMode, 0);

...

Device1_Process0_Trigger_ExsyncEnable = TrgPortArea::ON;

Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncEnable_Id, &Device1_Process0_Trigger_ExsyncEnable, 0);

...

Device1_Process0_Trigger_SoftwareTrgPulse = 1;

Fg_setParameter(fg, Device1_Process0_Trigger_SoftwareTrgPulse_Id, &Device1_Process0_Trigger_SoftwareTrgPulse, 0);

...

Device1_Process0_Trigger_ImgTrgInSource = TrgPortArea::SoftwareTrigger;

Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInSource_Id, &Device1_Process0_Trigger_ImgTrgInSource, 0);

...

Device1_Process0_Trigger_ImgTrgInPolarity = TrgPortArea::HighActive;

Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInPolarity_Id, &Device1_Process0_Trigger_ImgTrgInPolarity, 0);

...

Device1_Process0_Trigger_ExsyncFramesPerSec = 8;

Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncFramesPerSec_Id, &Device1_Process0_Trigger_ExsyncFramesPerSec, 0);

...

Device1_Process0_Trigger_ExsyncExposure = 4000;

Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncExposure_Id, &Device1_Process0_Trigger_ExsyncExposure, 0);

...

Device1_Process0_Trigger_ExsyncPolarity = TrgPortArea::LowActive;

Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncPolarity_Id, &Device1_Process0_Trigger_ExsyncPolarity, 0);

...

// ---------------------------------------------------------------------------

int id0 = CreateDisplay(8 * byteWidth0, width0, height0);

SetBufferWidth(id0, width0, height0);

int id1 = CreateDisplay(8 * byteWidth1, width1, height1);

SetBufferWidth(id1, width1, height1);

// ---------------------------------------------------------------------------

i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);

...

i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);

...

// ---------------------------------------------------------------------------

for(i = 1;i<=100;i++){

...

frameindex_t status;

status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);

...

status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);

...

void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);

DrawBuffer(id0,iPtr0,i,0);

void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);

DrawBuffer(id1,iPtr1,i,0);

}

// ---------------------------------------------------------------------------

Fg_stopAcquireEx(fg,0,pmem0,0);

Fg_stopAcquireEx(fg,1,pmem1,0);

Fg_FreeGrabber(fg);

return (0);

}




5.1.3.3 Acquisition is controlled by external signal - External trigger

Description

In operation mode External Trigger (external trigger) the grabbing of images is controlled by an external signal (i.e. a light barrier). One edge of the trigger signal initiates an image trigger and hereby the grabbing of an image. Synchronously a pulse is generated, optionally delayed by software, for using i.e. as impulse for strobe control. The external signal has to be connected to a trigger module and generates a trigger signal for the camera which will be transfered over CC signals via CameraLink to the camera. With this function the grabber controls the pulse width as well as the polarity.

Basis for the following example code is the VisualApplets example BasicExternalTrigger.va (see VisualApplets installation ../examples)

Example

#include <stdio.h>

#include <stdlib.h>

#include "os_type.h"

#include "vasFgProject.h"

// ---------------------------------------------------------------------------

int main () {

// ---------------------------------------------------------------------------

Fg_Struct* fg = Fg_Init("BasicExternalTrigger.hap",0);

...

/*============ Polarity : Invert ============== */

...

Process0_Invert_Invert = Polarity::Invert;

Fg_setParameter(fg, Process0_Invert_Invert_Id, &Process0_Invert_Invert, 0);

/*============ SignalWidth : Width ============== */

...

Process0_Width_Width = 2000000;

Fg_setParameter(fg, Process0_Width_Width_Id, &Process0_Width_Width, 0);

/*============ Select : SelectInput ============== */

...

Process0_SelectInput_Select = 0;

Fg_setParameter(fg, Process0_SelectInput_Select_Id, &Process0_SelectInput_Select, 0);

/*============ SignalDebounce : Debounce ============== */

...

Process0_Debounce_Debounce = 40;

Fg_setParameter(fg, Process0_Debounce_Debounce_Id, &Process0_Debounce_Debounce, 0);

...

// ---------------------------------------------------------------------------

int id0 = CreateDisplay(8 * byteWidth0, width0, height0);

SetBufferWidth(id0, width0, height0);

int id1 = CreateDisplay(8 * byteWidth1, width1, height1);

SetBufferWidth(id1, width1, height1);

// ---------------------------------------------------------------------------

i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);

...

i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);

...

// ---------------------------------------------------------------------------

for(i = 1;i<=100;i++){

...

frameindex_t status;

status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);

...

status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);

...

void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);

DrawBuffer(id0,iPtr0,i,0);

void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);

DrawBuffer(id1,iPtr1,i,0);

}

// ---------------------------------------------------------------------------

Fg_stopAcquireEx(fg,0,pmem0,0);

Fg_stopAcquireEx(fg,1,pmem1,0);

Fg_FreeGrabber(fg);

return (0);

}




5.1.3.4 Acquisition is triggered by software - Software trigger mode

Description

The operation mode Softwaretrigger works similar to the External Trigger. In this case the image grabbing is not initiated by an external signal, but by a software access. The camera workes external triggered. However, the grabber defines trigger signals which are transfered over CC signals via CameraLink to acquire images. The trigger signals are sent to camera via software access by the user. With a function the grabber controls the frequency, the pulse width as well as the polarity.

The operation mode configuration to SoftwareTrigger mode is made by the parametric function Fg_setParameter(). In this case, the trigger mode and the time of exposure have to be set. With this function the grabber controls the pulse width as well as the polarity. Please note, that the trigger mode is set first. Otherwise, some parameters aren't accessable.

The operation mode can be configured separately for each DMA channel.

Minimum settings step by step (using VisualApplets)

  1. Developing a design with VisualApplets (i.e. based on the example DualGrayAreaBase.va) and synthesizing it to an applet.
  2. Opening the SDK example which has been created during synthesis.
  3. Changing the settings and adding some new functions to the example as follows:
    • Checking the FG_TIMEOUT value
    • Setting the TriggerMode to ExternSw_Trigger
    • Activating the ExsyncEnable
    • Activating the SoftwareTrgPulse
    • Changing the ImgTrgInSource to SoftwareTrigger
  • Checking the ImgTrgInPolarity if neccessary
  • Starting the acquisition
  • Sending SoftwareTrgPulse as much as you like and at any time you like

    Example

    #include <stdio.h>

    #include <stdlib.h>

    #include "os_type.h"

    #include "vasFgProject.h"

    // ---------------------------------------------------------------------------

    int main () {

    // ---------------------------------------------------------------------------

    Fg_Struct* fg = Fg_Init("myFirstTrigger.hap",0);

    ...

    int timeout = 5;

    Fg_setParameter(fg, FG_TIMEOUT, &timeout, 0);

    /*============ TrgPortArea : Trigger ============== */

    ...

    Device1_Process0_Trigger_TriggerMode = TrgPortArea::ExternSw_Trigger;

    Fg_setParameter(fg, Device1_Process0_Trigger_TriggerMode_Id, &Device1_Process0_Trigger_TriggerMode, 0);

    ...

    Device1_Process0_Trigger_ExsyncEnable = TrgPortArea::ON;

    Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncEnable_Id, &Device1_Process0_Trigger_ExsyncEnable, 0);

    ...

    Device1_Process0_Trigger_SoftwareTrgPulse = 1;

    Fg_setParameter(fg, Device1_Process0_Trigger_SoftwareTrgPulse_Id, &Device1_Process0_Trigger_SoftwareTrgPulse, 0);

    ...

    Device1_Process0_Trigger_ImgTrgInSource = TrgPortArea::SoftwareTrigger;

    Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInSource_Id, &Device1_Process0_Trigger_ImgTrgInSource, 0);

    ...

    Device1_Process0_Trigger_ImgTrgInPolarity = TrgPortArea::HighActive;

    Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInPolarity_Id, &Device1_Process0_Trigger_ImgTrgInPolarity, 0);

    ...

    Device1_Process0_Trigger_ExsyncPolarity = TrgPortArea::LowActive;

    Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncPolarity_Id, &Device1_Process0_Trigger_ExsyncPolarity, 0);

    ...

    // ---------------------------------------------------------------------------

    int id0 = CreateDisplay(8 * byteWidth0, width0, height0);

    SetBufferWidth(id0, width0, height0);

    int id1 = CreateDisplay(8 * byteWidth1, width1, height1);

    SetBufferWidth(id1, width1, height1);

    // ---------------------------------------------------------------------------

    i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);

    ...

    i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);

    ...

    // ---------------------------------------------------------------------------

    for(i = 1;i<=100;i++){

    ...

    Device1_Process0_Trigger_SoftwareTrgPulse = 1;

    Fg_setParameter(fg,Device1_Process0_Trigger_SoftwareTrgPulse_Id,&Device1_Process0_Trigger_SoftwareTrgPulse,0);

    ...

    Device1_Process1_Trigger_SoftwareTrgPulse = 1;

    Fg_setParameter(fg,Device1_Process1_Trigger_SoftwareTrgPulse_Id,&Device1_Process1_Trigger_SoftwareTrgPulse,0);

    ...

    frameindex_t status;

    status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);

    ...

    status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);

    ...

    void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);

    DrawBuffer(id0,iPtr0,i,0);

    void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);

    DrawBuffer(id1,iPtr1,i,0);

    ...

    Device1_Process0_Trigger_SoftwareTrgPulse = 1;

    Fg_setParameter(fg,Device1_Process0_Trigger_SoftwareTrgPulse_Id,&Device1_Process0_Trigger_SoftwareTrgPulse,0);

    ...

    Device1_Process1_Trigger_SoftwareTrgPulse = 1;

    Fg_setParameter(fg,Device1_Process1_Trigger_SoftwareTrgPulse_Id,&Device1_Process1_Trigger_SoftwareTrgPulse,0);

    }

    // ---------------------------------------------------------------------------

    Fg_stopAcquireEx(fg,0,pmem0,0);

    Fg_stopAcquireEx(fg,1,pmem1,0);

    Fg_FreeGrabber(fg);

    return (0);

    }




    5.2 Coprocessor Functionality (only unseable in the context of VisualApplets)

    Description

    The function Fg_sendImage() or Fg_sendImageEx() transmits images to the microEnable framegabber. It is affordable for coprocessor purposes.


    Syntax

    int Fg_sendImage(Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex)

    int Fg_sendImageEx(Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex, dma_mem *memHandle)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    startImage
    frameindex_t
    The first image that should be sent.
    PicCount
    frameindex_t
    Number of images to be sent.
    nFlag
    int
    ACQ_STANDARD, ACQ_BLOCK, ACQ_PULSE
    DmaIndex
    unsigned int
    Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
    All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between
    DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1
    is associated with PORT B and so on.
    memHandle
    dma_mem *
    Pointer to frame buffer handle.


    Return values

    Return value

    Description

    FG_OK

    Grabbing has been started correctly.
    (when grabbing synchronously also finished correctly).

    FG_NOT_INIT

    Frame grabber was not initialised correctly.

    FG_NO_VALID_DESIGN

    No valid design was loaded.

    FG_INVALID_MEMORY

    Image memory was not allocated.

    FG_NOT_ENOUGH_MEMORY

    Insufficient image memory was allocated for specified image parameter.

    FG_ALREADY_STARTED

    Grabbing is already started and can’t be started twice.

    FG_INVALID_PARAMETER

    Invalid parameter is set.




    5.3 Shading Interface with Defective Pixel Interpolation (AcquisitonApplets)

    5.3.1 Overview

    The shading feature allows the allocation and the release of buffers, getting access to it and settings the maximum lines that have to be corrected, the setting of subtraction, multiplication and noise correction values, the writing of the corrected lines and the ending of the access to the buffer. These functions will be shown in the following overview.

    For more information on how the shading correction works, please take a look at the shading application note.


    1. Allocating and freeing some buffer

    Function

    Description

    Fg_AllocShading()

    Allocate some buffer.

    Fg_FreeShading()

    Free the allocated buffer.


    2. Access to shading functionality

    Function

    Description

    Shad_GetAccess()

    Enables the access to the shading functionality.

    Shad_FreeAccess()

    Closes the access to the shading functionality.


    3. Getting information about the maximum lines

    Function

    Description

    Shad_GetMaxLine()

    Getting the maximum lines of the
    image which has to be corrected.


    4. Setting the substration, multiplication and noise correction values

    Function

    Description

    Shad_SetSubValueLine()

    To set the substraction values.

    Shad_SetMultValueLine()

    To set the multiplication values.

    Shad_SetFixedPatternNoiseLine()

    To set the noise correction values
    with the help of a fixed pattern.
    Fixed Pattern Noise Correction is also known
    as Defective Pixel Interpolation.


    5. Freeing the access to the allocated buffer and writing the currently corrected line

    Function

    Description

    Shad_WriteActLine()

    Writing the currently corrected line.




    5.3.2 Allocating Buffer for Shading Feature

    Description

    Before using the shading functionality, it is neccessary to allocate some buffer for shading calculation. Fg_AllocShading() is the first function to be used for complete shading feature.


    Syntax

    void* Fg_AllocShading(Fg_Struct *Fg, int dataSet, int CamPort)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    set int

    Parameter set which can be dynamically chosen out of 4.
    Each set can have different shading parameters.
    Therefore, switching between sets is very easy.

    CamPort int

    Logical number of used CameraLink port.
    CameraLink port A = 0 and CameraLink port B = 1.


    Return Values

    Return Value

    Description

    void*

    Buffer allocation succeeded.

    NULL Buffer allocation failed.




    5.3.3 Freeing Buffer

    Description

    Freeing the buffer that has been allocated before (with Fg_AllocShading()) for the shading feature can be done with Fg_FreeShading().


    Syntax

    int Fg_FreeShading(Fg_Struct *Fg, void *sh)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.


    Return Values

    Return Value

    Description

    0

    Freeing the buffer succeeded.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.3.4 Getting Access to Shading Interface

    Description

    Before using the shading interface, it is neccessary to activate the access with Shad_GetAccess(). In detail, the registers on your grabber will be prepared for shading. Afterwards, the interface can be closed with Shad_FreeAccess().


    Syntax

    int Shad_GetAccess(Fg_Struct *Fg, void *sh)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.


    Return Values

    Return Value

    Description

    0

    Access has been activated successfully.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.3.5 Closing the Access

    Description

    After opening the access to the shading interface and after working with the shading feature, the shading interface can be closed with Shad_FreeAccess().


    Syntax

    int Shad_FreeAccess(Fg_Struct *Fg, void *sh)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.


    Return Values

    Return Value

    Description

    0

    Access has been closed successfully.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.3.6 Getting the Line Number of the Current Image

    Description

    Before shading calculation for the current image can be done, the line number has to be known. Shad_GetMaxLine() returns with that information.


    Syntax

    int Shad_GetMaxLine(Fg_Struct *Fg, void *sh)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.


    Return Values

    Return Value

    Description

    >= 0

    Line number of the current image.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.3.7 Setting Parameters for Shading Calculation and Defective Pixel Interpolation

    Description

    Before shading calculation can be done, some parameters have to be set. Shad_SetSubValueLine() sets parameters for the offset (subtractive correction). Shad_SetMultValueLine() sets parameters for the gain (multiplicative correction). Shad_SetFixedPatternNoiseLine() sets parameters for the defective pixel interpolation.

    Besides frame grabber structure and handle on shading interface, the position in line, the color channel and either subtraction, multiplication or switch value has to be set.

    You can either manually set values for shading with the functions listed below or you can otherwise set a path to a file for defective pixel interpolation, subtraction or multiplication calculation. Therefore you need the function FG_setParameter() together with the parameters FG_SHADING_SUBFILE0, FG_SHADING_MULTFILE0 or FG_SHADING_FPNFILE0.


    Syntax

    int Shad_SetSubValueLine (Fg_Struct *Fg, void *sh, int x, int channel, float sub)

    int Shad_SetMultValueLine(Fg_Struct *Fg, void *sh, int x, int channel, float mult)

    int Shad_SetFixedPatternNoiseLine(Fg_Struct *Fg, void *sh, int x, int channel, int on)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.
    x int Position in a line.
    channel int Color channel which has to be used.
    In monochrome applets: Gray = 0.
    In color scale applets: Red = 0, Green = 1, Blue = 2.
    sub float

    Shading correction calculation with subtraction value.
    The value can be between 0 and 1.

    mult float

    Shading correction calculation with multiplication value.
    The value can be between 0 and 8.

    on int Enabling or disabling the noise correction.


    Return Values

    Return Value

    Description

    0

    Parameters has been set successfully.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.3.8 Writing the Currently Corrected Line

    Description

    The currently corrected line can be written with Shad_WriteActLine().


    Syntax

    int Shad_WriteActLine(Fg_Struct *Fg, void *sh, int Line)


    Parameters

    Parameter

    Type

    Description

    Fg

    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    sh void* Handle on shading interface.
    Line int Line number which currently has to be corrected.


    Return Values

    Return Value

    Description

    0

    Currently corrected line has been written successfully.

    FG_INVALID_PARAMETER An invalid parameter has been used.




    5.4 PixelPlant

    PixelPlant applets does not work with the hardware on its own. It is neccessary to merge a PixelPlant design together with a microEnable IV design within VisualApplets. Only then, the resulting applet can be used for microEnable IV with PixelPlant. Please note, that the applet must have been merged. Then, the merged applet can be loaded under microDisplay or under the SDK.




    6 Asynchronous Grabbing (APC)

    The Silicion Software Framegrabber SDK offers the possibility for an event driven development by using the so called asynchronous procedure call methods (APC). As a result, the APC interfaces is an alternative approach of getting images by polling the images buffers. In case of newly grabbed images, the client application gets informed by this interface. This notification is done by a callback mechanism (callback function). Additional settings are availabe for defining the behaviour in detail.

    The APC-interface consists of a set of elements, which are shown in the following table:

    Elements

    Description

    Fg_registerApcHandler

    Method for registering / unregistering a callback functions for notifications

    Fg_ApcFunc_t

    Data type of the function pointer for the callback function

    FgApcControl

    Data type for the specific APC setup information




    6.1 Registering a callback handler

    The first step of using the interface is the registration of a callback functions / callback handler(see Fg_registerApcHandler), that gets called by the SDK when new images are available. This registration stays valid, as long as the image acquisition is running. When the acquistion stops (either manual by calling the Fg_StopAcquire or automatically), the callback gets unregistered implicitly. This behaviour can be influenced by an according flag at the setup control structure (FgApcControl), to keep a handler registered permanently.

    Important note: only one APC handler per DMA channel can be registered at the same time.



    6.2 Callback notifications

    As mentioned above, each time when a new image is available, the notification is done by calling the currently registerd callback. This notification is done for each image or for multiple images depending on an according flag at the setup structure (FgApcControl).

    The callback handler passes client data, which has been declared during the setup (FgApcControl::data). It is possible to stop the notification by passing a non-zeor value as a return value fo the callback function.



    6.3 Termination of APC / Stopping the acquisition

    When the acquisition is stopped, the APC notification is stopped as well, even if there are images pending (default behavour).

    To get a synchronisation between the concurrently running procedure of stopping acquisition on one side and on terminating APC handlers on the other side, a specific flag at the Fg_StopAcquireEx() method is available (STOP_SYNC_TO_APC). In this case, the Fg_StopAcquire() waits a predefined timeout, until it returns. This timeout can be set by the Fg_SetParameter function (Parameter: FG_APC_STOP_TIMEOUT).

    The Fg_StopAcquire waits at maximum of the defined timeout for a currently processed callback. If the callback returns before the timeout is exceeded, the Fg_stopAcquire() returns synchronously to the callback. The return value indicates, wether the timeout is elapsed or not (see images below).

    Pending image notifications get processed furtherly, until the timeout is reached. An additional control flag at the APC setup structure has to be set therefore (see image "Situation 3" below.


    Situation 1: Predefined timeout is not elapsed, when waiting for a pending APC

    Situation 2: Predefined timeout is elapsed, when waiting for a pendig APC

    Situation 3: Fg_StopAcquire waits for all multiple images to be processed

    7 Serial interface (CL and LVDS frame grabber)

    Please follow this link to get to a detailled description of serial interface over CameraLink including SDK functionality.



    8 Error functions

    8.1 Description of last error message

    Description

    With the function Fg_getLastErrorDescription() the last occurred error will be displayed as error message.


    Syntax

    const char *Fg_getLastErrorDescription(Fg_Struct *Fg)


    Parameters

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.


    Return values

    Return value

    Description

    char*

    Returns the last error that occurred.

    Example (VA Applets)

    #include <stdio.h>
    #include "fgrab_struct.h"
    #include "fgrab_prototyp.h"
    #include "fgrab_define.h"

    int main(){

    int error;
    const char* str;
    Fg_Struct *fg;

    // Initialization of frame grabber 0

    if((fg = Fg_Init("myVADesign.hap",0)) == NULL){

    str=Fg_getLastErrorDescription(fg);
    error=Fg_getLastErrorNumber(fg);
    fprintf(stdout,"Init Error(%d): %s\n",error,str);
    return 0;

    }
    ...

    }




    8.2 Getting the last error code

    Description

    The function Fg_getLastErrorNumber() displays the error code of last occurred fault.


    Syntax

    int Fg_getLastErrorNumber(Fg_Struct *Fg)


    Parameters

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.


    Return values

    Return value

    Description

    int

    Returns the last error that occurred.


    Example (VA Applets)

    #include <stdio.h>
    #include "fgrab_Struct.h"
    #include "fgrab_prototyp.h"
    #include "fgrab_define.h"

    int main(){

    int error;
    const char* str;
    Fg_Struct *fg;

    // Initialization of frame grabber 0

    if((fg = Fg_Init("myVADesign.hap",0)) == NULL){

    str=Fg_getLastErrorDescription(fg);
    error=Fg_getLastErrorNumber(fg);
    fprintf(stdout,"Init Error(%d): %s\n",error,str);
    return 0;

    }
    ...

    }




    8.3 Obtaining Error Messages From Error Codes

    Description

    The function Fg_getErrorDescription() displays the error message, when receiving the error code.


    Syntax

    const char* Fg_getErrorDescription(Fg_Struct *Fg, int errorNumber)


    Parameters

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    errorNumber
    int
    Identification number of error code.


    Return values

    Return value

    Description

    char*

    Error message of a special error code.


    Example

    #include <stdio.h>
    #include "fgrab_struct.h"
    #include "fgrab_prototyp.h"
    #include "fgrab_define.h"

    int main(){

    int error;
    const char* str;
    Fg_Struct *fg;

    // Initialization of frame grabber 0

    if((fg = Fg_Init("myVADesign.hap",0)) == NULL){

    str=Fg_getLastErrorDescription(fg);
    error=Fg_getLastErrorNumber(fg);
    fprintf(stdout,"Init Error(%d): %s\n",error,str);
    return 0;

    }

    fprintf(stdout,"Errorcode -2001 Errordescription=%s\n", Fg_getErrorDescription(fg,-2001));

    ...

    }




    8.4 Error Messages

    Fault value

    Fault text

    Description

    1

    FG_INIT_OK

    Initialization successfully finished.

    0

    FG_OK

    No error occured.

    -1

    FG_ERROR / FG_DUMMY_BUFFER

    A non-specific internal error is occuring.

    -2
    FG_NO_PICTURE_AVAILABLE
    At the moment, an image is not available.

    -10

    FG_ALR_INIT

    Frame grabber is already initialized.

    -20
    FG_NO_BOARD_AVAILABLE
    There is no board available that could get initialized.
    -21
    FG_INVALID_BOARD_NUMBER
    The given board number is invalid.
    -22
    FG_BOARD_INIT_FAILED
    Board couldn't get initialized.
    -26
    FG_INVALID_DESIGN_NAME
    The given design name is not valid.
    -28
    FG_RESSOURCES_STILL_IN_USE
    Resources are already in use by the SDK
    / microDisplay or microDiagnosis.
    -50
    FG_WRONG_ARCHITECTURE
    The architecture doesn't fit.

    -60

    FG_SOFTWARE_TRIGGER_BUSY

    It is not possible to send a software trigger.

    -100

    FG_HAP_FILE_NOT_LOAD

    The specified hap file could not be loaded.

    -110

    FG_MICROENABLE_NOT_INIT

    microEnable could not be initialized.

    -120

    FG_DLL_NOT_LOAD

    The specified frame grabber DLL cannot be found.

    -121
    FG_REG_KEY_NOT_FOUND
    The registration key cannot be found.
    -122
    FG_VASDLL_NOT_LOAD
    The vas.dll couldn't be loaded.
    -300
    FG_PTR_INVALID
    The given pointer is not valid.
    -400
    FG_RANGE_ERR
    The given value is not in range.
    -500
    FG_NOT_ENOUGH_MEM
    There is not enough memory available.
    -600
    FG_DMATRANSFER_INVALID
    The DMA transfer is not valid.
    -700
    FG_HAP_FILE_DONT_MATCH
    The applet doesn't fit to the hardware.

    -2001

    FG_NOT_INIT

    Frame grabber structure is not initialized.

    -2003
    FG_LIB_UNLOAD_FAIL
    Unloading the library failed.

    -2010

    FG_WRONG_NUMBER_OF_BUFFER

    Invalid number of subbuffers has been specified.

    -2011

    FG_TOO_MANY_BUFFER

    More buffers than allowed have been tried to select.

    -2020

    FG_NOT_ENOUGH_MEMORY

    Not enough memory available or allocated to do the operation.

    -2024

    FG_MEMORY_ALREADY_ALLOCATED

    Memory already is allocated and has not been released.

    -2026
    FG_CANNOT_WRITE_MEM_CONFIG_FAILED
    Writing the memory configuration failed.

    -2030

    FG_INTERNAL_STATUS_ERROR

    A non-specific internal error is occuring.

    -2031

    FG_INTERNAL_ERROR

    A non-specific internal error is occuring.

    -2040

    FG_CANNOT_START

    Image grabbing cannot be started by the frame grabber.

    -2042

    FG_CANNOT_STOP

    Image grabbing cannot be stopped by the frame grabber.

    -2045
    FG_SYNC_ACQUIRE_NOT_SUPPORTED
    Synchroneous acquisition is not supported.

    -2050

    FG_INVALID_DESIGN

    No valid design is selected during configuration of frame grabber.

    -2052

    FG_CONFIGURE_FAILED

    Configuration of frame grabber failed.

    -2053

    FG_RECONFIGURE_FAILED

    Reconfiguration of frame grabber failed.

    -2055

    FG_NO_APPLET_ID

    No applet in frame grabber DLL found for specified value.

    -2056

    FG_APPLET_NOT_IN_LIST

    No applet in frame grabber DLL found for specified applet name.

    -2060

    FG_INVALID_MEMORY

    No frame buffer is allocated.

    -2070

    FG_INVALID_PARAMETER

    An invalid parameter have been tried to set.

    -2075
    FG_INVALID_VALUE
    The given value is not valid.

    -2076

    FG_INVALID_FILENAME

    An invalid configuration file name has been specified.

    -2080

    FG_NOT_LOAD

    Specified configuration cannot be loaded.

    -2090

    FG_ALREADY_STARTED

    The image grabbing is already started and cannot be started once more.

    -2100

    FG_STILL_ACTIVE

    The frame grabber is still busy during image transmission.

    -2110

    FG_NO_VALID_DESIGN

    No valid design has been tried to load.

    -2120

    FG_TIMEOUT_ERR

    A timeout error is occuring.

    -2130
    FG_NOT_IMPLEMENTED
    It is not implemented what you're asking for.
    Please contact Basler.

    -2140

    FG_NOT_WRONG_TRIGGER_MODE

    A wrong trigger mode has been tried to set.

    -2150
    FG_ALL_BUFFER_BLOCKED
    All available buffers are still blocked.
    -3000
    FG_CANNOT_INIT_MICROENABLE
    Initializing the microEnable failed.

    -3010

    FG_TRANSFER_NOT_ACTIVE

    Data transfer is not active.

    -3120
    FG_CLOCK_NOT_LOCKED
    The clock hasn't been locked.

    -5000

    FG_INVALID_CONFIGFILE

    An incorrect configuration file has been tried to load.

    -6000

    FG_VALUE_OUT_OF_RANGE

    The selected value is out of range.

    -7000
    FG_CANNOT_CHANGE_DISPLAY_WIDTH
    Display width cannot be changed.
    -7005
    FG_CANNOT_CHANGE_DISPLAY_HEIGHT
    Display height cannot be changed.
    -7010
    FG_CANNOT_CHANGE_DISPLAY_SIZE
    Display size cannot be changed.
    -7020
    FG_NO_VALID_LICENSE
    The entered license code or the license file is incorrect.
    -7030
    FG_CANNOT_CHANGE_CAMERA_FORMAT
    The camera format cannot be changed.
    -7040
    FG_INVALID_REGISTER
    The register is not existing.
    -7050
    FG_REGISTER_INIT_FAILED
    The register update failed.
    -7060
    FG_INVALID_SHADING_CORRECTION_FILE
    The loaded file for shading correction is invalid.
    -7070
    FG_WRITE_LINE_SHADING_TIMEOUT
    A timeout is occuring during line shading calculation.
    -7080
    FG_INVALID_MODULO
    The entered value is not able to be calculated
    with the corresponding modulo value
    concerning the specified parameter.
    -7090
    FG_CANNOT_CHANGE_DURING_ACQU
    During acquisition coresponding parameter cannot be changed.
    -8000
    FG_TOKEN_NOT_FOUND_ERROR
    The entered token cannot be found.
    -8010
    FG_WRITE_ACCESS_DENIED
    Write access on coresponding register is denied.




    9 Further Functions For Information Retrieval

    9.1 Software Version Number

    Description

    The function Fg_getSWVersion() returns the runtime version of the SDK running.


    Syntax

    const char* Fg_getSWVersion()


    Return values

    Return value

    Description

    const char*

    Runtime version of the SDK running, i. e. "5.0"




    9.2 Board Type

    Description

    Fg_getBoardType() returns the type of board: If it is a microEnable III / -XXL or microEnable IV-Full x1 / -Full x4. PixelPlant is not able to be detected at the moment.


    Syntax

    int Fg_getBoardType(int BoardIndex)


    Parameters

    Parameter

    Type

    Description

    BoardIndex
    int

    Logical number of the board.


    Return values

    Return value

    Description

    int

    Board type:
    0xA30 -> microEnable III
    0xA31 -> microEnable III-XXL
    0xA41 -> microEnable IV-Full x1
    0xA44 -> microEnable IV-Full x4




    9.3 Serial Number

    Description

    The function Fg_getSerialNumber() reads the serial number of the frame grabber.


    Syntax

    unsigned int Fg_getSerialNumber(Fg_Struct *Fg)


    Parameters

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.


    Return values

    Return value

    Description

    unsigned int

    Hexadecimal value in 32bit which represents the serial number of the board.


    Example

    #include <stdio.h>
    #include "fgrab_Struct.h"
    #include "fgrab_prototyp.h"
    #include "fgrab_define.h"

    int main(){

    int error;
    const char* str;
    Fg_Struct *fg;

    // Initialization of frame grabber 0

    if((fg = Fg_Init("myVADesign.hap",0)) == NULL){

    str=Fg_getLastErrorDescription(fg);
    error=Fg_getLastErrorNumber(fg);
    fprintf(stdout,"Init Error(%d): %s\n",error,str);
    return 0;

    }
    fprintf(stdout,"Serial number of frame grabber %x\n",Fg_getSerialNumber(fg));
    ...

    }


    9.4 Applet ID

    Description

    The function Fg_getAppletId() returns the applet ID. The applet name can be chosen, but is not neccessary.


    Syntax

    int Fg_getAppletId(Fg_Struct *Fg, char* Appletname)


    Parameter (VA Applets)

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    Appletname
    char*
    Applet name, if known.


    Parameter (Acquisition Applets)

    Parameter

    Type

    Description

    Fg Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    AppletId int // BASE X1

    DUAL_AREA_GRAY16_ME4BASEX1 -> 0xa400010
    DUAL_AREA_RGB48_ME4BASEX1 -> 0xa400020
    DUAL_LINE_GRAY16_ME4BASEX1 -> 0xa400030
    DUAL_LINE_RGB48_ME4BASEX1 -> 0xa400040
    MEDIUM_AREA_GRAY16_ME4BASEX1 -> 0xa400050
    MEDIUM_AREA_RGB36_ME4BASEX1 -> 0xa400060
    MEDIUM_LINE_GRAY16_ME4BASEX1 -> 0xa400070
    MEDIUM_LINE_RGB36_ME4BASEX1 -> 0xa400080

    // FULL X1

    DUAL_AREA_BAYER12_ME4FULLX1 -> 0xa410010
    DUAL_AREA_GRAY16_ME4FULLX1 -> 0xa410020
    DUAL_AREA_RGB48_ME4FULLX1 -> 0xa410030
    DUAL_LINE_GRAY16_ME4FULLX1 -> 0xa410040
    DUAL_LINE_RGB30_ME4FULLX1 -> 0xa410050
    FULL_AREA_GRAY8_ME4FULLX1 -> 0xa410060
    FULL_LINE_GRAY8_ME4FULLX1 -> 0xa410070
    MEDIUM_AREA_GRAY16_ME4FULLX1 -> 0xa410080
    MEDIUM_AREA_RGB36_ME4FULLX1 -> 0xa410090
    MEDIUM_LINE_GRAY16_ME4FULLX1 -> 0xa4100a0
    MEDIUM_LINE_RGB36_ME4FULLX1 -> 0xa4100b0
    SINGLE_AREA_BAYERHQ_ME4FULLX1 -> 0xa4100c0
    SINGLE_AREA_GRAY2DSHADING_ME4FULLX1 -> 0xa4100d0

    // FULL X1

    // GigE

    Return values

    Return value

    Description

    int

    AppletId in hexadecimal value as shown above.




    9.5 Applet Version

    Description

    The function Fg_getAppletVersion() returns the version number to the given applet ID.


    Syntax

    const char* Fg_getAppletVersion(Fg_Struct *Fg, int AppletID)


    Parameter

    Parameter

    Type

    Description

    Fg
    Fg_Struct*

    Pointer to frame grabber structure Fg_Struct.

    AppletID
    int
    ID of the corresponding applet.


    Return values

    Return value

    Description

    const char*

    Applet version concerning the given applet ID.





    9.6 Global Write Access Flag

    Description

    The parameter FG_GLOBAL_ACCESS allows the user to define the access right to all the parameters. FG_GLOBAL_ACCESS can be set using the standard Fg_setParameter() function. The following values are valid:

    Auto = 0 (default)
    The access rights are defined automatically by the software for each parameter depending on the state of the frame grabber.

    Read = 1
    All the parameters except FG_GLOBAL_ACCESS are in "read only" mode.

    Read Write = 3
    All the parameters can be read and write. The write is not allowed during the acquisition.

    Read Write Change = 7
    All the parameters can be read and write.

    Important: The mode "Read Write Change = 7" must be used carefully. In this mode changing some parameters during the acquisition could put the frame grabber in an unstable state. It is highly advised to stay in the "Auto = 0" mode.




    9.7 Using The Type ENUM

    Description

    The generated SDK project contains one namespace per operator type. This namespace contains the “enum” definition of each “enum” parameter.

    The type ENUM can be used within SDK as following example describes:

    the module “CameraGrayAreaBase” will generate the following namespace in header file:

    namespace CameraGrayAreaBase {
    enum UseDval {DVAL_Enabled=1,DVAL_Disabled=0};
    enum Format {SingleTap8Bit=0,SingleTap10Bit=1,SingleTap12Bit=2,SingleTap14Bit=3,SingleTap16Bit=4,DualTap8Bit=5,DualTap10Bit=6,DualTap12Bit=7};
    };

    The user can use this enums like this:

    int value = CameraGrayAreaBase::DVAL_Enabled;
    Fg_setParameter(fg, Process0_modul4_Format_Id,&value, dmaNo);




    10 Event Management

    10.1 Event system

    The SDK enables an application to get notifications about certain state changes at the data flow from camera to RAM and the image processing as well. Typical events are for example detection of new images at certain points of the image processing chain, detected external signals at the framegrabber or error conditions occurred during at the image processing and transport steps. Therefore a specific subsystem is available called the event subsystem. The following graphic demonstrates this in a schematic way based on the data flow of images from camera to RAM:

    As this graphic illustrates, the set of available events (types) depends on the type of processing (applet) and the hardware (framegrabber) itselt. To get a complete list of event present at a certain combination of applet and framegrabber, please consult the the applet documentation.

    The event subsystem itself consists of a set of API functions for:

    • querying available events (type of events)

    • controlling event notifications

    • getting event notifications

    Following functions are available for event management:

    Function

    Description

    Get the event mask by name.

    Get the name of the event by mask

    Activate a specific event or a group of events.

    Clear previously raised events.

    Blocking wait for a specific event or a group of events.

    Register a callback for asynchrous event notification
    for a specific event or group of events.

    10.2 Query available events

    In general, the events at the events subsystem are identified by their event names in form of strings, which are unique within one applet, but my vary among the set of applets. Please consult the applet documentation for getting the corresponding names. Having the name of a certain event, the corresponding bitmask of this event can be retrieve from the SDK by using the

    Fg_getEventMask
    method, which has to be used furtheron to access this event, either for activation or for getting the according notification.


    10.3 Example: List of camera link protocoll based events

    The following table shows the events based on camera link protocol. These events are supported by the following frame grabber models: microEnable IV AD4-CL/-PoCL, microEnable IV AD4-LVDS, and microEnable IV VD4-CL/-PoCL.

    Event

    Description

    CamPortATransferStart

    Rising edge of signal FVAL on CameraLink Port A. Supported in Base, Medium and Full area applets. Event generation doesn't depend on image acquisition.

    CamPortATransferEnd

    Falling edge of signal FVAL on CameraLink Port A. Supported in Base, Medium and Full area applets. Event generation doesn't depend on image acquisition.

    CamPortBTransferStart

    Rising edge of signal FVAL on CameraLink Port A. Supported in Base area applets. Event generation doesn't depend on image acquisition.

    CamPortBTransferEnd

    Falling edge of signal FVAL on CameraLink Port A. Supported in Base area applets. Event generation doesn't depend on image acquisition.

    A rising or falling edge of the Frame Valid signal (FVAL) indicates the start repectively the end of an image transfer between camera and frame grabber.


    10.4 Controlling event notifications

    The event system is in an idle state until the events are activated. For activation of the event, the corresponding bit mask as described at the previous chapter it needed. For enabling the event notification, the

    Fg_activeEvents
    method

    can be used. Take note, that this function is used for disabling the event notification as well. The activation of the event can be done either event by event or for groups of events in one call. The corresponding bit masks have to be ore’d in that case.

    It’s recommended to cleanup the currently present events at the image processing chain by using the Fg_clearEvents method to ensure, that pending no events caused by previous processing are notified.


    10.5 Event notification

    If a situation at the processing and transport chain is changed, so that the corresponding event should be raised, the application gets a signal from the event subsystem. To react on this state change, the application either can:

    • wait until this happens synchronously by using the Fg_eventWait method or

    • react asynchronously by registering a callback function to be called in case of the event by using the Fg_registerEventCallback method.

    In both cases, these mechanisms can either be used for a specific event or for combinations of multiple events types through one event handler (callback and wait function as well).

    Event notification is done as soon as possible, when the situation of the event is detected. The listener has to take care of this fact, at least in cases, when waiting for or-combined bit masks of different event types. Different event types might occur sequentially, and the SDK reacts either on doing the notification at minimum once, but also by a series of calls. The listener can react on this issue by evaluating the event mask given from the SDK. Herby the information is given, for which event the notification is done. It is guaranteed, that one event is not being notified multiple times.