basler_fg.h File Reference

basler_fg.h File Reference

Header file for all functions exported. More...

#include <stdint.h>
#include <sys/types.h>
#include "fg_struct.h"
#include "fg_define.h"
#include "fg_error_codes.h"
#include "os_type.h"
#include "os_funcs.h"
#include "SisoDisplay.h"

Go to the source code of this file.

Macros

#define PUBLIC_API
 

Typedefs

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

Functions

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.

PUBLIC_API 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). .
 
PUBLIC_API void Fg_FreeLibraries ()
 The function Fg_FreeLibraries() releases internal structures of the library. .
 
PUBLIC_API int Fg_InitLibraries (const char *sisoDir)
 The function Fg_InitLibraries() initializes internal structures of the library. .
 
PUBLIC_API 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). .
 
PUBLIC_API void Fg_InitLibrariesStartNextSlave ()
 The function Fg_InitLibrariesStartNextSlave() signals the next slave process to start. .
 
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.

PUBLIC_API 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. .
 
PUBLIC_API int Fg_FreeGrabber (Fg_Struct *Fg)
 Releasing frame grabber resources. .
 
PUBLIC_API Fg_StructFg_Init (const char *FileName, unsigned int BoardIndex)
 The function Fg_Init() initializes the frame grabber. .
 
PUBLIC_API 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). .
 
PUBLIC_API 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). .
 
PUBLIC_API Fg_StructFg_InitEx (const char *FileName, unsigned int BoardIndex, int flags)
 Initialize a frame grabber in master or slave mode. .
 
Memory Management

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

PUBLIC_API int Fg_AddMem (Fg_Struct *Fg, void *pBuffer, const size_t Size, const frameindex_t bufferIndex, dma_mem *memHandle)
 Adding user memory. .
 
PUBLIC_API 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. .
 
PUBLIC_API 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. .
 
PUBLIC_API dma_memFg_AllocMemHead (Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)
 Use an allocated user memory as frame buffer. .
 
PUBLIC_API int Fg_DelMem (Fg_Struct *Fg, dma_mem *memHandle, const frameindex_t bufferIndex)
 Deleting user memory, .
 
PUBLIC_API int Fg_FreeMem (Fg_Struct *Fg, const unsigned int DmaIndex)
 Releasing a frame buffer. .
 
PUBLIC_API int Fg_FreeMemEx (Fg_Struct *Fg, dma_mem *mem)
 Releasing frame buffers. .
 
PUBLIC_API int Fg_FreeMemHead (Fg_Struct *Fg, dma_mem *memHandle)
 Releasing memory. .
 
PUBLIC_API 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. .
 
PUBLIC_API int Fg_getBitsPerPixel (int format)
 Calculate the bits per pixel for a specific output format (FG_GRAY, FG_COL24, etc.).
 
PUBLIC_API int Fg_getNrOfParameter (Fg_Struct *Fg)
 The function Fg_getNrOfParameter() returns the number of parameters available within the loaded applet. .
 
PUBLIC_API int Fg_getParameter (Fg_Struct *Fg, int Parameter, void *Value, const unsigned int DmaIndex)
 Getting special parameter settings. .
 
PUBLIC_API 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. .
 
PUBLIC_API int Fg_getParameterId (Fg_Struct *fg, int index)
 The function Fg_getParameterId() returns the parameter ID of the parameter referenced by index. .
 
PUBLIC_API 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. .
 
PUBLIC_API int Fg_getParameterInfoXML (Fg_Struct *Fg, int port, char *infoBuffer, size_t *infoBufferSize)
 Get parameter description in a Genicam compatible XML format. .
 
PUBLIC_API const char * Fg_getParameterName (Fg_Struct *fg, int index)
 The function Fg_getParameterName() informs about the name of a special parameter by index. .
 
PUBLIC_API const char * 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. .
 
PUBLIC_API enum FgParamTypes Fg_getParameterType (Fg_Struct *fg, int index)
 The function Fg_getParameterType() informs about the type of a special parameter by index. .
 
PUBLIC_API enum FgParamTypes Fg_getParameterTypeById (Fg_Struct *fg, const unsigned int id, const unsigned int dma)
 The function Fg_getParameterTypeById() informs about the type of a parameter by its id. .
 
PUBLIC_API 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. .
 
PUBLIC_API int Fg_loadConfig (Fg_Struct *Fg, const char *Filename)
 Loading a frame grabber configuration. .
 
PUBLIC_API int Fg_loadFieldParameterFromFile (Fg_Struct *Fg, const int Parameter, const unsigned int DmaIndex, const char *FileName)
 Loading field parameter from file.
 
PUBLIC_API void * Fg_NumaAllocDmaBuffer (Fg_Struct *Fg, size_t Size)
 NUMA aware allocation of memory. .
 
PUBLIC_API int Fg_NumaFreeDmaBuffer (Fg_Struct *Fg, void *Buffer)
 NUMA aware freeing of memory. .
 
PUBLIC_API int Fg_NumaPinThread (Fg_Struct *Fg)
 NUMA aware pinning of thread affinity. .
 
PUBLIC_API int Fg_saveConfig (Fg_Struct *Fg, const char *Filename)
 Saving a frame grabber configuration .
 
PUBLIC_API int Fg_saveFieldParameterToFile (Fg_Struct *Fg, const int Parameter, const unsigned int DmaIndex, const char *FileName)
 Saving applet field parameter.
 
PUBLIC_API int Fg_setParameter (Fg_Struct *Fg, const int Parameter, const void *Value, const unsigned int DmaIndex)
 Setting frame grabber parameters. .
 
PUBLIC_API 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. .
 
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.

PUBLIC_API int Fg_Acquire (Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount)
 Starting image grabbing. .
 
PUBLIC_API int Fg_AcquireEx (Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount, const int nFlag, dma_mem *memHandle)
 Starting image grabbing. .
 
PUBLIC_API const char * Fg_getErrorDescription (Fg_Struct *Fg, int ErrorNumber)
 Description of error message to an error code. .
 
PUBLIC_API 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. .
 
PUBLIC_API 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. .
 
PUBLIC_API void * Fg_getImagePtr (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex)
 Access on frame buffer. .
 
PUBLIC_API void * Fg_getImagePtrEx (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, dma_mem *pMem)
 Access on frame buffer. .
 
PUBLIC_API const char * Fg_getLastErrorDescription (Fg_Struct *Fg)
 Description of last error message. .
 
PUBLIC_API int Fg_getLastErrorNumber (Fg_Struct *Fg)
 Getting the last error code. .
 
PUBLIC_API frameindex_t Fg_getLastPicNumber (Fg_Struct *Fg, const unsigned int DmaIndex)
 Requesting the current image number (non-blocking). .
 
PUBLIC_API frameindex_t Fg_getLastPicNumberBlocking (Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, const int Timeout)
 Requesting the current image number (blocking) .
 
PUBLIC_API 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) .
 
PUBLIC_API frameindex_t Fg_getLastPicNumberEx (Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *pMem)
 Requesting the current image number (non-blocking). .
 
PUBLIC_API int Fg_queueBuffer (Fg_Struct *fg, frameindex_t bufferIndex, uint64_t transferLength, uint32_t dmaIndex, dma_mem *memoryHandle)
 Queues a buffer for DMA transmission.
 
PUBLIC_API 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. .
 
PUBLIC_API 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 .
 
PUBLIC_API 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 .
 
