Toupcam API Manual

1. Version & Platform

• Version: 60.32956.20261018

• Platform
  • Win32:
    • x64: Win7 or above
    • x86: XP SP3 or above; CPU supports SSE2 instruction set or above
    • arm64: Win10 or above
  • WinRT/UWP: x64, x86, arm64; Windows10 or above
  • macOS: x64+arm64: macOS 11.0 or above, support x64 and Apple silicon (such as M1, M2, etc)
  • Linux: kernel 2.6.27 or above
    • x64: GLIBC 2.14 or above
    • x86: CPU supports SSE3 instruction set or above; GLIBC 2.8 or above
    • arm64: GLIBC 2.17 or above
    • arm64: musl libc
    • armhf: GLIBC 2.8 or above
    • armel: GLIBC 2.8 or above
    • ostl: STMicroelectronics OpenSTLinux
  • Android: __ANDROID_API__ >= 24 (Android 7.0); built by android-ndk-r18b; see here
    • arm64: arm64-v8a
    • arm: armeabi-v7a
    • x64: x86_64
    • x86

2. Introduction

Toupcam cameras support various kinds of APIs (Application Program Interface), namely Native C/C++, .NET (C# & VB.NET), Python, Java, DirectShow, Twain, LabView, MabLab and so on. Compared with other APIs, Native C/C++ API, as a low level API, don't depend any other runtime libraries. Besides, this interface is simple, flexible and easy to be integrated into the customized applications. The SDK zip file contains all of the necessary resources and information:

• inc

toupcam.h, C/C++ head file

• win: For Microsoft Windows
  • dotnet

    toupcam.cs, for C#. The toupcam.cs use P/Invoke to call into toupcam.dll. Please copy toupcam.cs to your C# project to use it.
    toupcam.vb, for VB.NET. The toupcam.vb use P/Invoke to call into toupcam.dll. Please copy toupcam.vb to your VB.NET project to use it.
    

  • x86: toupcam.dll, toupcam.lib
  • x64: toupcam.dll, toupcam.lib
  • arm: toupcam.dll, toupcam.lib
  • arm64: toupcam.dll, toupcam.lib
  • winrt

    DLL files for WinRT / UWP (Universal Windows Platform) / Windows Store App.
    These dll files are compatible with Windows Runtime, and can be consumed from a Universal Windows Platform app.
    If use C# to develop the UWP, toupcam.cs wrapper class can be used to P/Invoke into toupcam.dll.
    Please pay attation to:

    1. uwp must use winusb, cannot use the proprietary driver. If the proprietary driver has already been installed, please uninstall it in the device manager, after this, Windows will use winusb automatically.
    2. DeviceCapability of uwp, see: How to add USB device capabilities to the app manifest.

  • drivers

    USB (Cameras manufactured after January 1, 2017, have built-in support for WinUSB. No driver installation is required on Windows 8 or later)

    Unless preventing the device from appearing in the “Safely Remove Hardware” list is required, driver installation is not recommended on Windows 8 or later.
    If driver installation is required, DPInst.exe is recommended for automatic driver installation.
    If you still decide to install the driver, it is recommended that you use DPInst.exe to install the driver automatically. If you use NSIS to make the installation file, you can use a statement similar to the following:

    ExecWait '"$INSTDIR\drivers\x64\DPInst.exe" /SA /SW /PATH "$INSTDIR\drivers\x64"'

    GigE: GigE Performance Driver (Win7 or above)

• linux: For Linux
  • udev: 99-toupcam.rules, udev rule file. Please see: http://reactivated.net/writing_udev_rules.html

    Reload rule without reboot:

    udevadm control --reload-rules && udevadm trigger

  • x86: libtoupcam.so, so file for x86
  • x64: libtoupcam.so, so file for x64
  • armel: libtoupcam.so, so file for armel, use toolchain arm-linux-gnueabi
  • armhf: libtoupcam.so, so file for armhf, use toolchain arm-linux-gnueabihf
  • arm64/glibc: libtoupcam.so, so file for arm64 + glibc, use toolchain aarch64-linux-gnu
  • arm64/musl: libtoupcam.so, so file for arm64 + musl libc, use toolchain aarch64-linux-musleabi

  ***An easy way to distinguish the target platform armel/armhf/arm64, Execute file /bin/ls on the target platform. The following is the result under a Raspberry Pi, it can be seen that it belongs to armhf:

  $ file /bin/ls /bin/ls: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, ...

  Another example, which can be seen to belong to x64:

  $ file /bin/ls /bin/ls: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), ...

• android: libtoupcam.so for Android on arm, arm64, x86 and x64

• mac: For macOS, universal dylib: x64+x86, x64+arm64

• python: toupcam.py and sample code

• java: toupcam.java and sample code

• doc: User manuals in English and Simplified Chinese

• extra
  • update: tools for update firmware. Remind: they all depend on the camera dynamic library, please copy toupcam.dll/so/dylib to the directory where it is running.
    • updatefw: update firmware, rename camera, set MAC/IP address for GigE camera, GUI, support Windows only
    • updatecli: update firmware, console UI, support Windows/Linux/MacOS
  • directshow: DirectShow SDK and demo
  • twain: TWAIN SDK
  • labview: Labview SDK and demo
  • matlab: MatLab demo
  • imagepro: liveedf, live stitch, live stack

3. Concepts & Terminology

a. Camera ID (camId) vs Camera SN (Serial Number)

Please distinguish between camera ID (camId) and camera SN:
(a) SN is unique and persistent, fixed inside the camera and remains unchanged, and does not change with connection or system restart.
(b) Camera ID (camId) may change due to connection or system restart. Enumerate the cameras to get the camera ID, and then call the Open function to pass in the camId parameter to open the camera.

b. Modes for accessing image data: "ImagePtr" mode vs "Frame memory copy" Mode

1. ImagePtr mode

The application obtains a pointer to the frame buffer directly from the SDK, eliminating the need to copy frame data and thus improving performance. It calls Toupcam_PullImagePtr to retrieve the frame buffer and Toupcam_PushImagePtr to return it.

typedef struct {
    unsigned id;                    /* Each frame buffer is assigned a unique ID, 0 is reserved as an invalid id */
    unsigned char pixelFormat;      /* TOUPCAM_PIXELFORMAT_xxxx */
    unsigned char ergb;             /* see TOUPCAM_OPTION_RGB */
    unsigned char snapR;            /* see Toupcam_SnapR */
    unsigned char infoVer;          /* ToupcamFrameInfo version, >= 4 */
    unsigned reserved;
    unsigned strideRaw;             /* RAW data stride, 0 means no padding */
    ToupcamFrameInfoV4* ptrInfo;
    void* snapCtx;
    void* ptrRaw;                   /* RAW, see TOUPCAM_OPTION_IMAGEPTRRAW */
    unsigned char* ptr8;            /* 8bits, RGB24, RGB32, Grey8 */
    unsigned short* ptr16;          /* 16bits RGB48, RGB64, Grey16 */
} ToupcamImagePtr;

2. Frame memory copy (memcpy) mode

Frame data is memcpy from the SDK internal buffer to the user-provided buffer. Compared to the ImagePtr mode, this introduces an extra copy and results in a performance penalty.

"Pull mode" and "Push Mode" are Functionally equivalent. The former is recommended since it's simpler and the application seldom gets stuck in multithreading conditions, especially when using windows message to notify the events.

• In Pull Mode, toupcam plays a passive role and the application 'PULL' image data from toupcam. The internal thread of toupcam obtains image data from the camera hardware and saves them to the internal buffers, then notify the application (see below). The application then call functions Toupcam_PullImageV4(V3) or Toupcam_PullImage(WithRowPitch)(V2), Toupcam_PullStillImage(WithRowPitch)(V2) to access image data.

There are to ways to notify applications:

a) Use Windows message: Start pull mode by using the function Toupcam_StartPullModeWithWndMsg. When event occurs, toupcam will post message (PostMessage) to the specified window. Parameter WPARAM is the event type, refer to the definition of TOUPCAM_EVENT_xxxx. This model avoids the multithreading issues, so it's the most simple way. (Obviously, this is only supported in Windows systems, and not supported in Linux and macOS.)

b) Use Callback function: Start pull mode by using the function Toupcam_StartPullModeWithCallback. When event occurs, toupcam will callback the function PTOUPCAM_EVENT_CALLBACK.

• In Push Mode, toupcam plays an active role. Once the video data is obtained from camera by internal thread, toupcam will 'PUSH' the image data to the application through PTOUPCAM_DATA_CALLBACK. Call the function Toupcam_StartPushMode to start push mode. Push mode is more complex. There are some special precautions, such as multithread issues, being impossible to call Toupcam_Close and Toupcam_Stop in callback function PTOUPCAM_DATA_CALLBACK_V4/V3, etc.

c. Event Notify

d. Still Capture (Still Image)

Most cameras support the so-called still capture capability. This function switches the camera to another resolution temporarily when the camera is in preview mode, after a "still" image in the new resolution is captured and then switch back to the original resolution and resume preview mode.

For example, UCMOS05100KPA support 3 resolutions and the current one in preview mode is 1280 * 960. Call Toupcam_Snap(h, 0) to "still capture" an image in 2592 * 1944 resolution. To realize this function, the camera will temporarily switch to 2592 * 1944 firstly, get an image in 2592 * 1944 resolution and then switch back to 1280 * 960 and resume preview.

a) In pull mode operation, after the still capture, TOUPCAM_EVENT_STILLIMAGE will be sent out for external acknowledgement. The external application should call Toupcam_PullImageV4(V3) or Toupcam_PullStillImage(V2) to get the still captured image.

b) In push mode operation, after the still capture, the callback function PTOUPCAM_DATA_CALLBACK_V4/V3 will be called with bSnap parameter setting TRUE. The image information including the resolution information will be obtained via the parameter pHeader.

To check whether the camera have the still capture capability, call Toupcam_get_StillResolutionNumber function or check the still field of the struct ToupcamModelV2.

e. Data format: RGB vs RAW

Toupcam supports two data formats: RGB format (default) and RAW format. RAW format could be enabled by assigning TOUPCAM_OPTION_RAW parameter to 1 when calling Toupcam_put_Option function.

• RGB format: The output of every pixel contains 3 componants which stand for R/G/B value respectively. This output is a processed output from the internal color processing engine.

• RAW format: In this format, the output is the raw data directly output from the sensor. The RAW format is for the users that want to skip the internal color processing and obtain the raw data for user-specific purpose (RAW = -1 slightly different, indicating partial processing). With the raw format output enabled, the functions that are related to the internal color processing will not work, such as Toupcam_put_Hue or Toupcam_AwbOnce function and so on.

Users could switch these two format by calling Toupcam_put_Option function with different value setting to TOUPCAM_OPTION_RAW. You change this option only when camera is NOT running.

Users could change RGB bits by calling Toupcam_put_Option with different value setting to TOUPCAM_OPTION_RGB. You change this option only when camera is NOT running.

f. White Balance and Auto White Balance: Temp/Tint mode vs RGB Gain mode

1. Toupcam sdk supports two independent modes for white balance: a) Temp/Tint Mode; b) RGB Gain Mode

a) Temp/Tint mode is the default white balance mode. In this mode, temp and tint are the parameters that could be used to control the white balance. Toupcam_get_TempTint function is used to acquire the temp and tint values and Toupcam_put_TempTint is used to set the temp and tint values. Function Toupcam_AwbOnce is used to execute the auto white balance. When the white balance parameters change, TOUPCAM_EVENT_TEMPTINT event will be notified for external use.

