Silicon Software Logo

Silicon Software Frame Grabber SDK: fgrab_prototyp.h File Reference

fgrab_prototyp.h File Reference

Header file for all functions exported. More...

#include <stdint.h>
#include <sys/types.h>
#include "fgrab_struct.h"
#include "sisoboards.h"
#include "os_type.h"
#include "fgrab_define.h"

Go to the source code of this file.

Typedefs

typedef struct dma_mem_s dma_mem
 DMA buffer head control object.
typedef struct ShadingMaster_s ShadingMaster
 Shading control object.

Functions

int Fg_freeParameterStringWithType (Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, const enum FgParamTypes type)
 Release previously allocated frame grabber string parameter.
int Fg_getBitsPerPixel (int format)
 Calculate the bits per pixel for a specific output format (FG_GRAY, FG_COL24, etc.).
const char *const Fg_getErrorDescription (Fg_Struct *Fg, int ErrorNumber)
 Description of error message to an error code.
const char *const Fg_getLastErrorDescription (Fg_Struct *Fg)
 Description of last error message.
int Fg_getLastErrorNumber (Fg_Struct *Fg)
 Getting the last error code.
int Fg_getNrOfParameter (Fg_Struct *Fg)
 The function Fg_getNrOfParameter() returns the number of parameters available within the loaded applet.
int Fg_getParameter (Fg_Struct *Fg, int Parameter, void *Value, const unsigned int DmaIndex)
 Getting special parameter settings.
int Fg_getParameterEx (Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, dma_mem *pMem, const frameindex_t ImgNr)
 Getting special parameter settings.
int Fg_getParameterId (Fg_Struct *fg, int index)
 The function Fg_getParameterId() returns the parameter ID of the parameter referenced by index.
int Fg_getParameterIdByName (Fg_Struct *fg, const char *name)
 The function Fg_getParameterIdByName() searchs for the ID of the parameter referenced by the string name.
int Fg_getParameterInfoXML (Fg_Struct *Fg, int port, char *infoBuffer, size_t *infoBufferSize)
 Get parameter description in a Genicam compatible XML format.
const char *const Fg_getParameterName (Fg_Struct *fg, int index)
 The function Fg_getParameterName() informs about the name of a special parameter by index.
const char *const Fg_getParameterNameById (Fg_Struct *fg, const unsigned int id, const unsigned int dma)
 The function Fg_getParameterNameById() informs about the name of a parameter by its id.
int Fg_getParameterWithType (Fg_Struct *Fg, const int Parameter, void *Value, const unsigned int DmaIndex, const enum FgParamTypes type)
 Getting frame grabber parameters with type information.
int Fg_loadConfig (Fg_Struct *Fg, const char *Filename)
 Loading a frame grabber configuration.
int Fg_loadFieldParameterFromFile (Fg_Struct *Fg, const int Parameter, const unsigned int DmaIndex, const char *FileName)
 Loading field parameter from file.
int Fg_registerAsyncNotifyCallback (Fg_Struct *Fg, Fg_AsyncNotifyFunc_t handler, void *context)
 register callback for asynchronous notifications
int Fg_resetAsyncNotify (Fg_Struct *Fg, unsigned long notification, unsigned long pl, unsigned long ph)
 acknowledge an asynchronous notifications
int Fg_saveConfig (Fg_Struct *Fg, const char *Filename)
 Saving a frame grabber configuration.
int Fg_saveFieldParameterToFile (Fg_Struct *Fg, const int Parameter, const unsigned int DmaIndex, const char *FileName)
 Saving applet field parameter.
int Fg_sendSoftwareTrigger (Fg_Struct *Fg, const unsigned int CamPort)
 send trigger signal to the camera
int Fg_sendSoftwareTriggerEx (Fg_Struct *Fg, const unsigned int CamPort, const unsigned int Triggers)
 send multiple trigger signals to the camera
int Fg_setExsync (Fg_Struct *Fg, int Flag, const unsigned int CamPort)
 set Exsync camera signal
int Fg_setFlash (Fg_Struct *Fg, int Flag, const unsigned int CamPort)
 set strobe camera signal
int Fg_setParameter (Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex)
 Setting frame grabber parameters.
int Fg_setParameterWithType (Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex, const enum FgParamTypes type)
 Setting frame grabber parameters with type information.
int Fg_unregisterAsyncNotifyCallback (Fg_Struct *Fg, Fg_AsyncNotifyFunc_t handler, void *context)
 unregister callback for asynchronous notifications
const char *const getErrorDescription (int ErrorNumber)
 Description of error message.
int getLastErrorNumber ()
 stub to maintain interface compatibility
Library initialization and release

These functions will initialize the library. Calling these functions is completely optional, but can speed up enumeration of devices in certain circumstances significantly. Note however, that if you call Fg_InitLibraries(), you must also call Fg_FreeLibraries.

void Fg_AbortInitLibraries ()
 The function Fg_AbortInitLibraries() aborts and fails the initialization of internal structures and the synchronization of the startup of the application(s).
void Fg_FreeLibraries ()
 The function Fg_FreeLibraries() releases internal structures of the library.
int Fg_InitLibraries (const char *sisoDir)
 The function Fg_InitLibraries() initializes internal structures of the library.
int Fg_InitLibrariesEx (const char *sisoDir, unsigned int flags, const char *id, unsigned int timeout)
 The function Fg_InitLibrariesEx() initializes internal structures of the library and synchronizes the startup of the application(s).
void Fg_InitLibrariesStartNextSlave ()
 The function Fg_InitLibrariesStartNextSlave() signals the next slave process to start.
Acquisition control

These functions control sending and receiving data frames to and from the device. The memory used to transfer the frames needs to be allocated with functions from the Memory Management section first.

int Fg_Acquire (Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount)
 Starting image grabbing.
int Fg_AcquireEx (Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount, const int nFlag, dma_mem *memHandle)
 Starting image grabbing.
frameindex_t Fg_getImage (Fg_Struct *Fg, const int Param, const frameindex_t PicNr, const unsigned int DmaIndex, const unsigned int Timeout)
 Getting the image.
frameindex_t Fg_getImageEx (Fg_Struct *Fg, const int Param, const frameindex_t PicNr, const unsigned int DmaIndex, const unsigned int Timeout, dma_mem *pMem)
 Getting the image.
void * Fg_getImagePtr (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex)
 Access on frame buffer.
void * Fg_getImagePtrEx (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, dma_mem *pMem)
 Access on frame buffer.
frameindex_t Fg_getLastPicNumber (Fg_Struct *Fg, const unsigned int DmaIndex)
 Requesting the current image number (non-blocking).
frameindex_t Fg_getLastPicNumberBlocking (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, const int Timeout)
 Requesting the current image number (blocking).
frameindex_t Fg_getLastPicNumberBlockingEx (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, const int Timeout, dma_mem *pMem)
 Requesting the current image number (blocking).
frameindex_t Fg_getLastPicNumberEx (Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *pMem)
 Requesting the current image number (non-blocking).
int Fg_registerApcHandler (Fg_Struct *Fg, const unsigned int DmaIndex, const struct FgApcControl *control, enum FgApcControlFlags flags)
 Register an APC handler for the given DMA channel.
int Fg_sendImage (Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex)
 Sending images from Software to the applet.
int Fg_sendImageEx (Fg_Struct *Fg, const frameindex_t startImage, const frameindex_t PicCount, const int nFlag, const unsigned int DmaIndex, dma_mem *memHandle)
 Sending images from Software to the applet.
int Fg_stopAcquire (Fg_Struct *Fg, const unsigned int DmaIndex)
 Stopping image grabbing.
int Fg_stopAcquireEx (Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *memHandle, int nFlag)
 Stopping image grabbing.
Events

These functions offer notifications about certain conditions like level change of the CameraLink FVAL signal. The available events depend on applet and board type.

int Fg_activateEvents (Fg_Struct *Fg, uint64_t mask, const unsigned int enable)
 activates/disable event generation
int Fg_clearEvents (Fg_Struct *Fg, uint64_t mask)
 drop all already queued events
uint64_t Fg_eventWait (Fg_Struct *Fg, uint64_t mask, unsigned int timeout, const unsigned int flags, struct fg_event_info *info)
 wait for events
int Fg_getEventCount (Fg_Struct *Fg)
 get the number of available event types
uint64_t Fg_getEventMask (Fg_Struct *Fg, const char *name)
 get the event mask for the named event
const char *const Fg_getEventName (Fg_Struct *Fg, uint64_t mask)
 get the name for the event represented by the event mask
int Fg_getEventPayload (Fg_Struct *Fg, uint64_t mask)
 get the payload size for the event represented by the event mask
int Fg_registerEventCallback (Fg_Struct *Fg, uint64_t mask, Fg_EventFunc_t handler, struct fg_event_data *data, const unsigned int flags, struct fg_event_info *info)
 register callback for events
Device and Applet Information

These functions will return static information of the given device or applet or combination thereof. Calling these functions again on the same input will usually return the same information again.

Fg_AppletIteratorItem Fg_addAppletIteratorItem (Fg_AppletIteratorType iter, const char *path, int *numItems)
 Add an applet to applet iterator.
Fg_AppletIteratorItem Fg_findAppletIteratorItem (Fg_AppletIteratorType iter, const char *path)
 Looks for an item from applet iterator matching the applet path, file, or name.
int Fg_freeAppletIterator (Fg_AppletIteratorType iter)
 This function releases an applet iterator.
int Fg_getAppletId (Fg_Struct *Fg, const char *ignored)
 Get the ID of the currently running applet.
int64_t Fg_getAppletIntProperty (Fg_AppletIteratorItem item, const enum FgAppletIntProperty property)
 Gets an integer applet properties.
int Fg_getAppletIterator (int boardIndex, const enum FgAppletIteratorSource src, Fg_AppletIteratorType *iter, int flags)
 Gets an applet iterator.
Fg_AppletIteratorItem Fg_getAppletIteratorItem (Fg_AppletIteratorType iter, int index)
 Gets an item from applet iterator by index.
const char * Fg_getAppletStringProperty (Fg_AppletIteratorItem item, const enum FgAppletStringProperty property)
 Gets string applet properties.
const char * Fg_getAppletVersion (Fg_Struct *Fg, int AppletId)
 Get the version of the currently running applet.
const char * Fg_getBoardNameByType (const int BoardType, const int UseShortName)
 Board name from type.
int Fg_getBoardType (int BoardIndex)
 Board type.
int Fg_getParameterProperty (Fg_Struct *Fg, const int parameterId, const enum FgProperty propertyId, void *buffer, int *bufLen)
 query the properties of a given parameter
int Fg_getParameterPropertyEx (Fg_Struct *Fg, const int parameterId, const enum FgProperty propertyId, const int DmaIndex, void *buffer, int *bufLen)
 query the properties of a given parameter
unsigned int Fg_getSerialNumber (Fg_Struct *Fg)
 Serial number.
frameindex_t Fg_getStatus (Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex)
 Reading the status of frame buffer.
frameindex_t Fg_getStatusEx (Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex, dma_mem *pMem)
 Reading the status of frame buffer.
const char *const Fg_getSWVersion ()
 Software version number.
int Fg_getSystemInformation (Fg_Struct *Fg, const enum Fg_Info_Selector selector, const enum FgProperty propertyId, int param1, void *buffer, unsigned int *bufLen)
 query information about the overall framegrabber setup
int Fg_readUserDataArea (Fg_Struct *Fg, const int boardId, const unsigned int offs, const unsigned int size, void *buffer)
 read user data area
int Fg_setStatus (Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex)
 Setting the status of frame buffer.
int Fg_setStatusEx (Fg_Struct *Fg, const int Param, const frameindex_t Data, const unsigned int DmaIndex, dma_mem *pMem)
 Setting the status of frame buffer.
int Fg_writeUserDataArea (Fg_Struct *Fg, const int boardId, const unsigned int offs, const unsigned int size, const void *buffer)
 write user data area