PUBLIC_API int Fg_startBufferQueue (Fg_Struct *fg, uint32_t dmaIndex, dma_mem *memoryHandle)
 Starts transmission of queued buffers.
 
PUBLIC_API int Fg_stopAcquire (Fg_Struct *Fg, const unsigned int DmaIndex)
 Stopping image grabbing. .
 
PUBLIC_API int Fg_stopAcquireEx (Fg_Struct *Fg, const unsigned int DmaIndex, dma_mem *memHandle, int nFlag)
 Stopping image grabbing .
 
PUBLIC_API int Fg_stopBufferQueue (Fg_Struct *fg, uint32_t dmaIndex, int32_t flags)
 Stops the processing of the buffer queue.
 
PUBLIC_API int Fg_waitForBuffers (Fg_Struct *fg, uint32_t dmaIndex, uint64_t timeoutSeconds, void *reserved1, size_t reserved2)
 Waits for new buffers to be become available again. If any buffers were processed when calling this function, it returns immediately. Otherwise it blocks until at least one buffer becomes available.
 
PUBLIC_API const char * getErrorDescription (int ErrorNumber)
 Description of error message. .
 
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.

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

PUBLIC_API int DEPRECATED (Fg_setExsync(Fg_Struct *Fg, int Flag, const unsigned int CamPort))
 set Exsync camera signal
 
PUBLIC_API int DEPRECATED (Fg_setFlash(Fg_Struct *Fg, int Flag, const unsigned int CamPort))
 set strobe camera signal
 
PUBLIC_API int Fg_activateEvents (Fg_Struct *Fg, uint64_t mask, int enable)
 activates/disable event generation
 
PUBLIC_API int Fg_clearEvents (Fg_Struct *Fg, uint64_t mask)
 drop all already queued events
 
PUBLIC_API uint64_t Fg_eventWait (Fg_Struct *Fg, uint64_t mask, unsigned int timeout, unsigned int flags, struct fg_event_info *info)
 wait for events
 
PUBLIC_API int Fg_getEventCount (Fg_Struct *Fg)
 get the number of available event types
 
PUBLIC_API uint64_t Fg_getEventMask (Fg_Struct *Fg, const char *name)
 get the event mask for the named event
 
PUBLIC_API const char * Fg_getEventName (Fg_Struct *Fg, uint64_t mask)
 get the name for the event represented by the event mask
 
PUBLIC_API int Fg_getEventPayload (Fg_Struct *Fg, uint64_t mask)
 get the payload size for the event represented by the event mask
 
PUBLIC_API int Fg_registerAsyncNotifyCallback (Fg_Struct *Fg, Fg_AsyncNotifyFunc_t handler, void *context)
 register callback for asynchronous notifications
 
PUBLIC_API int Fg_registerEventCallback (Fg_Struct *Fg, uint64_t mask, Fg_EventFunc_t handler, void *data, unsigned int flags, struct fg_event_info *info)
 register callback for events
 
PUBLIC_API int Fg_resetAsyncNotify (Fg_Struct *Fg, unsigned long notification, unsigned long pl, unsigned long ph)
 acknowledge an asynchronous notifications
 
PUBLIC_API int Fg_sendSoftwareTrigger (Fg_Struct *Fg, const unsigned int CamPort)
 send trigger signal to the camera
 
PUBLIC_API int Fg_sendSoftwareTriggerEx (Fg_Struct *Fg, const unsigned int CamPort, const unsigned int Triggers)
 send multiple trigger signals to the camera
 
PUBLIC_API int Fg_setAsyncNotify (Fg_Struct *Fg, unsigned long notification, unsigned long pl, unsigned long ph)
 trigger an asynchronous notifications
 
PUBLIC_API int Fg_unregisterAsyncNotifyCallback (Fg_Struct *Fg, Fg_AsyncNotifyFunc_t handler, void *context)
 unregister callback for asynchronous notifications
 
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.
PUBLIC_API int DEPRECATED (getLastErrorNumber())
 stub to maintain interface compatibility
 
PUBLIC_API ShadingMasterFg_AllocShading (Fg_Struct *Fg, int set, const unsigned int CamPort)
 allocate shading control object
 
PUBLIC_API int Fg_FreeShading (Fg_Struct *Fg, ShadingMaster *sh)
 release shading control object
 
PUBLIC_API int Shad_FreeAccess (Fg_Struct *Fg, ShadingMaster *sh)
 deactivate shading object
 
PUBLIC_API int Shad_GetAccess (Fg_Struct *Fg, ShadingMaster *sh)
 activate shading object
 
PUBLIC_API int Shad_GetMaxLine (Fg_Struct *Fg, ShadingMaster *sh)
 query current line number for shading correction
 
PUBLIC_API int Shad_SetFixedPatternNoiseLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, int on)
 set defective pixel interpolation value for shading correction
 
PUBLIC_API int Shad_SetMultValueLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, float mult)
 set multiplicative correction value for shading correction
 
PUBLIC_API int Shad_SetSubValueLine (Fg_Struct *Fg, ShadingMaster *sh, int x, int channel, float sub)
 set substractive correction value for shading correction
 
PUBLIC_API int Shad_WriteActLine (Fg_Struct *Fg, ShadingMaster *sh, int Line)
 write shading correction values for given line
 

Detailed Description

Header file for all functions exported.

basler_fg.h

Copyright (c) 2021-2024 Basler AG, All Rights Reserved.

Author
Basler AG

Macro Definition Documentation

◆ PUBLIC_API

#define PUBLIC_API

Typedef Documentation

◆ dma_mem

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.

◆ ShadingMaster

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

◆ DEPRECATED() [1/3]

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

set Exsync camera signal

Parameters
Fgframe grabber to use
FlagExsync value to set (FG_ON or FG_OFF).
CamPortCamera port to set.
Returns
Status code.
Return values
FG_OKExsync value was set.
FG_INVALID_PARAMETERan 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.

◆ DEPRECATED() [2/3]

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

set strobe camera signal

Parameters
Fgframe grabber to use
FlagStrobe value to set (FG_ON or FG_OFF).
CamPortCamera port to set.
Returns
Status code.
Return values
FG_OKExsync value was set.
FG_INVALID_PARAMETERan 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.

◆ DEPRECATED() [3/3]

