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.

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:

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.
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.
Repeat the intialization for each slave.
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.
Do the slave specific initilization by calling the Fg_setParameter() function and the according slave handle.
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
	When using this mode, the assignment is read from an ASCII file named board_order.cfg The file is located at the <INSTALLDIR>\BIN directory 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
	When using this mode, the assignment is read from an ASCII file named board_order.cfg. The file is located at the <INSTALLDIR>\BIN directory 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
	the board's serial number, which ist a 8 digit alphanumerical value 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:

User allocated frame memory: data is stored into memory locations specified by user application

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
Fg_AllocMem()	Allocation of a frame buffer (old version).
Fg_FreeMem()	Release of a frame buffer (old version).
Fg_AllocMemEx()	Allocation of a frame buffer (new version).
Fg_FreeMemEx()	Release of a frame buffer (new version).
Fg_AllocMemHead()	Allocation of buffer management for usage of user memory as frame buffer.
Fg_AddMem()	Adding user memory to frame buffer.
Fg_DelMem()	Deletion of user memory from frame buffer.
Fg_FreeMemHead()	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
Fg_Acquire() Fg_AcquireEx()	Starts the image acquisition.
Fg_stopAcquire() Fg_stopAcquireEx()	Stops the image acquisition.

2. The request of the current transferred image

Function	Description
Fg_getImage() Fg_getImageEx()	Transfers an image from the frame buffer.
Fg_getLastPicNumber() Fg_getLastPicNumberEx()	Returns the number of the last grabbed image.
Fg_getLastPicNumberBlocking() Fg_getLastPicNumberBlockingEx()	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
Fg_getImagePtr() Fg_getImagePtrEx()	Calculation of the frame buffer, according to an image number.

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

Function	Description
Fg_getStatus() Fg_getStatusEx()	Reading of the status information of the frame buffer.
Fg_setStatus() Fg_setStatusEx()	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().

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.
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

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

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

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

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

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

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

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

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 = 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

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

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

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

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

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)

Developing a design with VisualApplets (i.e. based on the example DualGrayAreaBase.va) and synthesizing it to an applet.

Opening the SDK example which has been created during synthesis.

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

Software Development Kit (SDK)

Table of Content

1

1.1

1.2

2

2.1

2.2

2.2.1

2.2.2

2.2.3

2.2.4

2.3

2.3.1

2.3.2

2.4

2.4.1

2.4.2

2.5

2.5.1

2.5.2

2.5.3

2.5.3.1

2.5.3.2

2.5.4

2.5.5

3

3.1

3.1.1

3.1.2

3.2

3.2.1

3.2.1.1

3.2.1.2

3.2.2

3.2.2.1

3.2.2.2

3.3

3.3.1

3.3.2

3.3.3

3.3.4

3.3.5

3.4

4

4.1

4.2

4.3

4.3.1

4.3.2

4.3.3

4.3.4

4.4

4.4.1

4.4.1.1

4.4.1.2

4.4.1.2.1

4.4.1.2.2

4.4.2

4.5

4.6

4.6.1

4.6.2

4.6.3

4.6.4

4.6.5

4.6.6

4.7

4.8

4.9

4.10

5

5.1

5.1.1

5.1.2

5.1.2.1