b) In RGB Gain mode, the while balace is controled by the gain values of the R,G,B channels. Toupcam_get_WhiteBalanceGain is used to acquire the parameters and Toupcam_put_WhiteBalanceGain is used to set the white balance parameters. Toupcam_AwbInit is used to execute the execute the auto white balance. When the white balance parameters change, TOUPCAM_EVENT_WBGAIN event will be notified for external use.

The functions for these two modes cannot be misused:

a) In Temp/Tint mode, please use Toupcam_get_TempTint and Toupcam_put_TempTint and Toupcam_AwbOnce. Toupcam_get_WhiteBalanceGain and Toupcam_put_WhiteBalanceGain and Toupcam_AwbInit cannot be used, they always return E_NOTIMPL.
b) In RGB Gain mode, please use Toupcam_get_WhiteBalanceGain and Toupcam_put_WhiteBalanceGain and Toupcam_AwbInit. Toupcam_get_TempTint and Toupcam_put_TempTint and Toupcam_AwbOnce cannot be used, they always return E_NOTIMPL

This mode is specified when the camera is opened and cannot be changed unless the camera is closed and opened again. Please see here.

2. There are two auto white balance mechanisms available in this field: one is continuous auto white balance and the other is a "once" auto white balance. The white balance parameters will be always calculated and updated for the continuous auto white balance mechanism. For "once" auto white balance mechanism, the white balance parameters will be calculated and updated only when triggered. Toupcam cameras support "once" auto white balance mechanism since it is more accurate and propriate for the microscope application, especially when the background is in pure color. Continuous white balance mechanism will encounter some problem in some cases.

3. Monochromatic camera does not support white balance. The functions metioned above always return E_NOTIMPL.

g. Trigger Mode

1. What is Trigger Mode

Toupcam camera has two working modes: video mode and trigger mode. When in trigger mode, no images will be available until the trigger conditions are met. Cameras have 2 types for triggering according to the types of trigger source, including software trigger mode, external trigger mode and simulated trigger mode.

2. The Difference between Trigger and Snap

Trigger mode is designed for accurate control of the camera and images would be acquired only when the conditions are met. Users could get the images by controlling the trigger conditions. Trigger mode must be pre-specified. Once the trigger mode is entered, no images will come out from the camera until the trigger conditions are met. The triggered images will stay the same property as the pre-specified resolution. Snap is designed to acquire the images from the camera in video mode. The resolution of the snapped image could be the same resolution as the video or could be different.

3. Software Trigger Mode

Camera could be triggered by software. In software trigger mode, images burst out only when users trigger the camera from the software. Numbers of the images of the triggering could also be controlled by software.

4. External Trigger Mode

Camera could be triggered by external trigger signal. By now Toupcam camera only supports positive-edge trigger mode.

5. Mix Trigger Mode

Both external and software trigger are enabled.

6. Simulated Trigger Mode

For cameras that do not support software trigger and external trigger, simulated trigger mode could be available. When in simulated trigger mode, the camera hardware actually works in the same mode as the video mode. But the up-level software will not obtain any images from the camera. The software buffer will stay empty until the user set the trigger conditions by software.

7. How to Enter the Trigger Mode

After the numeration of the connected camera, you can check the flag and find out what trigger mode does the camera support according to the following definition.

#define TOUPCAM_FLAG_TRIGGER_SOFTWARE 0x00080000 /* support software trigger */ #define TOUPCAM_FLAG_TRIGGER_EXTERNAL 0x00100000 /* support external trigger */ #define TOUPCAM_FLAG_TRIGGER_SINGLE 0x00200000 /* only support trigger single: one trigger, one image */

Function Toupcam_put_Option(HToupcam h, unsigned iOption, int iValue) could be used to set the camera to trigger mode when assign TOUPCAM_OPTION_TRIGGER to the iOption parameter. iValue is used to specify the types of the trigger modes. Please see the following for reference.

#define TOUPCAM_OPTION_TRIGGER 0x0b /* 0 = video mode, 1 = software or simulated trigger mode, 2 = external trigger mode, 3 = external + software trigger, default value = 0 */

Function Toupcam_get_Option(HToupcam h, unsigned iOption, int* piValue) could be used to get what type of trigger mode the camera is in.

8. How to Trigger the camera

Function Toupcam_Trigger(HToupcam h, unsigned short nNumber) could be used to trigger the camera. Assigning different value to nNumber means different:

nNumber = 0 means stop the trigger.
nNumber = 0xFFFF means trigger continuously, the same as video mode;
nNumber = other valid values means nNumber images will come out from the camera.

If the TOUPCAM_FLAG_TRIGGER_SINGLE flag is checked, the nNumber parameter must be assigned to 1 and 1 image will come out from the camera when Toupcam_Trigger is called.
Enter the trigger mode first and then call Toupcam_Trigger function to trigger the camera.

9. Trigger timeout

The timeout is recommended for not less than (Exposure Time * 102% + 4 Seconds).

h. Thread safe

We use a "thread-safety neutral" policy (similar to C++ standard library), which means:

a) A camera object is thread-safe for reading from multiple threads. For example, given a camera object A, it is safe to read A from thread 1 and from thread 2 simultaneously.

b) If a camera object is being written to by one thread, then all reads and writes to that object on the same or other threads must be protected. For example, given a camera object A, if thread 1 is writing to A, then thread 2 must be prevented from reading from or writing to A.

c) It's safe to read and write to one camera object even if another thread is reading or writing to a different camera object. For example, given camera objects A and B, it's safe when A is being written in thread 1 and B is being read or write in thread 2.

d) It's safe to pull image from multi threads

i. Log file

The SDK does not output logs by default. If there is a file with the same name and extension *.log in the directory where the SDK library file is located and it has write permission, the log will be enabled and recorded in this file:

a) The log file name is exactly the same as the library file, and the extension is changed to *.log (e.g. toupcam.dll corresponds to the log file toupcam.log; xyz.dll to xyz.log; libxyz.so to libxyz.log)

b) The log file time uses relative time by default, and the SDK startup time is recorded as [00:00:00.000]. If you want to use local time (e.g. [0923 17:11:01.491]), add the letter "l" to *.log (i.e. *.llog)

c) By default, the log file content is automatically cleared every time SDK is started, and the log is written from the beginning. Adding the letter "a" to *.log means that the append mode is used, and the log file content is not cleared when SDK is restarted (i.e. *.alog)

d) By default, logging is written to file synchronously. If logging is suspected to block normal operations, append the letter “s” to the *.log file name to enable asynchronous logging (i.e. *.slog)

e) Please make sure that the program has write permission to the log file(For example, if the program is installed in the Program Files directory, it often happens that the log file cannot be written in non-administrator mode. It is recommended to run the program in administrator mode or modify the permission of the log file.)

4. Functions

• HRESULT return value

  HRESULT is not uncommon on the Windows platform. It's borrowed to macOS and Linux, see table below:

  Please note that the return value >= 0 means success (especially S_FALSE is also successful, indicating that the internal value and the value set by the user is equivalent, which means "no operation"). Therefore, the SUCCEEDED and FAILED macros should generally be used to determine whether the return value is successful or failed.
  (Unless there are special needs, do not use "==S_OK" or "==0" to judge the return value)

  Name	Description	Remark	Value
  S_OK	Success		0x00000000
  S_FALSE	Yet another success	Different from S_OK, such as internal values and user-set values have coincided, equivalent to noop	0x00000001
  E_ACCESSDENIED	Permission denied	Insufficient permissions. This may be blocked by system security policies; on Linux, USB devices often require additional permission configuration, which can be resolved by setting up udev rules or running with root privileges	0x80070005
  E_INVALIDARG	One or more arguments are not valid		0x80070057
  E_NOTIMPL	Not supported or not implemented	This feature is not supported on this model of camera	0x80004001
  E_POINTER	Pointer that is not valid	Pointer is NULL	0x80004003
  E_UNEXPECTED	Catastrophic failure	Generally indicates that the conditions are not met, such as calling put_Option setting some options that do not support modification when the camera is running, and so on	0x8000ffff
  E_WRONG_THREAD	Call function in the wrong thread	See here, here, here	0x8001010e
  E_GEN_FAILURE	Device not functioning	It is generally caused by hardware errors, such as cable problems, USB port problems, poor contact, insufficient power supply, camera hardware damage, etc	0x8007001f
  E_BUSY	The requested resource is in use	The camera is already in use, such as duplicated opening/starting the camera, or being used by other application, etc	0x800700aa
  E_PENDING	The data necessary to complete this operation is not yet available	No data is available at this time	0x8000000a
  E_TIMEOUT	This operation returned because the timeout period expired		0x8001011f
  E_UNREACH	Network is unreachable	Please check the IP settings of the camera and the computer, or the firewall settings	0x80072743
  E_CANCELLED	The operation was canceled by the user		0x800704c7
  E_FAIL	Unspecified failure		0x80004005

  
  

  #define SUCCEEDED(hr) (((HRESULT)(hr)) >= 0) #define FAILED(hr) (((HRESULT)(hr)) < 0)

  On windows platform, these HRESULT constants are already defined in the system header file. On other platforms, if you need to use these constants, you can #define TOUPCAM_HRESULT_ERRORCODE_NEEDED before #include "toupcam.h". See below:

  #define TOUPCAM_HRESULT_ERRORCODE_NEEDED #include "toupcam.h"

• Calling Convention

  Win: __stdcall, please see here

  macOS, Linux and Android: __cdecl

• Callback: PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK_V4/V3

  These callback functions are called back from the internal thread in toupcam.dll, so great attention should be paid to multithread issue.
  Please ensure that the callback funcion is simple and return quickly.
  Otherwise, in callback mode, TOUPCAM_OPTION_CALLBACK_THREAD can be setted to use a dedicated thread for callback.

  Due to the need to wait for the callback function to return when performing the following actions, the callback function context has the following limitations:
  (a) Do NOT call Toupcam_Stop and Toupcam_Close in this callback function, otherwise, deadlocks.
  (b) Do NOT call Toupcam_put_Option with TOUPCAM_OPTION_TRIGGER, TOUPCAM_OPTION_BITDEPTH, TOUPCAM_OPTION_PIXEL_FORMAT, TOUPCAM_OPTION_BINNING, TOUPCAM_OPTION_ROTATE, it will fail with the error code E_WRONG_THREAD.
  (c) Do NOT call Toupcam_put_Roi, it will fail with the error code E_WRONG_THREAD.
  (d) If try to acquire the same lock when performing the above operations and when callback functions, it will cause waiting forever for the callback to end, deadlock

• Coordinate

  Functions with coordinate parameters, such as Toupcam_put_Roi, Toupcam_put_AEAuxRect, etc., the coordinate is always relative to the original resolution, even that the image has been flipped, rotated, digital binning, ROI, or combination of the previous operations.

  Exception:

  (a) if the image is upside down (see here), the coordinate must be also upsize down.

  (b) Hardware Binning.