PUBLIC_API int DEPRECATED ( 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.

◆ Fg_AbortInitLibraries()

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

◆ Fg_Acquire()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
PicCountMaximum number of images to be grabbed. Must be a positive number, GRAB_INFINITE or GRAB_ALL_BUFFERS. GRAB_INFINITE, means infinite grabbing. GRAB_ALL_BUFFERS, means grabbing until the buffer is filled.
Return values
FG_OKGrabbing has been started correctly. (when grabbing synchronously also finished correctly).
FG_NOT_INITFrame grabber was not initialised correctly.
FG_NO_VALID_DESIGNNo valid design was loaded.
FG_INVALID_MEMORYImage memory was not allocated.
FG_MEMORY_IN_USEImage memory is already used by another DMA channel.
FG_NOT_ENOUGH_MEMORYInsufficient image memory was allocated for specified image parameter.
FG_ALREADY_STARTEDGrabbing is already started and can't be started twice.
FG_INVALID_PARAMETERInvalid parameter is set.

◆ Fg_AcquireEx()

PUBLIC_API 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, ACQ_BLOCK and ACQ_SELECT. If the mode ACQ_STANDARD is used, the image memory is used as a cyclic buffer and all subbuffers will be overwritten continuously. Fg_getLastPicNumberBlockingEx should be used to wait for new images. If the mode ACQ_BLOCK is used, the acquired frame buffer is blocked as long as it is explicitly released by the user by calling Fg_setStatusEx using FG_UNBLOCK. 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. For each subbuffer number, the corresponding image number can be requested by calling Fg_getParameterEx using FG_IMAGE_NUMBER. Fg_getImageEx should be used to wait for new images. If the mode ACQ_SELECT is used, every subbuffer must be selected explicitly before it is used for image data transfer by calling Fg_setStatusEx using FG_SELECT_BUFFER. There is no unique assignment between image number and subbuffer number in this grabbing model. Keeping track of the use of subbuffers is the responsibility of the user. Fg_getLastPicNumberBlockingEx should be used to wait for new images.

If ACQ_NO_AUTOSTOP is used along ACQ_STANDARD, ACQ_BLOCK or ACQ_SELECT, and the number of images to be acquired was specified, then Fg_stopAcquireEx will not be called implicitly after the requested number of images was acquired. The acquisition is still stopped in the driver, however.

Parameters
Fgframe grabber to use
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
PicCountMaximum number of images to be grabbed. Must be a positive number, GRAB_INFINITE or GRAB_ALL_BUFFERS. GRAB_INFINITE, means infinite grabbing. GRAB_ALL_BUFFERS, means grabbing until the buffer is filled.
nFlagACQ_STANDARD, ACQ_BLOCK, ACQ_SELECT, ACQ_NO_AUTOSTOP
memHandlePointer to handle of frame buffer.
Return values
FG_OKGrabbing has been started correctly. (when grabbing synchronously also finished correctly).
FG_NOT_INITFrame grabber was not initialised correctly.
FG_INVALID_MEMORYImage memory was not allocated.
FG_MEMORY_IN_USEImage memory is already used by another DMA channel.
FG_NOT_ENOUGH_MEMORYInsufficient image memory was allocated for specified image parameter.
FG_ALREADY_STARTEDGrabbing is already started and can't be started twice.
FG_INVALID_PARAMETERInvalid parameter is set.
FG_ILLEGAL_WHILE_APCAn APC from a previous acquisition is still active

◆ Fg_activateEvents()

PUBLIC_API int Fg_activateEvents ( Fg_Struct * Fg,
uint64_t mask,
int enable )

activates/disable event generation

Parameters
Fgframe grabber to use
maskevent mask to work on
enable0 to disable, 1 to enable
Return values
FG_NOT_INITFg is NULL
FG_INVALID_PARAMETERenable 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_addAppletIteratorItem()

PUBLIC_API 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
iterApplet iterator
pathPath, file or name of the applet
numItemsNumber of all applet in iterator
Returns
Applet iterator item or NUll in case of an error

◆ Fg_AddMem()

PUBLIC_API 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
Fgframe grabber to use
pBufferPointer to user memory to be added.
SizeSize of user memory in byte.
bufferIndexIndex of subbuffer to add (range 0 to BufCnt as passed to Fg_AllocMemHead())
memHandlePointer to the handle on frame buffer.
Returns
Index of subbuffer.
Return values
FG_INVALID_PARAMETERAn invalid parameter has been used.

◆ Fg_AllocMem()

PUBLIC_API 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
Fgframe grabber to use
SizeSize of all image memory in byte.
BufCntNumber of internal buffer. Value must be 2, when using double-buffering.
DmaIndexLogical 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
NULLAn error occured. Use Fg_getLastErrorDescription() for more information.

◆ Fg_AllocMemEx()

PUBLIC_API 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
Fgframe grabber to use
SizeSize of all image memory in byte.
BufCntNumber of subbuffers.
Returns
A pointer to the allocated memory.
Return values
NULLAn error occured. Use Fg_getLastErrorDescription() for more information.

◆ Fg_AllocMemHead()

PUBLIC_API 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);
PUBLIC_API dma_mem * Fg_AllocMemHead(Fg_Struct *Fg, const size_t Size, const frameindex_t BufCnt)
Use an allocated user memory as frame buffer. .
struct dma_mem_s dma_mem
DMA buffer head control object.
Definition basler_fg.h:62
PUBLIC_API int Fg_FreeMemHead(Fg_Struct *Fg, dma_mem *memHandle)
Releasing memory. .
PUBLIC_API int Fg_DelMem(Fg_Struct *Fg, dma_mem *memHandle, const frameindex_t bufferIndex)
Deleting user memory, .
PUBLIC_API int Fg_AddMem(Fg_Struct *Fg, void *pBuffer, const size_t Size, const frameindex_t bufferIndex, dma_mem *memHandle)
Adding user memory. .
PUBLIC_API int Fg_AcquireEx(Fg_Struct *Fg, const unsigned int DmaIndex, const frameindex_t PicCount, const int nFlag, dma_mem *memHandle)
Starting image grabbing. .
Parameters
Fgframe grabber to use
SizeSize of all image memory in byte.
BufCntNumber of subbuffers.
Returns
A valid handle on frame buffer.
Return values
NULLAn 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.

◆ Fg_AllocShading()

PUBLIC_API ShadingMaster * Fg_AllocShading ( Fg_Struct * Fg,
int set,
const unsigned int CamPort )

allocate shading control object

Parameters
Fgframe grabber to use
setShading data set to use.
CamPortCamera port to associate this shading buffer.
Returns
Pointer to shading control object
Return values
NULLShading 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.

◆ Fg_clearEvents()

PUBLIC_API int Fg_clearEvents ( Fg_Struct * Fg,
uint64_t mask )

drop all already queued events

Parameters
Fgframe grabber to use
maskwhich events to clear
Return values
FG_NOT_INITFg is NULL
FG_INVALID_PARAMETERmask 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

◆ Fg_DelMem()

PUBLIC_API 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
Fgframe grabber to use
memHandlePointer to the handle on frame buffer.
bufferIndexIndex of subbuffers, the user memory should be deleted from.
Return values
FG_OKUser memory has been deleted correctly.
FG_INVALID_PARAMETERAn invalid parameter has been used.

◆ Fg_eventWait()

PUBLIC_API uint64_t Fg_eventWait ( Fg_Struct * Fg,
uint64_t mask,
unsigned int timeout,
unsigned int flags,
struct fg_event_info * info )

wait for events

Parameters
Fgframe grabber to use
maskevent mask
timeouttimeout in seconds
flagscontrol flags. Or'ed combination of FgEventControlFlags. In doubt use FG_EVENT_DEFAULT_FLAGS.
infoevent info structure to fill with additional data, in doubt pass NULL
Returns
mask of triggered events or 0 on error
Return values
0an 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

◆ Fg_findApplet()

PUBLIC_API 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 Basler Framegrabber SDK environment (e.g. BASLER_FG_SDK_DIR) If the applet file name exceeds the size of the buffer of returning the information, FG_NOT_ENOUGH_MEMORY is returned. is returned.

Parameters
BoardIndexLogical number of the board.
PathBuffer for returned string
SizeSize of the buffer in bytes
Returns
name of the applet as a 0 terminated string.
Return values
FG_OKsuccess, Path contains the applet path
FG_INVALID_PARAMETERbuffer or buffer size are invalid
FG_INVALID_BOARD_NUMBERinvalid board number (or board type)
FG_DLL_NOT_LOADunknown board type
FG_ENV_NOT_SETno search path available
FG_NOT_ENOUGH_MEMORYapplet file name exceeds the size of the buffer

◆ Fg_findAppletIteratorItem()

