ToupCam Native API Manual

1. Version

1.0.2774.20140217

2. Introduction

ToupCam cameras (model series: UCMOS, U3CMOS, UHCCD, EXCCD, SCCCD) support various kinds of APIs (Application Program Interface), namely Native C/C++, .Net/C#, DirectShow, Twain, LabView and so on. Compared with other APIs, Native C/C++ API, a low level one, characterized by the employment of Native C/C++ only without any other run-time libraries. Besides, this interface is simple, flexible and easy to integrate into the customized applications. The SDK zip file contains all of the necessary resources and information:

toupcam.h, C/C++ head file
toupcam.cs, for .Net/C#. The toupcam.cs use P/Invoke to call toupcam.dll. Please copy toupcam.cs to your .Net/C# project to use it.

toupcam.lib, lib file for x86.
toupcam.dll, dll file for x86.
toupcamdemocpp.exe, x86 C++ demo exe file.

toupcam.lib, lib file for x64.
toupcam.dll, dll file for x64.
toupcamdemocpp.exe, x64 C++ demo exe file.

x86 folder contains the kernel mode drivers for x86, including toupcam.cat, toupcam.inf and toupcam.sys.
x64 folder contains the kennel mode driver for x64, including toupcam.cat, toupcam.inf and toupcam.sys.

directshow directory contains the directshow SDK and demo.
twain directory contains the twain SDK and demo.
labview directory contains the labview SDK and demo.

User manuals in English and Chinese.

3. Modes for accessing image data: Pull Mode vs Push Mode

Toupcam offers two modes to obtain image data: Pull Mode and Push Mode. 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.

Two ways are listed below to notify applications for reference:

    1. Use Windows message: Start pull mode by using the function Toupcam_StartPullModeWithWndMsg. When event occurs, it will post message (PostMessage) to the specified window. Parameter WPARAM is the event type, refer to the definition of TOUPCAM_EVENT_xxxx
    2. Use Callback function: Start pull mode by using the function Toupcam_StartPullModeWithCallback. When event occurs, it will call PTOUPCAM_EVENT_CALLBACK to callback.

In Pull Mode, the SDK could not only notify the application that the image data or still image are available for access, but also inform you of the other events, such as:

TOUPCAM_EVENT_EXPOSURE exposure time changes
TOUPCAM_EVENT_TEMPTINT white balance parameters changes
TOUPCAM_EVENT_IMAGE Video image data arrives. Use Toupcam_PullImage to obtain data
TOUPCAM_EVENT_STILLIMAGE Still image arrives by function Toupcam_Snap. Use Toupcam_PullStillImage to obtain data
TOUPCAM_EVENT_ERROR Error occurs, data acquisition cannot continue

4. Functions

Return Value: non-negative integer, enumerated camera number

Parameters: ToupcamInst buffer

Remarks: call this function to enumerate ToupCam cameras that are currently connected to computer and when it is returned, ToupcamInst 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.

The code snippet shows as below:

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

 

typedef struct{
 #ifdef _WIN32
   const wchar_t*  name; /* model name */
 #else
   const char*    name;
 #endif
   unsigned     flag; /* TOUPCAM_FLAG_xxx */
   unsigned     maxspeed; /* number of speed level, Toupcam_get_MaxSpeed, the speed range = [0, max], closed interval */
   unsigned     preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */
   unsigned     still; /* number of still resolution, Toupcam_get_StillResolutionNumber */
   ToupcamResolution  res[TOUPCAM_MAX];
}ToupcamModel;

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

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

Remarks: open the camera instance.

Remarks: start camera instance.

Return Value: HRESULT type means success/failure

Parameters:

Remarks: snap image. When snap successfully, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK. Here, BOOL bSnap is TRUE.

Remarks: set/get current resolution

Remarks: choose FULL mode or FAST mode correspondingly. The default value is FULL.

Remarks: exposure time related.

Remarks: analog gain related.

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.

Remarks: set/obtain the color temperature and Tint parameters of white balance.

Toupcam_TempTint2RGB(...) and Toupcam_RGB2TempTint(...) can be used to convert RGB Gain from / to Temp / Tint.

Remarks: each camera has a unique serial number with 31 letters, eg,"TP110826145730ABCD1234FEDC56787"

Remarks: Once we set non-NULL callback function, then callback happens whenever the exposure time changes.

Remarks: once we set non-NULL callback function, then callback happens whenever the color/gray switches, eg, call Toupcam_put_Chrome

Remarks: obtain histogram data.

5. C# and .Net

Toupcam support.Net and C# development environment.

toupcam.cs in the 'inc' directory use P/Invoke call into toupcam.dll. Copy toupcam.cs to your .Net / C# project, please reference toupcamdemowinform in the samples directory.

The c# class ToupTek.ToupCam is a thin wrapper class to the native API of toupcam.dll, it's properties and methods P/Invoke into the corresponding Toupcam_xxxx functions of toupcam.dll. 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);
}

6. Others

Ranges and default value of some parameters

Parameters Range Default value
AutoExpoTarget 10~230 120
Temp 2000~15000 6503
Tint 200~2500 1000
LevelRange 0~255 Low = 0, High = 255
Contrast -100~100 0
Hue -180~180 0
Saturation 0~255 128
Brightness -64~64 0
Gamma 20~180 100

7. Contact Information

If you have any problems in using this SDK, please use the following information to contact us.
www: www.touptek.com
email: support@touptek.com