Memory Management

These functions allow fine grained control about the memory used to transfer data to and from the frame grabber.

int Fg_AddMem (Fg_Struct *Fg, void *pBuffer, const size_t Size, const frameindex_t bufferIndex, dma_mem *memHandle)
 Adding user memory.
void * Fg_AllocMem (Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt, const unsigned int DmaIndex)
 The function Fg_AllocMem() reserves a defined area of the user memory as frame grabber memory and blocks it in the system memory.
dma_memFg_AllocMemEx (Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)
 The function Fg_AllocMemEx() reserves an area of the main memory as frame buffer, blocks it and makes it available for the user.
dma_memFg_AllocMemHead (Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)
 Use an allocated user memory as frame buffer.
int Fg_DelMem (Fg_Struct *Fg, dma_mem *memHandle, const frameindex_t bufferIndex)
 Deleting user memory,.
int Fg_FreeMem (Fg_Struct *Fg, const unsigned int DmaIndex)
 Releasing a frame buffer.
int Fg_FreeMemEx (Fg_Struct *Fg, dma_mem *mem)
 Releasing frame buffers.
int Fg_FreeMemHead (Fg_Struct *Fg, dma_mem *memHandle)
 Releasing memory.
void * Fg_NumaAllocDmaBuffer (Fg_Struct *Fg, size_t Size)
 NUMA aware allocation of memory.
int Fg_NumaFreeDmaBuffer (Fg_Struct *Fg, void *Buffer)
 NUMA aware freeing of memory.
int Fg_NumaPinThread (Fg_Struct *Fg)
 NUMA aware pinning of thread affinity.
Shading Correction

These functions can only be used with acquisition applets that offer shading functionality.
VisualApplets generated applets with shading functionality do not use this interface. Please refer
to the VisualApplets operator manual for documentation of that shading interface.
ShadingMasterFg_AllocShading (Fg_Struct *Fg, int set, const unsigned int CamPort)
 allocate shading control object
int Fg_FreeShading (Fg_Struct *Fg, ShadingMaster *sh)
 release shading control object
int Shad_FreeAccess (Fg_Struct *Fg, ShadingMaster *sh)
 deactivate shading object
int Shad_GetAccess (Fg_Struct *Fg, ShadingMaster *sh)
 activate shading object
int Shad_GetMaxLine (Fg_Struct *Fg, ShadingMaster *sh)
 query current line number for shading correction
int Shad_SetFixedPatternNoiseLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, int on)
 set defective pixel interpolation value for shading correction
int Shad_SetMultValueLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, float mult)
 set multiplicative correction value for shading correction
int Shad_SetSubValueLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, float sub)
 set substractive correction value for shading correction
int Shad_WriteActLine (Fg_Struct *Fg, ShadingMaster *sh, int Line)
 write shading correction values for given line
Board initialization and release

These functions will initialize the requested device. They need to be called before any other operation on the device can be performed. The only functions that can be called independent of the device are some functions to query software or device information.

int Fg_findApplet (const unsigned int BoardIndex, char *Path, size_t Size)
 The function Fg_findApplet() returns the file name of the currently active applet for ME5 board.
int Fg_FreeGrabber (Fg_Struct *Fg)
 Releasing frame grabber resources.
Fg_StructFg_Init (const char *FileName, unsigned int BoardIndex)
 The function Fg_Init() initializes the frame grabber.
Fg_StructFg_InitConfig (const char *Config_Name, unsigned int BoardIndex)
 The function Fg_InitConfig() initializes the frame grabber and loads a parameter file (microEnable configuration file *.mcf).
Fg_StructFg_InitConfigEx (const char *Config_Name, unsigned int BoardIndex, int flags)
 The function Fg_InitConfigEx() initializes the frame grabber in master or slave mode and loads a parameter file (microEnable configuration file *.mcf).
Fg_StructFg_InitEx (const char *FileName, unsigned int BoardIndex, int flags)
 Initialize a frame grabber in master or slave mode.

Detailed Description

Header file for all functions exported.

fgrab_prototyp.h

Copyright (c) 2002-2017 Silicon Software GmbH, All Rights Reserved.

Author:
Silicon Software GmbH

Typedef Documentation

DMA buffer head control object.

A variable of this type contains the control information for DMA buffers. Take this as an opaque value and just pass it around to the functions that need it.

Shading control object.

A variable of this type contains the control information for a specific shading set. Take this as an opaque value and just pass it around to the functions that need it.


Function Documentation

void Fg_AbortInitLibraries (  ) 

The function Fg_AbortInitLibraries() aborts and fails the initialization of internal structures and the synchronization of the startup of the application(s).

This function aborts the initialization of internal structures in the library and interrupts any pending synchronization that is requested by the user calling Fg_InitLibraries() or Fg_InitLibrariesEx(). This function can be called from within a signal handler or any other mechanism that terminates the application asynchronously to make sure the main thread will not hang indefinitely. If the call to Fg_InitLibraries() or Fg_InitLibrariesEx() was aborted, those functions will return FG_OPERATION_ABORTED.

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

Starting image grabbing.

The function Fg_Acquire() starts a continuous grabbing. Having started the exact number of images will be grabbed (PicCount). 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()), the maximum image number has to be set to GRAB_INFINITE. When all buffers should be used exactly once GRAB_ALL_BUFFERS can be used. This is equivalent to passing the buffer count.

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

The grabbing mode is set to ACQ_STANDARD. The image memory is used as a ring buffer and all subbuffer will be overwritten cyclically.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
PicCount Maximum number of images to be grabbed, GRAB_INFINITE, means infinite grabbing.
Return values:
FG_OK Grabbing has been started correctly. (when grabbing synchronously also finished correctly).
FG_NOT_INIT Frame grabber was not initialised correctly.
FG_NO_VALID_DESIGN No valid design was loaded.
FG_INVALID_MEMORY Image memory was not allocated.
FG_MEMORY_IN_USE Image memory is already used by another DMA channel.
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.
int Fg_AcquireEx ( Fg_Struct Fg,
const unsigned int  DmaIndex,
const frameindex_t  PicCount,
const int  nFlag,
dma_mem memHandle 
)

Starting image grabbing.

The function Fg_AcquireEx() starts a continuous grabbing. Having started the exact number of images will be grabbed (PicCount). 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_stopAcquireEx()), the maximum image number has to be set to GRAB_INFINITE. When all buffers should be used exactly once GRAB_ALL_BUFFERS can be used. This is equivalent to passing the buffer count.

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 chosen, the acquired frame buffer is blocked as long as it is explicitly 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.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
PicCount Maximum number of images to be grabbed, GRAB_INFINITE, means infinite grabbing.
nFlag ACQ_STANDARD, ACQ_BLOCK
memHandle Pointer to handle of frame buffer.
Return values:
FG_OK Grabbing has been started correctly. (when grabbing synchronously also finished correctly).
FG_NOT_INIT Frame grabber was not initialised correctly.
FG_INVALID_MEMORY Image memory was not allocated.
FG_MEMORY_IN_USE Image memory is already used by another DMA channel.
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.
FG_ILLEGAL_WHILE_APC An APC from a previous acquisition is still active
int Fg_activateEvents ( Fg_Struct Fg,
uint64_t  mask,
const unsigned int  enable 
)

activates/disable event generation

Parameters:
Fg frame grabber to use
mask event mask to work on
enable 0 to disable, 1 to enable
Return values:
FG_NOT_INIT Fg is NULL
FG_INVALID_PARAMETER enable is not 0 or 1 or mask is not a valid event mask
Since:
5.1.2

mask may only contain valid event bits. As an exception it is allowed to pass a value where all bits are set (i.e. (uint64_t)-1) and enable set to 0 to disable all events which is explicitly allowed even if there are less than 64 events.

Fg_AppletIteratorItem Fg_addAppletIteratorItem ( Fg_AppletIteratorType  iter,
const char *  path,
int *  numItems 
)

Add an applet to applet iterator.

This function add an applet to applet iterator

Parameters:
iter Applet iterator
path Path, file or name of the applet
numItems Number of all applet in iterator
Returns:
Applet iterator item or NUll in case of an error
int Fg_AddMem ( Fg_Struct Fg,
void *  pBuffer,
const size_t  Size,
const frameindex_t  bufferIndex,
dma_mem memHandle 
)

Adding user memory.

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 memory limits depend on several factors, including but not limited to the amount of memory installed in the computer and operating system used.

Parameters:
Fg frame grabber to use
pBuffer Pointer to user memory to be added.
Size Size of user memory in byte.
bufferIndex Index of subbuffer to add (range 0 to BufCnt as passed to Fg_AllocMemHead())
memHandle Pointer to the handle on frame buffer.
Returns:
Index of subbuffer.
Return values:
FG_INVALID_PARAMETER An invalid parameter has been used.
void* Fg_AllocMem ( Fg_Struct Fg,
const size_t  Size,
const frameindex_t  BufCnt,
const unsigned int  DmaIndex 
)

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. Existent images will be overwritten.

Allocated memory can be released with Fg_FreeMem().

Please note, that there are memory limits existing!

Parameters:
Fg frame grabber to use
Size Size of all image memory in byte.
BufCnt Number of internal buffer. Value must be 2, when using double-buffering.
DmaIndex Logical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Returns:
A pointer to the allocated frame memory / image data.
Return values:
NULL An error occured. Use Fg_getLastErrorDescription() for more information.
dma_mem* Fg_AllocMemEx ( Fg_Struct Fg,
const size_t  Size,
const frameindex_t  BufCnt 
)

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(). The returned pointer represents the administrative data structure for all frame buffers.

Please note, that there are memory limits existing!

Parameters:
Fg frame grabber to use
Size Size of all image memory in byte.
BufCnt Number of subbuffers.
Returns:
A pointer to the allocated memory.
Return values:
NULL An error occured. Use Fg_getLastErrorDescription() for more information.
dma_mem* Fg_AllocMemHead ( Fg_Struct Fg,
const size_t  Size,
const frameindex_t  BufCnt 
)

Use an allocated user memory as frame buffer.

To transfer frames into user provided memory these memory areas have to be announced to the framegrabber system. Fg_AllocMemHead() creates the internal control stuctures to handle these memory. Afterwards you have to add the different memory buffers using Fg_AddMem(). Single buffers can be released with Fg_DelMem() from the buffer as long as this buffer is not currently used for frame transfer. The control structure must be released with Fg_FreeMemHead().

Please see the chapter "General memory limits" in the framegrabber documentation for general restrictions about the usable memory.

 #define BUFFERS 4
 #define BUFFERSIZE (1024 * 1024)
 char buf[BUFFERS + 1][BUFFERSIZE];

 dma_mem *mhead = Fg_AllocMemHead(Fg, BUFFERSIZE * BUFFERS, BUFFERS);
 if (mhead == NULL)
        ...

 for (int i = 0; i < BUFFERS; i++) {
        int ret = Fg_AddMem(Fg, buf[i], BUFFERSIZE, i, mhead);
        if (ret < 0)
                ...
 }

 // replace buf[0] with buf[4] for frame transfer
 Fg_DelMem(Fg, mhead, 0);
 Fg_AddMem(Fg, buf[BUFFERS], BUFFERSIZE, 0, mhead);

 Fg_AcquireEx(Fg, ..., mhead);

 Fg_FreeMemHead(Fg, mhead);
Parameters:
Fg frame grabber to use
Size Size of all image memory in byte.
BufCnt Number of subbuffers.
Returns:
A valid handle on frame buffer.
Return values:
NULL An error has occured. Use Fg_getLastErrorDescription() for more information.A return value of FG_INVALID_MODULO indicates, that the requested memory size does not match to the requirements.
ShadingMaster* Fg_AllocShading ( Fg_Struct Fg,
int  set,
const unsigned int  CamPort 
)

allocate shading control object