PUBLIC_API 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
iterapplet iterator
pathpath, 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

◆ Fg_freeAppletIterator()

PUBLIC_API int Fg_freeAppletIterator ( Fg_AppletIteratorType iter)

This function releases an applet iterator .

Parameters
iterThe iterator to be released
See also
Fg_getAppletIterator

◆ Fg_FreeGrabber()

PUBLIC_API 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
Fgframe grabber to release
Return values
FG_OKThe operating frame grabber has been stopped successfully.
FG_NOT_INITFrame grabber has not been initialized correctly.
FG_FILE_NOT_FOUNDThe file cannot be found
FG_INVALID_FILENAMEThe filename is not a valid filename
FG_ENV_NOT_SETThe environment variable BASLER_FG_SDK_DIR is not set
FG_NOT_ENOUGH_MEMThe system memory is insufficient for loading control structures
FG_CANNOT_INIT_MICROENABLEThe frame grabber cannot be initialized
FG_HAP_FILE_NOT_LOADThe Applet file (HAP file) is not a valid HAP file

◆ Fg_FreeLibraries()

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

◆ Fg_FreeMem()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values
FG_OKImage memory has been released successfully.
FG_NOT_INITA failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVETransfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.

◆ Fg_FreeMemEx()

PUBLIC_API 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
Fgframe grabber to use
memHandle on memory area which has been reserved with with Fg_AllocMemEx().
Return values
FG_OKImage memory has been released successfully.
FG_NOT_INITA failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVETransfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.

◆ Fg_FreeMemHead()

PUBLIC_API 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
Fgframe grabber to use
memHandleHandle on memory area, which has been reserved by Fg_AllocMemEx() or Fg_AllocMemHead().
Return values
FG_OKImage memory has been released successfully.
FG_NOT_INITA failed try to release. Although, frame grabber has not been initialized correctly.
FG_STILL_ACTIVETransfer of an image is still active. The transfer has to be stopped before releasing the frame grabber buffer.

◆ Fg_freeParameterStringWithType()

PUBLIC_API 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
FgThe frame grabber handle
ParameterThe parameter ID
ValueA pointer to the variable for the value
DmaIndexThe DMA, frame grabber port, or applet process index
typeThe 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).

◆ Fg_FreeShading()

PUBLIC_API int Fg_FreeShading ( Fg_Struct * Fg,
ShadingMaster * sh )

release shading control object

Parameters
Fgframe grabber to use
shShading control object to release.
Returns
Status code.
Return values
FG_OKShading control object was released.
FG_INVALID_PARAMETERan 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.

◆ Fg_getAppletId()

PUBLIC_API int Fg_getAppletId ( Fg_Struct * Fg,
const char * ignored )

Get the ID of the currently running applet. .

Parameters
Fgframe grabber to use
ignoredshould be NULL
Returns
the applet ID of the design if it is not a design created using VisualApplets.

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

◆ Fg_getAppletIntProperty()

PUBLIC_API 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
itemApplet item that is retrieved from Fg_getAppletIteratorItem
propertySelected property
Returns
integer value corresponding to the passed property

◆ Fg_getAppletIterator()

PUBLIC_API 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
boardIndexBoard index
srcApplets' source.
iterA pointer to return the iterator
flagsCan 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_getAppletIteratorItem()

PUBLIC_API 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
iterapplet iterator
indexindex 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

◆ Fg_getAppletStringProperty()

PUBLIC_API 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
itemapplet item that is retrieved from Fg_getAppletIteratorItem
propertyselected property
Returns
string value corresponding to the passed property

◆ Fg_getAppletVersion()

PUBLIC_API const char * Fg_getAppletVersion ( Fg_Struct * Fg,
int AppletId )

Get the version of the currently running applet. .

Parameters
Fgframe grabber to use
AppletIdThe applet ID returned by Fg_getappletId()
Returns
the applet version of the design if it is not a design created using VisualApplets.

See fg_define.h for the list of ids.

◆ Fg_getBitsPerPixel()

PUBLIC_API int Fg_getBitsPerPixel ( int format)

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

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

◆ Fg_getBoardNameByType()

PUBLIC_API 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
BoardTypetype of the board
UseShortNameget the short name for the board
Return values
NULLthere is no board with the given type

See sisoboards.h for the board type definitions.

◆ Fg_getBoardType()

PUBLIC_API 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
BoardIndexindex of the board
Return values
FG_INVALID_BOARD_NUMBERthere is no board with the given index
FG_ERRORthe board type could not be determined (e.g. the Framegrabber SDK is too old and does not support the given board)

See sisoboards.h for the board type definitions.

If you already have initialized the board, you can also use

uint32_t boardType = BINFO_BOARDTYPE;
PUBLIC_API 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. .
@ FG_PARAM_TYPE_UINT32_T
Definition fg_define.h:220
@ BINFO_BOARDTYPE
Definition fg_define.h:1047
#define FG_BOARD_INFORMATION
Definition fg_define.h:1036

◆ Fg_getErrorDescription()

PUBLIC_API const char * 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
Fgframe grabber to use
ErrorNumberIdentification number of error code.
Returns
Error message of the error code specified

◆ Fg_getEventCount()

PUBLIC_API int Fg_getEventCount ( Fg_Struct * Fg)

get the number of available event types

Parameters
Fgframe 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

◆ Fg_getEventMask()

PUBLIC_API uint64_t Fg_getEventMask ( Fg_Struct * Fg,
const char * name )

get the event mask for the named event

Parameters
Fgframe grabber to use
namename of the requested event
Returns
event mask of the event
Return values
0no event of the given name was found
Since
5.1.0

◆ Fg_getEventName()

PUBLIC_API const char * Fg_getEventName ( Fg_Struct * Fg,
uint64_t mask )

get the name for the event represented by the event mask

Parameters
Fgframe grabber to use
maskevent 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

◆ Fg_getEventPayload()

PUBLIC_API int Fg_getEventPayload ( Fg_Struct * Fg,
uint64_t mask )

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

Parameters
Fgframe grabber to use
maskevent 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

◆ Fg_getImage()

PUBLIC_API 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
Fgframe grabber to use
ParamSee table below ...
PicNr0 in blocking mode, image number in default grabbing mode.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
TimeoutDuration of timeout in seconds.
Returns
Buffer number, beginning with 0.
Return values
FG_TIMEOUT_ERRTimeout occurs.
FG_INVALID_PARAMETERThis error occurs, either if the image number is <= 0 or if the blocking mode has been chosen in case of flag SEL_NUMBER.

◆ Fg_getImageEx()

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

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
Fgframe grabber to use
ParamSee table below ...
PicNr0 in blocking mode, image number in default grabbing mode.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
TimeoutDuration of timeout in seconds.
pMemPointer to variable buffer.
Returns
Buffer number, beginning with 0.
Return values
FG_TIMEOUT_ERRTimeout occurs.
FG_INVALID_PARAMETERThis error occurs, either if the image number is <= 0 or if the blocking mode has been chosen in case of flag SEL_NUMBER.

◆ Fg_getImagePtr()

PUBLIC_API 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
Fgframe grabber to use
PicNrNumber of frame buffer or picture number.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
Returns
Pointer to current image position.

◆ Fg_getImagePtrEx()

PUBLIC_API 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
Fgframe grabber to use
PicNrNumber of frame buffer or picture number.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
pMemPointer to variable buffer.
Returns
Pointer to current image position.

◆ Fg_getLastErrorDescription()

