Buffer Interface

BufIn API Layer Overview

The primary purpose of the Buffer Interface API (BufIn) is to provide an easier means of using the advanced acquisition functionality of BitFlow's products. The BufIn API simplifies the programming effort by significantly reducing the number of function calls needed to develop two of the most fundamental components of an imaging application: sequence capture and circular buffer management.

Choose C, C++ or C#

Your application can access BufIn either through a standard C API or via a few simple C++ classes (see the link at left for the C++ documentation). Both methods provide the same performance and ease of programming, just use whichever suits your needs.

Choose 32-bit or 64-bit Windows

The BufIn API is the same for both 32-bit and 64-bit Windows. Moving your applications between the two types of operating systems just requires recompiling. In fact, it is quite easy to maintain one set of sources and build simultaneously for both OSs.

Sequence Acquisition

A developer that is simply capturing a predetermined sequence of frames or lines relative to an event trigger and does not need to process or view the image data in real-time may want to use sequence capture within their application. For sequence capture, an array of buffers is allocated which is then filled with image data automatically, starting with the first buffer and ending at the last buffer. The user has the ability to specify the start and end buffers with the only limitation on the number of buffers allocated being the amount of memory installed in the computer system. Once the sequence of images is in memory they can be viewed or saved to disk.

Circular Buffer Management

A developer requiring real-time processing of image data may choose to use circular buffer management. For circular buffer management, an array of buffers is allocated. The buffers are then filled with image data starting from the first buffer, filling the rest of the buffers in a round-robin fashion. When the end of the array is reached, the first buffer will be overwritten with new data. Unlike sequence management, where acquisition is stopped after the last buffer is filled, circular management will continue to acquire image data and overwrite previous data until the user specifies acquisition to end.

The idea behind circular buffer management is that a buffer can be processed by the CPU while BitFlow's board acquires into one of the other buffers. This separation between acquisition and processing used by BufIn is helpful in situations where the processing time is not constant. Buffer processing time can vary considerably - as long as the average processing time is equal to or less than the acquisition time, the number of buffers will not need to be increased to keep acquisition from catching up to the buffer being processed. If the average processing time were to increase for any reason, (i.e. an increased swing of processing times of the buffers), more buffers would be required to keep acquisition from catching up to the buffer being processed. In the ideal situation, enough buffers will be allocated to keep the acquisition of the image data from catching up to the buffer being processed, but this is not always the case. Therefore, BufIn provides a means of marking buffers so that they will not be overwritten. Similar to sequence management, the buffers can be viewed or saved to disk as a BMP, TIFF, AVI, or RAW file formats.

BufIn Support

The BufIn API supports the Alta, Axion, Cyton, Neon, Karbon, R64, and R3/R2 BitFlow product lines. Every model within each product family is supported by the BufIn API. BufIn will also support future BitFlow camera interface boards.

The BufIn API can support any size image that is supported by the particular BitFlow interface board.

The BufIn API supports 8, 10, 12, 24, and 32-bit data formats and any image formats that are supported by the camera interface card (two taps, reverse scan, etc.).

The BufIn API supports its own simplified error handling and viewing functions. The API also provides the ability to internally handle errors such as FIFO overflows, buffers being overwritten, and hardware exceptions.

Sequence capture and circular buffer management applications can be developed solely with the BufIn API. The API provides all functions needed to open the board, setup acquisition, control acquisition, handle errors, clean up, and close the board. No additional API calls are needed. Examples in the SDK have been provided to show how to use the BufIn API for sequence capture and circular buffer management. For comparison purposes, the sequence capture example BitFlow uses the BufIn API where the example application Flow does not use the BufIn API.

Code Samples

The following sequence of functions calls could be used for sequence capture:

  1. Bd Board;
  2. BIBA BufArray;
  3. // Open the first board in the system.
  4. BiBrdOpen(BiTypeR2, 0, hBoard);
  5. // Allocate 25 buffers, use camera file information for
  6. // image size and bit depth.
  7. BiBufferAllocCam(hBoard, &BufArray, 25);
  8. // Setup sequence acquisition using Host Qtabs and
  9. // DMA Engine J.
  10. BiSeqAqSetup(hBoard, &BufArray, BiQtabHost|BiAqEngJ);
  11. // Start image acquisition asyncronously.
  12. BiSeqControl(hBoard, &BufArray, BISTART, BiAsync);
  13. // Wait for 5 seconds for acquisition to complete.
  14. // (This can be placed in a separate thread that will
  15. // wake up when acquistion is complete.)
  16. BiSeqWaitDone(hBoard, &BufArray, 5000);
  17. // At this point, the image data is in memory. Now it
  18. // can be viewed, processed and/or saved to disk.
  19. // Save the sequence of images starting a 5 through 15,
  20. // to disk as a TIFF. Call the files SeqDemo.
  21. BiDiskBufWrite(hBoard, &BufArray, BITIF, 5, 10, SeqDemo, 0);
  22. // Clean up sequence acquisiton.
  23. BiSeqCleanUp(hBoard, &BufArray);
  24. // Free buffer memory that has been allocated.
  25. BiBufferFree(hBoard, &BufArray);
  26. // Close the board
  27. BiBrdClose(hBoard);

 

The following sequence of functions calls could be used for circular capture:

  1. Bd Board;
  2. BIBA BufArray;
  3. // Open the first RoadRunner or R3 in the system.
  4. BiBrdOpen(BiTypeR2, 0, hBoard);
  5. // Allocate 25 buffers, use camera file information for
  6. // image size and bit depth.
  7. BiBufferAllocCam(hBoard, &BufArray, 25);
  8. // Setup circular acquisition using Host Qtabs and
  9. // DMA Engine J.
  10. BiCircAqSetup(hBoard, &BufArray, BiQtabHost|BiAqEngJ);
  11. // Start image acquisition asyncronously.
  12. BiSeqControl(hBoard, &BufArray, BISTART, BiAsync);
  13. // Loop here until and display the image data to
  14. // the screen, until acquisition is stopped.
  15. while(ACQUISITION IS STILL RUNNING)
  16. {
  17.     BiCirWaitDoneFrame(hBoard, &BufArray, INFINITE, &CirHandle);
  18.     // DISPLAY IMAGE DATA.
  19. }
  20. // Save all images to disk as BMP. Call the files CircDemo.
  21. BiDiskBufWrite(hBoard, &BufArray, BIBMP, 0, 25, CirDemo, 0);
  22. // Acquisiton has been stopped.
  23. // Clean up circular acquisiton.
  24. BiSeqCleanUp(hBoard, &BufArray);
  25. // Free buffer memory that has been allocated.
  26. BiBufferFree(hBoard, &BufArray);
  27. // Close the board
  28. BiBrdClose(hBoard);