Init and Open Functions

Available Functions

• Initialization:
  • pl_pvcam_init - initializes PVCAM internals and detects cameras
  • pl_pvcam_uninit - releases all resources, closes cameras that were not closed explicitly
• Camera Enumeration:
  • pl_cam_get_total - returns number of cameras detected during initialization
  • pl_cam_get_name - returns the name of camera at a given index
• Open & Close:
  • pl_cam_open - opens camera with a given name
  • pl_cam_close - closes the camera

Initialization

Similar to other C libraries, PVCAM must be initialized first before its functions are called. During the initialization, PVCAM scans drivers and detects available compatible cameras. Afterwards, camera names can be read.

The cameras are detected in an order based primarily on the interface type followed by the device index on a USB root hub or PCIe slot number.

PVCAM API does not contain a function for checking whether the library has been initialized yet or not. It is up to the application to track this state as the second call to pl_pvcam_init without previous call to pl_pvcam_uninit always returns an error. Also, if pl_pvcam_uninit is called without the preceding call to pl_pvcam_init, an error is returned.
This behavior may change in future PVCAM releases.

Camera Enumeration

To open the camera, PVCAM uses a name instead of an index. By default, the camera name string will contain the interface type and a device index.

An example of default camera names for each interface type:

Interface	Windows Name	Linux Name	Details
PCI	PMCamera0	pvcamPCI_0	PCI-LVDS card, slot 6
USB	PMUSBCam00	pvcamUSB_0	on board, hub 0, device 3
USB	PMUSBCam01	pvcamUSB_1	PCIe-USB card, slot 2, hub 3, device 0
USB	PMUSBCam02	pvcamUSB_2	PCIe-USB card, slot 2, hub 3, device 1
FireWire	PM1394Cam00	N/A	PCI card, slot 3
PCIe	PMPCIECam00	pvcamPCIE_0	PCIe x4 card, slot 4
PCIe	PMPCIECam01	pvcamPCIE_1	PCIe-LVDS card, slot 5

A sample function that prints number of cameras with their names to standard output:

bool PvcamWrapperClass::DumpCameraNames()
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    int16 nrOfCameras = 0;
    if (PV_OK != pl_cam_get_total(&nrOfCameras))
    {
        // TODO: Handle error
        return false;
    }
    std::cout << "Found " << nrOfCameras << " camera(s)" << std::endl;

    char camName[CAM_NAME_LEN];
    for (int16 n = 0; n < nrOfCameras; ++n)
    {
        if (PV_OK != pl_cam_get_name(n, camName))
        {
            // TODO: Handle error
            return false;
        }
        std::cout << "Camera " << n << ": " << camName << std::endl;
    }
    
    return true;
}

Open & Close

Once camera name is known, it can be used when calling pl_cam_open function which assigns the camera a handle required by most PVCAM functions, including pl_cam_close, as unique camera identifier.

Similarly to PVCAM initialization, PVCAM API does not contain a function for checking whether the camera has been opened yet or not. It is up to the application to track this state as the second call to pl_cam_open without previous call to pl_cam_close always returns an error.
This behavior may change in future PVCAM releases.

An example of open and close functions usage:

bool PvcamWrapperClass::OpenCamera(char* camName, int16& hcam)
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    if (PV_OK != pl_cam_open(camName, &hcam, OPEN_EXCLUSIVE))
    {
        // TODO: Handle error
        return false;
    }
    m_isCamOpen = true;
    return true;
}
void PvcamWrapperClass::CloseCamera(int16 hcam)
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    if (PV_OK != pl_cam_close(hcam))
    {
        // TODO: Handle error, but keep going
    }
    m_isCamOpen = false;
}