pfGrab.h File Reference

#include <stdio.h>
#include <string>

Go to the source code of this file.

Defines

#define PFGRAB_API   __declspec(dllimport)

Enumerations

enum  PFGRAB_ERROR {
  PFGRAB_ERROR_OK = 0, PFGRAB_ERROR_UNKNOWN = -1, PFGRAB_ERROR_MEMORY = -2, PFGRAB_ERROR_INVALID_FILE = -5,
  PFGRAB_ERROR_FRAME_GRABBER_NOT_STARTED = -8, PFGRAB_ERROR_FRAME_GRABBER_STOPPED = -9, PFGRAB_ERROR_INVALID_AREA = -10, PFGRAB_ERROR_TIMEOUT = -16,
  PFGRAB_ERROR_FRAME_GRABBER_UNKNOWN = -18
}

Functions

PFGRAB_API void * pfGrab_InitFG (int port, const char *fgName, const char *param)
 Initializes the frame grabber driver.
PFGRAB_API long pfGrab_SetSize (void *driverData, long *width, long *height)
 Most frame grabbers, for performance reasons, can be configured with a region of interest (ROI) that specifies which part of the whole image we are interested and the grabber device will only transfer the data of that region. Normally the region of interest is specified in the configuration file for the frame grabber but some applications require change the size of the ROI. If the new region of interest's size could be set successful the function returns PFGRAB_ERROR_OK=0. If the given width or height is not allowed the function corrects the value and returns the new value. Keep in mind that the user is instructed to never change the region of interest while grabbing images.
PFGRAB_API long pfGrab_StartGrab (void *driverData)
 The function pfGrab_StartGrab instructs the frame grabber driver to start grabbing new frames. This function initialize the FG callbacks, queues, and any other data structure given by the grabber device's vendor.
PFGRAB_API long pfGrab_Wait (void *driverData, long timeout)
 A call to pfGrab_Wait means that pfGrab is waiting for the frame grabber driver to acquire a new frame. From the point of view of pfGrab a new frame is whatever the grabber device acquired since the last call to pfGrab_StartGrab or pfGrab_Wait. That means that if since the last call to wait three new frames have been acquired then the next call to wait won't need to wait to acquire the next frame, it is already available.
PFGRAB_API void * pfGrab_GetImage (void *driverData, void *buffer, long *bufferSize)
 The function pfGrab_GetImage is called by the application when there was a successful call to pfGrab_Wait. The purposes of this function if to get the pointer to the frame object that was created while waiting for an acquisition.
PFGRAB_API long pfGrab_StopGrab (void *driverData)
 The function pfGrab_StopGrab is called when the user is not interested in receiving more frames. The driver tells the hardware to stop acquiring frames and, if it kept a queue, to clean up the acquired frames that weren't returned to the user.
PFGRAB_API void pfGrab_ReleaseFG (void *driverData)
 When pfGrab no longer needs to keep the driver around because no one is using it anymore the driver must clean up its own resources. The application should call the release function when the driver must clean up itself.


Detailed Description


Function Documentation

PFGRAB_API void* pfGrab_GetImage ( void *  driverData,
void *  buffer,
long *  bufferSize 
)

The function pfGrab_GetImage is called by the application when there was a successful call to pfGrab_Wait. The purposes of this function if to get the pointer to the frame object that was created while waiting for an acquisition.

Parameters:
[in] driverData The pointer to the driverData.
[in] buffer Passing an optional buffer address for copying the image data to the destination of the buffer address. If the buffer address is NULL, the parameter is ignored.
[in] size In the case a buffer address is passed, the function copies the number of bytes defined in size to the buffer destination.
Returns:
The pointer to the frame object that was created while waiting for an acquisition.

PFGRAB_API void* pfGrab_InitFG ( int  port,
const char *  fgName,
const char *  param 
)

Initializes the frame grabber driver.

Parameters:
[in] The string parameter is a free-form string to create a new pfGrab object. It will be used to specify the frame grabber's configuration file, the port to use or even which ones of the system installed frame grabbers to use. This string is driver-specific and is documented for every frame grabber driver, even if it gets ignored by the driver.
Returns:
The return value is the pointer to the driverData. This pointer is later passed as a void pointer to all other functions in order to operate on the correct data. If there was an error in the initialization of the frame grabber driver the return value is NULL.

PFGRAB_API void pfGrab_ReleaseFG ( void *  driverData  ) 

When pfGrab no longer needs to keep the driver around because no one is using it anymore the driver must clean up its own resources. The application should call the release function when the driver must clean up itself.

Parameters:
[in] driverData The pointer to the driverData.

PFGRAB_API long pfGrab_SetSize ( void *  driverData,
long *  width,
long *  height 
)

Most frame grabbers, for performance reasons, can be configured with a region of interest (ROI) that specifies which part of the whole image we are interested and the grabber device will only transfer the data of that region. Normally the region of interest is specified in the configuration file for the frame grabber but some applications require change the size of the ROI. If the new region of interest's size could be set successful the function returns PFGRAB_ERROR_OK=0. If the given width or height is not allowed the function corrects the value and returns the new value. Keep in mind that the user is instructed to never change the region of interest while grabbing images.

Parameters:
[in] driverData The pointer to the driverData.
[in] width Image width to set
[in] height Image height to set
Returns:
PFGRAB_ERROR_OK if successful otherwise error code.

PFGRAB_API long pfGrab_StartGrab ( void *  driverData  ) 

The function pfGrab_StartGrab instructs the frame grabber driver to start grabbing new frames. This function initialize the FG callbacks, queues, and any other data structure given by the grabber device's vendor.

Parameters:
[in] driverData The pointer to the driverData.
Returns:
Return PFGRAB_ERROR_OK if there was no error starting to acquire new frames.

PFGRAB_API long pfGrab_StopGrab ( void *  driverData  ) 

The function pfGrab_StopGrab is called when the user is not interested in receiving more frames. The driver tells the hardware to stop acquiring frames and, if it kept a queue, to clean up the acquired frames that weren't returned to the user.

Parameters:
[in] driverData The pointer to the driverData.
Returns:
Return PFGRAB_ERROR_OK if there was no error starting to acquire new frames.

PFGRAB_API long pfGrab_Wait ( void *  driverData,
long  timeout 
)

A call to pfGrab_Wait means that pfGrab is waiting for the frame grabber driver to acquire a new frame. From the point of view of pfGrab a new frame is whatever the grabber device acquired since the last call to pfGrab_StartGrab or pfGrab_Wait. That means that if since the last call to wait three new frames have been acquired then the next call to wait won't need to wait to acquire the next frame, it is already available.

Parameters:
[in] driverData The pointer to the driverData.
[in] timeout The parameter expressed in milliseconds that sets the maximum number of milliseconds to wait for the next frame. If the driver wasn't able to acquire a new frame in the specified number of milliseconds then it returns PFGRAB_ERROR_TIMEOUT. Take into account that a negative number of milliseconds as timeout means that the driver must ignore the timeout and just wait until there's a frame available.
Returns:
Return PFGRAB_ERROR_OK if a new image is available.


Generated on Mon Aug 9 15:37:46 2010 for PhotonFocusCameraControlLibrary by  doxygen 1.5.8