Parameters:
Fg frame grabber to use
set Shading data set to use.
CamPort Camera port to associate this shading buffer.
Returns:
Pointer to shading control object
Return values:
NULL Shading control object was not created as an error occured.

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.

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Fg_clearEvents ( Fg_Struct Fg,
uint64_t  mask 
)

drop all already queued events

Parameters:
Fg frame grabber to use
mask which events to clear
Return values:
FG_NOT_INIT Fg is NULL
FG_INVALID_PARAMETER mask is not a valid event mask

mask may only contain valid event bits. As an exception it is allowed to pass a value where all bits are set (i.e. (uint64_t)-1) to clear all events which is explicitly allowed even if there are less than 64 events.

Since:
5.1.2
int Fg_DelMem ( Fg_Struct Fg,
dma_mem memHandle,
const frameindex_t  bufferIndex 
)

Deleting user memory,.

With the function Fg_DelMem() a user memory area of the image memory management can be removed which has been created with Fg_AllocMemHead() and added with Fg_AddMem() before. The memory area won't be freed, it will only be removed from frame memory queues. Releasing of the memory are is up to the user.

Parameters:
Fg frame grabber to use
memHandle Pointer to the handle on frame buffer.
bufferIndex Index of subbuffers, the user memory should be deleted from.
Return values:
FG_OK User memory has been deleted correctly.
FG_INVALID_PARAMETER An invalid parameter has been used.
uint64_t Fg_eventWait ( Fg_Struct Fg,
uint64_t  mask,
unsigned int  timeout,
const unsigned int  flags,
struct fg_event_info info 
)

wait for events

Parameters:
Fg frame grabber to use
mask event mask
timeout timeout in seconds
flags control flags. Or'ed combination of FgEventControlFlags. In doubt use FG_EVENT_DEFAULT_FLAGS.
info event info structure to fill with additional data, in doubt pass NULL
Returns:
mask of triggered events or 0 on error
Return values:
0 an error occurred

You must not call this function and Fg_registerEventCallback() on the same event.

If 0 is returned Fg_getLastErrorNumber() will return the information about the error type. Usually this will be FG_TIMEOUT_ERR.

The event mask can be obtained by calling Fg_getEventMask(). Several masks may be or'ed together to wait for the first of those events to happen. The return value states which events actually happened. If an info structure is passed the corresponding entries for those events will have the requested data filled in. The entries of all other events are left untouched.

You are strongly encouraged to call FG_EVENT_INFO_INIT(info) before every call to Fg_eventWait() if you are using the info parameter to make sure you don't see old data in the structure.

Since:
5.1.0
int Fg_findApplet ( const unsigned int  BoardIndex,
char *  Path,
size_t  Size 
)

The function Fg_findApplet() returns the file name of the currently active applet for ME5 board.

The applet file is searched within the active Silicon Software Runtime environment (e.g. SISODIR5) If the applet file name exceeds the size of the buffer of returning the information, FG_NOT_ENOUGH_MEMORY is returned. This function can be used only with ME5 boards. Otherwise, FG_INVALID_BOARD_NUMBER is returned.

Parameters:
BoardIndex Logical number of the board.
Path Buffer for returned string
Size Size of the buffer in bytes
Returns:
name of the applet as a 0 terminated string.
Return values:
FG_OK success, Path contains the applet path
FG_INVALID_PARAMETER buffer or buffer size are invalid
FG_INVALID_BOARD_NUMBER invalid board number (or board type)
FG_DLL_NOT_LOAD unknown board type
FG_SISODIR5_NOT_SET no search path available
FG_NOT_ENOUGH_MEMORY applet file name exceeds the size of the buffer
Fg_AppletIteratorItem Fg_findAppletIteratorItem ( Fg_AppletIteratorType  iter,
const char *  path 
)

Looks for an item from applet iterator matching the applet path, file, or name.

This function gets an identifier for the n-th applet in the iterator Identifier can then be used to get different applet properties.

Parameters:
iter applet iterator
path path, file or name of the applet
Returns:
the applet iterator item, or NULL if no matching item was found
See also:
Fg_getAppletIntProperty
Fg_getAppletStringProperty
int Fg_freeAppletIterator ( Fg_AppletIteratorType  iter  ) 

This function releases an applet iterator.

Parameters:
iter The iterator to be released
See also:
Fg_getAppletIterator
int Fg_FreeGrabber ( Fg_Struct Fg  ) 

Releasing frame grabber resources.

The function Fg_FreeGrabber() stops the operating frame grabber and releases the resources. Either, an already allocated frame buffer 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.

Parameters:
Fg frame grabber to release
Return values:
FG_OK The operating frame grabber has been stopped successfully.
FG_NOT_INIT Frame grabber has not been initialized correctly.
FG_FILE_NOT_FOUND The file cannot be found
FG_INVALID_FILENAME The filename is not a valid filename
FG_SISODIR5_NOT_SET The environment variable SISODIR5 is not set
FG_NOT_ENOUGH_MEM The system memory is insufficient for loading control structures
FG_CANNOT_INIT_MICROENABLE The frame grabber cannot be initialized
FG_HAP_FILE_NOT_LOAD The Applet file (HAP file) is not a valid HAP file
void Fg_FreeLibraries (  ) 

The function Fg_FreeLibraries() releases internal structures of the library.

This function releases all internal structures that were initialized by a successful call to Fg_InitLibraries(). It is recommended to call this function just before the program leaves the main() method, or exits in any other way.

int Fg_FreeMem ( Fg_Struct Fg,
const unsigned int  DmaIndex 
)

Releasing a frame buffer.

The function Fg_FreeMem() stops the frame grabber and releases the used memory which has been allocated with Fg_AllocMem() before.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values:
FG_OK Image memory has been released successfully.
FG_NOT_INIT A failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVE Transfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.
int Fg_FreeMemEx ( Fg_Struct Fg,
dma_mem mem 
)

Releasing frame buffers.

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

Parameters:
Fg frame grabber to use
mem Handle on memory area which has been reserved with with Fg_AllocMemEx().
Return values:
FG_OK Image memory has been released successfully.
FG_NOT_INIT A failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVE Transfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.
int Fg_FreeMemHead ( Fg_Struct Fg,
dma_mem memHandle 
)

Releasing memory.

The function Fg_FreeMemHead() releases a handle on a frame buffer that has been added with Fg_AllocMemHead(). 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 remove the frame memory using Fg_DelMem() before calling this function as they will automatically be removed.

Please note that this function will only remove the internal control structures and will not free the memory passed to Fg_AddMem().

Parameters:
Fg frame grabber to use
memHandle Handle on memory area, which has been reserved by Fg_AllocMemEx() or Fg_AllocMemHead().
Return values:
FG_OK Image memory has been released successfully.
FG_NOT_INIT A failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVE Transfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.
int Fg_freeParameterStringWithType ( Fg_Struct Fg,
const int  Parameter,
void *  Value,
const unsigned int  DmaIndex,
const enum FgParamTypes  type 
)

Release previously allocated frame grabber string parameter.

Parameters:
Fg The frame grabber handle
Parameter The parameter ID
Value A pointer to the variable for the value
DmaIndex The DMA, frame grabber port, or applet process index
type The parameter type

This function releases the value from a string paramater that was previously allocated through a call to Fg_getParameterWithType with type FG_PARAM_TYPE_CHAR_PTR_PTR. All parameters must match the previous call to Fg_getParameterWithType(), except for the value pointer, which must be the char pointer to be released (and not a pointer to the char pointer).

int Fg_FreeShading ( Fg_Struct Fg,
ShadingMaster sh 
)

release shading control object

Parameters:
Fg frame grabber to use
sh Shading control object to release.
Returns:
Status code.
Return values:
FG_OK Shading control object was released.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).
 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Fg_getAppletId ( Fg_Struct Fg,
const char *  ignored 
)

Get the ID of the currently running applet.

Parameters:
Fg frame grabber to use
ignored should be NULL
Returns:
the applet ID of the design if it is not a design created using VisualApplets.

See fgrab_define.h for the list of ids.

The second parameter is only there to be compatible with earlier software interfaces. It is ignored and should be NULL.

int64_t Fg_getAppletIntProperty ( Fg_AppletIteratorItem  item,
const enum FgAppletIntProperty  property 
)

Gets an integer applet properties.

This function gets an integer property of an applet. Different properties are available within enum FgAppletIntProperty. Before getting any property, FG_AP_INT_INFO property must be read to make sure that other properties are valid, using FG_AI_IS_VALID mask. If FG_AI_IS_VALID is not set, then all other properties are not valid. The applet item should be retrieved from an Fg_AppletIterator using function Fg_getAppletIteratorItem.

Parameters:
item Applet item that is retrieved from Fg_getAppletIteratorItem
property Selected property
Returns:
integer value corresponding to the passed property
int Fg_getAppletIterator ( int  boardIndex,
const enum FgAppletIteratorSource  src,
Fg_AppletIteratorType iter,
int  flags 
)

Gets an applet iterator.

This function gets an applet iterator for the applets on either the board or the filesystem Once not needed any more, the function Fg_freeAppletIterator() must be called to free the iterator.

Parameters:
boardIndex Board index
src Applets' source.
iter A pointer to return the iterator
flags Can be used to filter the applets according to Applet Flags.
FlagMeaning
FG_AF_IS_AVAILABLEApplet is available on the filesystem.
FG_AF_IS_CORRECT_PLATFORMApplet has the correct platform (E.g. Win 32/64 or Linux 32/64 Bit).
FG_AF_IS_VALID_LICENSEApplet has a valid license.
FG_AF_IS_ACTIVEApplet is currently active on the board.
FG_AF_IS_LOADABLEApplet can be loaded via Fg_Init.
FG_AF_IS_POWERUP_APPLETApplet is loaded when the system powers up.
FG_AF_IS_COMPATIBLEThis file is compatible with the flashed design (same FPGA UUID).
FG_AF_IS_FLASHEDThis exact file is flashed (same FPGA & APPLET UUID).
Returns:
the number of items found, or a negative value in case of an error
See also:
Fg_freeAppletIterator
Fg_getAppletIteratorItem
Fg_AppletIteratorItem Fg_getAppletIteratorItem ( Fg_AppletIteratorType  iter,
int  index 
)

Gets an item from applet iterator by index.

This function gets an identifier for the n-th applet in the iterator Identifier can then be used to get different applet properties.

Parameters:
iter applet iterator
index index of the applet
Returns:
the applet iterator item, or NULL if index is negative or larger than or equal to the iterator size.
See also:
Fg_getAppletIntProperty
Fg_getAppletStringProperty
const char* Fg_getAppletStringProperty ( Fg_AppletIteratorItem  item,
const enum FgAppletStringProperty  property 
)

Gets string applet properties.

This function gets a string property of an applet. Different properties are available within enum FgAppletStringProperty. Before getting any property, FG_AP_INT_INFO property must be read (using Fg_getAppletIntProperty) to make sure that other properties are valid, using FG_AI_IS_VALID mask. If FG_AI_IS_VALID is not set, then all other properties are not valid. The applet item should be retrieved from an Fg_AppletIterator using function Fg_getAppletIteratorItem.

Parameters:
item applet item that is retrieved from Fg_getAppletIteratorItem
property selected property
Returns:
string value corresponding to the passed property
const char* Fg_getAppletVersion ( Fg_Struct Fg,
int  AppletId 
)

Get the version of the currently running applet.

Parameters:
Fg frame grabber to use
AppletId The applet ID returned by Fg_getappletId()
Returns:
the applet version of the design if it is not a design created using VisualApplets.

See fgrab_define.h for the list of ids.

int Fg_getBitsPerPixel ( int  format  ) 

Calculate the bits per pixel for a specific output format (FG_GRAY, FG_COL24, etc.).

