Framegrabber API#
| Library | Purpose |
|---|---|
| fglib5 |
|
| siso_genicam |
|
| clsersis |
|
| iolibrt |
|
| display_lib |
|
The Framegrabber API can be used to write applications which acquire and process images from a camera connected to a Basler frame grabber. Cameras using the standards CameraLink, and CoaXPress are supported by the Basler frame grabbers and the Framegrabber API.
Info
Starting with version 5.9 of the Framegrabber API, some changes were made to the API. Throughout the documentation, such changes are highlighted in the respective sections. All changes are summarized in part Change History of the documentation.
The Basler frame grabbers transfer images from one or more cameras using direct memory access (DMA) directly into memory allocated by the application. The path the image data takes from the camera through the frame grabber into the application memory is referred to as DMA channel in the context of the Framegrabber API (from the view of Framegrabber API the image data enters the context of the application through a DMA transfer to the application memory).
The application can be designed to wait in an acquisition loop for new images, or a function can be registered to be called by the Framegrabber API when new images are available. In both cases, the application is made aware of new images only after they have been completely transferred into the computer memory and the image data can be safely processed by the application.
The application always has to specify a time, usually a number of seconds, to wait for new images. The functions called to wait for new images will call an operating system driver provided with the Framegrabber SDK installation and can put the calling thread to sleep until either new images arrive or the specified time passed, whichever happens first. If no images arrive in the specified waiting time, a timeout error will be generated and reported to the application.
The way in which the Framegrabber API works ensures low processor usage while waiting for new images and low latency transfer of image data from a camera to the application. However, it implies that most applications will be implemented to run image acquisition in separate threads, or use the the callback mechanism which again runs an acquisition loop in a separate thread managed by the Framegrabber API. Otherwise the application main thread can be blocked while the application waits for new images.
The time to wait for new images can also imply that an application can't exit without first waiting for threads to return from calls into the operating system driver. While this isn't so much of concern for an application running as the single user interface on a machine for example, applications running on multi-purpose computers, requiring a responsive user experience when exiting the application should rather use small waiting times and handle timeout errors accordingly.
The functions in the Framegrabber API are safe to use from different threads, but different threads should not control the same features or DMA channels concurrently.
The Basler frame grabbers can apply pre-processing to the image data before it is transferred to the application memory. While most frame grabbers support a standard set of commonly used pre-processing features, using Basler VisualApplets and the Basler's programmable frame grabbers, application developers can implement more sophisticated pre-processing, offloading image processing from the CPU to the FPGA of the frame grabber.