Using the Capture API

Background

The AxsunOCTCapture API provides users of the Axsun Ethernet/PCIe DAQ with the ability to retrieve digitized data for subsequent display, analysis, archival, or other user process. Refer to the AxsunOCTCapture Function Reference and sample code projects at www.axsun.com/downloads for more information about secondary and advanced functionality provided by the Capture API. Any functionality provided in GUI form by the Image Capture Tool also relies directly on the Capture API, so its documentation provides additional examples of the Capture API's secondary capabilities.

NOTE: Become familiar with the Basic Operation of the Ethernet/PCIe DAQ prior to reading this document.

Integrating Into Your Application

Basic functionality of the Capture API can be achieved with only several function calls architected as described below.

  • The Capture API is a "plain-old" ANSI C interface which can be directly called from applications coded in native C or C++.

  • LabVIEW integration can be achieved using the Call Library Function Node.

  • C#/.NET Framework integration can be acheived using P/Invoke and the DllImport attribute discussed here.

Starting a Capture Session

Starting a Capture session opens data interfaces and allocates resources, including the Main Image Buffer – the RAM location into which streamed data will be buffered for subsequent retrieval by the user. The Main Image Buffer size should be allocted based on the expected length of a Burst Record operation. It is a circular buffer, so allocating too small will limit the length of a Burst Record operation and allocating too large will unnecessarily reserve RAM which could be used by other processes.

  • To start a Capture session using the Ethernet interface, call axStartSession(size) where the size argument is the number of 1024-byte packets to reserve for the Main Image Buffer.

  • To start a Capture session using the PCIe interface, call axStartSessionPCIe(size) where the size argument is the number of Megabytes to reserve for the Main Image Buffer.

Querying Buffer Information

At any time following the start of a Capture session and preferably in a loop which executes regularly during image collection, query the current status of the Main Image Buffer using axGetStatus(..). This provides the active state of data streaming (i.e. is the DAQ currently transmitting images or is it idle?), the number of images captured since last reset, and other parameters.

Retrieving Image Info and Image Data

Following the capture of data into the Main Image Buffer and contained in a loop which executes repeatedly during live image display or during playback of previously recorded images, use the axGetImageInfo(..) and axRequestImage(..) functions to copy image data from the Main Image Buffer into user memory for subsequent interaction as desired.

Stopping a Capture Session

Call axStopSession() to release interfaces and free resources that were initially allocated when the Capture session was started.

Getting Info Messages

Immediately following any Capture API function call and especially if an error code was returned, use axGetMessage(..) to learn additional information about the session status and potential error.