• Toupcam_EnumV2
  Toupcam_EnumWithName

  Return value: non-negative integer, enumerated camera number

  Parameters:

  ToupcamDeviceV2 arr[TOUPCAM_MAX]: ToupcamDeviceV2 buffer

  Remarks: call this function to enumerate Toupcam cameras that are currently connected to computer and when it is returned, ToupcamDeviceV2 buffer contains the information of each camera instance enumerated.If we don't care about that multiple cameras connect to the computer simultaneously, it's optional to call this function to enumerate the camera instances.

  (1) The code snippet shows as below:
  

  ToupcamDeviceV2 arr[TOUPCAM_MAX]; unsigned cnt = Toupcam_EnumV2(arr); for (unsigned i = 0; i < cnt; ++i) ......

  
  

  typedef struct{ #ifdef _WIN32 const wchar_t* name; /* model name */ #else const char* name; #endif unsigned long long flag; /* TOUPCAM_FLAG_xxx */ unsigned maxspeed; /* maximum speed level, Toupcam_get_MaxSpeed, the speed range = [0, maxspeed], closed interval */ unsigned preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */ unsigned still; /* number of still resolution, Toupcam_get_StillResolutionNumber */ unsigned maxfanspeed; /* maximum fan speed, fan speed range = [0, max], closed interval */ unsigned ioctrol; /* number of input/output control */ float xpixsz; /* physical pixel size in micrometer */ float ypixsz; /* physical pixel size in micrometer */ ToupcamResolution res[TOUPCAM_MAX]; }ToupcamModelV2; /* device model v2 */ typedef struct { #if defined(_WIN32) wchar_t displayname[64]; /* display name: model name or user-defined name (if any and Toupcam_EnumWithName, Toupcam_EnumV2 always returns model name) */ wchar_t id[64]; /* camId */ #else char displayname[64]; /* display name: model name or user-defined name (if any and Toupcam_EnumWithName, Toupcam_EnumV2 always returns model name) */ char id[64]; /* camId */ #endif const ToupcamModelV2* model; /* Functionally equivalent to a global constant, remaining valid and unchanged throughout the lifetime of the process */ } ToupcamDeviceV2; /* device instance for enumerating */

  
  

  name	The name of this model
  flag	Bitwise flag
  	TOUPCAM_FLAG_CMOS	cmos sensor
  	TOUPCAM_FLAG_CCD_PROGRESSIVE	progressive ccd sensor
  	TOUPCAM_FLAG_CCD_INTERLACED	interlaced ccd sensor
  	TOUPCAM_FLAG_ROI_HARDWARE	support hardware ROI. Hardware ROI means only the ROI part of image is output from the sensor and the software cropping operation is not required. Higher frame rate is achieved when using hardware ROI method. Software ROI means the image with the complete field of view of the sensor will be output and software cropping operation is required to obtain the ROI image.
  	TOUPCAM_FLAG_MONO	monochromatic sensor
  	TOUPCAM_FLAG_BINSKIP_SUPPORTED	support bin/skip mode, see Toupcam_put_Mode and Toupcam_get_Mode
  	TOUPCAM_FLAG_USB32	USB 3.2 Gen 2
  	TOUPCAM_FLAG_USB30	usb3.0
  	TOUPCAM_FLAG_USB32_OVER_USB30	USB 3.2 Gen 2 camera connected to usb3.0 port
  	TOUPCAM_FLAG_USB30_OVER_USB20	usb3.0 camera connected to usb2.0 port
  	TOUPCAM_FLAG_ST4	ST4 port
  	TOUPCAM_FLAG_TEC	Thermoelectric Cooler
  	TOUPCAM_FLAG_GETTEMPERATURE	support to get the temperature of the sensor, Toupcam_get_Temperature
  	TOUPCAM_FLAG_HIGH_FULLWELL	support high fullwell capacity
  	TOUPCAM_FLAG_RAW10	TOUPCAM_PIXELFORMAT_RAW10 Pixel format, RAW 10 bits
  	TOUPCAM_FLAG_RAW10PACK	TOUPCAM_PIXELFORMAT_RAW10PACK Pixel format, RAW 10 bits, packed
  	TOUPCAM_FLAG_RAW11	TOUPCAM_PIXELFORMAT_RAW11 Pixel format, RAW 11 bits
  	TOUPCAM_FLAG_RAW12	TOUPCAM_PIXELFORMAT_RAW12 Pixel format, RAW 12 bits
  	TOUPCAM_FLAG_RAW12PACK	TOUPCAM_PIXELFORMAT_RAW12PACK Pixel format, RAW 12 bits, packed
  	TOUPCAM_FLAG_RAW14	TOUPCAM_PIXELFORMAT_RAW14 Pixel format, RAW 14 bits
  	TOUPCAM_FLAG_RAW14PACK	TOUPCAM_PIXELFORMAT_RAW14PACK Pixel format, RAW 14 bits, packed
  	TOUPCAM_FLAG_RAW16	TOUPCAM_PIXELFORMAT_RAW16 Pixel format, RAW 16 bits
  	TOUPCAM_FLAG_FAN	cooling fan
  	TOUPCAM_FLAG_TEC_ONOFF	Thermoelectric Cooler can be turn on or off, target temperature of TEC, see: TOUPCAM_OPTION_TEC TOUPCAM_OPTION_TECTARGET
  	TOUPCAM_FLAG_ISP	ISP (Image Signal Processing) chip
  	TOUPCAM_FLAG_TRIGGER_SOFTWARE	support software trigger
  	TOUPCAM_FLAG_TRIGGER_EXTERNAL	support external trigger
  	TOUPCAM_FLAG_TRIGGER_SINGLE	only support trigger single, one trigger, one image
  	TOUPCAM_FLAG_BLACKLEVEL	support set and get the black level
  	TOUPCAM_FLAG_FOCUSMOTOR	support focus motor
  	TOUPCAM_FLAG_AUTO_FOCUS	support auto focus
  	TOUPCAM_FLAG_BUFFER	frame buffer
  	TOUPCAM_FLAG_DDR	use very large capacity DDR (Double Data Rate SDRAM) for frame buffer. The capacity is not less than one full frame.
  	TOUPCAM_FLAG_CG	Conversion Gain: LCG, HCG
  	TOUPCAM_FLAG_CGHDR	Conversion Gain: LCG, HCG, HDR
  	TOUPCAM_FLAG_EVENT_HARDWARE	hardware event, such as exposure start & stop. see here and here
  	TOUPCAM_FLAG_YUV411	TOUPCAM_PIXELFORMAT_YUV411 Pixel format
  	TOUPCAM_FLAG_YUV422	TOUPCAM_PIXELFORMAT_YUV422 Pixel format
  	TOUPCAM_FLAG_YUV444	TOUPCAM_PIXELFORMAT_YUV444 Pixel format
  	TOUPCAM_FLAG_RGB888	TOUPCAM_PIXELFORMAT_RGB888 Pixel format
  	TOUPCAM_FLAG_RAW8	TOUPCAM_PIXELFORMAT_RAW8 Pixel format, RAW 8 bits
  	TOUPCAM_FLAG_GMCY8	TOUPCAM_PIXELFORMAT_GMCY8 Pixel format, GMCY 8 bits
  	TOUPCAM_FLAG_GMCY12	TOUPCAM_PIXELFORMAT_GMCY12 Pixel format, GMCY 12 btis
  	TOUPCAM_FLAG_GLOBALSHUTTER	global shutter
  	TOUPCAM_FLAG_PRECISE_FRAMERATE	support precise framerate & bandwidth, see TOUPCAM_OPTION_PRECISE_FRAMERATE & TOUPCAM_OPTION_BANDWIDTH
  	TOUPCAM_FLAG_HEAT	support heat to prevent fogging up, see TOUPCAM_OPTION_HEAT & TOUPCAM_OPTION_HEAT_MAX
  	TOUPCAM_FLAG_LOW_NOISE	support low noise mode, see TOUPCAM_OPTION_LOW_NOISE
  	TOUPCAM_FLAG_LEVELRANGE_HARDWARE	hardware level range
  	TOUPCAM_FLAG_GIGE	1 Gigabit GigE
  	TOUPCAM_FLAG_25GIGE	2.5 Gigabit GigE
  	TOUPCAM_FLAG_5GIGE	5 Gigabit GigE
  	TOUPCAM_FLAG_10GIGE	10 Gigabit GigE
  	TOUPCAM_FLAG_40GIGE	40 Gigabit GigE
  	TOUPCAM_FLAG_CAMERALINK	camera link
  	TOUPCAM_FLAG_CXP	CXP: CoaXPress
  	TOUPCAM_FLAG_LINESCAN	line scan camera
  	TOUPCAM_FLAG_FILTERWHEEL	astro filter wheel
  	TOUPCAM_FLAG_AUTOFOCUSER	astro auto focuser
  	TOUPCAM_FLAG_LIGHTSOURCE	embedded light source
  	TOUPCAM_FLAG_LIGHT_SOURCE	stand alone light source
  	TOUPCAM_FLAG_GHOPTO	ghopto sensor
  maxspeed	Maximum speed level, same with Toupcam_get_MaxSpeed. The speed range is [0, maxspeed]. see Toupcam_put_Speed and Toupcam_get_Speed
  preview	Number of preview resolution. Same with Toupcam_get_ResolutionNumber
  still	Number of still resolution, zero means still capture is not supported. Same with Toupcam_get_StillResolutionNumber
  ioctrol	Number of input/output control
  xpixsz ypixsz	Physical pixel size in micrometer, see Toupcam_get_PixelSize
  res	Resolution, width and height

  (2) On the Android platform, if the camera cannot be enumerated, it is possible that NDK has been restricted from enumerating USB devices. See here.

• Toupcam_HotPlug

  Return value: NA

  Parameters:

  PTOUPCAM_HOTPLUG funHotPlug: callback function

  typedef void (*PTOUPCAM_HOTPLUG)(void* ctxHotPlug);

  void* ctxHotPlug: callback context

  Remarks:

  This function is only available on macOS, Linux. To process the device plug in / pull out:

  • On Android, please refer here
  • On Linux/macOS, please call this function to register the callback function. When the device is inserted or pulled out, you will be notified by the callback funcion, and then call Toupcam_EnumV2(...) again to enum the cameras.
  • On macOS, IONotificationPortCreate series APIs can also be used as an alternative.
  • This function is not applicable to GigE devices. For notifications about GigE devices, please see here.

• Toupcam_GigeEnable

  Return value: HRESULT type means success or failure

  Parameters:

  PTOUPCAM_HOTPLUG funHotPlug: callback function, used to notify GigE cameras online/offline. If online/offline notifications are not required, this callback function can be set to NULL.

  void* ctxHotPlug: callback context

  Remarks: Initialize support for GigE cameras, it only needs to be called once when the process starts.

• Toupcam_Open

  Return value: HToupcam handle. Return NULL when fails (Such as the device has been pulled out).

  Parameters:

  camId: Toupcam camera ID, enumerated by Toupcam_EnumV2. If camId is NULL, Toupcam_Open will open the first enumerated camera which connects to the computer. So, if we don't care about that multiple cameras connect to the computer simultaneously, Toupcam_EnumV2 is optional, we can simply use NULL as the parameter.

  For USB, GigE, CameraLink or CXP camera, the camId can also be specified as (case sensitive, no spaces):
  (a) "sn:xxxxxxxxxxxx" (Use SN, such as sn:ZP250212241204105), or
  (b) "name:xxxxxxxxxxxx" (Use user-defined name, such as name:Camera1)

  Moreover, for GigE camera, the camId can also be specified as (case sensitive, no spaces):
  (a) "ip:xxx.xxx.xxx.xxx" (Use IP address, such as ip:192.168.1.100), or
  (b) "mac:xxxxxxxxxxxx" (Use MAC address, such as mac:d05f64ffff23) or

  Remarks: open the camera instance.

  (1) Supports attaching some additional parameters after camId parameter (Use semicolon (;) to split, case sensitive), such as:

  Toupcam_Open(L"\\?\usb#vid_0547&pid_1134#d&397c94f3&0&3;registry=;wb=rgb")

  see table below:

  Camera Configuration (see sample here)	No parameter is required after camId parameter if automatic parameter saving or loading is not required. Attach parameters, the camera configuration are automatically loaded when the camera is opened, and is automatically saved when the camera is close.
  	Source	;registry=xxxx\yyyy	Registry (Windows only)	Specify to use the relative path of the registry key HKEY_CURRENT_USER. Empty after “=” means that the default registry path will be used: Software\XXX(CompanyName)\capi\YYY(Camera model name)
  		;ini=x:\yyyy\zzzz.ini	ini file	Use x:\yyyy\zzzz.ini as the file where camera parameters are saved to or load from. Complete directory must be specified and empty is not allowed. Please Make sure that the target directory exists and is readable and writeable
  		;json=x:\yyyy\zzzz.json	json file	Use x:\yyyy\zzzz.json as the file where camera parameters are saved to or load from. Complete directory must be specified and empty is not allowed. Please Make sure that the target directory exists and is readable and writeable
  		;eeprom=xxxx	EEPROM	Use EEPROM as the device where the camera parameters are saved to or load from. xxxx is the starting address in EEPROM and empty means the starting address is 0
  	Preset	;preset=xxxx	Use a specific preset
  White Balance Mode		;wb=temptint or rgb	White Balance use Temp/Tint mode or RGB Gain mode, see here Default: Temp/Tint
  USB Block Size		;usbblocksize=xxx	Percentage, range: 10~1000, means 10%~1000%
  Zerocopy on linux platform		;zerocopy=1 or 0	Helps to reduce memory copy and improve efficiency. Requires kernel version >= 4.6 and hardware platform support. If the image is wrong, this indicates that the hardware platform does not support this feature, please disable it. Disabled by default on Android or ARM, enabled on non-Android x86/x64

  2. Android

  (a) If the NDK has been granted permission to enumerate the usb device, the same as the normal process, there is no difference.

  (b) If the NDK has NOT been granted permission to enumerate the usb device, so, we can only get device permissions on the Java side, and then transfer the file descriptor to Toupcam_Open. And then, there is no difference after getting the HToupcam handle. See below:

  usbManager = (UsbManager)getApplicationContext().getSystemService(Context.USB_SERVICE); HashMap<String, UsbDevice> deviceList = usbManager.getDeviceList(); for (UsbDevice usbDevice : deviceList.values()) { ModelV2 model = toupcam.get_Model((short)usbDevice.getVendorId(), (short)usbDevice.getProductId()); //Get the camera model by VID/PID, return null for non-supported devices if (model != null) { usbManager.requestPermission(usbDevice, mPermissionIntent); UsbDeviceConnection usbDeviceConnection = usbManager.openDevice(camDevice); if (usbDeviceConnection != null) { int fileDescriptor = usbDeviceConnection.getFileDescriptor(); //Get the native FileDescriptor toupcam cam = toupcam.Open(String.format("fd-%d-%04x-%04x", fileDescriptor, usbDevice.getVendorId(), usbDevice.getProductId())); //Open the camera usbDeviceConnection.close(); //Java side usb connection is no longer needed and is strongly recommended to be closed explicitly and immediately if (cam != null) { ... //From this point we can regularly use the toupcam object as usual } } } }

  3. Toupcam_Open/Close, Start/Stop are relatively heavyweight calls, frequent operation is not recommended unless necessary.

• Toupcam_Close

  Return value: void

  Parameters:

  HToupcam h: camera handle

  Remarks: close the camera. After the handle is closed, never use the HToupcam handle any more.

• Toupcam_Load

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  strPara: string parameter

  Remarks: Load configuration:

  (1) nullptr or empty string, load from EEPROM (address = 0)

  (2) eeprom=???, load from EEPROM (address = 0x???)

  (3) path\to\file.ini, load from ini file

  (4) path\to\file.json, load from json file

• Toupcam_StartPullModeWithWndMsg
  Toupcam_StartPullModeWithCallback

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  HWND hWnd: event occurs, message will be posted in this window

  unsigned nMsg: Windows custom message type. Its WPARAM parameter means event type TOUPCAM_EVENT_xxxx, LPARAM is useless (always zero)

  PTOUPCAM_EVENT_CALLBACK funEvent, void* ctxEvent: callback function specified by user's application and callback context parameter.

  typedef void (*PTOUPCAM_EVENT_CALLBACK)(unsigned nEvent, void* ctxEvent);

  see here.

  Remarks: Obviously, Toupcam_StartPullModeWithWndMsg is only supported in Windows OS.

• Toupcam_PullImagePtr
  Toupcam_WaitImagePtr

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int bStill: to pull still image, set to 1, otherwise 0

  unsigned waitMS: The timeout interval, in milliseconds. If a non-zero value is specified, the function either successfully fetches the image or waits for a timeout. If waitMS is zero, the function does not wait when there are no images to fetch; It always returns immediately; this is equal to Toupcam_PullImagePtr.

  ToupcamImagePtr* ptrImage: Frame buffer

  Remarks: Use the ImagePtr mode to fetch frame buffer.

• Toupcam_PushImagePtr

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned ptrId: Frame buffer ID

  Remarks: After a frame buffer has been used, it must be returned to the SDK for reuse. Please note the following:

  (a) The frame buffer must only be returned back after it is no longer in use. Any access after returning it is unsafe, as the SDK may have already reused the buffer and overwritten the memory with new data.

  (b) If a frame buffer is not returned, the pool of available buffers will gradually decrease.

  (c) Each frame buffer obtained via Pull (identified by its ID) may be returned only once; duplicate returns are not allowed.

  (d) The return order does not need to match the Pull order; buffers may be returned out of order.

  (e) Frame buffers that have not been returned remain valid after Toupcam_Stop. Frame buffers that have not been returned become invalid immediately after Toupcam_Close.

• Toupcam_PullImageV4
  Toupcam_WaitImageV4
  Toupcam_PullImageV3
  Toupcam_WaitImageV3
  Toupcam_PullImageV2
  Toupcam_PullStillImageV2
  Toupcam_PullImageWithRowPitchV2
  Toupcam_PullStillImageWithRowPitchV2
  Toupcam_PullImage
  Toupcam_PullStillImage
  Toupcam_PullImageWithRowPitch
  Toupcam_PullStillImageWithRowPitch

  Return value: HRESULT type means success or failure. Return E_PENDING when there isn't image ready for pull.

  Parameters:

  HToupcam h: camera handle

  unsigned waitMS: The timeout interval, in milliseconds. If a non-zero value is specified, the function either successfully fetches the image or waits for a timeout. If waitMS is zero, the function does not wait when there are no images to fetch; It always returns immediately; this is equal to Toupcam_PullImageV4(V3).

  void* pImageData: Data buffer. Users have to make sure that the data buffer capacity is enough to save the image data, data buffer capacity must >= rowPitch * nHeight.

  int bStill: to pull still image, set to 1, otherwise 0

  int bits: 24, 32, 48, 8, 16, 64, means RGB24, RGB32, RGB48, 8 bits grey, 16 bits grey or RGB64 images. bits = 0 means using default bits base on TOUPCAM_OPTION_RGB. This parameter is ignored in RAW mode.

  int rowPitch: the distance from one row to the next row, =0 means using the default row pitch, =-1 means minimum row pitch (zero padding)

  unsigned* pnWidth, unsigned* pnHeight: out parameter. width and height of image.

  ToupcamFrameInfoV4/V3/V2* pInfo: out parameter, frame info:

  #define TOUPCAM_FRAMEINFO_FLAG_SEQ 0x00000001 /* frame sequence number */ #define TOUPCAM_FRAMEINFO_FLAG_TIMESTAMP 0x00000002 /* timestamp */ #define TOUPCAM_FRAMEINFO_FLAG_EXPOTIME 0x00000004 /* exposure time */ #define TOUPCAM_FRAMEINFO_FLAG_EXPOGAIN 0x00000008 /* exposure gain */ #define TOUPCAM_FRAMEINFO_FLAG_BLACKLEVEL 0x00000010 /* black level */ #define TOUPCAM_FRAMEINFO_FLAG_SHUTTERSEQ 0x00000020 /* sequence shutter counter */ #define TOUPCAM_FRAMEINFO_FLAG_GPS 0x00000040 /* GPS */ #define TOUPCAM_FRAMEINFO_FLAG_AUTOFOCUS 0x00000080 /* auto focus: uLum & uFV */ #define TOUPCAM_FRAMEINFO_FLAG_COUNT 0x00000100 /* timecount, framecount, tricount */ #define TOUPCAM_FRAMEINFO_FLAG_MECHANICALSHUTTER 0x00000200 /* Mechanical shutter: closed */ #define TOUPCAM_FRAMEINFO_FLAG_STILL 0x00008000 /* still image */ #define TOUPCAM_FRAMEINFO_FLAG_CG 0x00010000 /* Conversion Gain: High */ typedef struct { unsigned width; /* image width, always available */ unsigned height; /* image height, always available */ unsigned flag; /* TOUPCAM_FRAMEINFO_FLAG_xxxx, the flag is bit set, which means the corresponding value is valid, this depends on camera model */ unsigned seq; /* frame sequence number */ unsigned long long timestamp; /* microsecond */ unsigned shutterseq; /* sequence shutter counter */ unsigned expotime; /* exposure time */ unsigned short expogain; /* exposure gain */ unsigned short blacklevel; /* black level */ } ToupcamFrameInfoV3; typedef struct { unsigned long long utcstart; /* exposure start time: nanosecond since epoch (00:00:00 UTC on Thursday, 1 January 1970, see https://en.wikipedia.org/wiki/Unix_time) */ unsigned long long utcend; /* exposure end time */ int longitude; /* millionth of a degree, 0.000001 degree */ int latitude; int altitude; /* millimeter */ unsigned short satellite; /* number of satellite */ unsigned short reserved; /* not used */ } ToupcamGps; typedef struct { ToupcamFrameInfoV3 v3; unsigned reserved; /* not used */ unsigned uLum; unsigned long long uFV; unsigned long long timecount; unsigned framecount, tricount; ToupcamGps gps; } ToupcamFrameInfoV4;

  Note: Except that the image width and height are always valid, everything else depends on whether the underlying hardware of the camera model supports it. Determine whether the corresponding value is valid by testing whether the corresponding flag bit is set.

  Remarks: when pImageData is NULL, while pInfo or pnWidth, pnHeight are not NULL, you can "peek" the meta data of images such as width and height.

  (a) When bits and TOUPCAM_OPTION_RGB are inconsistent, format conversion will have to be performed, resulting in loss of efficiency. See the following bits and TOUPCAM_OPTION_RGB correspondence table:

  TOUPCAM_OPTION_RGB	0 (RGB24)	1 (RGB48)	2 (RGB32)	3 (Grey8)	4 (Grey16)	5 (RGB64)
  bits = 0	24	48	32	8	16	64
  bits = 24	24	NA	Convert to 24	Convert to 24	NA	NA
  bits = 32	Convert to 32	NA	32	Convert to 32	NA	NA
  bits = 48	NA	48	NA	NA	Convert to 48	Convert to 48
  bits = 8	Convert to 8	NA	Convert to 8	8	NA	NA
  bits = 16	NA	Convert to 16	NA	NA	16	Convert to 16
  bits = 64	NA	Convert to 64	NA	NA	Convert to 64	64

  (b) Please ensure that the pImageData buffer is large enough to hold the entire frame data, see table below:

  Format		=0 means Default Row Pitch	=-1 means Minimum Row Pitch (zero paddding)
  RGB	RGB24	TDIBWIDTHBYTES(24 * Width)	Width * 3
  	RGB32	Width * 4	Width * 4
  	RGB48	TDIBWIDTHBYTES(48 * Width)	Width * 6
  	GREY8 grey image	TDIBWIDTHBYTES(8 * Width)	Width
  	GREY16 grey image	TDIBWIDTHBYTES(16 * Width)	Width * 2
  	RGB64	Width * 8	Width * 8
  RAW	8bits Mode	Width	Width
  	10bits, 12bits, 14bits, 16bits Mode	Width * 2	Width * 2

  
  

  #ifndef TDIBWIDTHBYTES #define TDIBWIDTHBYTES(bits)    ((unsigned)(((bits) + 31) & (~31)) / 8) #endif

• Toupcam_StartPushModeV4
  Toupcam_StartPushModeV3

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle.

  funData, void* ctxData: the callback function and callback context parameters that are specified by the user's program. Toupcam.dll gets image data from the camera, then calls back this function.

  typedef void (*PTOUPCAM_DATA_CALLBACK_V4)(const void* pData, const ToupcamFrameInfoV3* pInfo, int bSnap, void* ctxData);

  typedef void (*PTOUPCAM_DATA_CALLBACK_V3)(const void* pData, const ToupcamFrameInfoV2* pInfo, int bSnap, void* ctxData);

  see here.

  when calls back, if Parameter pData == NULL, then internal error occurs (eg: the camera is pulled out suddenly).
  The row pitch of pData is always the default value.
  For parameter int bSnap, TRUE means still image snap by Toupcam_Snap or Toupcam_SnapN function, FALSE means ordinary previewed pictures / videos.
  

  Remarks: start camera instance.

• Toupcam_Stop

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam handle

  Remarks: stop the camera instance. After stopped, it can be restart again. For example, switching the video resolution:

  Step 1: call Toupcam_Stop to stop

  Step 2: call Toupcam_put_Size or Toupcam_put_eSize to set the new resolution

  Step 3: call Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushModeV4/V3 to restart

• Toupcam_Pause

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int bPause: 1 => pause, 0 => continue

  Remarks: temporarily pause the video stream

• Toupcam_SnapN
  Toupcam_SnapR
  Toupcam_Snap

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned nResolutionIndex: resolution index. 0xffffffff means use the cureent preview resolution

  unsigned nNum: the number to be snapped.

  Remarks: snap 'still' image, please see here. When snap successfully:

  a) If we use Pull Mode, it will be notified by TOUPCAM_EVENT_STILLIMAGE.

  b) If we use Push Mode, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK_V4/V3 with the parameter int bSnap is TRUE.

  Most cameras can snap still image with different resolutions under continuous preview. For example, UCMOS03100KPA's previewed resolution is 1024*768, if we call Toupcam_Snap(h, 0), we get so called "still image" with 2048*1536 resolution.
  Some cameras hasn't this ability, so nResolutionIndex must be equal the preview resolution which is set by Toupcam_put_Size, or Toupcam_put_eSize.
  Whether it supports "still snap" or not, see "still" domain in ToupcamModelV2.

  Toupcam_SnapR is used to snap "RAW" still image, bypass the hardware ISP if any.

  Toupcam_Snap(h, index) == Toupcam_SnapN(h, index, 1)

