Camera Capture

Legacy API Deprecation Notice

The current API is a Legacy API and will be deprecated in future releases.

It is strongly recommended to migrate to the Recommended API as soon as possible to ensure future compatibility and support.

➡️  Recommended API Documentation

Introduction

These functions are responsible for capturing images from a camera.

VcCreateVizionCamDevice

• Function:

VizionCam* VcCreateVizionCamDevice()

• Function Description:

  1. This function is used to create an object of the VizionCam class.

  2. This function allocates memory for a new VizionCam object and returns a pointer to it.

• Parameter Description:

  1. This function does not take any input parameters.

• Example:

VizionCam* vizion_cam; 
vizion_cam=VcCreateVizionCamDevice();

VcGetVideoDeviceList

• Function:

int VcGetVideoDeviceList(VizionCam* vizion_cam, std::vector<std::wstring>& devname_list)

• Function Description:

  1. This function retrieves a list of available video devices and their names, and stores the device names in a vector of wide strings.

• Parameter Description:

  1. vizion_cam: A pointer to a VizionCam instance.

  2. devname_list: A vector of wide strings to store the retrieved device names.

  3. return 0 = PASS, return -1 = FAIL.

• Example:

// Declare a vector to store the device names
std::vector<std::wstring> devname_list;
// Call the function to retrieve the device names and store them in the vector
VcGetVideoDeviceList(vizion_cam, devname_list);

VcOpen

• Function:

int VcOpen(VizionCam* vizion_cam, int dev_idx)

• Function Description:

  1. This function is used to open a VizionCam device specified by the index in the device list obtained by calling VcGetVideoDeviceList().

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam object.

  2. list_idx: An integer specifying the index of the device to be opened in the device list.

  3. return 0 = PASS, return -1 = FAIL.

• Example:

VcOpen(vizion_cam, 0);

VcClose

• Function:

int VcClose(VizionCam *vizion_cam)

• Function Description:

  1. This function is used to close the camera device and release any allocated resources.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam object representing the camera device to be closed.

  2. return 0 = PASS, return -1 = FAIL.

• Example:

VcClose(vizion_cam); // Close the camera device represented by the VizionCam object.

VcGetCaptureFormatList

• Function:

int VcGetCaptureFormatList(VizionCam *vizion_cam, std::vector<VzFormat> &capformats)

• Function Description:

  1. This function is used to retrieve the available capture formats of a VizionCam device.

• Parameter Description:

  1. vizion_cam: A pointer to a VizionCam device object.

  2. capformats: A vector of VzFormat structures. The function will populate this vector with the available capture formats.

  3. VzFormat structures{uint16_t width; uint16_t height; uint16_t framerate};

  4. return 0 = PASS, return -1 = FAIL.

  5. VZ_IMAGE_FORMAT format:

enum VZ_IMAGE_FORMAT {
YUY2,
UYVY,
NV12,
MJPG,
};

• Example:

std::vector<VzFormat> capfmtlist;
VcGetCaptureFormatList(vizion_cam, capfmtlist); // Get the capture formats list

VcSetCaptureFormat

• Function:

int VcSetCaptureFormat(VizionCam *vizion_cam, VzFormat capformat)

• Function Description:

  1. The VcSetCaptureFormat function sets the capture format of the camera to the specified format.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam object.

  2. format: The capture format to be set. The format must be obtained from the VcGetCaptureFormatList function

  3. return 0 = PASS, return -1 = FAIL.

• Example:

VzFormat format = capfmtlist[0];
VcSetCaptureFormat(vizion_cam, format); // Set the capture format

VcGetRawImageCapture

• Function:

int VcGetRawImageCapture(VizionCam *vizion_cam, uint8_t *raw_data, int *data_size, uint16_t timeout=2500)

• Function Description:

  1. This function is used to get a single frame of raw image data. To capture multiple frames, the function should be repeatedly called.

※Note: This function call requires calling VcSetCaptureFormat first.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam object.

  2. raw_data: A pointer to a buffer that stores the raw image data.

  3. data_size: A pointer to an integer that stores the size of the raw image data.

  4. (Option)timeout: The timeout value in milliseconds, default value is 2500 ms.

  5. return 0 = PASS, return -1 = FAIL.

• Return Values:

  • VZ_SUCCESS = 0

  • VZ_TIMEOUT = -1

  • VZ_CAM_OCCUPIED = -2

  • VZ_FAIL = -3

  • VZ_OTHER_ERROR = -4

  • VZ_BUFFER_CORRUPTED = -5

  • VZ_CAPTURE_FORMAT_ERROR = -6

• Example:

uint8_t* img_data = new uint8_t[format.width * format.height * 3];
int data_size=0;
VcGetRawImageCapture(vizion_cam, img_data, &data_size, 2500);

VcGetVizionCamDeviceName

• Function:

int VcGetVizionCamDeviceName(VizionCam *vizion_cam, wchar_t *devname)

• Function Description:

  1. The function retrieves the device name of the specified VizionCam device.

  2. It is necessary to call VcOpen() before calling this function.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam instance.

  2. devname: A wide character buffer to store the device name string.

  3. return 0 = PASS, return -1 = FAIL.

• Example:

wchar_t  wchstr[256];
VcGetVizionCamDeviceName(vizion_cam, wchstr);
std::wcout << L"Device Name: " << std::wstring(wchstr) << std::endl;

VcGetUSBFirmwareVersion

• Function:

int VcGetUSBFirmwareVersion(VizionCam* vizion_cam, char* fw_ver)

• Function Description:

  1. This function retrieves the firmware version of the connected USB camera.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam structure obtained by calling VcOpen().

  2. fw_ver: A character array to store the firmware version. The array must have a minimum length of 16 bytes.

  3. return 0 = PASS, return -1 = FAIL.

• Example:

char fw_ver[16];
VcGetUSBFirmwareVersion(vizion_cam, fw_ver);
std::cout << "fw_ver ::"<< fw_ver << std::endl;

VcGetUniqueSensorID

• Function:

int VcGetUniqueSensorID(VizionCam* vizion_cam, char* sensor_id);

• Function Description:

  1. The function VcGetUniqueSensorID retrieves the unique sensor ID of the VizionCam device.

• Parameter Description:

  1. vizion_cam: A pointer to the VizionCam instance obtained through VcOpen function.

  2. sensor_id: A pointer to a character array that receives the unique sensor ID of the VizionCam device.

  3. return 0 = PASS, return -1 = FAIL.

• Example

char UID[24];
VcGetUniqueSensorID(vizion_cam,UID);