![]() |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Software Development Kit (SDK) |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![]() |
![]() |
![]() |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
. | ![]() |
2. Configuration of grabbing parameters
2.2 Initialization and Release2.2.1 Initializing without Configuration FileDescription 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().
2.2.2 Initializing with configuration fileDescription The function Fg_InitConfig() initializes the frame grabber and loads a parameter file (microEnable configuration file *.mcf). If the initialization succeeds, an initialized pointer will be returned on data structure Fg_Struct, if not, the result is NULL. If more than one microEnable frame grabber is available in the PC system, each hardware card will differ by a logical number, which is distributed by initialization. Attention: Each frame grabber card will be handled uniquely by a separate data structure Fg_Struct, after initialization. The selection of frame grabbers is sorted by the increasing number of slots in the PC. Please note, that the unique ID can differ from PC to PC. Besides, each grabber has a unique ID, the serial number which is printed on each board. It can be displayed with microDiagnosis / microDiagnosis mE4 or microDisplay. An additional possibility for identifying several grabbers is to use the function Fg_getSerialNumber() to ask for serial number via SDK. A frame grabber resource initialized by Fg_InitConfig() will be released by Fg_FreeGrabber().
2.2.3 Releasing frame grabber resourcesDescription 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.
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:
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:
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.
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:
2.2.4.1.1 Frame grabber adressing modes
|
|
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 |
|
|
|
Manual assignment of indices for each board according to PCI Bus IDs |
|
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 |
<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
|
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. |
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. |
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. |
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 |
Default value |
FG_PORT |
PORT_A = 0; |
Logical number of the used |
int |
0 |
FG_WIDTH |
Applet depending [*1] |
Width of the image |
int |
Applet depending [*1] |
FG_HEIGHT |
Applet depending [*1] |
Height of the image |
int |
Applet depending [*1] |
FG_XOFFSET |
Applet depending [*1] |
X-offset from the left top |
int |
0 pixels |
FG_YOFFSET |
Applet depending [*1] |
Y-offset from the left top |
int |
0 pixels |
FG_XSHIFT |
Applet depending [*1] |
Number of invalid words at |
int |
0 |
FG_TIMEOUT |
Applet depending [*1] |
Global Timeout. Time in seconds until device |
int |
1000000s |
FG_FRAMESPERSEC |
Applet depending [*1] |
Numbers of images per |
Double |
8.0fps |
FG_FORMAT |
FG_GRAY = 8bit |
Color format of |
int |
Applet depending [*1] |
FG_EXPOSURE |
Applet depending [*1] |
Exposure depending on |
int |
2000µs |
FG_TRIGGERMODE |
FREE_RUN |
Five available trigger modes. |
int |
FREE_RUN |
FG_STROBEPULSEDELAY |
0-2^10 |
Pulse delay in µs |
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 Astr2=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);...
}
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, |
int Fg_getParameterEx(Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, dma_mem *pMem, |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
Parameter |
int |
As argument, a identification number is needed. |
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 |
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 |
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 |
FG_STROBPULSEDELAY |
int |
Strobe delay to the trigger in µs. |
FG_TWOCAMMODEL |
int |
Returns the value, if the loaded camera applet |
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: BINFO_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. |
![]() |
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. |
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.
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 |
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 |
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, |
Alignment of bits for output format. |
int |
FG_PORT |
0 = PORT_A (base config.), |
Active port of the grabber. |
int |
FG_TIMEOUT |
min: 1 sec. |
Time in seconds until the |
int
|
FG_WIDTH
|
Depending on design.
|
Image width in pixels
|
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, |
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 |
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. |
If no camera is connected, the result is 0. |
int |
FG_CAMSTATUS_EXTENDED |
0 = CameraClk |
Extended information on the pixel clock from the camera, LVAL and FVAL, |
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, |
Alignment of bits for output format. |
int |
FG_PORT |
0 = PORT_A (base config.), |
Active port of the grabber. |
double |
FG_REVNR |
Depending. |
Revision number of this release version. |
int |
FG_TIMEOUT |
min: 1 sec. |
Time in seconds until the device driver displays a timeout. |
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. |
int
|
FG_WIDTH
|
Depending on design.
|
Image width in pixels.
|
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. |
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.
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. |
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. |
> 0 |
The number of parameters. |
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:
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.
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" .
Function |
Description |
Allocation of a frame buffer (old version). |
|
Release of a frame buffer (old version). |
|
Allocation of a frame buffer (new version). |
|
Release of a frame buffer (new version). |
|
Allocation of buffer management for usage of user memory as frame buffer. |
|
Adding user memory to frame buffer. |
|
Deletion of user memory from frame buffer. |
|
Release user memory control structure.
|
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.
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.
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. |
void* |
Pointer to a valid image 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. |
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().
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. |
dma_mem* |
Pointer to a valid image buffer. |
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 |
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. |
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.
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. |
dma_mem* |
A valid handle on frame buffer. |
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. |
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. |
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 |
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 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);
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.
The microEnable acquisition functions are optimated for maximum data transfer speed. It allows the linear acquisition mode which transfers the images periodically into a ring buffer. Besides the linear acquisition mode, it exists a blocking mode which only overwrites an acquired image, if it has been released explicitly.
Besides starting and stopping the image acquisition, in this chapter the functions for checking the status of transfer are described.
The function of the grabbing control is sorted in three groups:
1. Starting and stopping the grabbing
Function |
Description |
Starts the image acquisition. |
|
Stops the image acquisition. |
2. The request of the current transferred image
Function |
Description |
Transfers an image from the frame buffer. |
|
Returns the number of the last grabbed image. |
|
Returns the number of the picture of the last grabbed image. |
3. Frame buffer calculation for an image number
Function |
Description |
Calculation of the frame buffer, according to an image number. |
4. Reading and setting of the status information of the frame buffer
Function |
Description |
Reading of the status information of the frame buffer. |
|
Setting of the status information of the frame buffer. |
There are three different acquiring modes, which differ in the release of the acquired frame buffer. The acquiring modes are settable by Fg_AcquireEx().
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. |
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. |
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. |
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) |
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 |
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. |
#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;}
}
#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;}
}
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, |
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, |
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. |
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. |
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);
}
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, |
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;}
}
....
}
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. |
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;}
}
}
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. |
NUMBER_OF_LOST_IMAGES |
Sum of lost images. |
NUMBER_OF_BLOCK_LOST_IMAGES |
Sum of all images, which are lost by blocking of the frame buffer. |
NUMBER_OF_BLOCKED_IMAGES |
Sum of blocked images. |
NUMBER_OF_ACT_IMAGE |
Number of last acquired image. |
NUMBER_OF_LAST_IMAGE |
Number of last get image. |
NUMBER_OF_NEXT_IMAGE |
Number of next image after last get image. |
NUMBER_OF_IMAGES_IN_PROGRESS |
Sum of all images which aren't gotten, yet. |
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.
|
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);
}
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; imageTag = bufNum; |
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().
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; dmaLength = bufNum; |
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().
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; timeStamp = bufNum; |
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().
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; timeStampLong = bufNum; |
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().
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.
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 |
Default value |
FG_TIMEOUT |
2-2ˆ31 |
Time until a running grabbing |
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);
}
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.
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.
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.
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.
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 |
Default value |
FG_TRIGGERMODE |
FREE_RUN |
Setting of the operation mode of |
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){...
}
}
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 |
Default value |
FG_TRIGGERMODE |
GRABBER_CONTROLED |
Setting of the operation mode |
int |
FREE_RUN |
FG_EXPOSURE |
Applet depending [*1] |
Setting of the exposure |
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;}
}
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 |
Default value |
FG_TRIGGERMODE |
GRABBER_CONTROLED_SYNCHRON |
Setting of the operation mode |
int |
FREE_RUN |
FG_EXPOSURE |
Applet depending [*1] |
Setting of the exposure |
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;}
}
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.
The operation mode can be configured separately for each CameraLink port.
Parameter |
Value |
Description |
Expected |
Default value |
FG_TRIGGERMODE |
ASYNC_SOFTWARE_TRIGGER ASYNC_SOFTWARE_TRIGGER_QUEUED |
Setting of the operation mode |
int |
FREE_RUN |
FG_EXPOSURE |
Applet depending [*1] |
Setting of the exposure |
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
}
}
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 |
Default value |
FG_TRIGGERMODE |
ASYNC_TRIGGER |
The operation mode of |
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, |
The channel of the trigger |
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;}
}
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 |
Default value |
FG_PRESCALER, |
Applet depending [*1] |
Configuration of the |
int |
0 |
[*1] See parameter descriptions for microEnable IV-Base x1, for microEnable IV-Full x1, for microEnable IV-Full x4.
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 |
Default value |
FG_STROBEPULSDELAY |
Applet depending [*1] |
Flash light will be delayed |
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);
}
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. |
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. |
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);
}
Description
In the operation mode Grabber Controlled Mode, the frame grabber defines the speed of image grabbing. The grabber controls the camera with the signal image trigger which will be transfered over CC signals via CameraLink interface to the camera. With this function the grabber controls the frequency, the pulse width as well as the polarity.
Basis for the following example code is the VisualApplets example DualGrayAreaBase.va (see VisualApplets installation ../examples)
Example
#include <stdio.h>
#include <stdlib.h>
#include "os_type.h"
#include "vasFgProject.h"
// ---------------------------------------------------------------------------
int main () {
// ---------------------------------------------------------------------------
Fg_Struct* fg = Fg_Init("DualGrayAreaBase.hap",0);
...
int timeout = 5;
Fg_setParameter(fg, FG_TIMEOUT, &timeout, 0);
/*============ TrgPortArea : Trigger ============== */
...
Device1_Process0_Trigger_TriggerMode = TrgPortArea::ExternSw_Trigger;
Fg_setParameter(fg, Device1_Process0_Trigger_TriggerMode_Id, &Device1_Process0_Trigger_TriggerMode, 0);
...
Device1_Process0_Trigger_ExsyncEnable = TrgPortArea::ON;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncEnable_Id, &Device1_Process0_Trigger_ExsyncEnable, 0);
...
Device1_Process0_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg, Device1_Process0_Trigger_SoftwareTrgPulse_Id, &Device1_Process0_Trigger_SoftwareTrgPulse, 0);
...
Device1_Process0_Trigger_ImgTrgInSource = TrgPortArea::SoftwareTrigger;
Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInSource_Id, &Device1_Process0_Trigger_ImgTrgInSource, 0);
...
Device1_Process0_Trigger_ImgTrgInPolarity = TrgPortArea::HighActive;
Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInPolarity_Id, &Device1_Process0_Trigger_ImgTrgInPolarity, 0);
...
Device1_Process0_Trigger_ExsyncFramesPerSec = 8;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncFramesPerSec_Id, &Device1_Process0_Trigger_ExsyncFramesPerSec, 0);
...
Device1_Process0_Trigger_ExsyncExposure = 4000;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncExposure_Id, &Device1_Process0_Trigger_ExsyncExposure, 0);
...
Device1_Process0_Trigger_ExsyncPolarity = TrgPortArea::LowActive;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncPolarity_Id, &Device1_Process0_Trigger_ExsyncPolarity, 0);
...
// ---------------------------------------------------------------------------
int id0 = CreateDisplay(8 * byteWidth0, width0, height0);
SetBufferWidth(id0, width0, height0);
int id1 = CreateDisplay(8 * byteWidth1, width1, height1);
SetBufferWidth(id1, width1, height1);
// ---------------------------------------------------------------------------
i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);
...
i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);
...
// ---------------------------------------------------------------------------
for(i = 1;i<=100;i++){
...
frameindex_t status;
status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);
...
status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);
...
void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);
DrawBuffer(id0,iPtr0,i,0);
void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);
DrawBuffer(id1,iPtr1,i,0);
}
// ---------------------------------------------------------------------------
Fg_stopAcquireEx(fg,0,pmem0,0);
Fg_stopAcquireEx(fg,1,pmem1,0);
Fg_FreeGrabber(fg);
return (0);
}
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);
}
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)
Example
#include <stdio.h>
#include <stdlib.h>
#include "os_type.h"
#include "vasFgProject.h"
// ---------------------------------------------------------------------------
int main () {
// ---------------------------------------------------------------------------
Fg_Struct* fg = Fg_Init("myFirstTrigger.hap",0);
...
int timeout = 5;
Fg_setParameter(fg, FG_TIMEOUT, &timeout, 0);
/*============ TrgPortArea : Trigger ============== */
...
Device1_Process0_Trigger_TriggerMode = TrgPortArea::ExternSw_Trigger;
Fg_setParameter(fg, Device1_Process0_Trigger_TriggerMode_Id, &Device1_Process0_Trigger_TriggerMode, 0);
...
Device1_Process0_Trigger_ExsyncEnable = TrgPortArea::ON;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncEnable_Id, &Device1_Process0_Trigger_ExsyncEnable, 0);
...
Device1_Process0_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg, Device1_Process0_Trigger_SoftwareTrgPulse_Id, &Device1_Process0_Trigger_SoftwareTrgPulse, 0);
...
Device1_Process0_Trigger_ImgTrgInSource = TrgPortArea::SoftwareTrigger;
Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInSource_Id, &Device1_Process0_Trigger_ImgTrgInSource, 0);
...
Device1_Process0_Trigger_ImgTrgInPolarity = TrgPortArea::HighActive;
Fg_setParameter(fg, Device1_Process0_Trigger_ImgTrgInPolarity_Id, &Device1_Process0_Trigger_ImgTrgInPolarity, 0);
...
Device1_Process0_Trigger_ExsyncPolarity = TrgPortArea::LowActive;
Fg_setParameter(fg, Device1_Process0_Trigger_ExsyncPolarity_Id, &Device1_Process0_Trigger_ExsyncPolarity, 0);
...
// ---------------------------------------------------------------------------
int id0 = CreateDisplay(8 * byteWidth0, width0, height0);
SetBufferWidth(id0, width0, height0);
int id1 = CreateDisplay(8 * byteWidth1, width1, height1);
SetBufferWidth(id1, width1, height1);
// ---------------------------------------------------------------------------
i = Fg_AcquireEx(fg, 0, 100, ACQ_STANDARD, pmem0);
...
i = Fg_AcquireEx(fg, 1, 100, ACQ_STANDARD, pmem1);
...
// ---------------------------------------------------------------------------
for(i = 1;i<=100;i++){
...
Device1_Process0_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg,Device1_Process0_Trigger_SoftwareTrgPulse_Id,&Device1_Process0_Trigger_SoftwareTrgPulse,0);
...
Device1_Process1_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg,Device1_Process1_Trigger_SoftwareTrgPulse_Id,&Device1_Process1_Trigger_SoftwareTrgPulse,0);
...
frameindex_t status;
status = Fg_getLastPicNumberBlockingEx(fg,i,0,5,pmem0);
...
status = Fg_getLastPicNumberBlockingEx(fg,i,1,5,pmem1);
...
void* iPtr0 = Fg_getImagePtrEx(fg,i,0,pmem0);
DrawBuffer(id0,iPtr0,i,0);
void* iPtr1 = Fg_getImagePtrEx(fg,i,0,pmem1);
DrawBuffer(id1,iPtr1,i,0);
...
Device1_Process0_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg,Device1_Process0_Trigger_SoftwareTrgPulse_Id,&Device1_Process0_Trigger_SoftwareTrgPulse,0);
...
Device1_Process1_Trigger_SoftwareTrgPulse = 1;
Fg_setParameter(fg,Device1_Process1_Trigger_SoftwareTrgPulse_Id,&Device1_Process1_Trigger_SoftwareTrgPulse,0);
}
// ---------------------------------------------------------------------------
Fg_stopAcquireEx(fg,0,pmem0,0);
Fg_stopAcquireEx(fg,1,pmem1,0);
Fg_FreeGrabber(fg);
return (0);
}
Description
The function Fg_sendImage() or Fg_sendImageEx() transmits images to the microEnable framegabber. It is affordable for coprocessor purposes.
Syntax
int Fg_sendImage(Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex) |
int Fg_sendImageEx(Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex, dma_mem *memHandle) |
Parameters
Parameter |
Type
|
Description |
Fg |
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
startImage
|
frameindex_t
|
The first image that should be sent.
|
PicCount
|
frameindex_t
|
Number of images to be sent.
|
nFlag
|
int
|
ACQ_STANDARD, ACQ_BLOCK, ACQ_PULSE
|
DmaIndex
|
unsigned int
|
Logical number of used Dma port. The camera associated with the DMA port is depending on the applet.
All acquisition applets, delivered with the Silicon-Software Runtime, have a direct mapping between DMA ports and camera ports. This means DmaIndex 0 is associated with PORT A and DmaIndex 1 is associated with PORT B and so on. |
memHandle
|
dma_mem *
|
Pointer to frame buffer handle.
|
Return values
Return value |
Description |
FG_OK |
Grabbing has been started correctly. |
FG_NOT_INIT |
Frame grabber was not initialised correctly. |
FG_NO_VALID_DESIGN |
No valid design was loaded. |
FG_INVALID_MEMORY |
Image memory was not allocated. |
FG_NOT_ENOUGH_MEMORY |
Insufficient image memory was allocated for specified image parameter. |
FG_ALREADY_STARTED |
Grabbing is already started and can’t be started twice. |
FG_INVALID_PARAMETER |
Invalid parameter is set. |
The shading feature allows the allocation and the release of buffers, getting access to it and settings the maximum lines that have to be corrected, the setting of subtraction, multiplication and noise correction values, the writing of the corrected lines and the ending of the access to the buffer. These functions will be shown in the following overview.
For more information on how the shading correction works, please take a look at the shading application note.
1. Allocating and freeing some buffer
Function |
Description |
Allocate some buffer. |
|
Free the allocated buffer. |
2. Access to shading functionality
Function |
Description |
Enables the access to the shading functionality. |
|
Closes the access to the shading functionality. |
3. Getting information about the maximum lines
Function |
Description |
Getting the maximum lines of the |
4. Setting the substration, multiplication and noise correction values
Function |
Description |
To set the substraction values. |
|
To set the multiplication values. |
|
To set the noise correction values |
5. Freeing the access to the allocated buffer and writing the currently corrected line
Function |
Description |
Shad_WriteActLine() |
Writing the currently corrected line. |
Description
Before using the shading functionality, it is neccessary to allocate some buffer for shading calculation. Fg_AllocShading() is the first function to be used for complete shading feature.
Syntax
void* Fg_AllocShading(Fg_Struct *Fg, int dataSet, int CamPort) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
set | int |
Parameter set which can be dynamically chosen out of 4. |
CamPort | int |
Logical number of used CameraLink port. |
Return Values
Return Value |
Description |
void* |
Buffer allocation succeeded. |
NULL | Buffer allocation failed. |
Description
Freeing the buffer that has been allocated before (with Fg_AllocShading()) for the shading feature can be done with Fg_FreeShading().
Syntax
int Fg_FreeShading(Fg_Struct *Fg, void *sh) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
Return Values
Return Value |
Description |
0 |
Freeing the buffer succeeded. |
FG_INVALID_PARAMETER | An invalid parameter has been used. |
Description
Before using the shading interface, it is neccessary to activate the access with Shad_GetAccess(). In detail, the registers on your grabber will be prepared for shading. Afterwards, the interface can be closed with Shad_FreeAccess().
Syntax
int Shad_GetAccess(Fg_Struct *Fg, void *sh) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
Return Values
Return Value |
Description |
0 |
Access has been activated successfully. |
FG_INVALID_PARAMETER | An invalid parameter has been used. |
Description
After opening the access to the shading interface and after working with the shading feature, the shading interface can be closed with Shad_FreeAccess().
Syntax
int Shad_FreeAccess(Fg_Struct *Fg, void *sh) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
Return Values
Return Value |
Description |
0 |
Access has been closed successfully. |
FG_INVALID_PARAMETER | An invalid parameter has been used. |
int Shad_GetMaxLine(Fg_Struct *Fg, void *sh) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
Return Values
Return Value |
Description |
>= 0 |
Line number of the current image. |
FG_INVALID_PARAMETER | An invalid parameter has been used. |
Description
Before shading calculation can be done, some parameters have to be set. Shad_SetSubValueLine() sets parameters for the offset (subtractive correction). Shad_SetMultValueLine() sets parameters for the gain (multiplicative correction). Shad_SetFixedPatternNoiseLine() sets parameters for the defective pixel interpolation.
Besides frame grabber structure and handle on shading interface, the position in line, the color channel and either subtraction, multiplication or switch value has to be set.
You can either manually set values for shading with the functions listed below or you can otherwise set a path to a file for defective pixel interpolation, subtraction or multiplication calculation. Therefore you need the function FG_setParameter() together with the parameters FG_SHADING_SUBFILE0, FG_SHADING_MULTFILE0 or FG_SHADING_FPNFILE0.
Syntax
int Shad_SetSubValueLine (Fg_Struct *Fg, void *sh, int x, int channel, float sub) |
int Shad_SetMultValueLine(Fg_Struct *Fg, void *sh, int x, int channel, float mult) |
int Shad_SetFixedPatternNoiseLine(Fg_Struct *Fg, void *sh, int x, int channel, int on) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
x | int | Position in a line. |
channel | int | Color channel which has to be used. In monochrome applets: Gray = 0. In color scale applets: Red = 0, Green = 1, Blue = 2. |
sub | float |
Shading correction calculation with subtraction value. |
mult | float |
Shading correction calculation with multiplication value. |
on | int | Enabling or disabling the noise correction. |
int Shad_WriteActLine(Fg_Struct *Fg, void *sh, int Line) |
Parameters
Parameter |
Type |
Description |
Fg |
Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
sh | void* | Handle on shading interface. |
Line | int | Line number which currently has to be corrected. |
The Silicion Software Framegrabber SDK offers the possibility for an event driven development by using the so called asynchronous procedure call methods (APC). As a result, the APC interfaces is an alternative approach of getting images by polling the images buffers. In case of newly grabbed images, the client application gets informed by this interface. This notification is done by a callback mechanism (callback function). Additional settings are availabe for defining the behaviour in detail.
The APC-interface consists of a set of elements, which are shown in the following table:
Elements |
Description |
Method for registering / unregistering a callback functions for notifications |
|
Data type of the function pointer for the callback function |
|
Data type for the specific APC setup information |
The first step of using the interface is the registration of a callback functions / callback handler(see Fg_registerApcHandler), that gets called by the SDK when new images are available. This registration stays valid, as long as the image acquisition is running. When the acquistion stops (either manual by calling the Fg_StopAcquire or automatically), the callback gets unregistered implicitly. This behaviour can be influenced by an according flag at the setup control structure (FgApcControl), to keep a handler registered permanently.
Important note: only one APC handler per DMA channel can be registered at the same time.
As mentioned above, each time when a new image is available, the notification is done by calling the currently registerd callback. This notification is done for each image or for multiple images depending on an according flag at the setup structure (FgApcControl).
The callback handler passes client data, which has been declared during the setup (FgApcControl::data). It is possible to stop the notification by passing a non-zeor value as a return value fo the callback function.
When the acquisition is stopped, the APC notification is stopped as well, even if there are images pending (default behavour).
To get a synchronisation between the concurrently running procedure of stopping acquisition on one side and on terminating APC handlers on the other side, a specific flag at the Fg_StopAcquireEx() method is available (STOP_SYNC_TO_APC). In this case, the Fg_StopAcquire() waits a predefined timeout, until it returns. This timeout can be set by the Fg_SetParameter function (Parameter: FG_APC_STOP_TIMEOUT).
The Fg_StopAcquire waits at maximum of the defined timeout for a currently processed callback. If the callback returns before the timeout is exceeded, the Fg_stopAcquire() returns synchronously to the callback. The return value indicates, wether the timeout is elapsed or not (see images below).
Pending image notifications get processed furtherly, until the timeout is reached. An additional control flag at the APC setup structure has to be set therefore (see image "Situation 3" below.
Situation 1: Predefined timeout is not elapsed, when waiting for a pending APC
Situation 2: Predefined timeout is elapsed, when waiting for a pendig APC
Situation 3: Fg_StopAcquire waits for all multiple images to be processed
Description
With the function Fg_getLastErrorDescription() the last occurred error will be displayed as error message.
Syntax
const char *Fg_getLastErrorDescription(Fg_Struct *Fg) |
Parameters
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
Return values
Return value |
Description |
char* |
Returns the last error that occurred. |
Example (VA Applets)
#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"
int main(){
int error;
const char* str;
Fg_Struct *fg;
// Initialization of frame grabber 0
if((fg = Fg_Init("myVADesign.hap",0)) == NULL){str=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;}
...
}
Description
The function Fg_getLastErrorNumber() displays the error code of last occurred fault.
Syntax
int Fg_getLastErrorNumber(Fg_Struct *Fg) |
Parameters
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
Return values
Return value |
Description |
int |
Returns the last error that occurred. |
Example (VA Applets)
#include <stdio.h>
#include "fgrab_Struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"
int main(){
int error;
const char* str;
Fg_Struct *fg;
// Initialization of frame grabber 0
if((fg = Fg_Init("myVADesign.hap",0)) == NULL){str=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;}
...
}
Description
The function Fg_getErrorDescription() displays the error message, when receiving the error code.
Syntax
const char* Fg_getErrorDescription(Fg_Struct *Fg, int errorNumber) |
Parameters
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
errorNumber
|
int
|
Identification number of error code.
|
Return values
Return value |
Description |
char* |
Error message of a special error code. |
Example
#include <stdio.h>
#include "fgrab_struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"
int main(){
int error;
const char* str;
Fg_Struct *fg;
// Initialization of frame grabber 0
if((fg = Fg_Init("myVADesign.hap",0)) == NULL){str=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;}
fprintf(stdout,"Errorcode -2001 Errordescription=%s\n", Fg_getErrorDescription(fg,-2001));
...
}
Fault value |
Fault text |
Description |
1 |
FG_INIT_OK |
Initialization successfully finished. |
0 |
FG_OK |
No error occured. |
-1 |
FG_ERROR / FG_DUMMY_BUFFER |
A non-specific internal error is occuring. |
-2
|
FG_NO_PICTURE_AVAILABLE
|
At the moment, an image is not available.
|
-10 |
FG_ALR_INIT |
Frame grabber is already initialized. |
-20
|
FG_NO_BOARD_AVAILABLE
|
There is no board available that could get initialized.
|
-21
|
FG_INVALID_BOARD_NUMBER
|
The given board number is invalid.
|
-22
|
FG_BOARD_INIT_FAILED
|
Board couldn't get initialized.
|
-26
|
FG_INVALID_DESIGN_NAME
|
The given design name is not valid.
|
-28
|
FG_RESSOURCES_STILL_IN_USE
|
Resources are already in use by the SDK
/ microDisplay or microDiagnosis. |
-50
|
FG_WRONG_ARCHITECTURE
|
The architecture doesn't fit.
|
-60 |
FG_SOFTWARE_TRIGGER_BUSY |
It is not possible to send a software trigger. |
-100 |
FG_HAP_FILE_NOT_LOAD |
The specified hap file could not be loaded. |
-110 |
FG_MICROENABLE_NOT_INIT |
microEnable could not be initialized. |
-120 |
FG_DLL_NOT_LOAD |
The specified frame grabber DLL cannot be found. |
-121
|
FG_REG_KEY_NOT_FOUND
|
The registration key cannot be found.
|
-122
|
FG_VASDLL_NOT_LOAD
|
The vas.dll couldn't be loaded.
|
-300
|
FG_PTR_INVALID
|
The given pointer is not valid.
|
-400
|
FG_RANGE_ERR
|
The given value is not in range.
|
-500
|
FG_NOT_ENOUGH_MEM
|
There is not enough memory available.
|
-600
|
FG_DMATRANSFER_INVALID
|
The DMA transfer is not valid.
|
-700
|
FG_HAP_FILE_DONT_MATCH
|
The applet doesn't fit to the hardware.
|
-2001 |
FG_NOT_INIT |
Frame grabber structure is not initialized. |
-2003
|
FG_LIB_UNLOAD_FAIL
|
Unloading the library failed.
|
-2010 |
FG_WRONG_NUMBER_OF_BUFFER |
Invalid number of subbuffers has been specified. |
-2011 |
FG_TOO_MANY_BUFFER |
More buffers than allowed have been tried to select. |
-2020 |
FG_NOT_ENOUGH_MEMORY |
Not enough memory available or allocated to do the operation. |
-2024 |
FG_MEMORY_ALREADY_ALLOCATED |
Memory already is allocated and has not been released. |
-2026
|
FG_CANNOT_WRITE_MEM_CONFIG_FAILED
|
Writing the memory configuration failed.
|
-2030 |
FG_INTERNAL_STATUS_ERROR |
A non-specific internal error is occuring. |
-2031 |
FG_INTERNAL_ERROR |
A non-specific internal error is occuring. |
-2040 |
FG_CANNOT_START |
Image grabbing cannot be started by the frame grabber. |
-2042 |
FG_CANNOT_STOP |
Image grabbing cannot be stopped by the frame grabber. |
-2045
|
FG_SYNC_ACQUIRE_NOT_SUPPORTED
|
Synchroneous acquisition is not supported.
|
-2050 |
FG_INVALID_DESIGN |
No valid design is selected during configuration of frame grabber. |
-2052 |
FG_CONFIGURE_FAILED |
Configuration of frame grabber failed. |
-2053 |
FG_RECONFIGURE_FAILED |
Reconfiguration of frame grabber failed. |
-2055 |
FG_NO_APPLET_ID |
No applet in frame grabber DLL found for specified value. |
-2056 |
FG_APPLET_NOT_IN_LIST |
No applet in frame grabber DLL found for specified applet name. |
-2060 |
FG_INVALID_MEMORY |
No frame buffer is allocated. |
-2070 |
FG_INVALID_PARAMETER |
An invalid parameter have been tried to set. |
-2075
|
FG_INVALID_VALUE
|
The given value is not valid.
|
-2076 |
FG_INVALID_FILENAME |
An invalid configuration file name has been specified. |
-2080 |
FG_NOT_LOAD |
Specified configuration cannot be loaded. |
-2090 |
FG_ALREADY_STARTED |
The image grabbing is already started and cannot be started once more. |
-2100 |
FG_STILL_ACTIVE |
The frame grabber is still busy during image transmission. |
-2110 |
FG_NO_VALID_DESIGN |
No valid design has been tried to load. |
-2120 |
FG_TIMEOUT_ERR |
A timeout error is occuring. |
-2130
|
FG_NOT_IMPLEMENTED
|
It is not implemented what you're asking for.
Please contact Basler. |
-2140 |
FG_NOT_WRONG_TRIGGER_MODE |
A wrong trigger mode has been tried to set. |
-2150
|
FG_ALL_BUFFER_BLOCKED
|
All available buffers are still blocked.
|
-3000
|
FG_CANNOT_INIT_MICROENABLE
|
Initializing the microEnable failed.
|
-3010 |
FG_TRANSFER_NOT_ACTIVE |
Data transfer is not active. |
-3120
|
FG_CLOCK_NOT_LOCKED
|
The clock hasn't been locked.
|
-5000 |
FG_INVALID_CONFIGFILE |
An incorrect configuration file has been tried to load. |
-6000 |
FG_VALUE_OUT_OF_RANGE |
The selected value is out of range. |
-7000
|
FG_CANNOT_CHANGE_DISPLAY_WIDTH
|
Display width cannot be changed.
|
-7005
|
FG_CANNOT_CHANGE_DISPLAY_HEIGHT
|
Display height cannot be changed.
|
-7010
|
FG_CANNOT_CHANGE_DISPLAY_SIZE
|
Display size cannot be changed.
|
-7020
|
FG_NO_VALID_LICENSE
|
The entered license code or the license file is incorrect.
|
-7030
|
FG_CANNOT_CHANGE_CAMERA_FORMAT
|
The camera format cannot be changed.
|
-7040
|
FG_INVALID_REGISTER
|
The register is not existing.
|
-7050
|
FG_REGISTER_INIT_FAILED
|
The register update failed.
|
-7060
|
FG_INVALID_SHADING_CORRECTION_FILE
|
The loaded file for shading correction is invalid.
|
-7070
|
FG_WRITE_LINE_SHADING_TIMEOUT
|
A timeout is occuring during line shading calculation.
|
-7080
|
FG_INVALID_MODULO
|
The entered value is not able to be calculated
with the corresponding modulo value concerning the specified parameter. |
-7090
|
FG_CANNOT_CHANGE_DURING_ACQU
|
During acquisition coresponding parameter cannot be changed.
|
-8000
|
FG_TOKEN_NOT_FOUND_ERROR
|
The entered token cannot be found.
|
-8010
|
FG_WRITE_ACCESS_DENIED
|
Write access on coresponding register is denied.
|
Description
The function Fg_getSWVersion() returns the runtime version of the SDK running.
Syntax
const char* Fg_getSWVersion() |
Return values
Return value |
Description |
const char* |
Runtime version of the SDK running, i. e. "5.0" |
Description
Fg_getBoardType() returns the type of board: If it is a microEnable III / -XXL or microEnable IV-Full x1 / -Full x4. PixelPlant is not able to be detected at the moment.
Syntax
int Fg_getBoardType(int BoardIndex) |
Parameters
Parameter |
Type
|
Description |
BoardIndex
|
int
|
Logical number of the board. |
Return values
Return value |
Description |
int |
Board type: |
Description
The function Fg_getSerialNumber() reads the serial number of the frame grabber.
Syntax
unsigned int Fg_getSerialNumber(Fg_Struct *Fg) |
Parameters
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
Return values
Return value |
Description |
unsigned int |
Hexadecimal value in 32bit which represents the serial number of the board. |
Example
#include <stdio.h>
#include "fgrab_Struct.h"
#include "fgrab_prototyp.h"
#include "fgrab_define.h"
int main(){
int error;
const char* str;
Fg_Struct *fg;
// Initialization of frame grabber 0
if((fg = Fg_Init("myVADesign.hap",0)) == NULL){str=Fg_getLastErrorDescription(fg);
error=Fg_getLastErrorNumber(fg);
fprintf(stdout,"Init Error(%d): %s\n",error,str);
return 0;}
fprintf(stdout,"Serial number of frame grabber %x\n",Fg_getSerialNumber(fg));
...
}
Description
The function Fg_getAppletId() returns the applet ID. The applet name can be chosen, but is not neccessary.
Syntax
int Fg_getAppletId(Fg_Struct *Fg, char* Appletname) |
Parameter (VA Applets)
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
Appletname
|
char*
|
Applet name, if known.
|
Parameter (Acquisition Applets)
Parameter |
Type |
Description |
Fg | Fg_Struct* |
Pointer to frame grabber structure Fg_Struct. |
AppletId | int | // BASE X1
DUAL_AREA_GRAY16_ME4BASEX1 -> 0xa400010 // FULL X1 DUAL_AREA_BAYER12_ME4FULLX1 -> 0xa410010 // FULL X1 // GigE |
Return values
Return value |
Description |
int |
AppletId in hexadecimal value as shown above. |
Description
The function Fg_getAppletVersion() returns the version number to the given applet ID.
Syntax
const char* Fg_getAppletVersion(Fg_Struct *Fg, int AppletID) |
Parameter
Parameter |
Type
|
Description |
Fg
|
Fg_Struct*
|
Pointer to frame grabber structure Fg_Struct. |
AppletID
|
int
|
ID of the corresponding applet.
|
Return values
Return value |
Description |
const char* |
Applet version concerning the given applet ID. |
The parameter FG_GLOBAL_ACCESS allows the user to define the access right to all the parameters. FG_GLOBAL_ACCESS can be set using the standard Fg_setParameter() function. The following values are valid:
Auto = 0 (default)
The access rights are defined automatically by the software for each parameter depending on the state of the frame grabber.
Read = 1
All the parameters except FG_GLOBAL_ACCESS are in "read only" mode.
Read Write = 3
All the parameters can be read and write. The write is not allowed during the acquisition.
Read Write Change = 7
All the parameters can be read and write.
Important: The mode "Read Write Change = 7" must be used carefully. In this mode changing some parameters during the acquisition could put the frame grabber in an unstable state. It is highly advised to stay in the "Auto = 0" mode.
The generated SDK project contains one namespace per operator type. This namespace contains the “enum” definition of each “enum” parameter.
The type ENUM can be used within SDK as following example describes:
the module “CameraGrayAreaBase” will generate the following namespace in header file:
namespace CameraGrayAreaBase {
enum UseDval {DVAL_Enabled=1,DVAL_Disabled=0};
enum Format {SingleTap8Bit=0,SingleTap10Bit=1,SingleTap12Bit=2,SingleTap14Bit=3,SingleTap16Bit=4,DualTap8Bit=5,DualTap10Bit=6,DualTap12Bit=7};
};
The user can use this enums like this:
int value = CameraGrayAreaBase::DVAL_Enabled;
Fg_setParameter(fg, Process0_modul4_Format_Id,&value, dmaNo);
The SDK enables an application to get notifications about certain state changes at the data flow from camera to RAM and the image processing as well. Typical events are for example detection of new images at certain points of the image processing chain, detected external signals at the framegrabber or error conditions occurred during at the image processing and transport steps. Therefore a specific subsystem is available called the event subsystem. The following graphic demonstrates this in a schematic way based on the data flow of images from camera to RAM:
As this graphic illustrates, the set of available events (types) depends on the type of processing (applet) and the hardware (framegrabber) itselt. To get a complete list of event present at a certain combination of applet and framegrabber, please consult the the applet documentation.
The event subsystem itself consists of a set of API functions for:
• querying available events (type of events)
• controlling event notifications
• getting event notifications
Following functions are available for event management:
Function |
Description |
Get the event mask by name. |
|
Get the name of the event by mask |
|
Activate a specific event or a group of events. |
|
Clear previously raised events. |
|
Blocking wait for a specific event or a group of events. |
|
Register a callback for asynchrous event notification |
Fg_getEventMask
method, which has to be used furtheron to access this event, either for activation or for getting the according notification.
Event |
Description |
CamPortATransferStart |
Rising edge of signal FVAL on CameraLink Port A. Supported in Base, Medium and Full area applets. Event generation doesn't depend on image acquisition. |
CamPortATransferEnd |
Falling edge of signal FVAL on CameraLink Port A. Supported in Base, Medium and Full area applets. Event generation doesn't depend on image acquisition. |
CamPortBTransferStart |
Rising edge of signal FVAL on CameraLink Port A. Supported in Base area applets. Event generation doesn't depend on image acquisition. |
CamPortBTransferEnd |
Falling edge of signal FVAL on CameraLink Port A. Supported in Base area applets. Event generation doesn't depend on image acquisition. |
A rising or falling edge of the Frame Valid signal (FVAL) indicates the start repectively the end of an image transfer between camera and frame grabber.
The event system is in an idle state until the events are activated. For activation of the event, the corresponding bit mask as described at the previous chapter it needed. For enabling the event notification, the
Fg_activeEvents
method
can be used. Take note, that this function is used for disabling the event notification as well. The activation of the event can be done either event by event or for groups of events in one call. The corresponding bit masks have to be ore’d in that case.
It’s recommended to cleanup the currently present events at the image processing chain by using the Fg_clearEvents method to ensure, that pending no events caused by previous processing are notified.
If a situation at the processing and transport chain is changed, so that the corresponding event should be raised, the application gets a signal from the event subsystem. To react on this state change, the application either can:
• wait until this happens synchronously by using the Fg_eventWait method or
• react asynchronously by registering a callback function to be called in case of the event by using the Fg_registerEventCallback method.
In both cases, these mechanisms can either be used for a specific event or for combinations of multiple events types through one event handler (callback and wait function as well).
Event notification is done as soon as possible, when the situation of the event is detected. The listener has to take care of this fact, at least in cases, when waiting for or-combined bit masks of different event types. Different event types might occur sequentially, and the SDK reacts either on doing the notification at minimum once, but also by a series of calls. The listener can react on this issue by evaluating the event mask given from the SDK. Herby the information is given, for which event the notification is done. It is guaranteed, that one event is not being notified multiple times.