• Toupcam_Trigger

  Return value: HRESULT type means success or failure.

  Parameters:

  HToupcam h: camera handle

  unsigned short nNumber: 0xffff(trigger continuously), 0(stop / cancel trigger), others(number of images to be triggered)

  Remarks: in trigger mode, call this function to trigger an image:

  a) If we use Pull Mode, it will be notified by TOUPCAM_EVENT_IMAGE.

  b) If we use Push Mode, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK_V4/V3 with the parameter int bSnap is FALSE.

• Toupcam_TriggerSyncV4
  Toupcam_TriggerSync

  Return value: HRESULT type means success or failure.

  Parameters:

  HToupcam h: camera handle

  unsigned waitMS: The timeout interval, in milliseconds. If waitMS is zero, it means using the default value (exposure time * 102% + 4000 milliseconds), 0xffffffff means waiting forever, and other values represent the specific number of milliseconds.

  void* pImageData：Data buffer. Users have to make sure that the data buffer capacity is enough to save the image data, data buffer capacity must >= rowPitch * nHeight.

  int bits: 24, 32, 48, 8, 16, 64, means RGB24, RGB32, RGB48, 8 bits grey, 16 bits grey or RGB64 images. bits = 0 means using default bits base on TOUPCAM_OPTION_RGB. This parameter is ignored in RAW mode.

  int rowPitch: the distance from one row to the next row, =0 means using the default row pitch, =-1 means minimum row pitch (zero padding)

  ToupcamFrameInfoV4/V3* pInfo: out parameter, frame info

  Remarks: In trigger mode, call this function for a single software trigger and wait for the image to arrive.

