imgSessionExamineBuffer

NI IMAQ Function

imgSessionExamineBuffer

Usage

rval imgSessionExamineBuffer(SESSION_ID sid, uInt32 whichBuffer, void* bufferNumber, uInt32* bufferAddr);

Purpose

Extracts an image from a live acquisition. This function lets you lock an image out of a continuous loop sequence for processing when you are using a ring (continuous) sequence. If the requested image has been acquired and exists in memory, the function returns that image immediately. If the requested image has not yet been acquired, the function does not return until the image has been acquired or the timeout period has expired. If the requested image has already been overwritten, the function returns the most current image. If the buffer remains extracted long enough that the acquisition hardware wraps around the buffer list and encounters the extracted buffer again, the acquisition will stall, increment the lost frame count, and the extracted buffer will not be overwritten.

Parameters

Name Type Direction
sid SESSION_ID input
whichBuffer uInt32 input
bufferNumber void* input
bufferAddr uInt32* input
rval Int32 output

Parameter Discussion

sid: valid SESSION_ID.

whichBuffer: cumulative image number to extract. Pass IMG_CURRENT_BUFFER to get the buffer that is currently being acquired.

bufferNumber: on return, the function populates this parameter with the cumulative number of the returned image.

bufferAddr: on return, the function populates this parameter with the address of the locked image.

Return Value

This function returns 0 on success. On failure, this function returns an error code. For information about the error code, call imgShowError.

Note  Use imgSessionReleaseBuffer to release the image being held with imgSessionExamineBuffer.