PUBLIC_API const char * 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
Fgframe grabber to use
Returns
The message of the last error that occurred.

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

◆ Fg_getLastErrorNumber()

PUBLIC_API int Fg_getLastErrorNumber ( Fg_Struct * Fg)

Getting the last error code. .

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

Parameters
Fgframe grabber to use
Returns
The number of the last error that occurred.

◆ Fg_getLastPicNumber()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical 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
0Transmission is running, no image has been completely transfered, yet.
FG_TIMEOUT_ERRTimeout occurs.
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getLastPicNumberBlocking()

PUBLIC_API 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
Fgframe grabber to use
PicNrRequested image number. If PicNr is negative, the function waits for the next |picNr| frames. If PicNr is 0, the current frame index is returned (may be 0, if nothing was required, yet).
DmaIndexLogical number of used camera port camera port A = 0 and camera port B = 1
TimeoutTimeout in seconds.
Returns
Current image number, beginning with 1.
Return values
FG_TIMEOUT_ERRTimeout error occurred.
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getLastPicNumberBlockingEx()

PUBLIC_API 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
Fgframe grabber to use
PicNrRequested image number. If PicNr is negative, the function waits for the next |picNr| frames. If PicNr is 0, the current frame index is returned (may be 0, if nothing was required, yet).
DmaIndexLogical number of used camera port camera port A = 0 and camera port B = 1
TimeoutTimeout in seconds.
pMemPointer to variable buffer.
Returns
Current image number, beginning with 1.
Return values
FG_TIMEOUT_ERRTimeout error occurred.
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getLastPicNumberEx()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
pMemPointer to variable buffer.
Returns
Number of the last completely transferred image, transmission is running.
Return values
0Transmission is running, no image has been completely transfered, yet.
FG_TIMEOUT_ERRTimeout occurs.
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getNrOfParameter()

PUBLIC_API int Fg_getNrOfParameter ( Fg_Struct * Fg)

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

Parameters
Fgframe grabber to use
Returns
The number of parameters.
Return values
<0An error occured. (Use Fg_getLastErrorDescription() for more information.)

◆ Fg_getParameter()

PUBLIC_API 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
Fgframe grabber to use
ParameterThe 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 ...
ValuePointer to required value.
DmaIndexLogical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values
FG_OKThe parameter value has been read correctly.
FG_NOT_INITInitialization has failed.
FG_INVALID_PARAMETERAn invalid parameter has been entered.

◆ Fg_getParameterEx()

PUBLIC_API 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.
frameindex_tFG_IMAGE_NUMBERImage number of 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
Fgframe grabber to use
ParameterThe parameter ID.
ValuePointer to memory where requested value will be stored.
DmaIndexIgnored, should be 0.
pMemHandle on memory area which has been reserved.
ImgNrImage number to query.
Return values
FG_OKThe parameter value has been read correctly.
FG_NOT_INITInitialization has failed.
FG_INVALID_PARAMETERAn invalid parameter has been entered.

◆ Fg_getParameterId()

PUBLIC_API 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
fgframe grabber to use
indexParameter index.
Returns
The parameter ID.
Return values
<0The parameter couldn't be found.

◆ Fg_getParameterIdByName()

PUBLIC_API 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));
}
PUBLIC_API int Fg_getParameterId(Fg_Struct *fg, int index)
The function Fg_getParameterId() returns the parameter ID of the parameter referenced by index....
PUBLIC_API const char * Fg_getParameterName(Fg_Struct *fg, int index)
The function Fg_getParameterName() informs about the name of a special parameter by index....
Parameters
fgframe grabber to use
nameFull Parameter name.
Returns
The parameter ID.
Return values
<0The parameter couldn't be found.

◆ Fg_getParameterInfoXML()

PUBLIC_API 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
Fgframe grabber to use
portLogical number of used camera port. camera port A = 0 and camera port B = 1
infoBufferPointer to a buffer where the XML information will be placed.
infoBufferSizeInput: 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_OKThe operation was successful.
FG_INTERNAL_ERRORThe internal parameter structures are not existing
FG_NOT_ENOUGH_MEMThe infoBuffer size contained in infoBufferSize is not sufficient.

◆ Fg_getParameterName()

PUBLIC_API const char * Fg_getParameterName ( Fg_Struct * fg,
int index )

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

Parameters
fgframe grabber to use
indexParameter index.
Returns
A char pointer to the parameter full name string.

◆ Fg_getParameterNameById()

PUBLIC_API const char * 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
fgThe frame grabber to use
idParameter id.
dmaThe dma, process or port.
Returns
A char pointer to the parameter full name string.

◆ Fg_getParameterProperty()

PUBLIC_API 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
Fgframe grabber to use
parameterIdID of parameter
propertyIdproperty to be queried
bufferpointer 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_OKsuccess
<>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

◆ Fg_getParameterPropertyEx()

PUBLIC_API 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
Fgframe grabber to use
parameterIdID of parameter
propertyIdproperty to be queried
DmaIndexthe DMA index for the parameter to be queried
bufferpointer 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_OKsuccess
<>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

◆ Fg_getParameterType()

PUBLIC_API enum FgParamTypes Fg_getParameterType ( Fg_Struct * fg,
int index )

The function Fg_getParameterType() informs about the type of a special parameter by index. .

Parameters
fgframe grabber to use
indexParameter index.
Returns
The type of the parameter.

◆ Fg_getParameterTypeById()

PUBLIC_API enum FgParamTypes Fg_getParameterTypeById ( Fg_Struct * fg,
const unsigned int id,
const unsigned int dma )

The function Fg_getParameterTypeById() informs about the type of a parameter by its id. .

Parameters
fgThe frame grabber to use
idParameter id.
dmaThe dma, process or port.
Returns
The type of the parameter.

◆ Fg_getParameterWithType()

PUBLIC_API 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
FgThe frame grabber handle
ParameterThe parameter ID
ValueA pointer to the variable for the value
DmaIndexThe DMA, frame grabber port, or applet process index
typeThe 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.

◆ Fg_getSerialNumber()

PUBLIC_API unsigned int Fg_getSerialNumber ( Fg_Struct * Fg)

Serial number. .

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

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

◆ Fg_getStatus()

PUBLIC_API 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
Fgframe grabber to use
ParamSee table below ...
DataOptional data.
DmaIndexLogical 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_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getStatusEx()

PUBLIC_API 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
Fgframe grabber to use
ParamSee table below ...
DataOptional data, details see parameter "Param".
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
pMemPointer to variable buffer.
Returns
Return depends on given flag, see table above ...
Return values
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_getSWVersion()

PUBLIC_API const char * Fg_getSWVersion ( )

Software version number. .

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

Returns
version of the Framegrabber SDK running, i. e. "5.10.0"

◆ Fg_getSystemInformation()

PUBLIC_API 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
Fgframe grabber to use, might set to 0 for global information, must be set at certain parameters
selectorvalue to query
propertyIddetermine which information to get, corresponding to FgProperty
param11st 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
bufferbuffer for result value; for some queries the buffer is used both for input and output, on output the buffer will be overwritten
bufLenlength 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_Init()

PUBLIC_API 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
FileNameApplet name for initialization.
BoardIndexLogical number of the board.
Returns
Initialized pointer on the data structure of the FrameFrabber.
Return values
NULLThe initialization failed.

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

◆ Fg_InitConfig()

PUBLIC_API 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_NameApplet name for initialization.
BoardIndexLogical number of the board.
Returns
Initialized pointer on the data structure of the FrameFrabber.
Return values
NULLThe initialization failed.