Parameters:
format the output format
Returns:
The bits per pixel of the output format. FG_INVALID_PARAMETER if the pixelsize can not be derived from the format or the format is invalid or unknown.
const char* Fg_getBoardNameByType ( const int  BoardType,
const int  UseShortName 
)

Board name from type.

Fg_getBoardNameByType() returns the name for the type of board.

Parameters:
BoardType type of the board
UseShortName get the short name for the board
Return values:
NULL there is no board with the given type

See sisoboards.h for the board type definitions.

int Fg_getBoardType ( int  BoardIndex  ) 

Board type.

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.

Parameters:
BoardIndex index of the board
Return values:
FG_ERROR there is no board with the given index

See sisoboards.h for the board type definitions.

If you already have initialized the board use

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

Description of error message to an error code.

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

Parameters:
Fg frame grabber to use
ErrorNumber Identification number of error code.
Returns:
Error message of the error code specified
int Fg_getEventCount ( Fg_Struct Fg  ) 

get the number of available event types

Parameters:
Fg frame grabber to use
Returns:
number of available event types.

This function returns the number of available event types depending on the currently loaded applet. It may be used for querying purposes

Since:
5.2
uint64_t Fg_getEventMask ( Fg_Struct Fg,
const char *  name 
)

get the event mask for the named event

Parameters:
Fg frame grabber to use
name name of the requested event
Returns:
event mask of the event
Return values:
0 no event of the given name was found
Since:
5.1.0
const char* const Fg_getEventName ( Fg_Struct Fg,
uint64_t  mask 
)

get the name for the event represented by the event mask

Parameters:
Fg frame grabber to use
mask event mask
Returns:
name of event if any, NULL pointer if no event is associated with that name

Only one bit in the event mask may be set.

Since:
5.1.0
int Fg_getEventPayload ( Fg_Struct Fg,
uint64_t  mask 
)

get the payload size for the event represented by the event mask

Parameters:
Fg frame grabber to use
mask event mask
Returns:
size of payload of event if any, FG_INVALID_EVENTMASK or FG_NO_EVENTS_FOUND on error

Only one bit in the event mask may be set.

Since:
5.5.1
frameindex_t Fg_getImage ( Fg_Struct Fg,
const int  Param,
const frameindex_t  PicNr,
const unsigned int  DmaIndex,
const unsigned int  Timeout 
)

Getting the image.

After image acquisition, the buffer number of an image can be explicitly gotten by the help of the function Fg_getImage(). 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().

ParamMeaning
SEL_NEW_IMAGESelection of current acquired image (running process).
SEL_ACT_IMAGESelection of last acquired image.
SEL_NEXT_IMAGESelection of next image after last get image.
SEL_NUMBERSelection of an image by image number, not available in blocking mode!
Parameters:
Fg frame grabber to use
Param See table below ...
PicNr 0 in blocking mode, image number in default grabbing mode.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Timeout Duration of timeout in seconds.
Returns:
Buffer number, beginning with 0.
Return values:
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.
frameindex_t Fg_getImageEx ( Fg_Struct Fg,
const int  Param,
const frameindex_t  PicNr,
const unsigned int  DmaIndex,
const unsigned int  Timeout,
dma_mem pMem 
)

Getting the image.

After image acquisition, the buffer number of an image can be explicitly gotten by the help of the function 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_getImagePtrEx().

ParamMeaning
SEL_NEW_IMAGESelection of current acquired image (running process).
SEL_ACT_IMAGESelection of last acquired image.
SEL_NEXT_IMAGESelection of next image after last get image.
SEL_NUMBERSelection of an image by image number, not available in blocking mode!
Parameters:
Fg frame grabber to use
Param See table below ...
PicNr 0 in blocking mode, image number in default grabbing mode.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Timeout Duration of timeout in seconds.
pMem Pointer to variable buffer.
Returns:
Buffer number, beginning with 0.
Return values:
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.
void* Fg_getImagePtr ( Fg_Struct Fg,
const frameindex_t  PicNr,
const unsigned int  DmaIndex 
)

Access on frame buffer.

With the function Fg_getImagePtr() 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.

Parameters:
Fg frame grabber to use
PicNr Number of frame buffer or picture number.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Returns:
Pointer to current image position.
void* Fg_getImagePtrEx ( Fg_Struct Fg,
const frameindex_t  PicNr,
const unsigned int  DmaIndex,
dma_mem pMem 
)

Access on frame buffer.

With the function 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.

Parameters:
Fg frame grabber to use
PicNr Number of frame buffer or picture number.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
pMem Pointer to variable buffer.
Returns:
Pointer to current image position.
const char* const Fg_getLastErrorDescription ( Fg_Struct Fg  ) 

Description of last error message.

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

Parameters:
Fg frame grabber to use
Returns:
The message of the last error that occurred.

This function is equivalent to getErrorDescription(Fg_getLastErrorNumber(Fg)).

int Fg_getLastErrorNumber ( Fg_Struct Fg  ) 

Getting the last error code.

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

Parameters:
Fg frame grabber to use
Returns:
The number of the last error that occurred.
frameindex_t Fg_getLastPicNumber ( Fg_Struct Fg,
const unsigned int  DmaIndex 
)

Requesting the current image number (non-blocking).

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

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Returns:
Number of the last completely transferred image, transmission is running.
Return values:
0 Transmission is running, no image has been completely transfered, yet.
FG_TIMEOUT_ERR Timeout occurs.
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
frameindex_t Fg_getLastPicNumberBlocking ( Fg_Struct Fg,
const frameindex_t  PicNr,
const unsigned int  DmaIndex,
const int  Timeout 
)

Requesting the current image number (blocking).

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

In contrary to Fg_getLastPicNumber() 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 be 1, if no error occurs.

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

Parameters:
Fg frame grabber to use
PicNr Requested image number.
DmaIndex Logical number of used camera port camera port A = 0 and camera port B = 1
Timeout Timeout in seconds.
Returns:
Current image number, beginning with 1.
Return values:
FG_TIMEOUT_ERR Timeout error occurred.
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
frameindex_t Fg_getLastPicNumberBlockingEx ( Fg_Struct Fg,
const frameindex_t  PicNr,
const unsigned int  DmaIndex,
const int  Timeout,
dma_mem pMem 
)

Requesting the current image number (blocking).

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

In contrary to 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 be 1, if no error occurs.

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

Parameters:
Fg frame grabber to use
PicNr Requested image number.
DmaIndex Logical number of used camera port camera port A = 0 and camera port B = 1
Timeout Timeout in seconds.
pMem Pointer to variable buffer.
Returns:
Current image number, beginning with 1.
Return values:
FG_TIMEOUT_ERR Timeout error occurred.
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
frameindex_t Fg_getLastPicNumberEx ( Fg_Struct Fg,
const unsigned int  DmaIndex,
dma_mem pMem 
)

Requesting the current image number (non-blocking).

The number of the last, completely transferred image can be requested with a non-blocking call of 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.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
pMem Pointer to variable buffer.
Returns:
Number of the last completely transferred image, transmission is running.
Return values:
0 Transmission is running, no image has been completely transfered, yet.
FG_TIMEOUT_ERR Timeout occurs.
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
int Fg_getNrOfParameter ( Fg_Struct Fg  ) 

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

Parameters:
Fg frame grabber to use
Returns:
The number of parameters.
Return values:
<0 An error occured. (Use Fg_getLastErrorDescription() for more information.)
int Fg_getParameter ( Fg_Struct Fg,
int  Parameter,
void *  Value,
const unsigned int  DmaIndex 
)

Getting special parameter settings.

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

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

Output TypeFlagDescription
intFG_CAMSTATUSIf a camera signal is on microEnable's physical port, result is 1. If there are two pixel clocks recognized, result is 2. If no camera is connected, result is 0.
intFG_IMAGE_TAGImage tag on a buffer.
intFG_TIMEOUTTime in seconds until device driver displays a timeout of the frame grabber.
intFG_TIMESTAMPThe time stamp.
uint64_tFG_TIMESTAMP_LONGHigh performance time stamp.
size_tFG_TRANSFER_LENReturns the length of the last DMA transfer.
intFG_GLOBAL_ACCESSReturns the value for the set plausibility flag.
Parameters:
Fg frame grabber to use
Parameter The parameter ID. Can be either the value returned by Fg_getParameterId() or Fg_getParameterIdByName() or the ID of a generally available parameter. See table below for generally available parameters ...
Value Pointer to required value.
DmaIndex Logical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values:
FG_OK The parameter value has been read correctly.
FG_NOT_INIT Initialization has failed.
FG_INVALID_PARAMETER An invalid parameter has been entered.
int Fg_getParameterEx ( Fg_Struct Fg,
const int  Parameter,
void *  Value,
const unsigned int  DmaIndex,
dma_mem pMem,
const frameindex_t  ImgNr 
)

Getting special parameter settings.

Fg_getParameterEx() allows querying of values directly related to image transfers. These values are queried from the dma_mem pointer passed as argument. These values are available as long as the buffer memory is still available, i.e. even if the DMA transfer is no longer running or a DMA transfer is running with a different DMA buffer.

As all of these values have special characteristics only a small set of parameter ids may be queried using this interface:

Output TypeParameter idDescription
unsigned intFG_IMAGE_TAGImage tag on a buffer.
unsigned intFG_TIMESTAMPThe time stamp.
uint64_tFG_TIMESTAMP_LONGHigh performance time stamp.
size_tFG_TRANSFER_LENReturns the length of the last DMA transfer.
Parameters:
Fg frame grabber to use
Parameter The parameter ID.
Value Pointer to memory where requested value will be stored.
DmaIndex Ignored, should be 0.
pMem Handle on memory area which has been reserved.
ImgNr Image number to query.
Return values:
FG_OK The parameter value has been read correctly.
FG_NOT_INIT Initialization has failed.
FG_INVALID_PARAMETER An invalid parameter has been entered.
int Fg_getParameterId ( Fg_Struct fg,
int  index 
)

The function Fg_getParameterId() returns the parameter ID of the parameter referenced by index.

The value index is the index of the parameter. Its range is from 0 up to the value returned by Fg_getNrOfParameter() (-1).

Parameters:
fg frame grabber to use
index Parameter index.
Returns:
The parameter ID.
Return values:
<0 The parameter couldn't be found.
int Fg_getParameterIdByName ( Fg_Struct fg,
const char *  name 
)

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

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 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(s) of the box(es) 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, see the following snippet of code:

 int i;
 for (i = 0; i < nrOfParameter; i++) {
        const char *name = Fg_getParameterName(fg, i);
        fprintf(stdout, " Param %d: %s, 0x%x\n", i, name, Fg_getParameterId(fg, i));
 }
Parameters:
fg frame grabber to use
name Full Parameter name.
Returns:
The parameter ID.
Return values:
<0 The parameter couldn't be found.
int Fg_getParameterInfoXML ( Fg_Struct Fg,
int  port,
char *  infoBuffer,
size_t *  infoBufferSize 
)

Get parameter description in a Genicam compatible XML format.

Get Parameter information in XML format

This function delivers information about all parameters in a GenICam compatible XMl format. It can be used together with Genicam tools to access the parameters of an applet. Therefore the parameter ID is handled as an address. Read/write accesses are intended to be done with Fg_getParameter and Fg_setParameter with the delivered address as parameter ID. The buffer is filled with a null-terminated string containing the XML data. To be compliant against XML validation, the terminating 0 needs to be removed, when saving the data to a XML file

Parameters:
Fg frame grabber to use
port Logical number of used camera port. camera port A = 0 and camera port B = 1
infoBuffer Pointer to a buffer where the XML information will be placed.
infoBufferSize Input: The max available space of the infoBuffer in byte. Output: The number of bytes copied into the infoBuffer. In case the infoBuffer is a NULL-pointer the output is the required infoBuffer space in byte.
Return values:
FG_OK The operation was successful.
FG_INTERNAL_ERROR The internal parameter structures are not existing
FG_NOT_ENOUGH_MEM The infoBuffer size contained in infoBufferSize is not sufficient.
const char* const Fg_getParameterName ( Fg_Struct fg,
int  index 
)

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