• Toupcam_put_Size
  Toupcam_get_Size
  Toupcam_put_eSize
  Toupcam_get_eSize
  Toupcam_get_FinalSize

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned nResolutionIndex: current/present resolution index

  int nWidth, int nHeight: width and height of current resolution index

  Remarks: set/get current resolution

  Set resolution while camera is NOT running
  There are two ways to set current resolution: one is by resolution index, the other by width/height. Both ways are equivalent. For example, UCMOS03100KPA supports the following three kinds of resolution:
      Index 0: 2048, 1536
      Index 1: 1024, 768
      Index 2: 680, 510
  So Toupcam_put_Size(h, 1024, 768) is as effective as Toupcam_put_eSize(h, 1)

  Toupcam_get_FinalSize gets the final width and height of the image (after ROI, Binning, rotation, etc.)

• Toupcam_put_Roi
  Toupcam_get_Roi

  Return value: HRESULT type means success or failure.

  Parameters:

  HToupcam h: camera handle

  unsigned xOffset: x offset, must be even number

  unsigned yOffset: y offset, must be even number

  unsigned xWidth: width, must be even number and must not be less than 8

  unsigned yHeight: height, must be even number and must not be less than 8

  Remarks: set/get the ROI. Toupcam_put_Roi(h, 0, 0, 0, 0) means to clear the ROI and restore the original size.

  Important: It is forbidden to call Toupcam_put_Roi in the callback context of PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK_V4/V3, the return value is E_WRONG_THREAD.

  Pay attention to that the coordinate is always relative to the original resolution, see here.

• Toupcam_get_ResolutionNumber
  Toupcam_get_Resolution
  Toupcam_get_ResolutionRatio

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned nResolutionIndex: resolution index

  int* pWidth, int* pHeight: width/height

  Remarks: Toupcam_get_ResolutionNumber means the number of resolution supported. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_ResolutionNumber and get "3", which means it can support three kinds of resolution. Toupcam_get_Resolution gets the width/height of each resolution.

  These parameters have also been contained in ToupcamModelV2.

  Toupcam_get_ResolutionRatio gets the Binning number of the resolution, expressed as a fraction, such as 1/1, 1/2, 1/3, etc.

• Toupcam_get_RawFormat

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned* pFourCC: One of 4 Bayer pixel arrangement(MAKEFOURCC('G', 'B', 'R', 'G'), MAKEFOURCC('R', 'G', 'G', 'B'), MAKEFOURCC('B', 'G', 'G', 'R'), MAKEFOURCC('G', 'R', 'B', 'G'), see here). Please note that the Y-axis direction of the coordinate system used by different software to define Bayer may be different (Y-axis upward or downward), so some mapping may be required during interoperation. Like the same pixel arrangement, Bayer is GRBG when the Y-axis is downward, and BGGR when the Y-axis is upward.

  unsigned* pBitsPerPixel: bitdepth, such as 8, 10, 12, 14, 16

  #ifndef MAKEFOURCC #define MAKEFOURCC(a, b, c, d) ((unsigned)(unsigned char)(a) | ((unsigned)(unsigned char)(b) << 8) | ((unsigned)(unsigned char)(c) << 16) | ((unsigned)(unsigned char)(d) << 24)) #endif

  
  

• Toupcam_get_PixelFormatSupport

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  char cmd:

  -1: query the number
  0~number: query the nth pixel format

  int* pixelFormat: output, TOUPCAM_PIXELFORMAT_xxxx, see here

• Toupcam_get_PixelFormatName

  Return value: name of pixel format, such as "RAW10", "HDR12HL", etc

  Parameters:

  int pixelFormat: TOUPCAM_PIXELFORMAT_xxxx, see here

• Toupcam_get_Enum

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle; NULL queries the predefined enumeration list, a valid camera handle queries the enumeration list supported by that camera

  const char* strName: enumeration option name (case insensitive), see the table below

  int* pNumber: output, the number of enumeration items, cannot be NULL. *pNumber is not used to specify the array capacity

  int arrValue[]: output, the integer value array of the enumeration items, may be NULL to skip getting the integer values

  const char* arrString[]: output, the pointer array of the string names of the enumeration items, may be NULL to skip getting the string names. The returned strings are managed by the SDK and should not be modified or freed

  arrValue[i] and arrString[i] correspond to the same enumeration item, i ranges from 0 to *pNumber - 1. The integer value does not necessarily equal the array index.

  Usage: first set both arrValue and arrString to NULL and call this function to get the count; then allocate an array with at least that many elements and call this function to get the list. Keep the camera state and the settings that affect the enumeration list unchanged between the two calls to ensure the array capacity is sufficient.

  For example, ToneMapping integer values 0, 1, 2 correspond to the string names "Off", "Polynomial", "Logarithmic".

• Toupcam_put_Int
  Toupcam_get_Int
  Toupcam_put_Str
  Toupcam_get_Str
  Toupcam_put_Option
  Toupcam_get_Option

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned iOption: option of the legacy interface, will no longer be updated, see the table below

  const char* strName: option name (case insensitive), see the table below

  int iValue: value, see the table below

  const char* strValue: input value (case insensitive)

  char strValue[]: output value (128 bytes are always sufficient)

  Remarks:

  Value Type:

  Int: integer value, set or read via Toupcam_put_Int / Toupcam_get_Int by strName.

  Str: string value, set or read via Toupcam_put_Str / Toupcam_get_Str by strName.

  Enum: enumeration value; each discrete value represents a specific mode, state, algorithm or switch meaning, see the "Description" column. Use the Int interface to pass in or read the corresponding integer value; options that support the string form can also use the Str interface to pass in or read the corresponding string name (case insensitive); options that support enumeration query can use Toupcam_get_Enum to query the values and their correspondence.

  Option (iOption): iOption and its corresponding Toupcam_put_Option / Toupcam_get_Option belong to the legacy interface and will no longer be updated. For options with an iOption provided in the table, these two interfaces can be used to set or read the integer value by iOption. It is recommended to use Toupcam_put_Int / Toupcam_get_Int or Toupcam_put_Str / Toupcam_get_Str by strName.

  Categories: The following tables group options by function. Image format comes first; the remaining categories and principal option order follow the VisionLite feature groups. Related additional options are placed in their corresponding categories.

  Names and range queries: strName is case insensitive. For options supporting range queries, append Min, Max or Def to the name and use Toupcam_get_Int to query the minimum, maximum or default value, for example GainMin, GainMax or GainDef. These queries are read-only and are not listed separately in the table; units are the same as the base option. Not every option supports all three queries; check the returned HRESULT.

  For indexed options, place the index after the query suffix, for example SequencerExposureTimeMin1 or DebouncerTimeMax2. BlackLevel also provides BlackLevel8Max, BlackLevel10Max, BlackLevel11Max, BlackLevel12Max, BlackLevel14Max and BlackLevel16Max for the corresponding bit depths. ResolutionMax, BinningMax and BinningModeMax return entry counts, not the maximum index or enumeration value.

  Special default-query behavior: LightsourceDef returns the model maximum light source brightness, and HdrBDef returns the default HdrK value in the supplied implementation. Actual configurable limits such as AETimeMin/Max and AEGainMin/Max remain separate table entries.

  Indexed names: A trailing N denotes a decimal index placeholder, such as LineMode2 or SequencerExposureTime1; replace it with the actual index. Unsuffixed I/O properties use LineSelector, while sequencer and timed trigger properties use their respective selectors. Model-specific values and setting restrictions depend on the API result.

  String form: Enum options can use Str interfaces only when a string mapping is supported. Use Int interfaces for ordinary numeric values and Min/Max/Def queries; numeric strings are not automatically accepted by Str interfaces. Boolean string inputs accept On/Off, Enable/Disable, Yes/No and True/False (case insensitive), and string outputs are typically On or Off. String file operations take a file path rather than an enumeration value.

  Read/Write: RW = Read/Write; RO = Read Only; WO = Write Only. The actual read/write operations available are subject to the "Read/Write" column.

  Running Restriction: some settings can only be modified when the camera is not running (the "Can be changed when camera is running?" column is "No").