◆ Fg_InitConfigEx()

PUBLIC_API 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_NameApplet name for initialization.
BoardIndexLogical number of the board.
flagsFlags to modify the initialization behavior (see MeInitFlags).
Returns
Initialized pointer on the data structure of the FrameFrabber.
Return values
NULLThe initialization failed.

◆ Fg_InitEx()

PUBLIC_API 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
FileNameApplet name for initialization.
BoardIndexLogical number of the board.
flagsFlags to modify the initialization behavior.
Returns
Initialized pointer on the data structure of the FrameFrabber.
Return values
NULLThe initialization failed.

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

◆ Fg_InitLibraries()

PUBLIC_API 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 Basler Framegrabber SDK. When Fg_InitLibraries() returns 0, you must call Fg_FreeLibraries() before exiting your program.

Parameters
sisoDirUser supplied directory to the Framegrabber SDK installation (optional; can be NULL)
Returns
0 on success, or a non-zero error value otherwise
Return values
FG_OKsuccess
FG_NOT_IMPLEMENTEDfunction is not implemented
FG_ENV_NOT_SETno search path available
FG_OPERATION_ABORTEDsynchronization has been aborted

◆ Fg_InitLibrariesEx()

PUBLIC_API 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 Basler Framegrabber SDK. 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
sisoDirUser supplied directory to the Framegrabber SDK installation (optional; can be NULL)
flagsAdditional flags to control the synchronization
idThe identifier which should be used for synchronization (Master and Slaves must use the same identifier; not used in single mode)
timeoutTimeout in milliseconds to wait for synchronization
Returns
0 on success, or a non-zero error value otherwise
Return values
FG_OKsuccess
FG_NOT_IMPLEMENTEDfunction is not implemented
FG_ENV_NOT_SETno search path available
FG_OPERATION_ABORTEDsynchronization has been aborted
FG_TIMEOUTwaiting for synchronization timed out

◆ Fg_InitLibrariesStartNextSlave()

PUBLIC_API 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, ...).

◆ Fg_loadConfig()

PUBLIC_API 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
Fgframe grabber to use
FilenameName and path to microEnable configuration file.
Return values
FG_OKTransmission has been finished successfully.
FG_NOT_INITFrame grabber hasn't been initialized correctly.
FG_INVALID_FILENAMEFilename hasn't been found.
FG_INVALID_CONFIGFILEConfiguration file is invalid.
FG_INVALID_IMAGE_DIMENSIONSexternal image data does not match to Applets needs

◆ Fg_loadFieldParameterFromFile()

PUBLIC_API 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
Fgframe grabber to use
Parameterparameter id
DmaIndexcam port
FileNameName and path to field parameter file.
Return values
FG_OKLoading parameter done successfully.
FG_PARAMETER_NOT_IN_FILEParameter is not in file
FG_NOT_INITThe Frame grabber handle is invalid or null
FG_INVALID_CONFIGFILEFile format is incorrect or corrupted data if it already exists
FG_INVALID_PARAMETERThe 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_FOUNDFile name is invalid or not exists
FG_FILE_ACCESS_DENIEDUnexpected internal error by reading from or writing in file
FG_ERRORUnexpected internal error

◆ Fg_NumaAllocDmaBuffer()

PUBLIC_API 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
Fgframe grabber to use
SizeSize of all image memory in byte.
Returns
A pointer to the allocated frame memory / image data.
Return values
NULLAn error occured. Use Fg_getLastErrorDescription() for more information.

◆ Fg_NumaFreeDmaBuffer()

PUBLIC_API 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
Fgframe grabber to use
Bufferpointer to frame memory
Returns
0 on success.
Return values
<0An error occured. (Use Fg_getLastErrorDescription() for more information.)

◆ Fg_NumaPinThread()

PUBLIC_API int Fg_NumaPinThread ( Fg_Struct * Fg)

NUMA aware pinning of thread affinity. .

Parameters
Fgframe grabber to use
Returns
0 on success.
Return values
<0An error occured. (Use Fg_getLastErrorDescription() for more information.)

◆ Fg_queueBuffer()

PUBLIC_API int Fg_queueBuffer ( Fg_Struct * fg,
frameindex_t bufferIndex,
uint64_t transferLength,
uint32_t dmaIndex,
dma_mem * memoryHandle )

Queues a buffer for DMA transmission.

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

Parameters
fgframe grabber to use
bufferIndexbuffer to be queued. Indices starting with 0
transferLengthFor transmissions from frame grabber to PC: ignored. For transmissions from PC to frame grabber (requires special applets): length of the data to be transmitted in bytes, must be a multiple of 32.
dmaIndexLogical number of the DMA channel depending on the applet. Indices starting with 0. This argument can be omitted when a memoryHandle is provided. If conflicting dmaIndex and memoryHandle are provided, the provided memoryHandle is taken.
memoryHandlepointer to memory structure, which has been allocated be Fg_allocMemEx. If a dmaIndex is provided, for wich the buffer queue is already running, this argument may be NULL since it can be deduced from the dmaIndex. If conflicting dmaIndex and memoryHandle are provided, the provided memoryHandle is taken.
Returns
various FG-error codes, call Fg_getLastError to obtain the error

◆ Fg_readUserDataArea()

PUBLIC_API 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
Fgframe grabber to use, if set to 0 you must provide a board number
boardIdboard number, can be set to (-1) if you supply a frame grabber handle
offsoffset to the start of the user memory area
sizenumber of bytes to read
bufferbuffer 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

◆ Fg_registerApcHandler()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexDMA channel number to listen on
controlcontrol structure for APC operations
flagshow to handle the control structure
Returns
FG_OK if the handler was successfully registered, error code otherwise.
Return values
FG_NOT_INITFg is NULL
FG_INVALID_PORT_NUMBERDmaIndex is invalid
FG_INVALID_PARAMETEROne parameter or the combination of parameters is invalid
FG_ALREADY_STARTEDan APC handler for this DMA channel is already registered
FG_NOT_ENOUGH_MEMORYcreation of the internal control structures or the worker thread failed
FG_APC_PRIORITY_ERRORthe control structure requested FG_APC_HIGH_PRIORITY but setting the priority failed
FG_ACCESS_DENIEDsetting the Priority fails due to insufficient permissions
FG_APC_ALREADY_REGISTEREDan 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 fg_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:

PUBLIC_API 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. .
@ FG_APC_CONTROL_BASIC
Definition fg_define.h:1360

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 MyClass {
private:
Fg_Struct *fg;
unsigned int dma;
dma_mem *mem;
static int apcFunc(frameindex_t frame, void *context);
int processImage(frameindex_t frame);
// more private member functions ...
public:
MyClass(Fg_Struct *fg, unsigned int dma);
~MyClass();
int registerApc();
// more public member functions ...
};
int MyClass::apcFunc(frameindex_t frame, void *context)
{
return reinterpret_cast<MyClass *>(context)->processImage(frame);
}
int MyClass::processImage(frameindex_t frame)
{
void *data = Fg_getImagePtrEx(fg, frame, dma, mem);
size_t len = 0;
Fg_getParameterEx(fg, FG_TRANSFER_LEN, &len, dma, mem, frame);
// ... process image data
return 0;
}
MyClass::MyClass(Fg_Struct *fg, unsigned int dma)
: fg(fg), dma(dma), mem(nullptr)
{}
MyClass::~MyClass()
{
}
int MyClass::registerApc()
{
struct FgApcControl ctrl;
ctrl.func = &MyClass::apcFunc;
ctrl.data = this;
ctrl.flags = FG_APC_DEFAULTS;
ctrl.timeout = 10;
return Fg_registerApcHandler(apcdata.fg, apcdata.dma, &ctrl, FG_APC_CONTROL_BASIC);
}
PUBLIC_API void * Fg_getImagePtrEx(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, dma_mem *pMem)
Access on frame buffer. .
PUBLIC_API 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. .
#define FG_TRANSFER_LEN
Definition fg_define.h:731
@ FG_APC_DEFAULTS
Definition fg_define.h:1346
struct Fg_Struct_s Fg_Struct
The structure for a framegrabber.
Definition fg_struct.h:153
long frameindex_t
Definition os_type.h:78
Definition fg_struct.h:133
Fg_ApcFunc_t func
Definition fg_struct.h:136

