SDK Version Compatibility Language Date First Posted Primary Library Calls Link Visual C++ 2006/09/28 flycaptureInitializePlus()


The CustomBuffersEx sample program demonstrates the custom buffer and "locking" functionality available in the FlyCapture library. The ability to use custom or user allocated buffers is beneficial to users who do not have flexibility with respect to where images are written in memory. Enabling the 'Lock Next' functionality as opposed to the standard 'Lock Latest' method is useful when trying to avoid missing images. In this case, the library hands the user the next image that hasn't been seen as opposed to the latest image.

The program begins by initializing a block of memory that is large enough to accommodate the image data held in all of the image buffers. The size of this block depends on the number of buffers being allocated, the number of bytes in each raw image, and whether the images have been color processed or not.

The program initializes the camera using flycaptureInitializePlus(), which effectively tells the PGR FlyCapture driver to DMA the images to the block of memory pointed to by arpBuffers.

In this example, we allocate the size of arpBuffers manually, and pass that into flycaptureInitializePlus(). When allocating your own buffers, you must take padding into account. The maximum amount of padding required is 1 packet, which can be up to 4096 bytes for 1394a and 8192 bytes for 1394b. Adding this padding to the image size will ensure the buffer is large enough to accommodate the image.

The camera is then started using either flycaptureStartLockNext(), which initializes the library to use the "lock next" functionality, or flycaptureStart(), which initializes the library normally to use only the four buffers automatically allocated by the API.

The program then enters a grab loop, which will use either flycaptureLockNext() to lock the "next" image that has not been seen, or flycaptureLockLatest() to lock the "latest" image that has not been seen. Using flycaptureLockNext() is preferable when the goal is to avoid missed images. The program looks at the sequence numbers of each of the images and determines whether any images have been missed (due to earlier images being overwritten). If specified, it also color processes any images and saves them to disk. Finally, it unlocks the current image.

One thing to note is that the example provides two methods for saving data to disk. The first involves streaming the raw data to a single file. Although it will require a post processing step, this method will provide the best performance in terms of lost images. The other method involves storing individual images to the disk. This can be somewhat slower and may result in performance issues when storing large numbers of images.

Once the grab loop is completed, the camera is stopped, the memory allocated at the beginning of the program freed, and the number of missed images reported.

Return to List of Examples