Important:

It is forbidden to call Toupcam_put_Option with TOUPCAM_OPTION_TRIGGER, TOUPCAM_OPTION_BITDEPTH, TOUPCAM_OPTION_PIXEL_FORMAT, TOUPCAM_OPTION_BINNING, TOUPCAM_OPTION_ROTATE in the callback context of PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK_V4/V3, the return value is E_WRONG_THREAD.

• Toupcam_put_RealTime
  Toupcam_get_RealTime

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int val:

  0: Off

  stop grab frame when frame buffer deque is full, until the frames in the queue are pulled away and the queue is not full

  1: Both

  use minimum frame buffer. When new frame arrive, drop all the pending frame regardless of whether the frame buffer is full
  If DDR present, also limit the DDR frame buffer to only one frame.

  2: Soft

  use minimum frame buffer. When new frame arrive, drop all the pending frame regardless of whether the frame buffer is full
  If DDR present, DDR frame buffer unchanged.

  Remarks: If you set RealTime mode as 1, then you get shorter frame delay but lower frame rate which damages fluency. The default value is 0.

• Toupcam_get_AutoExpoEnable
  Toupcam_put_AutoExpoEnable
  Toupcam_get_AutoExpoTarget
  Toupcam_put_AutoExpoTarget
  Toupcam_put_MaxAutoExpoTimeAGain
  Toupcam_put_AutoExpoRange
  Toupcam_get_AutoExpoRange
  Toupcam_get_MaxAutoExpoTimeAGain
  Toupcam_put_MinAutoExpoTimeAGain
  Toupcam_get_MinAutoExpoTimeAGain

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int mode:

  0: disable auto exposure
  1: auto exposure continuous mode
  2: auto exposure once

  unsigned short Target: auto-exposure target

  unsigned maxTime, unsigned short maxAGain: the maximum time and maximum gain of auto exposure. The default values are 350ms and 500.

  unsigned minTime, unsigned short minAGain: the minimal time and minimal gain of auto exposure. The default values are 0 and 100.

  Remarks: If auto exposure is enabled, the exposure time and gain are controlled by software to make the average brightness of the target rectangle as close as possible to the auto exposure target. The auto exposure target value is the target brightness of the target rectangle (see Toupcam_put_AEAuxRect, Toupcam_get_AEAuxRect).

• Toupcam_get_ExpoTime
  Toupcam_put_ExpoTime
  Toupcam_get_ExpTimeRange
  Toupcam_get_RealExpoTime

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned Time: exposure time, unit: microsecond

  unsigned* nMin, unsigned* nMax, unsigned* nDef: the minimum, maximum and default value of exposure time.

  Remarks: exposure time related. Toupcam_get_RealExpoTime get the actual exposure time (The actual exposure time and the set exposure time may not be exactly the same, such as 50HZ/60HZ adjustment, sensor exposure time accuracy, etc).

• Toupcam_get_ExpoAGain
  Toupcam_put_ExpoAGain
  Toupcam_get_ExpoAGainRange

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned short AGain: gain, shown in percentage, eg, 200 means the gain is 200%

  unsigned short* nMin, unsigned short* nMax, unsigned short* nDef: the minimum, maximum and default value of gain.

  Remarks: gain related.

• Toupcam_put_Hue
  Toupcam_get_Hue
  Toupcam_put_Saturation
  Toupcam_get_Saturation
  Toupcam_put_Brightness
  Toupcam_get_Brightness
  Toupcam_get_Contrast
  Toupcam_put_Contrast
  Toupcam_get_Gamma
  Toupcam_put_Gamma

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  Remarks: set or get hue, saturation, brightness, contrast and gamma.

• Toupcam_get_Chrome
  Toupcam_put_Chrome

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int bChrome: 1(monochromatic) or color(0)

  Remarks: color or monochromatic mode

• Toupcam_get_VFlip
  Toupcam_put_VFlip
  Toupcam_get_HFlip
  Toupcam_put_HFlip

  Return value: HRESULT type means success or failure

  Parameters: HToupcam h: camera handle

  Remarks: vertical/horizontal flip.

• Toupcam_put_Speed
  Toupcam_get_Speed
  Toupcam_get_MaxSpeed

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned short nSpeed: frame rate level

  Remarks: the minimum frame rate level is "0", the maximum one can be achieved through Function "Toupcam_get_MaxSpeed" which equals to maxspeed in ToupcamModelV2.
  For some cameras that support the so-called precise frame rate, it is recommended to use precise frame rate control. In order to maintain compatibility, Speed is still valid, and the mapping mechanism is: MaxSpeed is 9 (10 levels in total), corresponding to the maximum frame rate when Bandwidth is from 10% to 100%. For example, set the speed to 8, which is equivalent to: The precise frame rate is set to the maximum frame rate with bandwith is set to 90%.

• Toupcam_get_FrameRate

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned* nFrame: The number of frames in the most recent time

  unsigned* nTime: milliseconds

  unsigned* nTotalFrame: The total number of frames since the camera was started

  Remarks: Get the actual frame rate of the camera at the most recent time (about a few seconds). Calculate using the following formula:

  FrameRate(fps) = nFrame * 1000.0 / nTime

• Toupcam_put_HZ
  Toupcam_get_HZ

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int nHZ: 0: 60Hz alternating current, 1: 50Hz alternating current, 2: direct current

  Remarks: set the light source power frequency

• Toupcam_get_Temperature
  Toupcam_put_Temperature

  Return value: HRESULT type means success or failure, E_NOTIMPL means not supporting get or set the temperature

  Parameters:

  HToupcam h: camera handle

  short nTemperature: in 0.1℃ (32 means 3.2℃, -35 means -3.5℃). Set "-2730" or below means using the default value of this model.

  Remarks: get the temperature of the sensor. see TOUPCAM_FLAG_GETTEMPERATURE.

  set the target temperature of the sensor, equivalent to Toupcam_put_Option(, TOUPCAM_OPTION_TECTARGET, ).

• Toupcam_put_Mode
  Toupcam_get_Mode

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  int bSkip: Bin mode or Skip mode.

  Remarks: set Bin mode or Skip mode. Cameras with higher resolution can support two sampling modes, one is Bin mode (Neighborhood averaging), the other is Skip (sampling extraction). In comparison, the former is with better image effect but decreasing frame rate while the latter is just the reverse.

• Toupcam_put_TempTint
  Toupcam_get_TempTint

  Return value: HRESULT type means success or failure. Works int Temp/Tint mode. Does not work int RGB Gain mode, E_NOTIMPL will be return. For mono camera, return value always is E_NOTIMPL.

  Parameters:

  HToupcam h: camera handle

  int nTemp, int nTint: color temperature and Tint

  Remarks: set/get the color temperature and Tint parameters of white balance (Temp/Tint Mode, please see here).

• Toupcam_AwbOnce

  Return value: HRESULT type means success or failure. Works int Temp/Tint mode. Does not work int RGB Gain mode, E_NOTIMPL will be return. For mono camera, return value always is E_NOTIMPL.

  Parameters:

  HToupcam h: camera handle

  PITOUPCAM_TEMPTINT_CALLBACK funTT, void* ctxTT: callback function and callback context when the automatic white balance completes.

  Remarks: Call this function to perform one "auto white balance" in Temp/Tint Mode. When the "auto white balance" completes, TOUPCAM_EVENT_TEMPTINT event notify the application (In Pull Mode) and callback happens. In pull mode, this callback is useless, set it to NULL.

• Toupcam_put_WhiteBalanceGain
  Toupcam_get_WhiteBalanceGain

  Return value: HRESULT type means success or failure. Works int RGB Gain mode. Does not work int Temp/Tint Gain mode, E_NOTIMPL will be return. For mono camera, return value always is E_NOTIMPL.

  Parameters:

  HToupcam h: camera handle

  int aGain[3]: RGB Gain

  Remarks: set/get the RGB gain parameters of white balance (RGB Gain Mode, please see here).

• Toupcam_AwbInit

  Return value: HRESULT type means success or failure. Works int RGB Gain mode. Does not work int Temp/Tint mode, E_NOTIMPL will be return. For mono camera, return value always is E_NOTIMPL.

  Parameters:

  HToupcam h: camera handle

  PITOUPCAM_WHITEBALANCE_CALLBACK funWB, void* ctxWB: callback function and callback context when the automatic white balance completes.

  Remarks: Call this function to perform one "auto white balance" in RGB Gain Mode. When the "auto white balance" completes, TOUPCAM_EVENT_WBGAIN event notify the application (In Pull Mode) and callback happens. In pull mode, this callback is useless, set it to NULL.

• Toupcam_AbbOnce

  Return value: HRESULT type means success or failure. For mono camera, return value always is E_NOTIMPL.

  Parameters:

  HToupcam h: camera handle

  PITOUPCAM_BLACKBALANCE_CALLBACK funBB, void* ctxBB: callback function and callback context when the automatic black balance completes.

  Remarks: Call this function to perform one "auto black balance". When the "auto black balance" completes, TOUPCAM_EVENT_BLACK event notify the application (In Pull Mode) and callback happens. In pull mode, this callback is useless, set it to NULL.

• Toupcam_put_BlackBalance
  Toupcam_get_BlackBalance

  Return value: HRESULT type means success or failure.

  Parameters:

  HToupcam h: camera handle

  unsigned short aSub[3]: RGB Offset

  Remarks: set/get the RGB offset parameters of black balance.

• Toupcam_put_AWBAuxRect
  Toupcam_get_AWBAuxRect
  Toupcam_put_AEAuxRect
  Toupcam_get_AEAuxRect
  Toupcam_put_ABBAuxRect
  Toupcam_get_ABBAuxRect

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  RECT: rectangle, minimum width & height: 4

  Remarks: set/get the rectangle of automatic white balance and auto-exposure and automatic black balance. The default Rectangle is in the center of the image, its width is 20% image with, its height is 20% image height.

  Pay attention to that the coordinate is always relative to the original resolution, see here.

  For mono camera, white balance always return E_NOTIMPL.

• Toupcam_get_MonoMode

  Return value: S_OK means mono mode, S_FALSE means color mode

  Parameters:

  Toupcam h: camera handle

  Remarks: grey camera or not, find the flag in ToupcamModelV2: TOUPCAM_FLAG_MONO

• Toupcam_get_MaxBitDepth

  Return value: the maximum bitdepth this camera supports.

  Parameters:

  HToupcam h: camera handle

  Remarks: Some cameras support the bitdepth which is more than 8 such as 10, 12, 14, 16.

• Toupcam_get_StillResolutionNumber
  Toupcam_get_StillResolution

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned nResolutionIndex: resolution index

  int* pWidth, int* pHeight: width/height

  Remarks: Toupcam_get_StillResolutionNumber means the number of supported still resolution. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_StillResolutionNumber and get "3", which means it can support three kinds of resolution. If it doesn't support "still snap", then we get "0". Toupcam_get_Resolution gs the width/height of each kind of resolution.

• Toupcam_get_SerialNumber
  Toupcam_get_FwVersion
  Toupcam_get_HwVersion
  Toupcam_get_ProductionDate
  Toupcam_get_Revision

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  char sn[32]: buffer to the serial number, such as: TP110826145730ABCD1234FEDC56787

  char fwver[16]: buffer to the firmware version, such as: 3.2.1.20140922

  char hwver[16]: buffer to the hardware version, such as: 3.12

  char pdate[10]: buffer to the production date, such as: 20150327

  unsigned short pRevision: revision

  Remarks: each camera has a unique serial number, here