◆ Fg_registerAsyncNotifyCallback()

PUBLIC_API int Fg_registerAsyncNotifyCallback ( Fg_Struct * Fg,
Fg_AsyncNotifyFunc_t handler,
void * context )

register callback for asynchronous notifications

Parameters
Fgframe grabber to use
handlernotification handler function to call
contextcontext 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

◆ Fg_registerEventCallback()

PUBLIC_API int Fg_registerEventCallback ( Fg_Struct * Fg,
uint64_t mask,
Fg_EventFunc_t handler,
void * data,
unsigned int flags,
struct fg_event_info * info )

register callback for events

Parameters
Fgframe grabber to use
maskevent mask
handlerevent handler function to call
datacontext data passed to handler on event
flagscontrol flags. Or'ed combination of FgEventControlFlags. In doubt use FG_EVENT_DEFAULT_FLAGS.
infoevent 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);
PUBLIC_API int Fg_registerEventCallback(Fg_Struct *Fg, uint64_t mask, Fg_EventFunc_t handler, void *data, unsigned int flags, struct fg_event_info *info)
register callback for events
@ FG_EVENT_DEFAULT_FLAGS
Definition fg_define.h:1388

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

◆ Fg_resetAsyncNotify()

PUBLIC_API int Fg_resetAsyncNotify ( Fg_Struct * Fg,
unsigned long notification,
unsigned long pl,
unsigned long ph )

acknowledge an asynchronous notifications

Parameters
Fgframe grabber to use
notificationthe notification code
plparameter 1 (notification dependent)
phparameter 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

◆ Fg_saveConfig()

PUBLIC_API 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
Fgframe grabber to use
FilenameName and path of the frame grabber configuration file.
Return values
FG_OKTransmission has been finished successfully.
FG_NOT_INITFrame grabber hasn't been initialized correctly.
FG_INVALID_FILENAMEFilename hasn't been found.

◆ Fg_saveFieldParameterToFile()

PUBLIC_API 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
Fgframe grabber to use
Parameterparameter id
DmaIndexcam port
FileNameName and path of field parameter file.
Return values
FG_OKSaving parameter done successfully.
FG_NOT_INITThe Frame grabber handle is invalid or null
FG_INVALID_CONFIGFILEFile format is incorrect or corrupted data if it already exists
FG_INVALID_PARAMETERThe 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_FOUNDFile name is invalid
FG_FILE_ACCESS_DENIEDUnexpected internal error by reading from or writing in file
FG_ERRORUnexpected internal error

◆ Fg_sendImage()

PUBLIC_API 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
Fgframe grabber to use
startImagefirst image to be sent as index of the frame buffer
PicCountnumber of images to be sent,
nFlagreserved, should be 0
DmaIndexLogical number of the DMA's depending on the applet. Indizes starting with 0
Return values
variousFG-error codes, call Fg_getLastError to obtain the error

◆ Fg_sendImageEx()

PUBLIC_API 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
Fgframe grabber to use
startImagefirst image to be sent as index of the frame buffer
PicCountnumber of images to be sent,
nFlagreserved, should be 0
DmaIndexLogical number of the DMA's depending on the applet. Indizes starting with 0
memHandlepointer to memory structure, which has been allocated be Fg_allocMemEx
Return values
variousFG-error codes, call Fg_getLastError to obtain the error

◆ Fg_sendSoftwareTrigger()

PUBLIC_API int Fg_sendSoftwareTrigger ( Fg_Struct * Fg,
const unsigned int CamPort )

send trigger signal to the camera

Parameters
Fgframe grabber to use
CamPortCamera port to set.
Returns
Status code.
Return values
FG_OKTrigger was accepted (softwaretrigger mode). Queue empty and trigger accepted (softwaretrigger queue mode)
FG_INVALID_PARAMETERAn invalid argument was passed (e.g. nonexistent camera port).
FG_SOFTWARE_TRIGGER_PENDINGTrigger 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_BUSYThe 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.

◆ Fg_sendSoftwareTriggerEx()

PUBLIC_API int Fg_sendSoftwareTriggerEx ( Fg_Struct * Fg,
const unsigned int CamPort,
const unsigned int Triggers )

send multiple trigger signals to the camera

Parameters
Fgframe grabber to use
CamPortCamera port to set.
TriggersNumber of triggers to be sent to the camera.
Returns
Status code.
Return values
FG_OKTrigger was accepted (softwaretrigger mode). Trigger will be processed immediately
FG_INVALID_PARAMETERAn invalid argument was passed (e.g. nonexistent camera port).
FG_SOFTWARE_TRIGGER_PENDINGTrigger 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_BUSYTrigger pulse is already active (softwaretrigger mode). Trigger queue is too full to accept the value. (softwaretrigger queue mode)
FG_VALUE_OUT_OF_RANGEThe 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

◆ Fg_setAsyncNotify()

PUBLIC_API int Fg_setAsyncNotify ( Fg_Struct * Fg,
unsigned long notification,
unsigned long pl,
unsigned long ph )

trigger an asynchronous notifications

Parameters
Fgframe grabber to use
notificationthe notification code
plparameter 1 (notification dependent)
phparameter 2 (notification dependent)
Returns
FG_OK on success, error code otherwise

Use this function to trigger an asynchronous notification. This is mainly an internal function for tests.

Since
5.7

◆ Fg_setParameter()

PUBLIC_API 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
Fgframe grabber to use
ParameterThe 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 ...
ValuePointer to required value.
DmaIndexLogical number of used DMA channel. channel 1 = 0, channel 2 = 1 ... and so on.
Return values
FG_OKThe parameter has been set correctly.
FG_NOT_INITInitialization has failed.
FG_INVALID_PARAMETERAn invalid parameter has been entered.
FG_VALUE_OUT_OF_RANGEThe entered value is besides valid ranges.

◆ Fg_setParameterWithType()

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

◆ Fg_setStatus()

PUBLIC_API 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.
FG_SELECT_BUFFERExplicit selction of one buffer.
Parameters
Fgframe grabber to use
ParamSee table below ...
DataOptional data.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
Returns
Pointer to the corresponding buffer.
Return values
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_setStatusEx()

PUBLIC_API 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.
FG_SELECT_BUFFERExplicit selction of one buffer.
Parameters
Fgframe grabber to use
ParamSee table below ...
DataOptional data.
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
pMemPointer to variable buffer.
Returns
Pointer to the corresponding buffer.
Return values
FG_INVALID_PARAMETERAn invalid parameter has been given to the function.

◆ Fg_startBufferQueue()

PUBLIC_API int Fg_startBufferQueue ( Fg_Struct * fg,
uint32_t dmaIndex,
dma_mem * memoryHandle )

