forked from NMGRL/toupcam
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtoupcam_sdk_en_docs.html
1716 lines (1715 loc) · 89.6 KB
/
toupcam_sdk_en_docs.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>ToupCam API Manual</title>
</head>
<body>
<h1 align="center">ToupCam API Manual</h1>
<hr/>
<h1><font color="#0000FF">1. Version & Platform</font></h1>
<hr/>
<ul><li>Version: 30.12838.2018.0905</li></ul>
<ul>
<li>Platform
<ul>
<li>Win32:
<ul>
<li>x86: XP SP3 or above; CPU supports SSE2 instruction set or above</li>
<li>x64: Win7 or above</li>
</ul>
</li>
<li>WinRT: x86 and x64; Windows10 or above</li>
<li>macOS: x86 and x64 bundle; macOS 10.10 or above</li>
<li>Linux: kernel 2.6.27 or above
<ul>
<li>x86: CPU supports SSE3 instruction set or above; GLIBC 2.8 or above</li>
<li>x64: GLIBC 2.14 or above</li>
<li>armel: GLIBC 2.17 or above; built by toolchain arm-linux-gnueabi (version 4.9.2)</li>
<li>armhf: GLIBC 2.17 or above; built by toolchain arm-linux-gnueabihf (version 4.9.2)</li>
<li>arm64: GLIBC 2.17 or above; built by toolchain aarch64-linux-gnu (version 4.9.2)</li>
</ul>
</li>
</ul>
</li>
</ul>
<hr/>
<h1><font color="#0000FF">2. Introduction</font></h1>
<hr/>
<p>ToupCam cameras support various kinds of APIs (Application Program Interface), namely
Native C/C++, .NET/C#/VB.NET, <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/dd375454(v=vs.85).aspx">DirectShow</a>, <a href="http://twain.org/">Twain</a>, LabView 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:</p>
<ul><li>inc</li></ul>
<blockquote>
<p align="left">toupcam.h, C/C++ head file<br/></p>
</blockquote>
<ul>
<li>win: For Microsoft Windows
<ul>
<li>dotnet
<blockquote>
<p align="left">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.<br/>
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.<br/>
</p>
</blockquote></li>
<li>x86
<blockquote>
<p align="left">toupcam.lib, lib file for x86.<br/>
toupcam.dll, dll file for x86.<br/>
democpp.exe, x86 C++ demo exe file.</p>
</blockquote></li>
<li>x64
<blockquote>
<p align="left">toupcam.lib, lib file for x64.<br/>
toupcam.dll, dll file for x64.<br/>
democpp.exe, x64 C++ demo exe file.</p>
</blockquote></li>
<li>winrt
<blockquote>
DLL files for WinRT / UWP (Universal Windows Platform) / Windows Store App.<br/>
These dll files are compatible with Windows Runtime, and can be consumed from a Universal Windows Platform app.<br/>
If use C# to develop the UWP, toupcam.cs wrapper class can be used to P/Invoke into toupcam.dll.<br/>
Please pay attation to DeviceCapability of uwp, see: <a href="https://msdn.microsoft.com/en-us/library/windows/hardware/dn303351(v=vs.85).aspx">How to add USB device capabilities to the app manifest</a>. (It seems that microsoft limits the number of Device items to 100)<br/>
demouwp.zip is a simple demo, before build and run this demo, please change the value of vidpid in file Package.appxmanifest<br/>
</blockquote>
</li>
<li>drivers (<b>The cameras produced after Jan. 1, 2017 support WinUSB, it's no longer need to install driver in Windows8 and above versions</b>)
<ol>
<li>x86 folder contains the kernel mode drivers for x86, including toupcam.cat, toupcam.inf and toupcam.sys.</li>
<li>x64 folder contains the kennel mode driver for x64, including toupcam.cat, toupcam.inf and toupcam.sys.</li>
</ol>
</li>
<li>samples
<ol>
<li>democpp, C++ sample. It demonstrates to enumerate device, open device, video preview, image capture, set the preview resolution, trigger, multi-format image saving (.bmp, .jpg, .png, etc), wmv format video recording, trigger mode and so on. This sample use Pull Mode. To keep the code clean, this sample uses the WTL library which can be downloaded from <a href="http://sourceforge.net/projects/wtl/">http://sourceforge.net/projects/wtl</a></li>
<li>demomfc, a simple C++ sample. It use MFC as the GUI library. It demonstrates to open device, video preview, image capture, set the preview resolution, multi-format image saving (.bmp, .jpg, .png, etc). This sample use Pull Mode.</li>
<li>demowinformcs1, C# winform sample. This sample use Pull Mode, StartPullModeWithWndMsg.</li>
<li>demowinformcs2, C# winform sample. This sample use Pull Mode, StartPullModeWithCallback.</li>
<li>demowinformcs3, C# winform sample. This sample use Push Mode, StartPushMode.</li>
<li>demowinformvb, VB.NET winform sample. This sample use Pull Mode.</li>
</ol>
</li>
<li>extras
<ol>
<li>directshow: DirectShow SDK and demo.</li>
<li>twain: TWAIN SDK.</li>
<li>labview: Labview SDK and demo.</li>
</ol>
</li>
</ul>
</li>
</ul>
<ul><li>linux: For Linux
<ul>
<li>udev: 99-toupcam.rules, udev rule file. Please see: <a href="http://reactivated.net/writing_udev_rules.html">http://reactivated.net/writing_udev_rules.html</a></li>
<li>c#: toupcam.cs, for .Net Core C#. The toupcam.cs use P/Invoke to call into libtoupcam.so. Please copy toupcam.cs to your C# project to use it.</li>
<li>x86: libtoupcam.so, so file for x86.</li>
<li>x64: libtoupcam.so, so file for x64.</li>
<li>armel: libtoupcam.so, so file for armel, use toolchain arm-linux-gnueabi.</li>
<li>armhf: libtoupcam.so, so file for armhf, use toolchain arm-linux-gnueabihf.</li>
<li>arm64: libtoupcam.so, so file for arm64, use toolchain aarch64-linux-gnu.</li>
</ul>
</li></ul>
<ul><li>mac: For macOS.</li></ul>
<ul><li>doc: User manuals in English and Chinese.</li></ul>
<ul><li>sample
<ul>
<li>demosimplest: a simplest sample, about 60 lines of code.</li>
<li>demoraw: raw data and snap still image, about 120 lines of code.</li>
</ul>
</li></ul>
<hr/>
<h1><font color="#0000FF">3. Concepts and terminology</font></h1>
<hr/>
<h2><font color="#0000FF">a. Modes for accessing image data: "Pull Mode" vs "Push Mode"</font></h2>
<p>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.</p>
<ul>
<li>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_PullImage(WithRowPitch)(V2) and Toupcam_PullStillImage(WithRowPitch)(V2) to access image data.</li>
</ul>
<blockquote>
<p>There are to ways to notify applications:</p>
<blockquote>
<p>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.)</p>
<p>b) Use Callback function: Start pull mode by using the function Toupcam_StartPullModeWithCallback. When event occurs, toupcam will callback the function PTOUPCAM_EVENT_CALLBACK.</p>
</blockquote>
</blockquote>
<blockquote>
<p>In Pull Mode, the SDK could not only notify the application that the image data or still image are available for 'PULL', but also inform you of the other events, such as:</p>
<div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_EXPOSURE</td>
<td width="73%" valign="top">exposure time changed</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_TEMPTINT</td>
<td width="73%" valign="top">white balance changed. Temp/Tint Mode, please see <a href="#wb">here</a>.</td>
</tr>
<tr>
<td valign="top">TOUPCAM_EVENT_WBGAIN</td>
<td valign="top">white balance changed. RGB Gain Mode, please see <a href="#wb">here</a>.</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_IMAGE</td>
<td width="73%" valign="top">Video image data arrives. Use Toupcam_PullImage(V2) to 'pull' the image data</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_STILLIMAGE</td>
<td width="73%" valign="top">Still image which is triggered by function Toupcam_Snap or Toupcam_SnapN arrives. Use Toupcam_PullStillImage(V2) to 'pull' the image data</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_ERROR</td>
<td width="73%" valign="top">Generic error, data acquisition cannot continue</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_DISCONNECTED</td>
<td width="73%" valign="top">Camera disconnected, maybe has been pulled out</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_TIMEOUT</td>
<td width="73%" valign="top">Grab image timeout error, data acquisition cannot continue</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_TRIGGERFAIL</td>
<td width="73%" valign="top">trigger failed (for example, bad frame data or timeout)</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_BLACK</td>
<td width="73%" valign="top">black balance changed</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_FFC</td>
<td width="73%" valign="top">flat field correction status changed</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_DFC</td>
<td width="73%" valign="top">dark field correction status changed</td>
</tr>
<tr>
<td width="27%" valign="top">TOUPCAM_EVENT_FACTORY</td>
<td width="73%" valign="top">restore factory settings. Please note that restoring factory settings may cause resolution changes.</td>
</tr>
</table>
</div>
</blockquote>
<ul>
<li>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, etc.</li>
</ul>
<h2><font color="#0000FF">b. <a id="stillcapture">Still Capture (Still Image)</a></font></h2>
<p>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.</p>
<p>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.</p>
<blockquote>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_PullStillImage(V2) to get the still captured image.</blockquote>
<blockquote>b) In push mode operation, after the still capture, the callback function PTOUPCAM_DATA_CALLBACK(_V2) will be called with bSnap parameter setting TRUE. The image information including the resolution information will be obtained via the parameter pHeader.</blockquote>
<p>To check whether the camera have the still capture capability, call Toupcam_get_StillResolutionNumber function or check the still field of the struct ToupcamModelV2.</p>
<h2><font color="#0000FF"><a id="raw">c. Data format: RGB vs RAW</a></font></h2>
<p>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.</p>
<ul><li>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.</li></ul>
<ul><li>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. 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_AwbOnePush function and so on.</li></ul>
<p>Users could switch these two format by calling Toupcam_put_Option function with different value setting to TOUPCAM_OPTION_RAW. You must call this function BEFORE the camera start function (Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushMode).</p>
<h2><font color="#0000FF"><a id="wb">d. White Balance and Auto White Balance: Temp/Tint mode vs RGB Gain mode</a></font></h2>
<p>1. Toupcam sdk supports two independent modes for white balance: a) Temp/Tint Mode; b) RGB Gain Mode</p>
<blockquote>
<p>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_AwbOnePush is used to execute the auto white balance. When the white balance parameters change, TOUPCAM_EVENT_TEMPTINT event will be notified for external use.</p>
<p>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.</p>
<p>The functions for these two modes cannot be misused:</p>
<blockquote>
a) In Temp/Tint mode, please use Toupcam_get_TempTint and Toupcam_put_TempTint and Toupcam_AwbOnePush. Toupcam_get_WhiteBalanceGain and Toupcam_put_WhiteBalanceGain and Toupcam_AwbInit cannot be used, they always return E_NOTIMPL.<br/>
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_AwbOnePush cannot be used, they always return E_NOTIMPL<br/>
</blockquote>
<p>When calling Toupcam_Open function, whether to add a '@' character at the beginning of the id parameter will determine the white balance mode. Add a '@' character at the beginning of the id parameter means the RGB gain mode. If you want to use the RGB Gain mode, for example, if the id parameter is "abcdef", please call the Toupcam_Open function with the id parameter "@abcdef".</p>
</blockquote>
<p>2. There are two auto white balance mechanisms available in this field: one is continuous auto white balance and the other is a "one push" auto white balance. The white balance parameters will be always calculated and updated for the continuous auto white balance mechanism. For "one push" auto white balance mechanism, the white balance parameters will be calculated and updated only when triggered. Toupcam cameras support "one push" 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.</p>
<p>3. Monochromatic camera does not support white balance. The functions metioned above always return E_NOTIMPL.</p>
<h2><font color="#0000FF">e. <a id="trigger">Trigger Mode</a></font></h2>
<p>1. What is Trigger Mode</p>
<blockquote>
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 3 types for triggering according to the types of trigger source, including software trigger mode, external trigger mode and simulated trigger mode.
</blockquote>
<p>2. The Difference between Trigger and Snap</p>
<blockquote>
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.
</blockquote>
<p>3. Software Trigger Mode</p>
<blockquote>
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.
</blockquote>
<p>4. External Trigger Mode</p>
<blockquote>
Camera could be triggered by external trigger signal. By now Toupcam camera only supports positive-edge trigger mode.
</blockquote>
<p>5. Simulated Trigger Mode</p>
<blockquote>
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.
</blockquote>
<p>6. How to Enter the Trigger Mode</p>
<blockquote>
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.
<blockquote><table width="100%" border="0" bgcolor="#B0D0B0"><tr><td><pre>#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 */</pre></td></tr></table></blockquote>
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.
<blockquote>
<table width="100%" border="0" bgcolor="#B0D0B0"><tr><td><pre>#define TOUPCAM_OPTION_TRIGGER 0x0b /* 0 = video mode, 1 = software or simulated trigger mode, 2 = external trigger mode, default value = 0 */</pre></td></tr></table>
</blockquote>
Function Toupcam_get_Option(HToupCam h, unsigned iOption, int* piValue) could be used to get what type of trigger mode the camera is in.
</blockquote>
<p>7. How to Trigger the camera</p>
<blockquote>
Function Toupcam_Trigger(HToupCam h, unsigned short nNumber) could be used to trigger the camera. Assigning different value to nNumber means different:
<blockquote>
nNumber = 0 means stop the trigger.<br/>
nNumber = 0xFFFF means trigger continuously, the same as video mode;<br/>
nNumber = other valid values means nNumber images will come out from the camera.<br/>
</blockquote>
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.
</blockquote>
<p>8. Trigger timeout</p>
<blockquote>
The timeout is recommended for not less than (Exposure Time * 102% + 8 Seconds).
</blockquote>
<hr/>
<h1><font color="#0000FF">4. Functions</font></h1>
<hr/>
<ul><li><h2>HRESULT return value</h2>
<p>HRESULT is not uncommon on the Windows platform. It's borrowed to macOS and Linux, see the table:</p>
<div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td width="20%">Name</td>
<td width="60%">Description</td>
<td width="20%">Value</td>
</tr>
<tr>
<td width="20%">S_OK</td>
<td width="60%">Operation successful</td>
<td width="20%">0x00000000</td>
</tr>
<tr>
<td width="20%">S_FALSE</td>
<td width="60%">Operation successful</td>
<td width="20%">0x00000001</td>
</tr>
<tr>
<td width="20%">E_FAIL</td>
<td width="60%">Unspecified failure</td>
<td width="20%">0x80004005</td>
</tr>
<tr>
<td width="20%">E_INVALIDARG</td>
<td width="60%">One or more arguments are not valid</td>
<td width="20%">0x80070057</td>
</tr>
<tr>
<td width="20%">E_NOTIMPL</td>
<td width="60%">Not supported or not implemented</td>
<td width="20%">0x80004001</td>
</tr>
<tr>
<td width="20%">E_POINTER</td>
<td width="60%">Pointer that is not valid</td>
<td width="20%">0x80004003</td>
</tr>
<tr>
<td width="20%">E_UNEXPECTED</td>
<td width="60%">Unexpected failure</td>
<td width="20%">0x8000FFFF</td>
</tr>
<tr>
<td width="20%">E_WRONG_THREAD</td>
<td width="60%">Called in wrong thread</td>
<td width="20%">0x8001010E</td>
</tr>
</table>
</div><br/>
<div align="center"><table width="100%" border="0" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr><td><pre>#define SUCCEEDED(hr) (((HRESULT)(hr)) >= 0)
#define FAILED(hr) (((HRESULT)(hr)) < 0)</pre></td></tr>
</table></div>
</li></ul>
<ul><li><h2>Calling Convention</h2>
<p>Win: __stdcall, please see <a href="https://docs.microsoft.com/en-us/cpp/cpp/stdcall">here</a></p>
<p>macOS and Linux: __cdecl</p>
</li></ul>
<ul><li><h2><a id="callback">Callback: PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK(_V2)</a></h2>
<p>These callback functions are called back from the internal thread in toupcam.dll, so great attention should be paid to multithread issue.</p>
<p><strong>There are limitation in the callback context:</strong></p>
<p><strong>(a) Do NOT call Toupcam_Stop and Toupcam_Close in this callback function, otherwise, deadlocks.</strong></p>
<p><strong>(b) Do NOT call Toupcam_put_Option with TOUPCAM_OPTION_TRIGGER, TOUPCAM_OPTION_BITDEPTH, TOUPCAM_OPTION_PIXEL_FORMAT, TOUPCAM_OPTION_BINNING, TOUPCAM_OPTION_ROTATE, the return value is E_WRONG_THREAD.</strong></p>
</li></ul>
<ul><li><h2>Toupcam_EnumV2</h2>
<p><strong>Return value:</strong> non-negative integer, enumerated camera number</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>ToupcamInstV2 pti[TOUPCAM_MAX]: ToupcamInstV2 buffer</p>
</blockquote>
<p><strong>Remarks:</strong> call this function to enumerate ToupCam cameras that are currently connected to computer and when it is returned, ToupcamInstV2 buffer contains the information of each camera instance enumerated.<strong>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</strong>.</p>
<p>The code snippet shows as below:<br/></p>
<table width="100%" border="0" bgcolor="#B0D0B0">
<tr><td><pre>ToupcamInstV2 arr[TOUPCAM_MAX];
unsigned cnt = Toupcam_EnumV2(arr);
for (unsigned i = 0; i < cnt; ++i)
......</pre></td></tr>
</table><br/>
<table width="100%" border="0" bgcolor="#B0D0B0">
<tr><td><pre>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 */
ToupcamResolution res[TOUPCAM_MAX];
}ToupcamModelV2;</pre></td></tr>
</table><br/>
<div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td width="8%" valign="top">name</td>
<td colspan="2" valign="top">The name of this model</td>
</tr>
<tr>
<td width="8%" rowspan="35" valign="top">flag</td>
<td colspan="2" valign="top">Bitwise flag</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_CMOS</td>
<td valign="top">cmos sensor</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_CCD_PROGRESSIVE</td>
<td valign="top">progressive ccd sensor</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_CCD_INTERLACED</td>
<td valign="top">interlaced ccd sensor</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_ROI_HARDWARE</td>
<td valign="top">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.</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_MONO</td>
<td width="63%" valign="top">monochromatic sensor</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_BINSKIP_SUPPORTED</td>
<td width="63%" valign="top">support bin/skip mode, see Toupcam_put_Mode and Toupcam_get_Mode</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_USB30</td>
<td width="63%" valign="top">usb3.0</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_TEC</td>
<td width="63%" valign="top">Thermoelectric Cooler</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_USB30_OVER_USB20</td>
<td width="63%" valign="top">usb3.0 camera connected to usb2.0 port</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_ST4</td>
<td width="63%" valign="top">ST4 port</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_GETTEMPERATURE</td>
<td width="63%" valign="top">support to get the temperature of the sensor, Toupcam_get_Temperature</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_PUTTEMPERATURE</td>
<td width="63%" valign="top">support to put the target temperature of the sensor, Toupcam_put_Temperature</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_RAW10</td>
<td width="63%" valign="top">Pixel format, RAW 10 bits</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_RAW12</td>
<td width="63%" valign="top">Pixel format, RAW 12 bits</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_RAW14</td>
<td width="63%" valign="top">Pixel format, RAW 14 bits</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_RAW16</td>
<td width="63%" valign="top">Pixel format, RAW 16 bits</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_FAN</td>
<td width="63%" valign="top">cooling fan</td>
</tr>
<tr>
<td width="29%" valign="top">TOUPCAM_FLAG_TEC_ONOFF</td>
<td width="63%" valign="top">Thermoelectric Cooler can be turn on or off, target temperature of TEC, see:<br/>
TOUPCAM_OPTION_TEC<br/>
TOUPCAM_OPTION_TECTARGET</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_ISP</td>
<td valign="top">ISP (Image Signal Processing) chip</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_TRIGGER_SOFTWARE</td>
<td valign="top">support software trigger</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_TRIGGER_EXTERNAL</td>
<td valign="top">support external trigger</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_TRIGGER_SINGLE</td>
<td valign="top">only support trigger single, one trigger, one image</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_BLACKLEVEL</td>
<td valign="top">support set and get the black level</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_AUTO_FOCUS</td>
<td valign="top">support auto focus</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_BUFFER</td>
<td valign="top">frame buffer</td>
</tr>
<tr>
<td valign="top"><a id="ddr">TOUPCAM_FLAG_DDR</a></td>
<td valign="top">use very large capacity DDR (Double Data Rate SDRAM) for frame buffer</td>
</tr>
<tr>
<td valign="top">>TOUPCAM_FLAG_CG</td>
<td valign="top">Conversion Gain: LCG, HCG</td>
</tr>
<tr>
<td valign="top">>TOUPCAM_FLAG_CGHDR</td>
<td valign="top">Conversion Gain: LCG, HCG, HDR</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_YUV411</td>
<td valign="top">pixel format, yuv411</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_YUV422</td>
<td valign="top">pixel format, yuv422</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_YUV444</td>
<td valign="top">pixel format, yuv444</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_RGB888</td>
<td valign="top">pixel format, RGB888</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_RAW8</td>
<td valign="top">pixel format, RAW 8 bits</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_GMCY8</td>
<td valign="top">pixel format, GMCY, 8bits</td>
</tr>
<tr>
<td valign="top">TOUPCAM_FLAG_GMCY12</td>
<td valign="top">pixel format, GMCY, 12 btis</td>
</tr>
<tr>
<td width="8%" valign="top">maxspeed</td>
<td colspan="2" valign="top">Maximum speed level, same with Toupcam_get_MaxSpeed. The speed range is [0, maxspeed]. see Toupcam_put_Speed and Toupcam_get_Speed</td>
</tr>
<tr>
<td width="8%" valign="top">preview</td>
<td colspan="2" valign="top">Number of preview resolution. Same with Toupcam_get_ResolutionNumber</td>
</tr>
<tr>
<td width="8%" valign="top">still</td>
<td colspan="2" valign="top">Number of still resolution, zero means still capture is not supported. Same with Toupcam_get_StillResolutionNumber</td>
</tr>
<tr>
<td width="8%" valign="top">res</td>
<td colspan="2" valign="top">Resolution, width and height</td>
</tr>
</table>
</div>
</li></ul>
<ul><li><h2>Toupcam_HotPlug</h2>
<p><strong>Return value:</strong> NA</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>PTOUPCAM_HOTPLUG pHotPlugCallback: callback function</p>
<blockquote>
<table width="100%" border="0" bgcolor="#B0D0B0">
<tr>
<td><div align="center">typedef void (*PTOUPCAM_HOTPLUG)(void* pCallbackCtx);</div></td>
</tr>
</table>
</blockquote>
<p>void* pCallbackCtx: callback context</p>
</blockquote>
<p><strong>Remarks:</strong></p><blockquote>
<p>This function is only available on macOS and Linux, it's unnecessary on Windows.</p>
<p>To process the device plug in / pull out in Windows, please refer to the MSDN(<a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa363224(v=vs.85).aspx">Device Management</a>, <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa363215(v=vs.85).aspx">Detecting Media Insertion or Removal</a>).</p>
<p>To process the device plug in / pull out in 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.</p>
<p>Recommendation: for better rubustness, when notify of device insertion arrives, don't open handle of this device immediately, but open it <b>after delaying a short time (e.g., 200 milliseconds)</b>.</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_Open</h2>
<p><strong>Return value:</strong> HToupCam handle. Return NULL when fails (Such as the device has been pulled out).</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>id: ToupCam camera instance, enumerated by Toupcam_EnumV2. <strong>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_EnumV2 is optional, we can simply use NULL as the parameter.</strong></p>
</blockquote>
<p><strong>Remarks:</strong> open the camera instance.</p>
</li></ul>
<ul><li><h2>Toupcam_Close</h2>
<p><strong>Return value:</strong> void</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
</blockquote>
<p><strong>Remarks:</strong> close the camera instance. After it is closed, never use the HToupCam handle any more.</p>
</li></ul>
<ul><li><h2>Toupcam_StartPullModeWithWndMsg, Toupcam_StartPullModeWithCallback</h2>
<p><strong>Return value:</strong> HRESULT type means "success / failure"</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: instance handle opened by Toupcam_Open</p>
<p>HWND hWnd: event occurs, message will be posted in this window</p>
<p>UINT nMsg: Windows custom message type. Its WPARAM parameter means event type TOUPCAM_EVENT_xxxx, LPARAM is useless (always zero)</p>
<p>PTOUPCAM_EVENT_CALLBACK pEventCallback, void* pCallbackContext: callback function specified by user's application and callback context parameter.</p>
<table width="100%" border="0">
<tr>
<td bgcolor="#B0D0B0"><div align="center">typedef void (*PTOUPCAM_EVENT_CALLBACK)(unsigned nEvent, void* pCallbackCtx);</div></td>
</tr>
</table>
<p>see <a href="#callback">here</a>.</p>
</blockquote>
<p><strong>Remarks:</strong> Obviously, Toupcam_StartPullModeWithWndMsg is only supported in Windows OS.</p>
</li></ul>
<ul><li><h2><a id="infov2">Toupcam_PullImageV2, Toupcam_PullStillImageV2, Toupcam_PullImageWithRowPitchV2, Toupcam_PullStillImageWithRowPitchV2</a>,
Toupcam_PullImage, Toupcam_PullStillImage, <a id="rowpitch1">Toupcam_PullImageWithRowPitch</a>, <a id="rowpitch2">Toupcam_PullStillImageWithRowPitch</a></h2>
<p><strong>Return value:</strong> HRESULT type means "success/ failure". Return E_FAIL when there isn't image ready for pull.</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: instance handle opened by Toupcam_Open</p>
<p>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.</p>
<p>int bits: 24, 32, 48, 8, 16, means RGB24, RGB32, RGB48, 8 bits gray or 16 bits gray images. This parameter is ignored in RAW mode.</p>
<p>int rowPitch: the distance from one row of to the next row. rowPitch = 0 means using the default row pitch.</p>
<p>unsigned* pnWidth, unsigned* pnHeight: out parameter. width and height of image.</p>
<p>ToupcamFrameInfoV2* pInfo: out parameter, frame info. Some cameras support frame sequence and frame timestamp, for other unsigned cameras, sequence and timestamp are always 0</p>
</blockquote>
<p><strong>Remarks:</strong> when pImageData is NULL, while pnWidth and pnHeight are not NULL, you can "peek" the width and height of images.</p>
<p>Please ensure that the pImageData buffer is large enough to hold the entire frame data, see the table below:</p>
<blockquote><div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td colspan="2" valign="top">Format</td>
<td width="63%" valign="top">Default Row Pitch</td>
</tr>
<tr>
<td width="10%" rowspan="4" valign="top">RGB</td>
<td width="27%" valign="top">RGB24</td>
<td width="63%" valign="top">TDIBWIDTHBYTES(24 * Width)</td>
</tr>
<tr>
<td width="27%" valign="top">RGB32</td>
<td width="63%" valign="top">Width * 4</td>
</tr>
<tr>
<td width="27%" valign="top">RGB48</td>
<td width="63%" valign="top">TDIBWIDTHBYTES(48 * Width)</td>
</tr>
<tr>
<td width="27%" valign="top">RGB8 grey image</td>
<td width="63%" valign="top">TDIBWIDTHBYTES(8 * Width)</td>
</tr>
<tr>
<td width="10%" rowspan="2" valign="top">RAW</td>
<td width="27%" valign="top">8bits Mode</td>
<td width="63%" valign="top">Width</td>
</tr>
<tr>
<td width="27%" valign="top">10bits, 12bits, 14bits, 16bits Mode</td>
<td width="63%" valign="top">Width * 2</td>
</tr>
</table>
</div><br/>
<div align="center"><table width="100%" border="0" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td>#ifndef TDIBWIDTHBYTES<br/>
#define TDIBWIDTHBYTES(bits) ((unsigned)(((bits) + 31) & (~31)) / 8)<br/>
#endif<br/>
</td></tr>
</table></div></blockquote>
</li></ul>
<ul><li><h2>Toupcam_StartPushModeV2, Toupcam_StartPushMode</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: instance handle opened by Toupcam.</p>
<p>PTOUPCAM_DATA_CALLBACK(_V2) pDataCallback, void* pCallbackCtx: 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.</p>
</blockquote>
<blockquote>
<table width="100%" border="0" bgcolor="#B0D0B0">
<tr>
<td>typedef void (*PTOUPCAM_DATA_CALLBACK)(const void* pData, const BITMAPINFOHEADER* pHeader, int bSnap, void* pCallbackCtx);<br/>
typedef void (*PTOUPCAM_DATA_CALLBACK_V2)(const void* pData, const ToupcamFrameInfoV2* pInfo, int bSnap, void* pCallbackCtx);</td>
</tr>
</table>
<p>see <a href="#callback">here</a>.</p>
</blockquote>
<blockquote>
<p align="left">when calls back, if Parameter pData == NULL, then internal error occurs (eg: the camera is pulled out suddenly).<br/>
The row pitch of pData is always the default value.<br/>
For parameter int bSnap, TRUE means still image snap by Toupcam_Snap or Toupcam_SnapN function, FALSE means ordinary previewed pictures / videos.<br/>
</p></blockquote>
<p><strong>Remarks:</strong> start camera instance.</p>
</li></ul>
<ul><li><h2>Toupcam_Stop</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam handle</p>
</blockquote>
<p><strong>Remarks:</strong> stop the camera instance. After stopped, it can be restart again. For example, switching the video resolution: </p>
<blockquote>
<p>Step 1: call Toupcam_Stop to stop</p>
<p>Step 2: call Toupcam_put_Size or Toupcam_put_eSize to set the new resolution</p>
<p>Step 3: call Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushMode to restart</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_Pause</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
</blockquote>
<p><strong>Remarks:</strong> pause/continue camera instance.</p>
</li></ul>
<ul><li><h2>Toupcam_Snap, Toupcam_SnapN</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned nResolutionIndex: resolution index.</p>
<p><a id="snapn">unsigned nNum: the number to be snapped.</a></p>
</blockquote>
<p><strong>Remarks:</strong> snap 'still' image, please see <a href="#stillcapture">here</a>. When snap successfully:</p>
<blockquote><blockquote>
<p>a) If we use Pull Mode, it will be notified by TOUPCAM_EVENT_STILLIMAGE.</p>
<p>b) If we use Push Mode, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK(_V2) with the parameter int bSnap is TRUE.</p>
</blockquote>
<p>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.<br/>
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.<br/>
Whether it supports "still snap" or not, see "still" domain in ToupcamModelV2.</p>
<p>Toupcam_Snap(h, index) == Toupcam_SnapN(h, index, 1)</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_Trigger</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure.</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned short nNumber: 0xffff(trigger continuously), 0(stop / cancel trigger), others(number of images to be triggered)</p>
</blockquote>
<p><strong>Remarks:</strong> in trigger mode, call this function to trigger an image:</p>
<blockquote>
<p>a) If we use Pull Mode, it will be notified by TOUPCAM_EVENT_IMAGE.</p>
<p>b) If we use Push Mode, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK(_V2) with the parameter int bSnap is FALSE.</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_put_Size, Toupcam_get_Size, Toupcam_put_eSize, Toupcam_get_eSize</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned nResolutionIndex: current/present resolution index</p>
<p>int nWidth, int nHeight: width and height of current resolution index</p>
</blockquote>
<p><strong>Remarks:</strong> set/get current resolution</p>
<blockquote>
<p align="left">Set resolution before running Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushMode<br/>
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: <br/>
Index 0: 2048, 1536<br/>
Index 1: 1024, 768<br/>
Index 2: 680, 510<br/>
So Toupcam_put_Size(h, 1024, 768) is as effective as Toupcam_put_eSize(h, 1)</p>
</blockquote>
</li></ul>
<ul><li><h2><a id="roi">Toupcam_put_Roi, Toupcam_get_Roi</a></h2>
<p><strong>Return value:</strong> HRESULT type means success or failure.</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned xOffset: x offset, must be even number</p>
<p>unsigned yOffset: y offset, must be even number</p>
<p>unsigned xWidth: width, must be even number and must not be less than 16</p>
<p>unsigned yHeight: height, must be even number and must not be less than 16</p>
</blockquote>
<p><strong>Remarks:</strong> set/get the ROI. Toupcam_put_Roi(h, 0, 0, 0, 0) means to clear the ROI and restore the original size.</p>
<blockquote>
<p><strong>Important: It is forbidden to call Toupcam_put_Roi in the callback context of PTOUPCAM_EVENT_CALLBACK and PTOUPCAM_DATA_CALLBACK(_V2), the return value is E_WRONG_THREAD.</strong></p>
<p>The second resolution of UHCCD03100KPB, UHCCD05000KPA, UHCCD05100KPA don't support ROI, so the return value is E_NOTIMPL.</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_get_ResolutionNumber, Toupcam_get_Resolution</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned nResolutionIndex: resolution index</p>
<p>int* pWidth, int* pHeight: width/height</p>
</blockquote>
<p><strong>Remarks:</strong> 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 kind of resolution.</p>
<blockquote>
<p align="left">These parameters have also been contained in ToupcamModelV2.</p>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_get_RawFormat</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned* nFourCC: raw format, see the table below</p>
<p>unsigned* bitdepth: Bit Depth, such as 8, 12, 14, 16</p>
<div align="center"><table width="100%" border="0" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td>#ifndef MAKEFOURCC<br/>
#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))<br/>
#endif<br/></td>
</tr>
</table></div><br/>
<div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td width="40%" valign="top">MAKEFOURCC('G', 'B', 'R', 'G')</td>
<td width="60%" valign="top">GBGBGB...<br/>RGRGRG...<br/>GBGBGB...<br/>RGRGRG...<br/>...<br/>see <a href="http://www.siliconimaging.com/RGB%20Bayer.htm">here</a></td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('R', 'G', 'G', 'B')</td>
<td width="60%" valign="top">RGRGRG...<br/>GBGBGB...<br/>RGRGRG...<br/>GBGBGB...<br/>...<br/></td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('B', 'G', 'G', 'R')</td>
<td width="60%" valign="top">BGBGBG...<br/>GRGRGR...<br/>BGBGBG...<br/>GRGRGR...<br/>...<br/></td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('G', 'R', 'B', 'G')</td>
<td width="60%" valign="top">GRGRGR...<br/>BGBGBG...<br/>GRGRGR...<br/>BGBGBG...<br/>...<br/></td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('V', 'U', 'Y', 'Y')</td>
<td width="60%" valign="top">YUV4:2:2, please see: <a href="http://www.fourcc.org">http://www.fourcc.org</a></td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('U', 'Y', 'V', 'Y')</td>
<td width="60%" valign="top">YUV4:2:2</td>
</tr>
<tr>
<td width="40%" valign="top">MAKEFOURCC('Y', 'Y', 'Y', 'Y')</td>
<td width="60%" valign="top">Black / White camera</td>
</tr>
</table>
</div>
</blockquote>
</li></ul>
<ul><li><h2>Toupcam_put_Option, Toupcam_get_Option</h2>
<p><strong>Return value:</strong> HRESULT type means success or failure</p>
<p><strong>Parameters:</strong></p>
<blockquote>
<p>HToupCam h: camera instance handle</p>
<p>unsigned iOption: see the table</p>
<p>int iValue: see the table</p>
<div align="center">
<table width="100%" border="1" cellpadding="0" cellspacing="0" bgcolor="#B0D0B0">
<tr>
<td width="28%">Option</td>
<td width="48%">Description</td>
<td width="4%">Default</td>
<td width="20%">The value can be changed after Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushMode?<br/>
<b>The value can be changed on-the-fly?</b></td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_NOFRAME_TIMEOUT</td>
<td width="48%">Report error if cannot grab frame in a certain time.<br/>
1 = enable this feature;<br/>0 = disable this feature.</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_THREAD_PRIORITY</td>
<td width="48%">set the priority of the internal thread which grab data from the usb device.<br/>
0 = THREAD_PRIORITY_NORMAL;<br/>1 = THREAD_PRIORITY_ABOVE_NORMAL;<br/>2 = THREAD_PRIORITY_HIGHEST;<br/>3 = THREAD_PRIORITY_TIME_CRITICAL;<br/>Please refer to <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms686277(v=vs.85).aspx">SetThreadPriority</a><br/>This option is not available at Linux and macOS.</td>
<td width="4%">1</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_PROCESSMODE</td>
<td width="48%">0 = better image quality, more cpu usage.<br/>
1 = lower image quality, less cpu usage.</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%"><a id="rawo">TOUPCAM_OPTION_RAW</a></td>
<td width="48%">0 means RGB mode.<br/>
1 means RAW mode, read the CMOS or CCD raw data.</td>
<td width="4%">0</td>
<td width="20%"><b>No</b><br/>
(The return value is E_UNEXPECTED when set this option after the camera is started)</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_BITDEPTH</td>
<td width="48%">Some cameras support the bit depth which is more than 8 such as 10, 12, 14, 16.<br/>
0 = use 8 bits depth.<br/>1 = use the maximum bits depth of this camera.</td>
<td width="4%">NA</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_FAN</td>
<td width="48%">Some cameras support the cooling fan.<br/>
0 = turn off the cooling fan<br/>[1, max] = fan speed</td>
<td width="4%">NA</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_TEC</td>
<td width="48%">Some cameras support to turn on or off the thermoelectric cooler.<br/>
0 = turn off the thermoelectric cooler<br/>1 = turn on the thermoelectric cooler</td>
<td width="4%">1</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_LINEAR</td>
<td width="48%">0 = turn off the builtin linear tone mapping<br/>
1 = turn on the builtin linear tone mapping</td>
<td width="4%">1</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_CURVE</td>
<td width="48%">0 = turn off the builtin curve tone mapping<br/>
1 = turn on the builtin polynomial curve tone mapping<br/>
2 = turn on the builtin logarithmic curve tone mapping</td>
<td width="4%">2</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_COLORMATIX</td>
<td width="48%">0 = turn off the builtin color matrix<br/>
1 = turn on the builtin color matrix</td>
<td width="4%">1</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_WBGAIN</td>
<td width="48%">0 = turn off the builtin white balance gain<br/>
1 = turn on the builtin white balance gain</td>
<td width="4%">1</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_TRIGGER</td>
<td width="48%">0 = video mode<br/>
1 = software or simulated trigger mode<br/>
2 = external trigger mode</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%"><a id="rgb">TOUPCAM_OPTION_RGB</a></td>
<td width="48%">0 = RGB24<br/>
1 = enable RGB48 format when bitdepth > 8<br/>
2 = RGB32<br/>
3 = 8 bits gray (only for mono camera)<br/>
4 = 16 bits gray (only for mono camera and bitdepth > 8)</td>
<td width="4%">0</td>
<td width="20%"><b>No</b><br/>
(The return value is E_UNEXPECTED when set this option after the camera is started)</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_TECTARGET</td>
<td width="48%">get or set the target temperature of the thermoelectric cooler, in 0.1℃. For example, 125 means 12.5℃, -35 means -3.5℃</td>
<td width="4%">NA</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_AGAIN</td>
<td width="48%">enable or disable adjusting the analog gain when auto exposure is enabled</td>
<td width="4%">Yes</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_FRAMERATE</td>
<td width="48%">limit the frame rate, range=[0, 63].<br/>frame rate control is disabled automatically in trigger mode.</td>
<td width="4%">0<br/>(means no limit)</td>
<td width="20%"><b>No</b><br/>(The return value is E_UNEXPECTED when set this option after the camera is started)</td>
</tr>
<tr>
<td width="28%"><a id="demosaic">TOUPCAM_OPTION_DEMOSAIC</a></td>
<td width="48%">Demosaic mothod for both video and still image: (Please refrence <a href="https://en.wikipedia.org/wiki/Demosaicing">https://en.wikipedia.org/wiki/Demosaicing</a>)<br/>
0 = BILINEAR<br/>
1 = VNG(Variable Number of Gradients interpolation)<br/>
2 = PPG(Patterned Pixel Grouping interpolation)<br/>
3 = AHD(Adaptive Homogeneity-Directed interpolation)<br/>
Always return E_NOTIMPL for monochromatic camera.</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_DEMOSAIC_VIDEO</td>
<td width="48%">Demosaic mothod for video</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_DEMOSAIC_STILL</td>
<td width="48%">Demosaic mothod for still image<br/>
Always return E_NOTIMPL for camera that don't support sill image capture.</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%"><a id="blacklevel">TOUPCAM_OPTION_BLACKLEVEL</a></td>
<td width="48%">Black Level<br/>
Always return E_NOTIMPL for camera that don't support black level.</td>
<td width="4%">0</td>
<td width="20%">Yes</td>
</tr>
<tr>
<td width="28%">TOUPCAM_OPTION_MULTITHREAD</td>
<td width="48%">multithread image processing</td>
<td width="4%">1</td>
<td width="20%"><b>No</b><br/>
(The return value is E_UNEXPECTED when set this option after the camera is started)</td>
</tr>
<tr>
<td width="28%"><a id="binning">TOUPCAM_OPTION_BINNING</a></td>
<td width="48%">digital binning:<br/>
0x01 (no binning)<br/>
0x02 (add, 2*2)<br/>
0x03 (add, 3*3)<br/>
0x04 (add, 4*4)<br/>
0x82 (average, 2*2)<br/>
0x83 (average, 3*3)<br/>
0x84 (average, 4*4)</td>
<td width="4%">1</td>