Parameters:
fg frame grabber to use
index Parameter index.
Returns:
A char pointer to the parameter full name string.
const char* const Fg_getParameterNameById ( Fg_Struct fg,
const unsigned int  id,
const unsigned int  dma 
)

The function Fg_getParameterNameById() informs about the name of a parameter by its id.

Parameters:
fg The frame grabber to use
id Parameter id.
dma The dma, process or port.
Returns:
A char pointer to the parameter full name string.
int Fg_getParameterProperty ( Fg_Struct Fg,
const int  parameterId,
const enum FgProperty  propertyId,
void *  buffer,
int *  bufLen 
)

query the properties of a given parameter

Parameters:
Fg frame grabber to use
parameterId ID of parameter
propertyId property to be queried
buffer pointer to memory for return value
bufLen [in,out] length of the buffer for the return value, returns the length of the needed buffer
Returns:
state of success
Return values:
FG_OK success
<> FG_OK : call fg_getErrorDescription to for details

This function allows to query additional information for a certain parameter like datatype,... The result is basically returned as a string value (null terminated string) In other cases, the type of data buffer has to be declared and a type check will be done internally When passing an null-pointer as buffer, the function will return the length of the needed buffersize (in bytes) to place the contents to.

Note:
PROP_ID_MIN_ID, PROP_ID_MAX_ID, PROP_ID_ACCESS_ID are returning virtual parameter IDs. The values therefore can be retrieved by a call to Fg_GetParameter functions
Since:
5.2.0
int Fg_getParameterPropertyEx ( Fg_Struct Fg,
const int  parameterId,
const enum FgProperty  propertyId,
const int  DmaIndex,
void *  buffer,
int *  bufLen 
)

query the properties of a given parameter

Parameters:
Fg frame grabber to use
parameterId ID of parameter
propertyId property to be queried
DmaIndex the DMA index for the parameter to be queried
buffer pointer to memory for return value
bufLen [in,out] length of the buffer for the return value, returns the length of the needed buffer
Returns:
state of success
Return values:
FG_OK success
<> FG_OK : call fg_getErrorDescription to for details

This function allows to query additional information for a certain parameter like datatype,... The result is basically returned as a string value (null terminated string) In other cases, the type of data buffer has to be declared and a type check will be done internally When passing an null-pointer as buffer, the function will return the length of the needed buffersize (in bytes) to place the contents to.

Note:
PROP_ID_MIN_ID, PROP_ID_MAX_ID, PROP_ID_ACCESS_ID are returning virtual parameter IDs. The values therefore can be retrieved by a call to Fg_GetParameter functions
Since:
5.5.1
int Fg_getParameterWithType ( Fg_Struct Fg,
const int  Parameter,
void *  Value,
const unsigned int  DmaIndex,
const enum FgParamTypes  type 
)

Getting frame grabber parameters with type information.

Parameters:
Fg The frame grabber handle
Parameter The parameter ID
Value A pointer to the variable for the value
DmaIndex The DMA, frame grabber port, or applet process index
type The parameter type

This function behaves like Fg_getParameter() but allows to specify the type of the given value. For compatibility reasons Fg_getParameter() only accepts 32 bit values for integer parameters. If you need to get a 64 bit int parameter you need this function or the upper 32 bit of the passed value will never be changed. Please not that when querying string parameters with type FG_PARAM_TYPE_CHAR_PTR_PTR, value must be a pointer to a char pointer variable. The memory to hold the string will be allocated and must be release using Fg_freeStringParameterWithType() after use.

unsigned int Fg_getSerialNumber ( Fg_Struct Fg  ) 

Serial number.

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

Parameters:
Fg frame grabber to use
Returns:
The serial number of the board. To get the same representation as seen on the board it should be written out in hexadecimal.
frameindex_t Fg_getStatus ( Fg_Struct Fg,
const int  Param,
const frameindex_t  Data,
const unsigned int  DmaIndex 
)

Reading the status of frame buffer.

With the function Fg_getStatus() 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() buffers can be blocked or unblocked.

ParameterMeaning
NUMBER_OF_GRABBED_IMAGESSum of all acquired images. The parameter data will be ignored.
NUMBER_OF_LOST_IMAGESSum of lost images. The parameter data requires the DMA no.
NUMBER_OF_BLOCK_LOST_IMAGESSum of all images, which are lost by blocking of the frame buffer. The parameter data requires the DMA no.
NUMBER_OF_BLOCKED_IMAGESSum of blocked images. The parameter data will be ignored.
NUMBER_OF_ACT_IMAGENumber of last acquired image. The parameter data requires the timeout value.
NUMBER_OF_LAST_IMAGENumber of last get image. The parameter data will be ignored.
NUMBER_OF_NEXT_IMAGENumber of next image after last get image. The parameter data will be ignored.
NUMBER_OF_IMAGES_IN_PROGRESSSum of all images which aren't gotten, yet. The parameter data will be ignored.
BUFFER_STATUS1 if the buffer is locked, otherwise 0. The parameter data will be ignored.
GRAB_ACTIVE_XTells whether the commad is active (1) at the moment (otherwise 0). The parameter data will be ignored.
Parameters:
Fg frame grabber to use
Param See table below ...
Data Optional data.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Returns:
Return depends on given flag, see table above ...
Return values:
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
frameindex_t Fg_getStatusEx ( Fg_Struct Fg,
const int  Param,
const frameindex_t  Data,
const unsigned int  DmaIndex,
dma_mem pMem 
)

Reading the status of frame buffer.

With the function 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_setStatusEx() buffers can be blocked or unblocked.

ParameterMeaning
NUMBER_OF_GRABBED_IMAGESSum of all acquired images. The parameter data will be ignored.
NUMBER_OF_LOST_IMAGESSum of lost images. The parameter data requires the DMA no.
NUMBER_OF_BLOCK_LOST_IMAGESSum of all images, which are lost by blocking of the frame buffer. The parameter data requires the DMA no.
NUMBER_OF_BLOCKED_IMAGESSum of blocked images. The parameter data will be ignored.
NUMBER_OF_ACT_IMAGENumber of last acquired image. The parameter data requires the timeout value.
NUMBER_OF_LAST_IMAGENumber of last get image. The parameter data will be ignored.
NUMBER_OF_NEXT_IMAGENumber of next image after last get image. The parameter data will be ignored.
NUMBER_OF_IMAGES_IN_PROGRESSSum of all images which aren't gotten, yet. The parameter data will be ignored.
BUFFER_STATUS1 if the buffer is locked, otherwise 0. The parameter data will be ignored.
GRAB_ACTIVE_XTells whether the commad is active (1) at the moment (otherwise 0). The parameter data will be ignored.
Parameters:
Fg frame grabber to use
Param See table below ...
Data Optional data, details see parameter "Param".
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
pMem Pointer to variable buffer.
Returns:
Return depends on given flag, see table above ...
Return values:
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
const char* const Fg_getSWVersion (  ) 

Software version number.

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

Returns:
Runtime version of the SDK running, i. e. "5.2.0"
int Fg_getSystemInformation ( Fg_Struct Fg,
const enum Fg_Info_Selector  selector,
const enum FgProperty  propertyId,
int  param1,
void *  buffer,
unsigned int *  bufLen 
)

query information about the overall framegrabber setup

returns various information about the currently present framegrabber system in form of a null-terminated string. For additional control / addressing the information to be queried, param1 can be used, depending on the value to e queried. Example: when querying information about a certain board in a multiboard system, the board has to be addressed. Param1 might be used for addressing the board When passing an null-pointer as buffer, the function will return the length of the needed buffersize (in bytes) to place the contents to.

Parameters:
Fg frame grabber to use, might set to 0 for global information, must be set at certain parameters
selector value to query
propertyId determine which information to get, corresponding to FgProperty
param1 1st parameter for addressing the information, depends on the selected info (selector) to be queried If there is a conflict to the passed. Fg parameter, this parameter gets ignored
buffer buffer for result value; for some queries the buffer is used both for input and output, on output the buffer will be overwritten
bufLen length of the allocated buffer [in], number of bytes filled into the buffer [out]
Returns:
FG_OK for success and valid data inside the buffer. In this case the parameter buflen is filled accordingly
<> FG_OK in case of errros, call fg_getLastErrorDescription() for Details
Since:
5.2.0
Fg_Struct* Fg_Init ( const char *  FileName,
unsigned int  BoardIndex 
)

The function Fg_Init() initializes the frame grabber.

This functions is equivalent to calling Fg_InitEx(FileName, BoardIndex, 0). Please see the documentation of Fg_InitEx() for a detailed description of the parameters.

An initialized frame grabber resource by Fg_Init() must be released by Fg_FreeGrabber().

Parameters:
FileName Applet name for initialization.
BoardIndex Logical number of the board.
Returns:
Initialized pointer on the data structure of the FrameFrabber.
Return values:
NULL The initialization failed.

If this function returns NULL you may call Fg_getLastErrorNumber(NULL) to get the error code.

Fg_Struct* Fg_InitConfig ( const char *  Config_Name,
unsigned int  BoardIndex 
)

The function Fg_InitConfig() initializes the frame grabber and loads a parameter file (microEnable configuration file *.mcf).

If more than one microEnable frame grabber is available within PC system, each hardware card will differ by a logical number, which is distributed by initialization. Sorting of the logical board number is influenced by each hardware's serial number. The serial number is printed on each board and can be displayed by microDiagnostics or microDisplay. An additional possibility for identifying several grabbers is to use a function to ask for serial number via Fg_getSerialNumber().

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 within PC. Please note, that the unique ID can differ from PC to PC.

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

Parameters:
Config_Name Applet name for initialization.
BoardIndex Logical number of the board.
Returns:
Initialized pointer on the data structure of the FrameFrabber.
Return values:
NULL The initialization failed.
Fg_Struct* Fg_InitConfigEx ( const char *  Config_Name,
unsigned int  BoardIndex,
int  flags 
)

The function Fg_InitConfigEx() initializes the frame grabber in master or slave mode and loads a parameter file (microEnable configuration file *.mcf).

If more than one microEnable frame grabber is available within PC system, each hardware card will differ by a logical number, which is distributed by initialization. Sorting of the logical board number is influenced by each hardware's serial number. The serial number is printed on each board and can be displayed by microDiagnostics or microDisplay. An additional possibility for identifying several grabbers is to use a function to ask for serial number via Fg_getSerialNumber().

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 within PC. Please note, that the unique ID can differ from PC to PC.

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, mE4AD1-CL boards, and mE4AS1-CL boards do not support slave mode.

A grabber initialized as slave has access to all resources of the board. Locking for concurrent accesses is left to the user to allow maximum flexibility. On the other hand some special resources will always protect themselves against concurrent usage, e.g DMA channels can't be started if they are already running.

