Capture and buffer control

Detailed Description

Functions buffer management and image acquisition.

See page Buffer management for a detailed description and also the Basic example source code.

Functions
UINT32 DLL_FG_API	FG_alloc_image (FG_IMAGE *img)
	Allocates a new image buffer for storing sensor frames. More...
UINT32 DLL_FG_API	FG_append_image (FG_IMAGE *img)
	Puts an image buffer into the aquisition queue. More...
UINT32 DLL_FG_API	FG_free_image (FG_IMAGE *img)
	Releases an image buffer. More...
UINT32 DLL_FG_API	FG_get_image (FG_IMAGE *img, UINT32 TimeOut_ms)
	Returns captured images to the user. More...
UINT32 DLL_FG_API	FG_get_timestamp (FG_IMAGE *img, UINT64 *pTimestamp)
	Returns the image completion timestamp of a captured image. More...
UINT32 DLL_FG_API	FG_save_image (FG_IMAGE *img, const char *filename)
	Saves the given image into an BMP file. More...
UINT32 DLL_FG_API	FG_stop_image (void)
	Forces the camera to stop grabbing and using any buffers. More...
UINT32 DLL_FG_API	FG_trigger_image (void)
	Triggers the next image in software triggered mode. More...

Function Documentation

FG_alloc_image()

UINT32 FG_alloc_image

(

FG_IMAGE *

img

)

Allocates a new image buffer for storing sensor frames.

The library allocates the correct buffer size and takes care of any limitations, e.g. cache, alignment, fragmentation.

The image buffer size can be obtained with FG_get_image_size().

Allocated buffers can be freed with FG_free_image() when under user control.

Note

• It's not allowed to use FG_set_aoi() / FG_set_scan_param() after calling this function, because the first call will determine the buffer size. Aquisition has to be stopped and buffers have to be released first.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_append_image()

UINT32 FG_append_image

(

FG_IMAGE *

img

)

Puts an image buffer into the aquisition queue.

After calling this function, the ownership of this buffer is transferred to the library for image aquisition. It is not allowed to access the buffer contents or to release the buffer until it is given back to the user by FG_get_image() or FG_stop_image().

See also: Buffer management

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_free_image()

UINT32 FG_free_image

(

FG_IMAGE *

img

)

Releases an image buffer.

The buffer must be under user control when calling this function.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_get_image()

UINT32 FG_get_image	(	FG_IMAGE *	img,
		UINT32	TimeOut_ms
	)

Returns captured images to the user.

The function blocks until a new image is captured, the timeout expires, or another error occurs.

If the function returns with FG_ERROR_CODE_NoError or FG_ERROR_CODE_BrokenImage, the ownership of the buffer is transferred back to the user. The buffer contents are only valid for FG_ERROR_CODE_NoError.

After the user has finished using the buffer, it has to be added to the free image queue again, or has to be deallocated (see example Acquisition loop).

The field FG_IMAGE::image_number is incremented for every successfully captured image. But note that it is not possible to detect a lost image, because this could occur due to an overtrigger situation or a skipped image if no free image buffer was available to the driver.

All waiting threads can be interrupted by calling FG_stop_image() in another thread.

Parameters

img	Pointer to a FG_IMAGE structure for storing the new image
TimeOut_ms	Maximum time to wait in milli-seconds. Use 0 for busy-wait polling, UINT_MAX for infinite timeout.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_get_timestamp()

UINT32 FG_get_timestamp	(	FG_IMAGE *	img,
		UINT64 *	pTimestamp
	)

Returns the image completion timestamp of a captured image.

The timestamp value contains the point in time of the image transfer completion within the driver. It is based on CLOCK_MONOTONIC and stored in micro-seconds. The value will be zero if the driver doesn't support timestamps.

Please note that the timestamp is measured by the driver after exposure and image transfer from the sensor to memory.

Parameters

img	Pointer to a FG_IMAGE structure containing a valid image
pTimestamp	Pointer for storing the timestamp value

Example for calculating the age of an image:

{
    FG_IMAGE fgImage;
    UINT32 fgResult;
 
    fgResult = FG_get_image(&fgImage, 1000);
    if (fgResult == FG_ERROR_CODE_NoError)
    {
        UINT64 timestamp;
        
        FG_get_timestamp(&fgImage, &timestamp);
        
        if (timestamp != 0)
        {
            // get the current time in micro-seconds
            struct timespec ts;
            clock_gettime(CLOCK_MONOTONIC, &ts);
            UINT64 currentTime = 1000000ull * ts.tv_sec + ts.tv_nsec / 1000;
 
            printf("Image %u is %llu us old\n", fgImage.image_number, currentTime - timestamp);
        }
    }
}

FG_save_image()

UINT32 FG_save_image	(	FG_IMAGE *	img,
		const char *	filename
	)

Saves the given image into an BMP file.

The image size and pixel format are determined by the pixel type and AOI of the camera. The pixel type FG_PIXEL_TYPE_Y_16 is currently not supported.

The generated BMP files can also be used with the Virtual File Camera.

Parameters

img	Pointer to a valid FG_IMAGE structure
filename	Name of the new BMP file

Note

• The image must be under user control when calling this function.
• Existing BMP files will be overwritten.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_stop_image()

UINT32 FG_stop_image

(

void

)

Forces the camera to stop grabbing and using any buffers.

A second thread which is waiting for a new image inside the library (FG_get_image()) will be released. The result can be varying, depending on the internal state. The grabbing is interrupted immediately, so the image data may be incomplete.

After this successful return, any previously allocated buffers are under user control and can be released with FG_free_image(). It is not necessary or possible to dequeue them via FG_get_image(). A detailed description can be found under Buffer management.

In order to capture images after calling this function again, all buffers have to be freed first.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

FG_trigger_image()

UINT32 FG_trigger_image

(

void

)

Triggers the next image in software triggered mode.

The call will fail if the camera was not previously configured to FG_TRIGGER_MODE_SOFTWARE via FG_set_trigger_mode(). Internally it works like hardware triggering; only the trigger pulse is not supplied externally, it is generated by this function call.

The function call will not fail or wait if the sensors are currently not ready to accept or recognize the trigger pulls.

Returns

FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)