Live Image Triggering

This example application demonstrates how to run the camera in continuous circular buffer mode. The camera is triggered by external hardware signal.

Note

This code sample requires an external trigger source to be connected to the camera trigger-in signal.

This sample is almost identical to the Live Image Callbacks example and therefore only the code parts that are different are shown below.

In order to initiate an acquisition with an external trigger source, the acquisition first needs to be configured accordingly and started. The configuration is done by setting the exp_mode argument in the pl_exp_setup_seq or pl_exp_setup_cont functions. For legacy cameras, the argument should be set to STROBED_MODE, for modern cameras the value of EXT_TRIG_EDGE_RISING is usually selected. For all available triggering modes please refer to Exposure Modes chapter.

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

Instead of pl_exp_get_latest_frame the pl_exp_get_latest_frame_ex alternative function is used. The 'ex' function additionally returns a FRAME_INFO structure containing frame number and timestamps. This is the same FRAME_INFO that is passed to the callback handler. If any of the two functions are called from inside the callback function, PVCAM guarantees that the FRAME_INFO returned by these functions is identical to the FRAME_INFO passed into the callback. However, in case of this example, the pl_exp_get_latest_frame_ex is called from within the main thread. Especially with fast frame rates, it may happen that a new frame arrives before the context is switched from the PVCAM callback thread to the main thread and the FRAME_INFO structure passed into the callback routine does not correspond to the FRAME_INFO structure received through the pl_exp_get_latest_frame_ex function. This example prints a message if it happens. When working with fast frame rates, Teledyne Photometrics recommends to use callback acquisition and to call the pl_exp_get_latest_frame_ex from inside the callback routine and either process the frames inside the callback or defer processing to another thread. PVCAM queues the callback notifications up to the size of the circular buffer before it starts dropping frames. Note that the eofFrameInfo in the CameraContext structure contains the FRAME_INFO reported by the callback function.

void* frameAddress;
FRAME_INFO latestFrameInfo;
if (PV_OK != pl_exp_get_latest_frame_ex(ctx->hcam, &frameAddress,
            &latestFrameInfo))
{
    PrintErrorMessage(pl_error_code(),
            "pl_exp_get_latest_frame_ex() error");
    errorOccurred = true;
    break;
}

// Timestamp is in hundreds of microseconds
printf("Frame #%u acquired (# from internal counter)\n",
        framesAcquired + 1);
printf("Frame #%d acquired (# from frame info), timestamp = %lldus\n",
        latestFrameInfo.FrameNr, 100 * latestFrameInfo.TimeStamp);
if (latestFrameInfo.FrameNr != ctx->eofFrameInfo.FrameNr)
{
    // Frame rate is too high or our processing is too slow
    printf("  Frame number from callback handler (%d) differs from "
            "number returned for latest frame (%d)!\n",
            ctx->eofFrameInfo.FrameNr, latestFrameInfo.FrameNr);
}
if (frameAddress != ctx->eofFrame)
{
    // Frame rate is too high or our processing is too slow
    printf("  Frame address from callback handler differs from "
            "address returned for latest frame!\n");
}
ShowImage(ctx, frameAddress, exposureBytes);