Starts transmission of queued buffers.

This function starts the processing of the buffer queue. The buffer queue will keep waiting for buffers to be queued and process these until the queue is stopped by calling Fg_stopBufferQueue().

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

Every subbuffer must be queued explicitly by calling #Fg_queueBufferEx.

There is no unique assignment between buffer number and subbuffer number. Keeping track of the use of subbuffers is the user's responsibility.

Fg_waitForBuffers should be used to wait for buffers to become available for re-queuing.

Parameters
fgframe grabber to use
memoryHandlehandle for the buffers, which should be used for this run of the buffer queue.
dmaIndexindex of the DMA channel to use
Return values
FG_OKThe buffer queue has been started correctly.
FG_NOT_INITThe frame grabber was not initialised correctly.
FG_INVALID_MEMORYBuffer memory was not allocated.
FG_MEMORY_IN_USEMemory handle is already used by another DMA channel.
FG_NOT_ENOUGH_MEMORYInsufficient buffer memory was allocated for specified buffer parameter.
FG_ALREADY_STARTEDBuffer queue processing is already started and can't be started twice.
FG_INVALID_PARAMETERInvalid parameter is set.
FG_ILLEGAL_WHILE_APCAn APC from a previous transmission is still active

◆ Fg_stopAcquire()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
Return values
FG_OKTransmission has been finished successfully.
FG_NOT_INITFrame grabber was not initialised correctly.
FG_TRANSFER_NOT_ACTIVETransmission was not started.
FG_INVALID_PARAMETERInvalid parameter is set.
FG_CANNOT_STOPFrame grabber could not stop.

◆ Fg_stopAcquireEx()

PUBLIC_API 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
Fgframe grabber to use
DmaIndexLogical number of used camera port. camera port A = 0 and camera port B = 1
memHandlePointer to handle of frame buffer.
nFlagSelecting 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_OKTransmission has been finished successfully.
FG_NOT_INITFrame grabber was not initialised correctly.
FG_TRANSFER_NOT_ACTIVETransmission was not started.
FG_INVALID_PARAMETERInvalid parameter is set.
FG_CANNOT_STOPFrame grabber could not stop.

◆ Fg_stopBufferQueue()

PUBLIC_API int Fg_stopBufferQueue ( Fg_Struct * fg,
uint32_t dmaIndex,
int32_t flags )

Stops the processing of the buffer queue.

This function stops processing of the buffer queue, therefore no more buffer transmissions will happen after calling this function.

In a dual grabber configuration, each port can be stopped separately. In a single grabber configuration only the active port.

The function Fg_stopBufferQueueEx() can stop the buffer queue processing asynchronously or synchronously. 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
fgframe grabber to use
dmaIndexLogical number of the DMA channel for which the queue is running.
flagsSelecting 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_OKThe buffer queue has been stopped successfully.
FG_NOT_INITFrame grabber was not initialised correctly.
FG_TRANSFER_NOT_ACTIVEThe buffer queue was not started.
FG_INVALID_PARAMETERInvalid parameter is set.
FG_CANNOT_STOPFrame grabber could not stop.

◆ Fg_unregisterAsyncNotifyCallback()

PUBLIC_API int Fg_unregisterAsyncNotifyCallback ( Fg_Struct * Fg,
Fg_AsyncNotifyFunc_t handler,
void * context )

unregister callback for asynchronous notifications

Parameters
Fgframe grabber to use
handlernotification handler function to call
contextcontext 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

◆ Fg_waitForBuffers()

PUBLIC_API int Fg_waitForBuffers ( Fg_Struct * fg,
uint32_t dmaIndex,
uint64_t timeoutSeconds,
void * reserved1,
size_t reserved2 )

Waits for new buffers to be become available again. If any buffers were processed when calling this function, it returns immediately. Otherwise it blocks until at least one buffer becomes available.

Only buffers which have become available after the last call to this function are taken into account.

Parameters
fgthe frame grabber to use
dmaIndexthe dma channel on which to wait for buffers
timeoutSecondstime to wait in seconds.
reserved1currently not used. Always set to NULL or nullptr.
reserved2currently not used. Always set to 0.
Returns
On success: The number of buffers which became available since the last call to this function. On failure: An error code < 0 (e.g. FG_TIMEOUT_ERR if no buffers become available before the specified timeout elapses)

◆ Fg_writeUserDataArea()

PUBLIC_API 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
Fgframe grabber to use, if set to 0 you must provide a board number
boardIdboard number, can be set to (-1) if you supply a frame grabber handle
offsoffset to the start of the user memory area
sizenumber of bytes to write
bufferbuffer 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

◆ getErrorDescription()

PUBLIC_API const char * getErrorDescription ( int ErrorNumber)

Description of error message. .

This returns a description string for the given error code.

Parameters
ErrorNumberThe error code to translate.
Returns
The message of the last error that occurred.

◆ Shad_FreeAccess()

PUBLIC_API int Shad_FreeAccess ( Fg_Struct * Fg,
ShadingMaster * sh )

deactivate shading object

Parameters
Fgframe grabber to use
shShading control object to deactivate.
Returns
Status code.
Return values
FG_OKShading control object was deactivated.
FG_INVALID_PARAMETERan 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.

◆ Shad_GetAccess()

PUBLIC_API int Shad_GetAccess ( Fg_Struct * Fg,
ShadingMaster * sh )

activate shading object

Parameters
Fgframe grabber to use
shShading control object to activate.
Returns
Status code.
Return values
FG_OKShading control object was activated.
FG_INVALID_PARAMETERan 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.

◆ Shad_GetMaxLine()

PUBLIC_API int Shad_GetMaxLine ( Fg_Struct * Fg,
ShadingMaster * sh )

query current line number for shading correction

Parameters
Fgframe grabber to use
shShading control object to use.
Returns
line number or negative error code
Return values
FG_INVALID_PARAMETERan 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.

◆ Shad_SetFixedPatternNoiseLine()

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

set defective pixel interpolation value for shading correction

Parameters
Fgframe grabber to use
shShading control object to use.
xPosition in the line.
channelColor channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
onenable or disable interpolation for this pixel (values 0 or 1).
Returns
Status code.
Return values
FG_OKShading value was set.
FG_INVALID_PARAMETERan 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.

◆ Shad_SetMultValueLine()

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

set multiplicative correction value for shading correction

Parameters
Fgframe grabber to use
shShading control object to use.
xPosition in the line.
channelColor channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
multMultiplicative correction value (range 0 to 8).
Returns
Status code.
Return values
FG_OKShading value was set.
FG_INVALID_PARAMETERan 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.

◆ Shad_SetSubValueLine()

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

set substractive correction value for shading correction

Parameters
Fgframe grabber to use
shShading control object to use.
xPosition in the line.
channelColor channel to use (0 for gray applets, FG_RED, FG_GREEN, or FG_BLUE for color applets).
subSubtractive correction value (range 0 to 1).
Returns
Status code.
Return values
FG_OKShading value was set.
FG_INVALID_PARAMETERan 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.

◆ Shad_WriteActLine()

PUBLIC_API int Shad_WriteActLine ( Fg_Struct * Fg,
ShadingMaster * sh,
int Line )

write shading correction values for given line

Parameters
Fgframe grabber to use
shShading control object to use.
LineLine number which has to be corrected.
Returns
Status code.
Return values
FG_OKShading value was set.
FG_INVALID_PARAMETERan 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.