-
Notifications
You must be signed in to change notification settings - Fork 4
/
rs.h
1077 lines (955 loc) · 64.8 KB
/
rs.h
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
/* License: Apache 2.0. See LICENSE file in root directory.
Copyright(c) 2015 Intel Corporation. All Rights Reserved. */
/** \file rs.h
* \brief
* Exposes librealsense functionality for C compilers
*/
#ifndef LIBREALSENSE_RS_H
#define LIBREALSENSE_RS_H
#ifdef __cplusplus
extern "C" {
#endif
#define RS_API_MAJOR_VERSION 1
#define RS_API_MINOR_VERSION 12
#define RS_API_PATCH_VERSION 4
#define STRINGIFY(arg) #arg
#define VAR_ARG_STRING(arg) STRINGIFY(arg)
/* Versioning rules : For each release at least one of [MJR/MNR/PTCH] triple is promoted */
/* : Versions that differ by RS_API_PATCH_VERSION only are interface-compatible, i.e. no user-code changes required */
/* : Versions that differ by MAJOR/MINOR VERSION component can introduce API changes */
/* Version in encoded integer format (1,9,x) -> 01090x. note that each component is limited into [0-99] range by design */
#define RS_API_VERSION (((RS_API_MAJOR_VERSION) * 10000) + ((RS_API_MINOR_VERSION) * 100) + (RS_API_PATCH_VERSION))
/* Return version in "X.Y.Z" format */
#define RS_API_VERSION_STR (VAR_ARG_STRING(RS_API_MAJOR_VERSION.RS_API_MINOR_VERSION.RS_API_PATCH_VERSION))
/** \brief Streams are different types of data provided by RealSense devices */
typedef enum rs_stream
{
RS_STREAM_DEPTH , /**< Native stream of depth data produced by RealSense device */
RS_STREAM_COLOR , /**< Native stream of color data captured by RealSense device */
RS_STREAM_INFRARED , /**< Native stream of infrared data captured by RealSense device */
RS_STREAM_INFRARED2 , /**< Native stream of infrared data captured from a second viewpoint by RealSense device */
RS_STREAM_FISHEYE , /**< Native stream of fish-eye (wide) data captured from the dedicate motion camera */
RS_STREAM_POINTS , /**< Synthetic stream containing point cloud data generated by deprojecting the depth image */
RS_STREAM_RECTIFIED_COLOR , /**< Synthetic stream containing undistorted color data with no extrinsic rotation from the depth stream */
RS_STREAM_COLOR_ALIGNED_TO_DEPTH , /**< Synthetic stream containing color data but sharing intrinsic of depth stream */
RS_STREAM_INFRARED2_ALIGNED_TO_DEPTH , /**< Synthetic stream containing second viewpoint infrared data but sharing intrinsic of depth stream */
RS_STREAM_DEPTH_ALIGNED_TO_COLOR , /**< Synthetic stream containing depth data but sharing intrinsic of color stream */
RS_STREAM_DEPTH_ALIGNED_TO_RECTIFIED_COLOR , /**< Synthetic stream containing depth data but sharing intrinsic of rectified color stream */
RS_STREAM_DEPTH_ALIGNED_TO_INFRARED2 , /**< Synthetic stream containing depth data but sharing intrinsic of second viewpoint infrared stream */
RS_STREAM_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_stream;
/** \brief Formats: defines how each stream can be encoded.
\c rs_format specifies how a frame is represented in memory (similar to the V4L pixel format). */
typedef enum rs_format
{
RS_FORMAT_ANY , /**< When passed to enable stream, librealsense will try to provide best suited format */
RS_FORMAT_Z16 , /**< 16-bit linear depth values. The depth is meters is equal to depth scale * pixel value. */
RS_FORMAT_DISPARITY16 , /**< 16-bit linear disparity values. The depth in meters is equal to depth scale / pixel value. */
RS_FORMAT_XYZ32F , /**< 32-bit floating point 3D coordinates. */
RS_FORMAT_YUYV , /**< Standard YUV pixel format as described in https://en.wikipedia.org/wiki/YUV */
RS_FORMAT_RGB8 , /**< 8-bit red, green and blue channels */
RS_FORMAT_BGR8 , /**< 8-bit blue, green, and red channels -- suitable for OpenCV */
RS_FORMAT_RGBA8 , /**< 8-bit red, green and blue channels + constant alpha channel equal to FF */
RS_FORMAT_BGRA8 , /**< 8-bit blue, green, and red channels + constant alpha channel equal to FF */
RS_FORMAT_Y8 , /**< 8-bit per-pixel grayscale image */
RS_FORMAT_Y16 , /**< 16-bit per-pixel grayscale image */
RS_FORMAT_RAW10 , /**< Four 10-bit luminance values encoded into a 5-byte macropixel */
RS_FORMAT_RAW16 , /**< 16-bit raw image */
RS_FORMAT_RAW8 , /**< 8-bit raw image */
RS_FORMAT_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_format;
/** \brief Output buffer format: sets how librealsense works with frame memory. */
typedef enum rs_output_buffer_format
{
RS_OUTPUT_BUFFER_FORMAT_CONTINUOUS , /**< Makes sure that the output frame is exposed as a single continuous buffer */
RS_OUTPUT_BUFFER_FORMAT_NATIVE , /**< Does not convert buffer to continuous. The user has to handle pitch manually. */
RS_OUTPUT_BUFFER_FORMAT_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_output_buffer_format;
/** \brief Presets: general preferences that are translated by librealsense into concrete resolution and FPS. */
typedef enum rs_preset
{
RS_PRESET_BEST_QUALITY , /**< Prefer best overall quality */
RS_PRESET_LARGEST_IMAGE , /**< Prefer largest image size */
RS_PRESET_HIGHEST_FRAMERATE, /**< Prefer highest frame rate */
RS_PRESET_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_preset;
/** \brief Source: allows you to choose between available hardware subdevices. */
typedef enum rs_source
{
RS_SOURCE_VIDEO , /**< Video streaming of depth, infrared, color, or fish-eye */
RS_SOURCE_MOTION_TRACKING, /**< Motion tracking from gyroscope and accelerometer */
RS_SOURCE_ALL , /**< Enable everything together */
RS_SOURCE_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_source;
/** \brief Distortion model: defines how pixel coordinates should be mapped to sensor coordinates. */
typedef enum rs_distortion
{
RS_DISTORTION_NONE , /**< Rectilinear images. No distortion compensation required. */
RS_DISTORTION_MODIFIED_BROWN_CONRADY, /**< Equivalent to Brown-Conrady distortion, except that tangential distortion is applied to radially distorted points */
RS_DISTORTION_INVERSE_BROWN_CONRADY , /**< Equivalent to Brown-Conrady distortion, except undistorts image instead of distorting it */
RS_DISTORTION_FTHETA , /**< Distortion model of the fish-eye camera */
RS_DISTORTION_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_distortion;
/** \brief For SR300 devices: provides optimized settings (presets) for specific types of usage. */
typedef enum rs_ivcam_preset
{
RS_IVCAM_PRESET_SHORT_RANGE , /**< Preset for short range */
RS_IVCAM_PRESET_LONG_RANGE , /**< Preset for long range */
RS_IVCAM_PRESET_BACKGROUND_SEGMENTATION , /**< Preset for background segmentation */
RS_IVCAM_PRESET_GESTURE_RECOGNITION , /**< Preset for gesture recognition */
RS_IVCAM_PRESET_OBJECT_SCANNING , /**< Preset for object scanning */
RS_IVCAM_PRESET_FACE_ANALYTICS , /**< Preset for face analytics */
RS_IVCAM_PRESET_FACE_LOGIN , /**< Preset for face login */
RS_IVCAM_PRESET_GR_CURSOR , /**< Preset for GR cursor */
RS_IVCAM_PRESET_DEFAULT , /**< Preset for default */
RS_IVCAM_PRESET_MID_RANGE , /**< Preset for mid-range */
RS_IVCAM_PRESET_IR_ONLY , /**< Preset for IR only */
RS_IVCAM_PRESET_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_ivcam_preset;
/** \brief Defines general configuration controls.
These can generally be mapped to camera UVC controls, and unless stated otherwise, can be set/queried at any time. */
typedef enum rs_option
{
RS_OPTION_COLOR_BACKLIGHT_COMPENSATION , /**< Enable/disable color backlight compensation*/
RS_OPTION_COLOR_BRIGHTNESS , /**< Color image brightness*/
RS_OPTION_COLOR_CONTRAST , /**< Color image contrast*/
RS_OPTION_COLOR_EXPOSURE , /**< Controls exposure time of color camera. Setting any value will disable auto exposure.*/
RS_OPTION_COLOR_GAIN , /**< Color image gain */
RS_OPTION_COLOR_GAMMA , /**< Color image gamma setting*/
RS_OPTION_COLOR_HUE , /**< Color image hue*/
RS_OPTION_COLOR_SATURATION , /**< Color image saturation setting*/
RS_OPTION_COLOR_SHARPNESS , /**< Color image sharpness setting*/
RS_OPTION_COLOR_WHITE_BALANCE , /**< Controls white balance of color image. Setting any value will disable auto white balance.*/
RS_OPTION_COLOR_ENABLE_AUTO_EXPOSURE , /**< Enable/disable color image auto-exposure*/
RS_OPTION_COLOR_ENABLE_AUTO_WHITE_BALANCE , /**< Enable/disable color image auto-white-balance*/
RS_OPTION_F200_LASER_POWER , /**< Power of the F200/SR300 projector, with 0 meaning projector off*/
RS_OPTION_F200_ACCURACY , /**< Set the number of patterns projected per frame. The higher the accuracy value, the more patterns projected. Increasing the number of patterns helps to achieve better accuracy. Note that this control affects the depth FPS. */
RS_OPTION_F200_MOTION_RANGE , /**< Motion vs. range trade-off, with lower values allowing for better motion sensitivity and higher values allowing for better depth range*/
RS_OPTION_F200_FILTER_OPTION , /**< Set the filter to apply to each depth frame. Each one of the filters is optimized per the application requirements.*/
RS_OPTION_F200_CONFIDENCE_THRESHOLD , /**< Confidence level threshold used by the depth algorithm pipe to set whether a pixel will get a valid range or will be marked with invalid range*/
RS_OPTION_F200_DYNAMIC_FPS , /**< (F200-only) Allows to reduce FPS without restarting streaming. Valid values are {2, 5, 15, 30, 60}.*/
RS_OPTION_SR300_AUTO_RANGE_ENABLE_MOTION_VERSUS_RANGE , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_ENABLE_LASER , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_MIN_MOTION_VERSUS_RANGE , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_MAX_MOTION_VERSUS_RANGE , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_START_MOTION_VERSUS_RANGE , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_MIN_LASER , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_MAX_LASER , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_START_LASER , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_UPPER_THRESHOLD , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_SR300_AUTO_RANGE_LOWER_THRESHOLD , /**< Configures SR300 depth auto-range setting. Should not be used directly but through the \c rs_apply_ivcam_preset method in rsutil.h.*/
RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED , /**< Enable/disable R200 auto-exposure. This will affect both the IR and depth images.*/
RS_OPTION_R200_LR_GAIN , /**< IR image gain*/
RS_OPTION_R200_LR_EXPOSURE , /**< This control allows manual adjustment of the exposure time value for the L/R imagers.*/
RS_OPTION_R200_EMITTER_ENABLED , /**< Enables/disables R200 emitter*/
RS_OPTION_R200_DEPTH_UNITS , /**< Micrometers per increment in integer depth values. 1000 is default (mm scale). Set before streaming.*/
RS_OPTION_R200_DEPTH_CLAMP_MIN , /**< Minimum depth in current depth units that will be output. Any values less than ג€˜Min Depthג€™ will be mapped to 0 during the conversion between disparity and depth. Set before streaming.*/
RS_OPTION_R200_DEPTH_CLAMP_MAX , /**< Maximum depth in current depth units that will be output. Any values greater than ג€˜Max Depthג€™ will be mapped to 0 during the conversion between disparity and depth. Set before streaming.*/
RS_OPTION_R200_DISPARITY_MULTIPLIER , /**< Disparity scale factor used when in disparity output mode. Can only be set before streaming.*/
RS_OPTION_R200_DISPARITY_SHIFT , /**< {0 - 512}. Can only be set before streaming starts.*/
RS_OPTION_R200_AUTO_EXPOSURE_MEAN_INTENSITY_SET_POINT , /**< Mean intensity set point. Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_BRIGHT_RATIO_SET_POINT , /**< Bright ratio set point. Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_KP_GAIN , /**< Kp gain. Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_KP_EXPOSURE , /**< Kp exposure. Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_KP_DARK_THRESHOLD , /**< Kp dark threshold. Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_TOP_EDGE , /**< Auto-exposure region-of-interest top edge (in pixels). Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_BOTTOM_EDGE , /**< Auto-exposure region-of-interest bottom edge (in pixels). Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_LEFT_EDGE , /**< Auto-exposure region-of-interest left edge (in pixels). Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_AUTO_EXPOSURE_RIGHT_EDGE , /**< Auto-exposure region-of-interest right edge (in pixels). Requires the \c RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED option to be set to 1.*/
RS_OPTION_R200_DEPTH_CONTROL_ESTIMATE_MEDIAN_DECREMENT , /**< Value to subtract when estimating the median of the correlation surface*/
RS_OPTION_R200_DEPTH_CONTROL_ESTIMATE_MEDIAN_INCREMENT , /**< Value to add when estimating the median of the correlation surface*/
RS_OPTION_R200_DEPTH_CONTROL_MEDIAN_THRESHOLD , /**< Threshold: by how much the winning score exceeds the median. */
RS_OPTION_R200_DEPTH_CONTROL_SCORE_MINIMUM_THRESHOLD , /**< Minimum correlation score that is considered acceptable*/
RS_OPTION_R200_DEPTH_CONTROL_SCORE_MAXIMUM_THRESHOLD , /**< Maximum correlation score that is considered acceptable*/
RS_OPTION_R200_DEPTH_CONTROL_TEXTURE_COUNT_THRESHOLD , /**< Parameter for determining whether the texture in the region is sufficient to justify a depth result*/
RS_OPTION_R200_DEPTH_CONTROL_TEXTURE_DIFFERENCE_THRESHOLD , /**< Parameter for determining whether the texture in the region is sufficient to justify a depth result*/
RS_OPTION_R200_DEPTH_CONTROL_SECOND_PEAK_THRESHOLD , /**< Threshold: how much the minimum correlation score must differ from the next best score.*/
RS_OPTION_R200_DEPTH_CONTROL_NEIGHBOR_THRESHOLD , /**< Neighbor threshold value for depth calculation*/
RS_OPTION_R200_DEPTH_CONTROL_LR_THRESHOLD , /**< Left-right threshold value for depth calculation*/
RS_OPTION_FISHEYE_EXPOSURE , /**< Fisheye image exposure time in msec*/
RS_OPTION_FISHEYE_GAIN , /**< Fisheye image gain*/
RS_OPTION_FISHEYE_STROBE , /**< Enable/disable fisheye strobe. When enabled, aligns timestamps to common clock-domain with the motion events.*/
RS_OPTION_FISHEYE_EXTERNAL_TRIGGER , /**< Enable/disable fisheye external trigger mode. When enabled, fisheye image will be aquired in-sync with the depth image.*/
RS_OPTION_FISHEYE_ENABLE_AUTO_EXPOSURE , /**< Enable/disable fisheye auto-exposure */
RS_OPTION_FISHEYE_AUTO_EXPOSURE_MODE , /**< 0 - static auto-exposure, 1 - anti-flicker auto-exposure, 2 - hybrid */
RS_OPTION_FISHEYE_AUTO_EXPOSURE_ANTIFLICKER_RATE , /**< Fisheye auto-exposure anti-flicker rate. Can be 50 or 60 Hz. */
RS_OPTION_FISHEYE_AUTO_EXPOSURE_PIXEL_SAMPLE_RATE , /**< In Fisheye auto-exposure sample frame every given number of pixels */
RS_OPTION_FISHEYE_AUTO_EXPOSURE_SKIP_FRAMES , /**< In Fisheye auto-exposure sample every given number of frames */
RS_OPTION_FRAMES_QUEUE_SIZE , /**< Number of frames the user is allowed to keep per stream. Trying to hold on to more frames will cause frame-drops.*/
RS_OPTION_HARDWARE_LOGGER_ENABLED , /**< Enable/disable fetching log data from the device */
RS_OPTION_TOTAL_FRAME_DROPS , /**< Total number of detected frame drops from all streams */
RS_OPTION_COUNT , /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_option;
/** \brief Types of value provided from the device with each frame */
typedef enum rs_frame_metadata
{
RS_FRAME_METADATA_ACTUAL_EXPOSURE, /**< Actual exposure at which the frame was captured */
RS_FRAME_METADATA_ACTUAL_FPS, /**< Actual FPS at the time of capture */
RS_FRAME_METADATA_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_frame_metadata;
/** \brief Specifies various capabilities of a RealSense device.
To check if a certain capability is supported by a particular device, at runtime call <tt>dev->supports(capability)</tt>. */
typedef enum rs_capabilities
{
RS_CAPABILITIES_DEPTH, /**< Provides depth stream */
RS_CAPABILITIES_COLOR, /**< Provides color stream */
RS_CAPABILITIES_INFRARED, /**< Provides infrared stream */
RS_CAPABILITIES_INFRARED2, /**< Provides second infrared stream */
RS_CAPABILITIES_FISH_EYE, /**< Provides wide field of view (fish-eye) stream */
RS_CAPABILITIES_MOTION_EVENTS, /**< Provides gyroscope and accelorometer events */
RS_CAPABILITIES_MOTION_MODULE_FW_UPDATE, /**< Provides method for upgrading motion module firmware */
RS_CAPABILITIES_ADAPTER_BOARD, /**< Internally MIPI-to-USB adapter */
RS_CAPABILITIES_ENUMERATION, /**< Provides enough basic functionality to be considered supported. This is to catch at runtime various outdated engineering samples. */
RS_CAPABILITIES_COUNT, /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_capabilities;
/** \brief Proprietary formats for direct communication with device firmware */
typedef enum rs_blob_type {
RS_BLOB_TYPE_MOTION_MODULE_FIRMWARE_UPDATE, /**< By using this option, new firmware can be uploaded to the ZR300 motion-module */
RS_BLOB_TYPE_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_blob_type;
/**\brief Read-only strings that can be queried from the device.
Not all information fields are available on all camera types.
This information is mainly available for camera debug and troubleshooting and should not be used in applications. */
typedef enum rs_camera_info {
RS_CAMERA_INFO_DEVICE_NAME , /**< Device friendly name */
RS_CAMERA_INFO_DEVICE_SERIAL_NUMBER , /**< Device serial number */
RS_CAMERA_INFO_CAMERA_FIRMWARE_VERSION , /**< Primary firmware version */
RS_CAMERA_INFO_ADAPTER_BOARD_FIRMWARE_VERSION, /**< MIPI-to-USB adapter board firmware version if such board is present */
RS_CAMERA_INFO_MOTION_MODULE_FIRMWARE_VERSION, /**< Motion module firmware version if motion module is present */
RS_CAMERA_INFO_CAMERA_TYPE , /**< R200/LR200/ZR300 camera type */
RS_CAMERA_INFO_OEM_ID , /**< OEM ID */
RS_CAMERA_INFO_ISP_FW_VERSION , /**< ISP firmware version, when available */
RS_CAMERA_INFO_CONTENT_VERSION , /**< R200/LR200/ZR300 content version */
RS_CAMERA_INFO_MODULE_VERSION , /**< R200/LR200/ZR300 module version */
RS_CAMERA_INFO_IMAGER_MODEL_NUMBER , /**< Primary imager model number */
RS_CAMERA_INFO_BUILD_DATE , /**< Device build date */
RS_CAMERA_INFO_CALIBRATION_DATE , /**< Primary calibration date */
RS_CAMERA_INFO_PROGRAM_DATE , /**< R200/LR200/ZR300 program date */
RS_CAMERA_INFO_FOCUS_ALIGNMENT_DATE , /**< Focus calibration date */
RS_CAMERA_INFO_EMITTER_TYPE , /**< R200/LR200/ZR300 emitter type */
RS_CAMERA_INFO_FOCUS_VALUE , /**< Result of the focus calibration */
RS_CAMERA_INFO_LENS_TYPE , /**< Primary lens type */
RS_CAMERA_INFO_3RD_LENS_TYPE , /**< Color imager lens type */
RS_CAMERA_INFO_LENS_COATING__TYPE , /**< Lens coating type */
RS_CAMERA_INFO_3RD_LENS_COATING_TYPE , /**< Color coating type */
RS_CAMERA_INFO_NOMINAL_BASELINE , /**< Nominal baseline */
RS_CAMERA_INFO_3RD_NOMINAL_BASELINE , /**< Color nominal baseline */
RS_CAMERA_INFO_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_camera_info;
/**\brief Severity of the librealsense logger */
typedef enum rs_log_severity {
RS_LOG_SEVERITY_DEBUG, /**< Detailed information about ordinary operations */
RS_LOG_SEVERITY_INFO , /**< Terse information about ordinary operations */
RS_LOG_SEVERITY_WARN , /**< Indication of possible failure */
RS_LOG_SEVERITY_ERROR, /**< Indication of definite failure */
RS_LOG_SEVERITY_FATAL, /**< Indication of unrecoverable failure */
RS_LOG_SEVERITY_NONE , /**< No logging will occur */
RS_LOG_SEVERITY_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
} rs_log_severity;
/** \brief Source device that triggered a specific timestamp event from the motion module */
typedef enum rs_event_source
{
RS_EVENT_IMU_ACCEL , /**< Event from accelerometer */
RS_EVENT_IMU_GYRO , /**< Event from the gyroscope */
RS_EVENT_IMU_DEPTH_CAM , /**< Event from depth camera (depth/IR frame) */
RS_EVENT_IMU_MOTION_CAM, /**< Event from the fish-eye camera */
RS_EVENT_G0_SYNC , /**< Event from external GPIO 0 */
RS_EVENT_G1_SYNC , /**< Event from external GPIO 1 */
RS_EVENT_G2_SYNC , /**< Event from external GPIO 2 */
RS_EVENT_SOURCE_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
}rs_event_source;
/** \brief Specifies the clock in relation to which the frame timestamp was measured.
When working with a motion microcontroller, motion data timestamps are always in the microcontroller timestamp domain.
Some frames, however, might not succesfully receive microcontroller timestamp and will be marked as camera domain. */
typedef enum rs_timestamp_domain
{
RS_TIMESTAMP_DOMAIN_CAMERA , /**< Frame timestamp was measured in relation to the camera clock */
RS_TIMESTAMP_DOMAIN_MICROCONTROLLER, /**< Frame timestamp was measured in relation to the microcontroller clock */
RS_TIMESTAMP_DOMAIN_COUNT /**< Number of enumeration values. Not a valid input: intended to be used in for-loops. */
}rs_timestamp_domain;
/** \brief Video stream intrinsics */
typedef struct rs_intrinsics
{
int width; /**< Width of the image in pixels */
int height; /**< Height of the image in pixels */
float ppx; /**< Horizontal coordinate of the principal point of the image, as a pixel offset from the left edge */
float ppy; /**< Vertical coordinate of the principal point of the image, as a pixel offset from the top edge */
float fx; /**< Focal length of the image plane, as a multiple of pixel width */
float fy; /**< Focal length of the image plane, as a multiple of pixel height */
rs_distortion model; /**< Distortion model of the image */
float coeffs[5]; /**< Distortion coefficients */
} rs_intrinsics;
/** \brief Motion device intrinsics: scale, bias, and variances */
typedef struct rs_motion_device_intrinsic
{
/* Scale X cross axis cross axis Bias X */
/* cross axis Scale Y cross axis Bias Y */
/* cross axis cross axis Scale Z Bias Z */
float data[3][4]; /**< Interpret data array values */
float noise_variances[3]; /**< Variance of noise for X, Y, and Z axis */
float bias_variances[3]; /**< Variance of bias for X, Y, and Z axis */
} rs_motion_device_intrinsic;
/** \brief Motion module intrinsics: includes accelerometer and gyroscope intrinsics structs of type \c rs_motion_device_intrinsic. */
typedef struct rs_motion_intrinsics
{
rs_motion_device_intrinsic acc;
rs_motion_device_intrinsic gyro;
} rs_motion_intrinsics;
/** \brief Cross-stream extrinsics: encode the topology describing how the different devices are connected. */
typedef struct rs_extrinsics
{
float rotation[9]; /**< Column-major 3x3 rotation matrix */
float translation[3]; /**< Three-element translation vector, in meters */
} rs_extrinsics;
/** \brief Timestamp data from the motion microcontroller */
typedef struct rs_timestamp_data
{
double timestamp; /**< Timestamp in milliseconds */
rs_event_source source_id; /**< Physical commponent that originated the event */
unsigned long long frame_number; /**< Relevant frame number, required to join timestamp data with the relevant frame */
} rs_timestamp_data;
/** \brief Motion data from gyroscope and accelerometer from the microcontroller */
typedef struct rs_motion_data
{
rs_timestamp_data timestamp_data;
unsigned int is_valid; /**< Signaled by firmware in case of an error */
float axes[3]; /**< Three [x,y,z] axes; 16-bit data for gyroscope [rad/sec], 12-bit for accelerometer; 2's complement [m/sec^2]*/
} rs_motion_data;
typedef struct rs_context rs_context;
typedef struct rs_device rs_device;
typedef struct rs_error rs_error;
typedef struct rs_frameset rs_frameset;
typedef struct rs_frame_ref rs_frame_ref;
typedef struct rs_motion_callback rs_motion_callback;
typedef struct rs_frame_callback rs_frame_callback;
typedef struct rs_timestamp_callback rs_timestamp_callback;
typedef struct rs_log_callback rs_log_callback;
typedef void (*rs_frame_callback_ptr)(rs_device * dev, rs_frame_ref * frame, void * user);
typedef void (*rs_motion_callback_ptr)(rs_device * , rs_motion_data, void * );
typedef void (*rs_timestamp_callback_ptr)(rs_device * , rs_timestamp_data, void * );
typedef void (*rs_log_callback_ptr)(rs_log_severity min_severity, const char * message, void * user);
/**
* \brief Creates RealSense context that is required for the rest of the API.
* \param[in] api_version Users are expected to pass their version of \c RS_API_VERSION to make sure they are running the correct librealsense version.
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Context object
*/
rs_context * rs_create_context(int api_version, rs_error ** error);
/**
* \brief Frees the relevant context object.
*
* This action might invalidate \c rs_device pointers created from this context.
* \param[in] context Object that is no longer needed
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_delete_context(rs_context * context, rs_error ** error);
/**
* \brief Determines number of connected devices.
* \param context Object representing librealsense session
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Device count
*/
int rs_get_device_count(const rs_context * context, rs_error ** error);
/**
* \brief Retrieves connected device by index
* \param context Object representing librealsense session
* \param[in] index Zero-based index of device to retrieve
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Requested device
*/
rs_device * rs_get_device(rs_context * context, int index, rs_error ** error);
/**
* \brief Retrieves human-readable device model string
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Model string, such as "Intel RealSense F200" or "Intel RealSense R200"
*/
const char * rs_get_device_name(const rs_device * device, rs_error ** error);
/**
* \brief Retrieves unique serial number of the device
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Serial number, in a format specific to the device model
*/
const char * rs_get_device_serial(const rs_device * device, rs_error ** error);
/**
* \brief Retrieves camera specific information, such as versions of various internal componnents
* \param[in] device Relevant RealSense device
* \param[out] info Information that is retrieved
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Requested camera information string, in a format specific to the device model.
*/
const char * rs_get_device_info(const rs_device * device, rs_camera_info info, rs_error ** error);
/**
* \brief Retrieves the USB port number of the device
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return USB port number in a string of format: "##-##"
*/
const char * rs_get_device_usb_port_id(const rs_device * device, rs_error ** error);
/**
* \brief Retrieves the version of the firmware currently installed on the device
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored
* \return Firmware version string, in a format that is specific to device model
*/
const char * rs_get_device_firmware_version(const rs_device * device, rs_error ** error);
/**
* \brief Retrieves extrinsic transformation between the viewpoints of two different streams
* \param[in] device Relevant RealSense device
* \param[in] from_stream Stream whose coordinate space to transform from
* \param[in] to_stream Stream whose coordinate space to transform to
* \param[out] extrin Transformation between the two streams
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_device_extrinsics(const rs_device * device, rs_stream from_stream, rs_stream to_stream, rs_extrinsics * extrin, rs_error ** error);
/**
* \brief Retrieves extrinsic transformation between specific stream and the motion module
* \param[in] device Relevant RealSense device
* \param[in] from Stream
* \param[out] extrin Transformation between the specific stream and motion module
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_motion_extrinsics_from(const rs_device * device, rs_stream from, rs_extrinsics * extrin, rs_error ** error);
/**
* \brief Retrieves mapping between the units of the depth image and meters
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Depth in meters corresponding to a depth value of 1
*/
float rs_get_device_depth_scale(const rs_device * device, rs_error ** error);
/**
* \brief Determines if the device allows a specific option to be queried and set
* \param[in] device Relevant RealSense device
* \param[in] option Option
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if the option can be queried and set
*/
int rs_device_supports_option(const rs_device * device, rs_option option, rs_error ** error);
/**
* \brief Determines the number of streaming modes available for a given stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return the count of available modes
*/
int rs_get_stream_mode_count(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Determines the properties of a specific streaming mode
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] index Zero-based index of the streaming mode
* \param[out] width Width of a frame image in pixels
* \param[out] height Height of a frame image in pixels
* \param[out] format Pixel format of a frame image
* \param[out] framerate Number of frames that will be streamed per second
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_stream_mode(const rs_device * device, rs_stream stream, int index, int * width, int * height, rs_format * format, int * framerate, rs_error ** error);
/**
* \brief Enables a specific stream and requests specific properties
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] width Desired width of a frame image in pixels, or 0 if any width is acceptable
* \param[in] height Desired height of a frame image in pixels, or 0 if any height is acceptable
* \param[in] format Pixel format of a frame image, or ANY if any format is acceptable
* \param[in] framerate Number of frames that will be streamed per second, or 0 if any frame rate is acceptable
* \param[in] output_format Output buffer format (contious in memory / native with pitch)
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_enable_stream_ex(rs_device * device, rs_stream stream, int width, int height, rs_format format, int framerate, rs_output_buffer_format output_format, rs_error ** error);
/**
* \brief Enables a specific stream and requests specific properties
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] width Desired width of a frame image in pixels, or 0 if any width is acceptable
* \param[in] height Desired height of a frame image in pixels, or 0 if any height is acceptable
* \param[in] format Pixel format of a frame image, or ANY if any format is acceptable
* \param[in] framerate Number of frames that will be streamed per second, or 0 if any frame rate is acceptable
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_enable_stream(rs_device * device, rs_stream stream, int width, int height, rs_format format, int framerate, rs_error ** error);
/**
* \brief Enables a specific stream and requests properties using a preset
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] preset Preset to use to enable the stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_enable_stream_preset(rs_device * device, rs_stream stream, rs_preset preset, rs_error ** error);
/**
* \brief Disables a specific stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_disable_stream(rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Determines if a specific stream is enabled
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if the stream is currently enabled
*/
int rs_is_stream_enabled(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves the width in pixels of a specific stream, equivalent to the width field from the stream's intrinsic
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Width in pixels of images from this stream
*/
int rs_get_stream_width(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves the height in pixels of a specific stream, equivalent to the height field from the stream's intrinsic
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Height in pixels of images from this stream
*/
int rs_get_stream_height(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves the pixel format for a specific stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Pixel format of the stream
*/
rs_format rs_get_stream_format(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves the frame rate for a specific stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame rate of the stream, in frames per second
*/
int rs_get_stream_framerate(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves intrinsic camera parameters for a specific stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[out] intrin Intrinsic parameters of the stream
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_stream_intrinsics(const rs_device * device, rs_stream stream, rs_intrinsics * intrin, rs_error ** error);
/**
* \brief Retrieves intrinsic camera parameters for a motion module
* \param[in] device Relevant RealSense device
* \param[out] intrinsic Intrinsic parameters
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_motion_intrinsics(const rs_device * device, rs_motion_intrinsics * intrinsic, rs_error ** error);
/**
* \brief Sets up a frame callback that is called immediately when an image is available, with no synchronization logic applied
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] on_frame Callback that will receive the frame data and timestamp
* \param[in] user User data point to be passed to the callback
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \see \c rs_set_frame_callback_cpp()
*/
void rs_set_frame_callback(rs_device * device, rs_stream stream, rs_frame_callback_ptr on_frame, void * user, rs_error ** error);
/**
* \brief Enables and configures motion-tracking data handlers
* \param[in] device Relevant RealSense device
* \param[in] on_motion_event User-defined routine to be invoked when a motion data arrives
* \param[in] motion_handler User data point to be passed to the motion event callback
* \param[in] on_timestamp_event User-defined routine to be invoked on timestamp
* \param[in] timestamp_handler User data point to be passed to the motion event callback
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \see \c rs_enable_motion_tracking_cpp()
*/
void rs_enable_motion_tracking(rs_device * device,
rs_motion_callback_ptr on_motion_event, void * motion_handler,
rs_timestamp_callback_ptr on_timestamp_event, void * timestamp_handler,
rs_error ** error);
/**
* \brief Enables and configures motion-tracking data handlers
*
* <b>Note</b>:
*
* The \c rs_enable_motion_tracking_cpp() method is responsible for activating the motion module on-board the device.
* One of the services it provides is to produce shared and high-resolution timestamps for all components that are connected to it.
* For Depth, IR, Color and Fisheye sensors, librealsense takes care of that and copies the timestamps on the relevant frames.
*
* However, when you have an external device (such as a compass, magnetometer, light sensor, or other) and wish to synchronize it precisely with image and
* motion streams, you can connect that sensor to a GPIO that is available on some devices. Every time the sensor signals, you
* get a timestamp callback with a frame number, source ID, and a timestamp.
* This timestamp callback allows advanced users to synchronize compass events (presumably coming though I2C or some other method) with RealSense data.
*
* This variant of \c rs_enable_motion_tracking() is provided specifically to enable passing lambdas with capture lists safely into the library.
* \param[in] device Relevant RealSense device
* \param[in] motion_callback User-defined routine to be invoked when motion data arrives
* \param[in] timestamp_callback User-defined routine to be invoked on timestamp
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \see \c rs_enable_motion_tracking()
*/
void rs_enable_motion_tracking_cpp(rs_device * device,
rs_motion_callback * motion_callback,
rs_timestamp_callback * timestamp_callback,
rs_error ** error);
/**
* \brief Sets up a frame callback that is called immediately when an image is available, with no synchronization logic applied
* This variant of \c rs_set_frame_callback() is provided specifically to enable passing lambdas with capture lists safely into the library.
* \param[in] device Relevant RealSense device
* \param[in] stream Stream
* \param[in] callback Callback that will receive the frame data and timestamp
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \see \c rs_set_frame_callback()
*/
void rs_set_frame_callback_cpp(rs_device * device, rs_stream stream, rs_frame_callback * callback, rs_error ** error);
/**
* \brief Disables motion-tracking handlers
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_disable_motion_tracking(rs_device * device, rs_error ** error);
/**
* \brief Checks if data acquisition is active
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if motion tracking is active
*/
int rs_is_motion_tracking_active(rs_device * device, rs_error ** error);
/**
* \brief Begins streaming on all enabled streams for this device
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_start_device(rs_device * device, rs_error ** error);
/**
* \brief Ends data acquisition for the specified source providers
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_stop_device(rs_device * device, rs_error ** error);
/**
* \brief Begins streaming on all enabled streams for this device
* \param[in] device Relevant RealSense device
* \param[in] source Data source to be activated
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_start_source(rs_device * device, rs_source source, rs_error ** error);
/**
* \brief Ends data acquisition for the specified source providers
* \param[in] device Relevant RealSense device
* \param[in] source Data source to be terminated
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_stop_source(rs_device * device, rs_source source, rs_error ** error);
/**
* \brief Determines if the device is currently streaming
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if the device is currently streaming
*/
int rs_is_device_streaming(const rs_device * device, rs_error ** error);
/**
* \brief Retrieves the available range of values for a supported option
* \param[in] device Relevant RealSense device
* \param[in] option Option
* \param[out] min Minimum value that is acceptable for this option
* \param[out] max Maximum value that is acceptable for this option
* \param[out] step Granularity of options that accept discrete values, or zero if the option accepts continuous values
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_device_option_range(rs_device * device, rs_option option, double * min, double * max, double * step, rs_error ** error);
/**
* \brief Retrieves the available range of values for a supported option
* \param[in] device Relevant RealSense device
* \param[in] option Option
* \param[out] min Minimum value that is acceptable for this option
* \param[out] max Maximum value that is acceptable for this option
* \param[out] step Granularity of options that accept discrete values, or zero if the option accepts continuous values
* \param[out] def Default value of the option
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_device_option_range_ex(rs_device * device, rs_option option, double * min, double * max, double * step, double * def, rs_error ** error);
/**
* \brief Efficiently retrieves the value of an arbitrary number of options, using minimal hardware IO
* \param[in] device Relevant RealSense device
* \param[in] options Array of options that should be queried
* \param[in] count Length of options and values arrays
* \param[out] values Array that receives the values of the queried options
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_get_device_options(rs_device * device, const rs_option * options, unsigned int count, double * values, rs_error ** error);
/**
* \brief Efficiently sets the value of an arbitrary number of options, using minimal hardware IO
* \param[in] device Relevant RealSense device
* \param[in] options Array of options that should be set
* \param[in] count Length of options and values arrays
* \param[in] values Array of values to which the options should be set
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_set_device_options(rs_device * device, const rs_option * options, unsigned int count, const double * values, rs_error ** error);
/**
* \brief Efficiently resets the value of an arbitrary number of options to default
* \param[in] device Relevant RealSense device
* \param[in] options Array of options that should be set to default
* \param[in] count Length of the options array
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_reset_device_options_to_default(rs_device * device, const rs_option* options, int count, rs_error ** error);
/**
* \brief Retrieves the current value of a single option
* \param[in] device Relevant RealSense device
* \param[in] option Option
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Value of the option
*/
double rs_get_device_option(rs_device * device, rs_option option, rs_error ** error);
/**
* \brief Retrieves a static description of what a particular option does on given device
* \param[in] device Relevant RealSense device
* \param[in] option Option
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Value of the option
*/
const char * rs_get_device_option_description(rs_device * device, rs_option option, rs_error ** error);
/**
* \brief Sets the current value of a single option
* \param[in] device Relevant RealSense device
* \param[in] option Option whose value should be set
* \param[in] value Value of the option
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_set_device_option(rs_device * device, rs_option option, double value, rs_error ** error);
/**
* \brief Blocks until new frames are available
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_wait_for_frames(rs_device * device, rs_error ** error);
/**
* \brief Checks if new frames are available, without blocking
* \param[in] device Relevant RealSense device
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return 1 if new frames are available, 0 if no new frames have arrived
*/
int rs_poll_for_frames(rs_device * device, rs_error ** error);
/**
* \brief Determines device capabilities
* \param[in] device Relevant RealSense device
* \param[in] capability Capability to check
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if device has this capability
*/
int rs_supports(rs_device * device, rs_capabilities capability, rs_error ** error);
/**
* \brief Returns true if given camera information parameter is supported by the device
* \param[in] device Relevant RealSense device
* \param[in] info_param Parameter to check
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if the parameter both exists and is well-defined for the specific device
*/
int rs_supports_camera_info(rs_device * device, rs_camera_info info_param, rs_error ** error);
/**
* \brief Retrieves metadata from a frame reference
* \param[in] frame Current frame reference
* \param[in] frame_metadata Metadata
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Metadata value
*/
double rs_get_detached_frame_metadata(const rs_frame_ref * frame, rs_frame_metadata frame_metadata, rs_error ** error);
/**
* \brief Determines device metadata
* \param[in] frame Current frame reference
* \param[in] frame_metadata Metadata
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return true if device has this metadata
*/
int rs_supports_frame_metadata(const rs_frame_ref * frame, rs_frame_metadata frame_metadata, rs_error ** error);
/**
* \brief Retrieves time at which the latest frame on a stream was captured
* \param[in] device Relevant RealSense device
* \param[in] stream Stream whose latest frame is of interest
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Timestamp of the frame, in milliseconds, since the device was started
*/
double rs_get_frame_timestamp(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves frame number
* \param[in] device Relevant RealSense device
* \param[in] stream Stream whose latest frame is of interest
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame number
*/
unsigned long long rs_get_frame_number(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Retrieves the contents of the latest frame on a stream
* \param[in] device Relevant RealSense device
* \param[in] stream Stream whose latest frame is of interest
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Pointer to start of the frame data
*/
const void * rs_get_frame_data(const rs_device * device, rs_stream stream, rs_error ** error);
/**
* \brief Releases frame handle
* \param[in] device Relevant RealSense device
* \param[in] frame Handle returned either detach, clone_ref or from frame callback
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Pointer to start of the frame data
*/
void rs_release_frame(rs_device * device, rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves timestamp from frame reference
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Timestamp of the frame, in milliseconds since the device was started
*/
double rs_get_detached_frame_timestamp(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves timestamp domain from frame reference
* This method is used to check if two timestamp values are comparable (meaning, are generated from the same clock).
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Timestamp domain of the frame (camera/ microcontroller)
*/
rs_timestamp_domain rs_get_detached_frame_timestamp_domain(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame number from frame reference
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame number, in milliseconds since the device was started
*/
unsigned long long rs_get_detached_frame_number(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves data from frame reference
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Pointer to start of the frame data
*/
const void * rs_get_detached_frame_data(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame intrinsic width in pixels
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Intrinsic width
*/
int rs_get_detached_frame_width(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame intrinsic height
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Intrinsic height
*/
int rs_get_detached_frame_height(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame intrinsic frame rate
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Intrinsic frame rate
*/
int rs_get_detached_framerate(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame stride, meaning the actual line width in memory in bytes (not the logical image width)
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame pad crop
*/
int rs_get_detached_frame_stride(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame <b><i>bits</i></b> per pixel
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame pad crop
*/
int rs_get_detached_frame_bpp(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame format
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Frame format
*/
rs_format rs_get_detached_frame_format(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Retrieves frame stream type
* \param[in] frame Current frame reference
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Stream type
*/
rs_stream rs_get_detached_frame_stream_type(const rs_frame_ref * frame, rs_error ** error);
/**
* \brief Sends arbitrary binary data to the device
* \param[in] device Relevant RealSense device
* \param[in] type Type of raw data to send to the device
* \param[in] data Raw data pointer to send
* \param[in] size Size, in bytes of the raw data to send
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
*/
void rs_send_blob_to_device(rs_device * device, rs_blob_type type, void * data, int size, rs_error ** error);
/**
* \brief Retrieves API version from the source code. Evaluate that the value is conformant to the established policies
* \param[out] error If non-null, receives any error that occurs during this call, otherwise, errors are ignored.
* \return Version API encoded into integer value. For example: "1.9.3" becomes "10903".
*/
int rs_get_api_version (rs_error ** error);