A board can only be opened in slave mode if the master is already opened, otherwise the error code is set to FG_NOT_AVAILABLE ( FG_INVALID_PARAMETER , if slave modes isn't supported at all for this applet)

Please note that a configuration has to be edited manually before it can be applied in slave mode safely. Each save is supposed to touch only parameters that no other slave or the master will touch. A configuration saved from microDisplay contains all parameters, and is not master/slave aware.

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

Parameters:
Config_Name Applet name for initialization.
BoardIndex Logical number of the board.
flags Flags to modify the initialization behavior (see MeInitFlags).
Returns:
Initialized pointer on the data structure of the FrameFrabber.
Return values:
NULL The initialization failed.
Fg_Struct* Fg_InitEx ( const char *  FileName,
unsigned int  BoardIndex,
int  flags 
)

Initialize a frame grabber in master or slave mode.

This function initializes a framegrabber with a given applet. Both standard applets as well as VisualApplets generated HAP files are supported. The BoardIndex parameter is used to address multiple framegrabbers in the same system.

Board numbers depend on the system architecture and operating system. In general the board numbers depend on the PCI setup, i.e. boards with lower PCI bus and slot numbers will have lower board numbers. On Windows systems meIII grabbers will always get lower numbers than meIV devices. On Linux the order depends only on the PCI bus numbers, resulting in meIII devices usually appearing on higher device numbers as PCI buses are usually the last child bus of PCI Express bridges. The easiest way to find out the mapping from boards to their board id is using microDiagnostics which shows board type, serial number, and board index.

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, mE4AD1-CL boards, and mE4AS1-CL boards do not support slave mode.

A grabber initialized as slave has access to all resources of the board. Locking for concurrent accesses is left to the user to allow maximum flexibility. On the other hand some special resources will always protect themselves against concurrent usage, e.g DMA channels can't be started if they are already running.

A board can only be opened in slave mode if the master is already opened, otherwise the error code is set to FG_NOT_AVAILABLE ( FG_INVALID_PARAMETER , if slave modes isn't supported at all for this applet)

An initialized frame grabber resource by Fg_InitEx() must be released by Fg_FreeGrabber().

Parameters:
FileName Applet name for initialization.
BoardIndex Logical number of the board.
flags Flags to modify the initialization behavior.
Returns:
Initialized pointer on the data structure of the FrameFrabber.
Return values:
NULL The initialization failed.

If this function returns NULL you may call Fg_getLastErrorNumber(NULL) to get the error code.

int Fg_InitLibraries ( const char *  sisoDir  ) 

The function Fg_InitLibraries() initializes internal structures of the library.

This function initializes internal structures in the library and keeps them in memory until Fg_FreeLibraries() is called. This can help to speed up certain operations like enumerating boards or getting information about a board before calling Fg_Init(). It is recommended to call this function in the main() method before any other calls to fglib5, or any other library supplied with the Silicon Software Runtime. When Fg_InitLibraries() returns 0, you must call Fg_FreeLibraries() before exiting your program.

Parameters:
sisoDir User supplied directory to Runtime installation (optional; can be NULL)
Returns:
0 on success, or a non-zero error value otherwise
Return values:
FG_OK success
FG_NOT_IMPLEMENTED function is not implemented
FG_SISODIR5_NOT_SET no search path available
FG_OPERATION_ABORTED synchronization has been aborted
int Fg_InitLibrariesEx ( const char *  sisoDir,
unsigned int  flags,
const char *  id,
unsigned int  timeout 
)

The function Fg_InitLibrariesEx() initializes internal structures of the library and synchronizes the startup of the application(s).

This function initializes internal structures in the library and keeps them in memory until Fg_FreeLibraries() is called. This can help to speed up certain operations like enumerating boards or getting information about a board before calling Fg_Init(). Furthermore, the startup of the application can be synchronized with the startup of the Generic Service, or with a Master or the other Slaves in a Master/Slave setup. It is recommended to call this function in the main() method before any other calls to fglib5, or any other library supplied with the Silicon Software Runtime. When Fg_InitLibraries() returns 0, you must call Fg_FreeLibraries() before exiting your program.

Note: microDisplay can be used as a master and you can synchronize your own slave application against microDisplay. The id of microDisplay is siso-microdisplay-master and it uses (FG_INIT_LIBRARIES_MASTER | FG_INIT_LIBRARIES_AUTOSTART_ON_INIT). To synchronize your slave application against microDisplay, use the same id and FG_INIT_LIBRARIES_SLAVE. Strictly sequential startup is not supported by microDisplay, and thus slave priorities are not allowed.

Note: The following flags and macros can be used to control the synchronization: FG_INIT_LIBRARIES_SINGLE Standard init, no synchronization (same as calling Fg_InitLibraries()) FG_INIT_LIBRARIES_MASTER Master init, prepare slave synchronization FG_INIT_LIBRARIES_SLAVE Slave init, wait for master FG_INIT_LIBRARIES_WAIT_FOR_SERVICE Wait for service to be started (valid only for single application and master modes) FG_INIT_LIBRARIES_SEQUENTIAL Strictly sequential startup (slaves must use unique priority; number of slaves must be given on master init) FG_INIT_LIBRARIES_AUTOSTART_ON_INIT Start next slave on Fg_Init() FG_INIT_LIBRARIES_SET_MODE(n) Set mode (single, master, slave) FG_INIT_LIBRARIES_SET_SLAVE_PRIORITY(n) Set slave priority (allowed values are 1..63; priority 0 will select priority automatically) FG_INIT_LIBRARIES_SET_NUMBER_OF_SLAVES(n) Set number of slaves (allowed values are 1..63)

Parameters:
sisoDir User supplied directory to Runtime installation (optional; can be NULL)
flags Additional flags to control the synchronization
id The identifier which should be used for synchronization (Master and Slaves must use the same identifier; not used in single mode)
timeout Timeout in milliseconds to wait for synchronization
Returns:
0 on success, or a non-zero error value otherwise
Return values:
FG_OK success
FG_NOT_IMPLEMENTED function is not implemented
FG_SISODIR5_NOT_SET no search path available
FG_OPERATION_ABORTED synchronization has been aborted
FG_TIMEOUT waiting for synchronization timed out
void Fg_InitLibrariesStartNextSlave (  ) 

The function Fg_InitLibrariesStartNextSlave() signals the next slave process to start.

This function is required for synchronization of the startup of processes in master/slave mode when FG_INIT_LIBRARIES_AUTOSTART_SLAVE was not set in Fg_IitLibrariesEx. This is generally needed if the process requires further initialization beyond Fg_Init() that must be synchronized with other slave processes or the master process. Most likely, this will be applicable to initialization in the master process, but should generally not be the case for slave processes, as these should be using completely separate resources (DMA, parameters, ...).

int Fg_loadConfig ( Fg_Struct Fg,
const char *  Filename 
)

Loading a frame grabber configuration.

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

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

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

Parameters:
Fg frame grabber to use
Filename Name and path to microEnable configuration file.
Return values:
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.
FG_INVALID_IMAGE_DIMENSIONS external image data does not match to Applets needs
int Fg_loadFieldParameterFromFile ( Fg_Struct Fg,
const int  Parameter,
const unsigned int  DmaIndex,
const char *  FileName 
)

Loading field parameter from file.

A field parameter file can also be saved with Fg_saveFieldParameterToFile().

The extension of the field parameter file is always *.mfs.

Parameters:
Fg frame grabber to use
Parameter parameter id
DmaIndex cam port
Filename Name and path to field parameter file.
Return values:
FG_OK Loading parameter done successfully.
FG_PARAMETER_NOT_IN_FILE Parameter is not in file
FG_NOT_INIT The Frame grabber handle is invalid or null
FG_INVALID_CONFIGFILE File format is incorrect or corrupted data if it already exists
FG_INVALID_PARAMETER The requested parameter is not a field parameter or parameter id is negative and invalid or parameter id is not in applet at all
FG_FILE_NOT_FOUND File name is invalid or not exists
FG_FILE_ACCESS_DENIED Unexpected internal error by reading from or writing in file
FG_ERROR Unexpected internal error
void* Fg_NumaAllocDmaBuffer ( Fg_Struct Fg,
size_t  Size 
)

NUMA aware allocation of memory.

Allocated memory can be released with Fg_NumaFreeDmaBuffer().

Please note, that there are memory limits existing! However, this function will never fail, but give you memory from other nodes, or even the page file, if you exceed the node memory limit.

Parameters:
Fg frame grabber to use
Size Size of all image memory in byte.
Returns:
A pointer to the allocated frame memory / image data.
Return values:
NULL An error occured. Use Fg_getLastErrorDescription() for more information.
int Fg_NumaFreeDmaBuffer ( Fg_Struct Fg,
void *  Buffer 
)

NUMA aware freeing of memory.

Only use this function to release memory allocated with Fg_NumaAllocateDmaBuffer().

Parameters:
Fg frame grabber to use
Buffer pointer to frame memory
Returns:
0 on success.
Return values:
<0 An error occured. (Use Fg_getLastErrorDescription() for more information.)
int Fg_NumaPinThread ( Fg_Struct Fg  ) 

NUMA aware pinning of thread affinity.

Parameters:
Fg frame grabber to use
Returns:
0 on success.
Return values:
<0 An error occured. (Use Fg_getLastErrorDescription() for more information.)
int Fg_readUserDataArea ( Fg_Struct Fg,
const int  boardId,
const unsigned int  offs,
const unsigned int  size,
void *  buffer 
)

read user data area

Using Fg_readUserDataArea() you can read a block of memory from reserved space in the configuration memory of the frame grabber. Please consult the manual of your frame grabber about support for this feature. Also note that the memory might be very limited, slow and implemented on a device that only provides a limited number of write cycles.

Parameters:
Fg frame grabber to use, if set to 0 you must provide a board number
boardId board number, can be set to (-1) if you supply a frame grabber handle
offs offset to the start of the user memory area
size number of bytes to read
buffer buffer for the memory transfer
Returns:
FG_OK for success and valid data inside the buffer.
<> FG_OK in case of errros, call Fg_getLastErrorDescription() for Details.
FG_NOT_IMPLEMENTED if the feature is not supported on the hardware.
FG_INVALID_BOARD_NUMBER if no handle was supplied and the board number could not be found (or the handle and board number don't match).
FG_RANGE_ERR if the requested offset is not within the size of the user data area.
FG_SIZE_ERROR if the requested size is too large to fit in the user data area (from the given offset).
FG_PTR_INVALID if the buffer address is invalid (or the size is 0)
Since:
5.3
int Fg_registerApcHandler ( Fg_Struct Fg,
const unsigned int  DmaIndex,
const struct FgApcControl control,
enum FgApcControlFlags  flags 
)

Register an APC handler for the given DMA channel.

Parameters:
Fg frame grabber to use
DmaIndex DMA channel number to listen on
control control structure for APC operations
flags how to handle the control structure
Returns:
FG_OK if the handler was successfully registered, error code otherwise.
Return values:
FG_NOT_INIT Fg is NULL
FG_INVALID_PORT_NUMBER DmaIndex is invalid
FG_INVALID_PARAMETER One parameter or the combination of parameters is invalid
FG_ALREADY_STARTED an APC handler for this DMA channel is already registered
FG_NOT_ENOUGH_MEMORY creation of the internal control structures or the worker thread failed
FG_APC_PRIORITY_ERROR the control structure requested FG_APC_HIGH_PRIORITY but setting the priority failed
FG_ACCESS_DENIED setting the Priority fails due to insufficient permissions
FG_APC_ALREADY_REGISTERED an APC handler is already registered

This function registers an APC (asynchronous procedure call) handler to be called once images on the given DMA channel arrive.

   This function does not start the acquisition itself, this needs to be done using
   Fg_Acquire() or Fg_AcquireEx(). If an APC handler is registered for a DMA channel you
   can not use Fg_getLastPicNumberBlocking() or Fg_getLastPicNumberBlockingEx() to wait
   for images on that channel. The DMA channel will not be stopped by the APC handler
   thread on any circumstances even when the handler will terminate itself by those.

Once the DMA is started the APC handler function will get called for new images. The exact behaviour can be controlled by setting the flags member of the control struct using the constants defined in enum Fg_Apc_Flag in fgrab_define.h. If you are unsure just pass Fg_Apc_Flag::FG_APC_DEFAULTS here.

The handler function is stored as func in the control struct. It will be called with the image number to work on as first and the value given for data in the control struct as second argument.

See also:
struct fg_apc_data

If you request FG_APC_HIGH_PRIORITY through the flag member of the control structure, your application must have the necessary privileges to change the thread scheduling and priority. Note that on Linux this generally means you have to run the application as root or use setuid.

The flags parameter allows future expansions of the APC operation mode. The only value value currently valid is FG_APC_CONTROL_BASIC. You must set the version number in the control struct.

If you want to unregister an APC handler for a given channel call this function as:

You must always unregister the APC handler from a DMA channel even if the APC thread was automatically stopped. This will happen e.g. if a image timeout occurs and Fg_Apc_Flag::FG_APC_IGNORE_TIMEOUTS was not set or if your handler function returns with error code and Fg_Apc_Flag::FG_APC_IGNORE_APCFUNC_RETURN was not set. You do not need to unregister the APC handler if registering failed with an error code.

 class my_class;

 struct fg_apc_data {
     Fg_Struct *fg;
     unsigned int dma;
     dma_mem *mem;
     my_class *my;
 };

 class my_class {
 private:
     struct fg_apc_data apcdata;
 public:
     my_class(Fg_Struct *fg, unsigned int dma);
     ~my_class();

     int registerApc();
     void doSomethingWithImage(void *imageData, size_t imageLength);
 ...
 };

 ...

 extern "C" int my_apc_func(int image, struct fg_apc_data *apcdata)
 {
     void *data = Fg_getImagePtrEx(apcdata->fg, image, apcdata->dma, apcdata->mem);
     size_t len;

     Fg_getParameterEx(apcdata->fg, FG_TRANSFER_LEN, &len, apcdata->dma, apcdata->mem, image);

     apcdata->my->doSomethingWithImage(data, len);

     return 0;
 }

 my_class::my_class(Fg_Struct *fg, unsigned int dma)
 {
     apcdata.version = 0;
     apcdata.fg = fg;
     apcdata.dma = dma;
     apcdata.my = this;
     // apcdata.mem is later initialized by some other method of my_class
 }

 my_class::~my_class()
 {
     Fg_registerApcHandler(apcdata.fg, apcdata.dma, NULL, FG_APC_CONTROL_BASIC);
 }

 int my_class::registerApc()
 {
     struct FgApcControl ctrl;

     ctrl.func = my_apc_func;
     ctrl.data = &apcdata;
     ctrl.flags = FG_APC_DEFAULTS;
     ctrl.timeout = 10;

     return Fg_registerApcHandler(apcdata.fg, apcdata.dma, &ctrl, FG_APC_CONTROL_BASIC);
 }
int Fg_registerAsyncNotifyCallback ( Fg_Struct Fg,
Fg_AsyncNotifyFunc_t  handler,
void *  context 
)

register callback for asynchronous notifications

Parameters:
Fg frame grabber to use
handler notification handler function to call
context context data passed to handler on notification
Returns:
FG_OK on success, error code otherwise

Use this function to register a callback function for asynchronous notifications sent by the driver. This will install a new callback function, but not override any callbacks that were registered before. The same callback function can be registered more than once, only if you provide a unique, non-NULL context pointer for each registration. You cannot register the same callback, if it was already registered with NULL as context.

To unregister a callback, call Fg_unregisterAsyncNotifyCallback().

All callbacks of one board will be handled in the same thread. If your callback handler takes a long time to complete it will delay all further notifications until it has finished. If you need both a long running notification handler and short reaction time you must create your own worker thread and start it's execution from the callback.

  If your event handler returns a value other than 0 it is automatically unregistered.
Since:
5.3
int Fg_registerEventCallback ( Fg_Struct Fg,
uint64_t  mask,
Fg_EventFunc_t  handler,
struct fg_event_data data,
const unsigned int  flags,
struct fg_event_info info 
)

register callback for events

Parameters:
Fg frame grabber to use
mask event mask
handler event handler function to call
data context data passed to handler on event
flags control flags. Or'ed combination of FgEventControlFlags. In doubt use FG_EVENT_DEFAULT_FLAGS.
info event info structure to fill with additional data, in doubt pass NULL
Returns:
FG_OK on success, error code otherwise

You must not call this function and Fg_eventWait() on the same event.

Use this function to register a callback function for any combination of event masks. This will overwrite the handler for any events in mask. Use Fg_getEventMask() to obtain the event mask corresponding to a specific event.

To unregister a callback pass NULL as handler to this function. You must pass the same event mask you passed in when registering the callback. The flags argument must be set to FG_EVENT_DEFAULT_FLAGS.

 Fg_registerEventCallback(Fg, mask, NULL, NULL, FG_EVENT_DEFAULT_FLAGS, NULL);

All callbacks of one board will be handled in the same thread. If your callback handler takes a long time to complete it will delay all further events until it has finished. If you need both a long running event handler and short reaction time you must create your own worker thread and start it's execution from the callback.

You may register multiple callbacks with different event masks at the same time. You may also register the same event handler with different data arguments at the same time.

  If your event handler returns a value other than 0 it is automatically unregistered from
  all events it was registered to with the same data argument.

If you pass a value different from NULL as info these structure will be filled with the requested information before handler is called. You should never use the data outside your handler as it will be overwritten before handler is called. You must not change the contents of the struct inside the handler.

Since:
5.1.0
int Fg_resetAsyncNotify ( Fg_Struct Fg,
unsigned long  notification,
unsigned long  pl,
unsigned long  ph 
)

acknowledge an asynchronous notifications

Parameters:
Fg frame grabber to use
notification the notification code
pl parameter 1 (notification dependent)
ph parameter 2 (notification dependent)
Returns:
FG_OK on success, error code otherwise

Use this function to acknowledge an asynchronous notification that was received through one of your registered handlers.

Since:
5.3
int Fg_saveConfig ( Fg_Struct Fg,
const char *  Filename 
)

Saving a frame grabber configuration.

The frame grabber's configuration can be saved into a file by Fg_saveConfig(). Parameterization will be handled by loading of 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.

Parameters:
Fg frame grabber to use
Filename Name and path of the frame grabber configuration file.
Return values:
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.
int Fg_saveFieldParameterToFile ( Fg_Struct Fg,
const int  Parameter,
const unsigned int  DmaIndex,
const char *  FileName 
)

Saving applet field parameter.

The applet's fields parameters can be saved into a file by Fg_saveFieldParameterToFile()

A field parameter file can also be loaded with Fg_loadFieldParameterFromFile().

The extension of the field parameter is always *.mfs.

Parameters:
Fg frame grabber to use
Parameter parameter id
DmaIndex cam port
Filename Name and path of field parameter file.
Return values:
FG_OK Saving parameter done successfully.
FG_NOT_INIT The Frame grabber handle is invalid or null
FG_INVALID_CONFIGFILE File format is incorrect or corrupted data if it already exists
FG_INVALID_PARAMETER The requested parameter is not a field parameter or parameter id is negative and invalid or parameter id is not in applet at all
FG_FILE_NOT_FOUND File name is invalid
FG_FILE_ACCESS_DENIED Unexpected internal error by reading from or writing in file
FG_ERROR Unexpected internal error
int Fg_sendImage ( Fg_Struct Fg,
const frameindex_t  startImage,
const frameindex_t  PicCount,
const int  nFlag,
const unsigned int  DmaIndex 
)

Sending images from Software to the applet.

This function provides an interface in order to send images from a client software to the applet. This functions uses frame buffers which are allocated by using the Fg_allocMem() function. It shouldn't be used in combination with the Fg_allocMemEx() functions. Please note that when using this function, special applets which support this possibility are needed

Parameters:
Fg frame grabber to use
startImage first image to be sent as index of the frame buffer
PicCount number of images to be sent,
nFlag reserved, should be 0
DmaIndex Logical number of the DMA's depending on the applet. Indizes starting with 0
Return values:
various FG-error codes, call Fg_getLastError to obtain the error
int Fg_sendImageEx ( Fg_Struct Fg,
const frameindex_t  startImage,
const frameindex_t  PicCount,
const int  nFlag,
const unsigned int  DmaIndex,
dma_mem memHandle 
)

Sending images from Software to the applet.

This function provides an interface in order to send images from a client software to the applet. Please note that when using this function, special applets which support this possibility are needed

Parameters:
Fg frame grabber to use
startImage first image to be sent as index of the frame buffer
PicCount number of images to be sent,
nFlag reserved, should be 0
DmaIndex Logical number of the DMA's depending on the applet. Indizes starting with 0
memHandle pointer to memory structure, which has been allocated be Fg_allocMemEx
Return values:
various FG-error codes, call Fg_getLastError to obtain the error
int Fg_sendSoftwareTrigger ( Fg_Struct Fg,
const unsigned int  CamPort 
)

send trigger signal to the camera

Parameters:
Fg frame grabber to use
CamPort Camera port to set.
Returns:
Status code.
Return values:
FG_OK Trigger was accepted (softwaretrigger mode). Queue empty and trigger accepted (softwaretrigger queue mode)
FG_INVALID_PARAMETER An invalid argument was passed (e.g. nonexistent camera port).
FG_SOFTWARE_TRIGGER_PENDING Trigger is accepted but can't be performed immediately since another trigger is currently processed. The trigger is added to the queue and will be processed delayed as soon as possible (only in software trigger queue mode)
FG_SOFTWARE_TRIGGER_BUSY The trigger command cannot be accepted and gets lost due to on of the following reasons: Trigger pulse is already active (in softwaretrigger mode). Trigger queue is too full to accept the trigger. (softwaretrigger queue mode)

This function can be used to send immediately a single trigger pulse to the camera in softwaretrigger mode or to add one trigger to the queue in softwaretrigger queue mode. The length of the signals is determined by the exposure time and is configured by the function Fg_setParameter(). During the duration of the camera trigger, a new trigger signal can't be sent in software trigger mode. In software trigger queue mode a new trigger signal to the camera are created if the previous triggered image was fully transfered onto the grabber.

Besides the camera trigger, the signal StrobePulse is activated, which can be used as control for flash lights. The delay of the StrobePulse relative to the camera trigger is set by the function Fg_getParameter() (see flash light control).

This function internally calls Fg_setParameter() with parameter FG_SENDSOFTWARETRIGGER with Triggers as value. You should use that interface as this has slightly less overhead.

The microEnable IV-GigE x4 currently does not support the trigger system.
This function can only be used with acquisition applets. VisualApplets generated applets
do not use this interface. Please refer to the VisualApplets operator manual for documentation
for trigger operators.
int Fg_sendSoftwareTriggerEx ( Fg_Struct Fg,
const unsigned int  CamPort,
const unsigned int  Triggers 
)

send multiple trigger signals to the camera

Parameters:
Fg frame grabber to use
CamPort Camera port to set.
Triggers Number of triggers to be sent to the camera.
Returns:
Status code.
Return values:
FG_OK Trigger was accepted (softwaretrigger mode). Trigger will be processed immediately
FG_INVALID_PARAMETER An invalid argument was passed (e.g. nonexistent camera port).
FG_SOFTWARE_TRIGGER_PENDING Trigger is accepted but can't be performed immediately since another trigger is currently processed. The trigger is added to the queue and will be processed delayed as soon as possible (only in software trigger queue mode)
FG_SOFTWARE_TRIGGER_BUSY Trigger pulse is already active (softwaretrigger mode). Trigger queue is too full to accept the value. (softwaretrigger queue mode)
FG_VALUE_OUT_OF_RANGE The entered value is outside of the valid range.

This function can be used either to send immediately a single trigger pulse to the camera in softwaretrigger mode or to add (and send) multiple triggers to the queue in softwaretrigger queue mode. The length of the signals is determined by the exposure time and is configured by the function Fg_setParameter(). During the duration of the camera trigger, a new trigger signal can't be sent in software trigger mode. In software trigger queue mode next trigger signal to the camera is created if the previous triggered image was fully transfered onto the grabber.

Besides the camera trigger, the signal StrobePulse is activated, which can be used as control for flash lights. The delay of the StrobePulse relative to the camera trigger is set by the function Fg_getParameter() (see flash light control).

This function internally calls Fg_setParameter() with parameter FG_SENDSOFTWARETRIGGER with Triggers as value. You should use that interface as this has slightly less overhead.

The microEnable IV-GigE x4 currently does not support the trigger system.
This function can only be used with acquisition applets. VisualApplets generated applets
do not use this interface. Please refer to the VisualApplets operator manual for documentation
for trigger operators.
Since:
5.1.2
int Fg_setExsync ( Fg_Struct Fg,
int  Flag,
const unsigned int  CamPort 
)

set Exsync camera signal

Parameters:
Fg frame grabber to use
Flag Exsync value to set (FG_ON or FG_OFF).
CamPort Camera port to set.
Returns:
Status code.
Return values:
FG_OK Exsync value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. nonexistent camera port).

The function int Fg_setExsync() explicitly allows a switch to on and off of the exsync signal to the camera.

Deprecated:
This function internally calls Fg_setParameter() with parameter FG_EXSYNCON and passes Flag as value. You should use that interface as this has slightly less overhead.
 This function can only be used with acquisition applets. VisualApplets generated applets
 do not use this interface. Please refer to the VisualApplets operator manual for documentation
 for trigger operators.
int Fg_setFlash ( Fg_Struct Fg,
int  Flag,
const unsigned int  CamPort 
)

set strobe camera signal

Parameters:
Fg frame grabber to use
Flag Strobe value to set (FG_ON or FG_OFF).
CamPort Camera port to set.
Returns:
Status code.
Return values:
FG_OK Exsync value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. nonexistent camera port).

The function int Fg_setFlash() explicitly allows a switch to on and off of the strobe signal.

Deprecated:
This function internally calls Fg_setParameter() with parameter FG_FLASHON and passes Flag as value. You should use that interface as this has slightly less overhead.
 This function can only be used with acquisition applets. VisualApplets generated applets
 do not use this interface. Please refer to the VisualApplets operator manual for documentation
 for trigger operators.
int Fg_setParameter ( Fg_Struct Fg,
const int  Parameter,
const void *  Value,
const unsigned int  DmaIndex 
)

Setting frame grabber parameters.

Each applet, 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 design created with VisualApplets. The available parameters are determined by the VisualApplets operators used within the 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.

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:

Expected Input TypeFlagValueDescription
intFG_TIMEOUTmin: 1 sec. max: 2,147,483,646 sec.Time in seconds until device driver displays a timeout.
intFG_GLOBAL_ACCESSauto = 0, read = 1, read write = 3, read write change = 7Access flag for plausibilities.
Parameters:
Fg frame grabber to use
Parameter The parameter ID. Can be either the value returned by Fg_getParameterId() or Fg_getParameterIdByName() or the ID of a generally available parameter. See table below for generally available parameters ...
Value Pointer to required value.
DmaIndex Logical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values:
FG_OK The parameter has been set correctly.
FG_NOT_INIT Initialization has failed.
FG_INVALID_PARAMETER An invalid parameter has been entered.
FG_VALUE_OUT_OF_RANGE The entered value is besides valid ranges.
int Fg_setParameterWithType ( Fg_Struct Fg,
const int  Parameter,
const void *  Value,
const unsigned int  DmaIndex,
const enum FgParamTypes  type 
)

Setting frame grabber parameters with type information.

This function behaves like Fg_setParameter() but allows to specify the type of the given value. For compatibility reasons Fg_setParameter() only accepts 32 bit values for integer parameters. If you need to set a 64 bit int parameter you need this function or the upper 32 bit of the passed value will be lost.

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

Setting the status of frame buffer.

The function Fg_setStatus() explicitely allows, blocking or releasing of a blocked buffer (see table).

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

ParameterMeaning
FG_UNBLOCK_ALLExplicit release of all buffers.
FG_UNBLOCKExplicit release of one buffer.
Parameters:
Fg frame grabber to use
Param See table below ...
Data Optional data.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Returns:
Pointer to the corresponding buffer.
Return values:
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
int Fg_setStatusEx ( Fg_Struct Fg,
const int  Param,
const frameindex_t  Data,
const unsigned int  DmaIndex,
dma_mem pMem 
)

Setting the status of frame buffer.

The function Fg_setStatus() explicitely allows, blocking or releasing of a blocked buffer (see table).

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

ParameterMeaning
FG_UNBLOCK_ALLExplicit release of all buffers.
FG_UNBLOCKExplicit release of one buffer.
Parameters:
Fg frame grabber to use
Param See table below ...
Data Optional data.
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
pMem Pointer to variable buffer.
Returns:
Pointer to the corresponding buffer.
Return values:
FG_INVALID_PARAMETER An invalid parameter has been given to the function.
int Fg_stopAcquire ( Fg_Struct Fg,
const unsigned int  DmaIndex 
)

Stopping image grabbing.

The function Fg_stopAcquire() stops the running image grabbing that has been started with Fg_Acquire(). 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.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
Return values:
FG_OK Transmission has been finished successfully.
FG_NOT_INIT Frame grabber was not initialised correctly.
FG_TRANSFER_NOT_ACTIVE Transmission was not started.
FG_INVALID_PARAMETER Invalid parameter is set.
FG_CANNOT_STOP Frame grabber could not stop.
int Fg_stopAcquireEx ( Fg_Struct Fg,
const unsigned int  DmaIndex,
dma_mem memHandle,
int  nFlag 
)

Stopping image grabbing.

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

The function Fg_stopAcquireEx() stopps the image acquiring asynchronous or synchronous. nFlag 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 acquiring.

Parameters:
Fg frame grabber to use
DmaIndex Logical number of used camera port. camera port A = 0 and camera port B = 1
memHandle Pointer to handle of frame buffer.
nFlag Selecting stopping mode and timeout in seconds (STOP_SYNC, STOP_ASYNC) . When using STOP_SYNC: The timeout is defined by the parameter FG_STOP_TIMEOUT
Return values:
FG_OK Transmission has been finished successfully.
FG_NOT_INIT Frame grabber was not initialised correctly.
FG_TRANSFER_NOT_ACTIVE Transmission was not started.
FG_INVALID_PARAMETER Invalid parameter is set.
FG_CANNOT_STOP Frame grabber could not stop.
int Fg_unregisterAsyncNotifyCallback ( Fg_Struct Fg,
Fg_AsyncNotifyFunc_t  handler,
void *  context 
)

unregister callback for asynchronous notifications

Parameters:
Fg frame grabber to use
handler notification handler function to call
context context data passed to handler on notification
Returns:
FG_OK on success, error code otherwise

Use this function to unregister a callback function for asynchronous notifications that was registered before with Fg_registerAsyncNotifyCallback(). You must provide the same parameters that you used for registering the callback. You can, however, provide NULL for the context, in which case all callbacks using the same function with different context pointers will be unregistered.

Since:
5.3
int Fg_writeUserDataArea ( Fg_Struct Fg,
const int  boardId,
const unsigned int  offs,
const unsigned int  size,
const void *  buffer 
)

write user data area

Using Fg_writeUserDataArea() you can write a block of memory to reserved space in the configuration memory of the frame grabber. Please consult the manual of your frame grabber about support for this feature. Also note that the memory might be very limited, slow and implemented on a device that only provides a limited number of write cycles.

Parameters:
Fg frame grabber to use, if set to 0 you must provide a board number
boardId board number, can be set to (-1) if you supply a frame grabber handle
offs offset to the start of the user memory area
size number of bytes to write
buffer buffer for the memory transfer
Returns:
FG_OK for success and valid data inside the buffer.
<> FG_OK in case of errros, call Fg_getLastErrorDescription() for Details.
FG_NOT_IMPLEMENTED if the feature is not supported on the hardware.
FG_INVALID_BOARD_NUMBER if no handle was supplied and the board number could not be found (or the handle and board number don't match).
FG_RANGE_ERR if the requested offset is not within the size of the user data area.
FG_SIZE_ERROR if the requested size is too large to fit in the user data area (from the given offset).
FG_PTR_INVALID if the buffer address is invalid (or the size is 0)
Since:
5.3
const char* const getErrorDescription ( int  ErrorNumber  ) 

Description of error message.

This returns a description string for the given error code.

Parameters:
ErrorNumber The error code to translate.
Returns:
The message of the last error that occurred.
int getLastErrorNumber (  ) 

stub to maintain interface compatibility

Returns:
The last error code of the framegrabber library
Deprecated:
This function is only here to maintain interface compatibility. It will only call Fg_getLastErrorNumber(NULL) internally. Do not use it as it will eventually go away.
int Shad_FreeAccess ( Fg_Struct Fg,
ShadingMaster sh 
)

deactivate shading object

Parameters:
Fg frame grabber to use
sh Shading control object to deactivate.
Returns:
Status code.
Return values:
FG_OK Shading control object was deactivated.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

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

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_GetAccess ( Fg_Struct Fg,
ShadingMaster sh 
)

activate shading object

Parameters:
Fg frame grabber to use
sh Shading control object to activate.
Returns:
Status code.
Return values:
FG_OK Shading control object was activated.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

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

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_GetMaxLine ( Fg_Struct Fg,
ShadingMaster sh 
)

query current line number for shading correction

Parameters:
Fg frame grabber to use
sh Shading control object to use.
Returns:
line number or negative error code
Return values:
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

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

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_SetFixedPatternNoiseLine ( Fg_Struct Fg,
ShadingMaster sh,
int  x,
int  channel,
int  on 
)

set defective pixel interpolation value for shading correction

Parameters:
Fg frame grabber to use
sh Shading control object to use.
x Position in the line.
channel Color channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
on enable or disable interpolation for this pixel (values 0 or 1).
Returns:
Status code.
Return values:
FG_OK Shading value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

Before shading calculation can be done, some parameters have to be set. Shad_SetFixedPatternNoiseLine() sets parameters for the defective pixel interpolation.

You can either manually set values for shading with this function or you can otherwise set a path to a file for defective pixel interpolation. This can be done with Fg_setParameter() using FG_SHADING_FPNFILE0 parameter.

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_SetMultValueLine ( Fg_Struct Fg,
ShadingMaster sh,
int  x,
int  channel,
float  mult 
)

set multiplicative correction value for shading correction

Parameters:
Fg frame grabber to use
sh Shading control object to use.
x Position in the line.
channel Color channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
mult Multiplicative correction value (range 0 to 8).
Returns:
Status code.
Return values:
FG_OK Shading value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

Before shading calculation can be done, some parameters have to be set. Shad_SetMultValueLine() sets parameters for the gain (multiplicative correction).

You can either manually set values for shading with this function or you can otherwise set a path to a file for multiplication calculation. This can be done with Fg_setParameter() using FG_SHADING_MULTFILE0 parameter.

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_SetSubValueLine ( Fg_Struct Fg,
ShadingMaster sh,
int  x,
int  channel,
float  sub 
)

set substractive correction value for shading correction

Parameters:
Fg frame grabber to use
sh Shading control object to use.
x Position in the line.
channel Color channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
sub Subtractive correction value (range 0 to 1).
Returns:
Status code.
Return values:
FG_OK Shading value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

Before shading calculation can be done, some parameters have to be set. Shad_SetSubValueLine() sets parameters for the offset (subtractive correction).

You can either manually set values for shading with this function or you can otherwise set a path to a file for subtraction calculation. This can be done with Fg_setParameter() using FG_SHADING_SUBFILE0 parameter.

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.
int Shad_WriteActLine ( Fg_Struct Fg,
ShadingMaster sh,
int  Line 
)

write shading correction values for given line

Parameters:
Fg frame grabber to use
sh Shading control object to use.
Line Line number which has to be corrected.
Returns:
Status code.
Return values:
FG_OK Shading value was set.
FG_INVALID_PARAMETER an invalid argument was passed (e.g. a NULL pointer).

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

 This function can only be used with acquisition applets that offer shading functionality.
 VisualApplets generated applets with shading functionality do not use this interface. Please refer
 to the VisualApplets operator manual for documentation of that shading interface.