• Toupcam_get_PixelSize

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned nResolutionIndex: resolution index

  float* x, float* y: sensor physical pixel size, such as 2.4μm × 2.4μm

• Toupcam_put_LEDState

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned short iLed: the index of LED light

  unsigned short iState: LED status, 1 => Ever bright; 2 => Flashing; other => Off

  unsigned short iPeriod: Flashing Period (>= 500ms)

  Remarks: One or more LED lights installed on some camera. This function controls the status of these lights.

• Toupcam_read_EEPROM
  Toupcam_write_EEPROM

  Return value: HRESULT type means failure or byte(s) transferred

  Parameters:

  HToupcam h: camera handle

  unsigned addr: EEPROM address

  const unsigned char* pBuffer: data buffer to be written

  unsigned char* pBuffer: read EEPROM to buffer

  unsigned nBufferLen: buffer length

  Remarks: In some cameras, EEPROM is available for read and write. If failed to read or write, a negative HRESULT error code will be return, when success, the bytes number has been read or written will be return.

• Toupcam_IoControl

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned ioLine:

  0 => Opto-isolated input
  1 => Opto-isolated output
  2 => GPIO0
  3 => GPIO1

  unsigned nType: type of control

  int outVal: output control value

  int* inVal: input control value

  TOUPCAM_IOCONTROLTYPE_GET_SUPPORTEDMODE	get the supported mode: 0x01 => Input 0x02 => Output (0x01 | 0x02) => support both Input and Output
  TOUPCAM_IOCONTROLTYPE_GET_GPIODIR	0x00 => Input, 0x01 => Output
  TOUPCAM_IOCONTROLTYPE_SET_GPIODIR
  TOUPCAM_IOCONTROLTYPE_GET_FORMAT	format: 0x00 => not connected 0x01 => Tri-state 0x02 => TTL 0x03 => LVDS 0x04 => RS422 0x05 => Opto-coupled
  TOUPCAM_IOCONTROLTYPE_SET_FORMAT
  TOUPCAM_IOCONTROLTYPE_GET_OUTPUTINVERTER	boolean, only support output signal
  TOUPCAM_IOCONTROLTYPE_SET_OUTPUTINVERTER
  TOUPCAM_IOCONTROLTYPE_GET_INPUTACTIVATION	0x00 => Rising edge, 0x01 => Falling edge, 0x02 => Level high, 0x03 => Level low
  TOUPCAM_IOCONTROLTYPE_SET_INPUTACTIVATION
  TOUPCAM_IOCONTROLTYPE_GET_DEBOUNCERTIME	debouncer time in microseconds, [0, 20000]
  TOUPCAM_IOCONTROLTYPE_SET_DEBOUNCERTIME
  TOUPCAM_IOCONTROLTYPE_GET_TRIGGERSOURCE	0x00 => Opto-isolated input 0x01 => GPIO0 0x02 => GPIO1 0x03 => Counter 0x04 => PWM 0x05 => Software
  TOUPCAM_IOCONTROLTYPE_SET_TRIGGERSOURCE
  TOUPCAM_IOCONTROLTYPE_GET_TRIGGERDELAY	Trigger delay time in microseconds, [0, 5000000]
  TOUPCAM_IOCONTROLTYPE_SET_TRIGGERDELAY
  TOUPCAM_IOCONTROLTYPE_GET_BURSTCOUNTER	Burst Counter, range: [1, 65535]
  TOUPCAM_IOCONTROLTYPE_SET_BURSTCOUNTER
  TOUPCAM_IOCONTROLTYPE_GET_COUNTERSOURCE	0x00 => Opto-isolated input 0x01 => GPIO0 0x02 => GPIO1
  TOUPCAM_IOCONTROLTYPE_SET_COUNTERSOURCE
  TOUPCAM_IOCONTROLTYPE_GET_COUNTERVALUE	Counter Value, range: [1, 65535]
  TOUPCAM_IOCONTROLTYPE_SET_COUNTERVALUE
  TOUPCAM_IOCONTROLTYPE_SET_RESETCOUNTER
  TOUPCAM_IOCONTROLTYPE_GET_PWM_FREQ	PWM Frequency, range: [0, 0xffffffff]
  TOUPCAM_IOCONTROLTYPE_SET_PWM_FREQ
  TOUPCAM_IOCONTROLTYPE_GET_PWM_DUTYRATIO	PWM Duty Ratio, default: 50, range: [0, 100]
  TOUPCAM_IOCONTROLTYPE_SET_PWM_DUTYRATIO
  TOUPCAM_IOCONTROLTYPE_GET_PWMSOURCE	0x00 => Opto-isolated input 0x01 => GPIO0 0x02 => GPIO1
  TOUPCAM_IOCONTROLTYPE_SET_PWMSOURCE
  TOUPCAM_IOCONTROLTYPE_GET_OUTPUTMODE	0x00 => Frame Trigger Wait 0x01 => Exposure Active 0x02 => Strobe 0x03 => User output 0x04 => Counter Output 0x05 => Timer Output
  TOUPCAM_IOCONTROLTYPE_SET_OUTPUTMODE
  TOUPCAM_IOCONTROLTYPE_GET_STROBEDELAYMODE	boolean, 0 => pre-delay, 1 => delay; compared to exposure active signal
  TOUPCAM_IOCONTROLTYPE_SET_STROBEDELAYMODE
  TOUPCAM_IOCONTROLTYPE_GET_STROBEDELAYTIME	Strobe delay or pre-delay time in microseconds, [0, 5000000]
  TOUPCAM_IOCONTROLTYPE_SET_STROBEDELAYTIME
  TOUPCAM_IOCONTROLTYPE_GET_STROBEDURATION	Strobe duration time in microseconds, [0, 5000000]
  TOUPCAM_IOCONTROLTYPE_SET_STROBEDURATION
  TOUPCAM_IOCONTROLTYPE_GET_USERVALUE	bit0 => Opto-isolated output bit1 => GPIO0 output bit2 => GPIO1 output
  TOUPCAM_IOCONTROLTYPE_SET_USERVALUE
  TOUPCAM_IOCONTROLTYPE_GET_UART_ENABLE	UART enable: 1 => on; 0 => off
  TOUPCAM_IOCONTROLTYPE_SET_UART_ENABLE
  TOUPCAM_IOCONTROLTYPE_GET_UART_BAUDRATE	baud rate: 0 => 9600 1 => 19200 2 => 38400 3 => 57600 4 => 115200
  TOUPCAM_IOCONTROLTYPE_SET_UART_BAUDRATE
  TOUPCAM_IOCONTROLTYPE_GET_UART_LINEMODE	Line Mode: 0 => TX(GPIO_0)/RX(GPIO_1) 1 => TX(GPIO_1)/RX(GPIO_0)
  TOUPCAM_IOCONTROLTYPE_SET_UART_LINEMODE
  TOUPCAM_IOCONTROLTYPE_GET_EXPO_ACTIVE_MODE	exposure time signal: 0 => specified line 1 => common exposure time
  TOUPCAM_IOCONTROLTYPE_SET_EXPO_ACTIVE_MODE
  TOUPCAM_IOCONTROLTYPE_GET_EXEVT_ACTIVE_MODE	exposure event: 0 => specified line 1 => common exposure time
  TOUPCAM_IOCONTROLTYPE_SET_EXEVT_ACTIVE_MODE
  TOUPCAM_IOCONTROLTYPE_GET_EXPO_START_LINE	exposure start line, default: 0, range: [0, 16384]
  TOUPCAM_IOCONTROLTYPE_SET_EXPO_START_LINE
  TOUPCAM_IOCONTROLTYPE_GET_EXPO_END_LINE	exposure end line, default: 0, range: [0, 16384] end line must be no less than start line
  TOUPCAM_IOCONTROLTYPE_SET_EXPO_END_LINE
  TOUPCAM_IOCONTROLTYPE_GET_OUTPUTCOUNTERVALUE	Output Counter Value, range: [0, 65535]
  TOUPCAM_IOCONTROLTYPE_SET_OUTPUTCOUNTERVALUE
  TOUPCAM_IOCONTROLTYPE_SET_OUTPUT_PAUSE	Output pause: 1 => puase, 0 => unpause
  TOUPCAM_IOCONTROLTYPE_GET_INPUT_STATE	Input state: 0 (low level) or 1 (high level)
  TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_HIGH	User pulse high level time: us, range: [0, 0xffffffff]
  TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_HIGH
  TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_LOW	User pulse low level time: us, range: [0, 0xffffffff]
  TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_LOW
  TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_NUMBER	User pulse number: default 0, range: [0, 0xffffffff]
  TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_NUMBER
  TOUPCAM_IOCONTROLTYPE_GET_EXTERNAL_TRIGGER_NUMBER	External trigger number
  TOUPCAM_IOCONTROLTYPE_GET_DEBOUNCER_TRIGGER_NUMBER	Trigger signal number after debounce
  TOUPCAM_IOCONTROLTYPE_GET_EFFECTIVE_TRIGGER_NUMBER	Effective trigger signal number

• Toupcam_read_UART
  Toupcam_write_UART

  Return value: HRESULT type means failure or byte(s) transferred

  Parameters:

  HToupcam h: camera handle

  const unsigned char* pBuffer: data buffer to be written

  unsigned char* pBuffer: read buffer

  unsigned nBufferLen: buffer length

  Remarks: If failed to read or write, a negative HRESULT error code will be return, when success, the bytes number has been read or written will be return.

• Toupcam_FfcOnce
  Toupcam_DfcOnce
  Toupcam_FpncOnce

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

• Toupcam_FfcExport
  Toupcam_FfcImport
  Toupcam_DfcExport
  Toupcam_DfcImport
  Toupcam_FpncExport
  Toupcam_FpncImport

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  filepath: file path

  Remarks: Export or import *.raw or *.dfc, *.ffc, *.fpnc file.

• Toupcam_LevelRangeAuto

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  Remarks: auto Level Range.

• Toupcam_put_LevelRange
  Toupcam_get_LevelRange

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned short aLow[4], unsigned short aHigh[4]: Level Range of R, G, B, and Grey. RGB is only available for color image, and grey is only available for grey image.

  Remarks: level range related.

• Toupcam_put_LevelRangeV2
  Toupcam_get_LevelRangeV2

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  unsigned short mode:

  TOUPCAM_LEVELRANGE_MANUAL	Manual mode
  TOUPCAM_LEVELRANGE_ONCE	Once
  TOUPCAM_LEVELRANGE_CONTINUE	Continue mode
  TOUPCAM_LEVELRANGE_ROI	Update the ROI rectangle

  RECT* pRoiRect: ROI rectangle

  unsigned short aLow[4], unsigned short aHigh[4]: Level Range of R, G, B, and Grey. RGB is only available for color image, and grey is only available for grey image.

  Remarks: level range related.

• Toupcam_put_Demosaic

  Return value: HRESULT type means success or failure

  Parameters:

  funDemosaic: To replace the builtin demosaic function

  typedef void (*PTOUPCAM_DEMOSAIC_CALLBACK)(unsigned nFourCC, int nW, int nH, const void* input, void* output, unsigned char nBitDepth, void* ctxDemosaic);

  ctxDemosaic: callback context

• Toupcam_Update

  Return value: HRESULT type means success or failure

  Parameters:

  camId: camera ID

  filePath: *.ufw file full path

  pFun, ctxProgress: progress percent callback

  Remarks: firmware update. Please do not unplug the camera or lost power during the upgrade process, this is very very important. Once an unplugging or power outage occurs during the upgrade process, the camera will no longer be available and can only be returned to the factory for repair.

