![]() |
PVCAM
3.9.x
Programmable Virtual Camera Access Method library
|
In order to reduce repetitive code, all code samples use additional structures and helper functions that are defined in separate source files. The most important types are documented in a separate chapter Common Data Types.
Please note that although PVCAM is a C99 API, the code samples in our SDK are written using C++11 features. This also helps to keep the code short and more readable.
All code samples use PrintErrorMessage
to log an error. This function prints the most recent error condition (returned by pl_error_code function) together with the related error message (received via pl_error_message function). For more information please refer to Error Handling chapter.
General initialization is implemented inside InitPVCAM
function. This function first calls the pl_pvcam_init method, then, by calling pl_cam_get_total it retrieves the number of cameras that are recognized by PVCAM. Finally, the function creates an instance of CameraContext structure for every camera. The structure is initially filled with camera name that is obtained using pl_cam_get_name call.
Two more helper functions are used in order to further simplify the code samples: the first function opens one camera at a given index, the second function opens multiple cameras starting from index 0.
Before calling any of the PVCAM API functions the library must be initialized. This only needs to be done once. Initialization section:
Retrieve the number of cameras connected to the system. The order of cameras and their names follow a specific scheme, please see Camera Enumeration for more details.
The camera has been opened successfully. From now on, the ctx->hcam
handle will be used to identify the camera when calling camera-specific API functions.
The OpenCamera
function fully initializes the CameraContext structure and retrieves various camera information that do not change during camera operation. Such information may include:
This function closes the camera if it has been opened previously. It's unlikely that the pl_cam_close call fails, but if it does, the camera is considered closed anyway.
PVCAM library is uninitialized via UninitPVCAM
function. It calls pl_pvcam_uninit after all CameraContext
instances are released.
Following is a function that closes all cameras and releases PVCAM library in one convenient call. This function is often used inside error handlers where a critical error leads to the immediate program interruption.
Several code examples in the SDK show how to use external hardware trigger feature. In order to cancel an acquisition that waits for the external trigger or long exposure acquisition, the example code uses the following function to install a termination handler. The handler is usually invoked by pressing Ctrl+C inside a running console application or system terminal.
In the SDK code samples, PVCAM parameters are usually read by directly calling pl_get_param or pl_set_param functions without using additional wrappers. However, there are two exceptions made to improve the code readability: a check whether a particular parameter is available (function IsParamAvaliable
), and an extraction of all values from an enumerable parameter (function ReadEnumeration
).
The functions IsParamAvailable
and ReadEnumeration
accept paramName
argument only to output the parameter name to console in case an error occurs.
The details of these functions are documented in Parameter Access Functions chapter and Enumeration Parameters section with error handling implementation.
Most of the SDK code samples use the recommended 'callback' acquisition technique (see chapter Polling versus Callbacks). For callback acquisition the application must register a 'callback' function via the pl_cam_register_callback_ex3 API call. The function below is used for the EOF (end-of-frame) callback notification and it is called by PVCAM automatically every time a frame is written into the frame buffer. For the purpose of SDK code samples, the function only unblocks another waiting thread. In any case, it is not recommended to do lengthy processing and hold this callback routine longer than necessary. An std::conditional_variable
from standard library is used for that synchronization.
The callback is usually registered upon opening the camera and before starting any acquisition.
This is an implementation of a helper function that waits for the EOF event set in GenericEofHandler which effectively reduces the boiler-plate code that would be copied to most of the code samples using callbacks.
Each code sample has different requirements on how to interact with the user. The following functions provide means of interaction with the user via console application or system terminal.
GetCh
and GetChE
functions are used for single key press detection.
Next two functions can be used to retrieve a string or numerical input.
GetMenuSelection
can be used to print a formatted menu with title and items from NVPC structure. The user should enter one of the values from the NVP items for valid input.
ShowImage
function prints out the first few pixel values. The function is generic and its implementations shows how to process the pixel data for various image formats and bit-depths via C++ templates.
The following set of functions prints out content of all metadata structures. See Embedded Frame Metadata chapter for details.
SaveImage
writes raw image pixels to a file.
Please, read the Post-Processing chapter first to understand what post-processing is and how it is presented to application.
These helper functions simplify the access to post-processing functionality.
A helper function simplifying use of SMART Streaming feature