Single Image Callbacks

This sample demonstrates acquisition of multiple "snaps" using callback notification approach. Each acquisition is started by the host with an 'emulated' software trigger (using the pl_exp_start_seq function repeatedly, without re-configuring the acquisition).

The code snippet below initializes PVCAM and opens the first available camera. Please refer to the actual code sample in the SDK installation directory for more details about the common helper functions used in this documentation.

std::vector<CameraContext*> contexts;
if (!InitAndOpenOneCamera(contexts, cSingleCamIndex))
    return APP_EXIT_ERROR;
CameraContext* ctx = contexts[cSingleCamIndex];

This code example uses the recommended callbacks acquisition (see Polling versus Callbacks). A part of the code omitted here defines a static callback function and registers the function with PVCAM. This approach is used in other code samples as well. The relevant code part is described in Frame Callback Handler section.

Prepare the acquisition. The pl_exp_setup_seq function returns the size of the frame buffer required for the entire sequence. Since we are only requesting a single frame, the size of one frame will be reported. For more details please refer to Acquisition Configuration. section.

uns32 exposureBytes;
const uns32 exposureTime = 40; // milliseconds
const int16 exposureMode = EXT_TRIG_INTERNAL | EXPOSE_OUT_FIRST_ROW;

if (PV_OK != pl_exp_setup_seq(ctx->hcam, 1, 1, &ctx->region, exposureMode,
            exposureTime, &exposureBytes))
{
    PrintErrorMessage(pl_error_code(), "pl_exp_setup_seq() error");
    CloseAllCamerasAndUninit(contexts);
    return APP_EXIT_ERROR;
}

Note

For detailed information about error handling, please, refer to Getting Error Messages.

This example uses the extended trigger mode configuration and sets up the camera to use internal trigger with first-row expose out mode. However, legacy cameras do not support the extended modes and the list of supported expose out modes may differ as well. It is important to always discover the supported modes using the PARAM_EXPOSURE_MODE and PARAM_EXPOSE_OUT_MODE parameters when working with multiple camera models.

Allocate a buffer of the size reported by the pl_exp_setup_seq function.

uns8* frameInMemory = new (std::nothrow) uns8[exposureBytes];
if (!frameInMemory)
{
    printf("Unable to allocate buffer for camera %d\n", ctx->hcam);
    CloseAllCamerasAndUninit(contexts);
    return APP_EXIT_ERROR;
}

Acquire 5 images in a loop:

bool errorOccured = false;
uns32 imageCounter = 0;
while (imageCounter < 5)
{

Start the acquisition - the command below is used as the software trigger. In hardware trigger modes this function call will put camera into a waiting state - the camera will wait for an external signal to start the acquisition:

if (PV_OK != pl_exp_start_seq(ctx->hcam, frameInMemory))
{
    PrintErrorMessage(pl_error_code(), "pl_exp_start_seq() error");
    errorOccured = true;
    break;
}

Here we need to wait for a frame readout notification signaled by eofEvent in CameraContext which is raised in the callback handler we registered. If the frame does not arrive within 5 seconds, or if the user aborts the acquisition with ctrl+c shortcut, the main while loop is interrupted and the acquisition is aborted.

printf("Waiting for EOF event to occur on camera %d\n", ctx->hcam);
if (!WaitForEofEvent(ctx, 5000, errorOccurred))
    break;

printf("Frame #%u has been delivered from camera %d\n",
        imageCounter + 1, ctx->hcam);
ShowImage(ctx, frameInMemory, exposureBytes);

When acquiring single frames with callback notifications, call the pl_exp_finish_seq function after each frame before new acquisition is started.

    if (PV_OK != pl_exp_finish_seq(ctx->hcam, frameInMemory, 0))
        PrintErrorMessage(pl_error_code(), "pl_exp_finish_seq() error");

    imageCounter++;
} // End of while loop

Although the sequence acquisition with single frame goes automatically to idle state, the main while loop can also be interrupted by the user. For this reason we always call pl_exp_abort. For more details, please, refer to the Closing Camera and Uninitializing PVCAM section.

if (PV_OK != pl_exp_abort(ctx->hcam, CCS_HALT))
    PrintErrorMessage(pl_error_code(), "pl_exp_abort() error");

delete [] frameInMemory;

CloseAllCamerasAndUninit(contexts);

if (errorOccured)
    return APP_EXIT_ERROR;
return 0;