• Toupcam_Replug

  Return value: >0: the number of device has been replug; = 0: no device found; E_ACCESSDENIED: no UAC Administrator privileges

  Parameters:

  camId: camera ID

  Remarks: simulate replug. for each device found, it will take about 3 seconds.

• Toupcam_GetHistogram

  Return value: HRESULT type means success or failure

  Parameters:

  HToupcam h: camera handle

  PITOUPCAM_HISTOGRAM_CALLBACK funHistogram, void* ctxHistogram: callback function and callback context of histogram data.

  Remarks: get histogram data.

• Ranges and default value of some parameters

  Parameters			Range	Default value	Get	Set	Auto
  Auto Exposure Target			16~220	120	Toupcam_get_AutoExpoTarget	Toupcam_put_AutoExpoTarget
  Exposure Gain			100~	100	Toupcam_get_ExpoAGain	Toupcam_put_ExpoAGain
  White Balance	Temp/Tint Mode	Color Temperature	2000~15000	6503	Toupcam_get_TempTint	Toupcam_put_TempTint	Toupcam_AwbOnce
  		Tint	200~2500	1000
  	RGB Gain Mode	Red Gain	-127~127	0	Toupcam_get_WhiteBalanceGain	Toupcam_put_WhiteBalanceGain	Toupcam_AwbInit
  		Green Gain
  		Blue Gain
  Black Balance			0~255(bitdepth=8) 0~1023(bitdepth=10) 0~4095(bitdepth=12) 0~16383(bitdepth=14) 0~65535(bitdepth=16)	0	Toupcam_get_BlackBalance	Toupcam_put_BlackBalance	Toupcam_AbbOnce
  LevelRange		Software	0~255	Low = 0 High = 255	Toupcam_get_LevelRange	Toupcam_put_LevelRange	Toupcam_LevelRangeAuto
  		Hardware			Toupcam_get_LevelRangeV2	Toupcam_put_LevelRangeV2
  Contrast			-255~255	0	Toupcam_get_Contrast	Toupcam_put_Contrast
  Hue			-180~180	0	Toupcam_get_Hue	Toupcam_put_Hue
  Saturation			0~255	128	Toupcam_get_Saturation	Toupcam_put_Saturation
  Brightness			-255~255	0	Toupcam_get_Brightness	Toupcam_put_Brightness
  Gamma			20~180	100	Toupcam_get_Gamma	Toupcam_put_Gamma
  Black Level			0~31 (bitdepth=8) 0~31 * 4 (bitdepth=10) 0~31 * 16 (bitdepth=12) 0~31 * 64 (bitdepth=14) 0~31 * 256 (bitdepth=16)	Model Specific	Toupcam_get_Option	Toupcam_put_Option
  Auto Exposure	Max	Exposure Time		350ms	Toupcam_get_AutoExpoRange Toupcam_get_MaxAutoExpoTimeAGain Toupcam_get_MinAutoExpoTimeAGain	Toupcam_put_AutoExpoRange Toupcam_put_MaxAutoExpoTimeAGain Toupcam_put_MinAutoExpoTimeAGain
  		Gain		500
  	Min	Exposure Time		0	Toupcam_get_MinAutoExpoTimeAGain	Toupcam_put_MinAutoExpoTimeAGain
  		Gain		100
  	Percent		0~100	0(Disable) 10(Enable)	TOUPCAM_OPTION_AUTOEXPOSURE_PERCENT
  TEC Target			Model Specific	Model Specific	TOUPCAM_OPTION_TECTARGET

5. .NET (C# & VB.NET)

Toupcam does support .NET development environment (C# and VB.NET).

toupcam.cs use P/Invoke to call into toupcam.dll. Copy toupcam.cs to your C# project, please reference samples.

Please pay attation to that the object of the C# class Toupcam. Toupcam must be obtained by static mothod Open or OpenByIndex, it cannot be obtained by obj = new Toupcam (The constructor is private on purpose).

Most properties and methods of the Toupcam class P/Invoke into the corresponding Toupcam_xxxx functions of toupcam.dll/so. So, the descriptions of the Toupcam_xxxx function are also applicable for the corresponding C# properties or methods. For example, the C# Snap method call the function Toupcam_Snap, the descriptions of the Toupcam_Snap function is applicable for C# Snap method:

[DllImport("toupcam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
private static extern int Toupcam_Snap(SafeHToupcamHandle h, uint nResolutionIndex);

public bool Snap(uint nResolutionIndex)
{
    if (_handle == null || _handle.IsInvalid || _handle.IsClosed)
        return false;
    return (Toupcam_Snap(_handle, nResolutionIndex) >= 0);
}

VB.NET is similar with C#, not otherwise specified.

6. Python

Toupcam does support Python (version 3.0 or above), please import toupcam to use toupcam.py and reference the sample code simplest.py, qt5.py, qt6.py.

Please pay attation to that the object of the python class toupcam.Toupcam must be obtained by classmethod Open or OpenByIndex, it cannot be obtained by obj = toupcam.Toupcam()

Most methods of the Toupcam class use ctypes to call into the corresponding Toupcam_xxxx functions of toupcam.dll/so/dylib. So, the descriptions of the Toupcam_xxxx function are also applicable for the corresponding python methods.

Please reference __errcheck in toupcam.py, the original HRESULT return code is mapped to HRESULTException exception (in win32 it's inherited from OSError).

Please make sure the toupcam dll/so/dylib library file is in the same directory with toupcam.py.

7. Java

Toupcam does support Java, toupcam.java use JNA to call into toupcam.dll/so/dylib. Copy toupcam.java to your java project, please reference the sample code simplest.java (Console), javafx.java, swing.java.

Please pay attation to that the object of the java class toupcam must be obtained by static method Open or OpenByIndex, it cannot be obtained by obj = new toupcam()(The constructor is private on purpose).

Most methods of the toupcam class use JNA to call into the corresponding Toupcam_xxxx functions of toupcam.dll/so/dylib. So, the descriptions of the Toupcam_xxxx function are also applicable for the corresponding java methods.

Please reference errcheck in toupcam.java, the original HRESULT return code is mapped to HRESULTException exception.

Remark: (1) Download jna-*.jar from github; (2) Make sure toupcam.dll/so/dylib is placed in the correct directory.

8. GigE Camera

a. Enable Jumbo Frames on the network interface card (NIC). Using smaller packet sizes will result in lower performance.

netsh interface ipv4 show subinterface

b. GigE Performance Driver

Install:   netcfg.exe -v -l gigepdrv.inf -c s -i gigepdrv
Uninstall: netcfg.exe -u gigepdrv

c. Firewall and NIC protocols

Disable firewall (NIC name "xx"):  Set-NetFirewallProfile -Name Private,Public,Domain -DisabledInterfaceAliases "xx"
Restore all NIC: Set-NetFirewallProfile -Name Private,Public,Domain -DisabledInterfaceAliases @()

d. The automatic camera discovery process uses broadcast packets with the address 255.255.255.255. Please ensure that your system's security policies do not block network broadcasts.

9. Samples

10. Changelog

v60: Add ImagePtr mode. Please see here

v59: Add RAW=-1 mode. Please see here

v58: Open the camera by sn, name (GigE: ip, mac)

v57: Add Toupcam_PullImageV4, ToupcamFrameInfoV4, GPS

v56: Performance improvements: reduced frame data copy in RAW mode

v55: Add Support to HDR Pixel Format

v54: Add support to GigE. Please see here

v53: Add ToupcamFrameInfoV3, Toupcam_PullImageV3, Toupcam_StartPushModeV4

v52: Android Java side transfer file descriptor to Toupcam_Open to open camera. Please see here

v51: Add support auto exposure "once" mode. Please see here

v50: SIMD optimize in Windows(x86/x64), Linux(x64) and Android(x64)
       frontend and backend deque length: TOUPCAM_OPTION_FRONTEND_DEQUE_LENGTH, TOUPCAM_OPTION_BACKEND_DEQUE_LENGTH

v49: Add support to save & load configuration. Please see here

v48: hardware event. Please see here, here and here

v47: hardware level range. Please see here and here

v46: Add support denose. Please see here

v45: Add sequencer trigger, UART, mix trigger (external and software trigger both are enabled)

v44: Extend the realtime mode, Please see here
       Add TOUPCAM_OPTION_CALLBACK_THREAD and TOUPCAM_OPTION_FRAME_DEQUE_LENGTH

v43: Reload the last frame in the trigger mode. Please see TOUPCAM_OPTION_RELOAD

v42: Precise frame rate and bandwidth. Please see here and TOUPCAM_FLAG_PRECISE_FRAMERATE

v41: no packet timeout. Please see here

v40: Auto test tool, see samples\autotest

v39: Update C#/VB.NET/Java/Python

v38: Add support to byte order, change BGR/RGB. Please see here

v37: Add Android support
       Add Toupcam_StartPushModeV3 (Toupcam_StartPushModeV2 and Toupcam_StartPushMode are obsoleted)

v36: Add Java support. Please see here

v35: Add Python support. Please see here

v34: Auto Focus and Focus Motor

v33: extend TOUPCAM_OPTION_AGAIN to TOUPCAM_OPTION_AUTOEXP_POLICY, support more options. Please see here

v32: Addd support to Windows 10 on ARM and ARM64, both desktop and WinRT

v31: Add Toupcam_deBayerV2, support RGB48 and RGB64

v30: Add TOUPCAM_FLAG_CGHDR

v29: Add ToupcamFrameInfoV2, a group of functions (PullImageV2 and StartPushModeV2), some cameras support frame sequence number and timestamp. Please see here

v28: Add Toupcam_read_Pipe, Toupcam_write_Pipe, Toupcam_feed_Pipe

v27: Add Toupcam_SnapN, support to snap multiple images, please see here and democpp

v26: Add support to restore factory settings, TOUPCAM_OPTION_FACTORY

v25: Add sharpening, TOUPCAM_OPTION_SHARPENING

v24: Add support to Exposure time with the 50/60 HZ constraint

v23: Add support to Linux armhf, armel and arm64
       Add FFC and DFC, please see here and here

v22: Add TOUPCAM_OPTION_DDR_DEPTH, please see here

v21: Add Toupcam_IoControl

v20: Add Toupcam_EnumV2, ToupcamModelV2, ToupcamDeviceV2; (Toupcam_Enum, ToupcamModel and ToupcamDevice are obsoleted)
       Add Pixel Format, see TOUPCAM_OPTION_PIXEL_FORMAT; (TOUPCAM_OPTION_PIXEL_FORMAT is the super set of TOUPCAM_OPTION_BITDEPTH)
       Add Flat Field Correction

v19: Add Black Balance: please see here

v18: Add Toupcam_get_Revision

v17: Add TOUPCAM_OPTION_ROTATE

v16: Add TOUPCAM_FLAG_DDR, use very large capacity DDR (Double Data Rate SDRAM) for frame buffer

v15: Add TOUPCAM_OPTION_BINNING

v14: Add support to WinRT / UWP (Universal Windows Platform) / Windows Store App

v13: support row pitch, please see Toupcam_PullImageWithRowPitch and Toupcam_PullStillImageWithRowPitch

v12: support RGB32, 8 bits Grey, 16 bits Grey, please see here

v11: black level: please see here

v10: demosaic method: please see here

v9: change the histogram data type from double to float

v8: support simulated trigger, please see here

v7: support RGB48 when bitdepth > 8, please see here

v6: support trigger mode, please see here

v5: White Balance: Temp/Tint Mode vs RGB Gain Mode, please see here

v4: ROI (Region Of Interest) supported: please see here

v3: more bitdepth supported: 10bits, 12bits, 14bits, 16bits

v2: support RAW format, please see here and here; support Linux and macOS

v1: initial release