1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
3 .. _v4l2-meta-fmt-d4xx:
5 *******************************
6 V4L2_META_FMT_D4XX ('D4XX')
7 *******************************
9 Intel D4xx UVC Cameras Metadata
15 Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
16 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
17 means, that the private D4XX metadata, following the standard UVC header, is
18 organised in blocks. D4XX cameras implement several standard block types,
19 proposed by Microsoft, and several proprietary ones. Supported standard metadata
20 types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
21 and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
22 document describes proprietary metadata types, used by D4xx cameras.
24 V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
25 V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
26 payload header data. D4xx cameras use bulk transfers and only send one payload
27 per frame, therefore their headers cannot be larger than 255 bytes.
29 This document implements Intel Configuration version 3 [9_].
31 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
32 where all fields are in little endian order:
34 .. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
37 .. flat-table:: D4xx metadata
44 * - :cspan:`1` *Depth Control*
48 - Size in bytes, include ID (all protocol versions: 60)
50 - Version of this structure. The documentation herein covers versions 1,
51 2 and 3. The version number will be incremented when new fields are
54 - A bitmask of flags: see [2_] below
56 - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
59 - Exposure time (in microseconds) used to capture the frame
61 - Power of the laser LED 0-360, used for depth measurement
63 - 0: manual; 1: automatic exposure
64 * - __u32 Exposure priority
65 - Exposure priority value: 0 - constant frame rate
67 - Left border of the AE Region of Interest (all ROI values are in pixels
68 and lie between 0 and maximum width or height respectively)
69 * - __u32 AE ROI right
70 - Right border of the AE Region of Interest
72 - Top border of the AE Region of Interest
73 * - __u32 AE ROI bottom
74 - Bottom border of the AE Region of Interest
76 - Preset selector value, default: 0, unless changed by the user
77 * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
78 - 0: off, 1: on, same as __u32 Laser mode for v1
79 * - __u8 RFU byte (v3 only)
80 - Spare byte for future use
81 * - __u16 LED Power (v3 only)
82 - Led power value 0-360 (F416 SKU)
83 * - :cspan:`1` *Capture Timing*
87 - Size in bytes, include ID (all protocol versions: 40)
89 - Version of this structure. The documentation herein corresponds to
90 version xxx. The version number will be incremented when new fields are
93 - A bitmask of flags: see [3_] below
94 * - __u32 Frame counter
95 - Monotonically increasing counter
96 * - __u32 Optical time
97 - Time in microseconds from the beginning of a frame till its middle
98 * - __u32 Readout time
99 - Time, used to read out a frame in microseconds
100 * - __u32 Exposure time
101 - Frame exposure time in microseconds
102 * - __u32 Frame interval
103 - In microseconds = 1000000 / framerate
104 * - __u32 Pipe latency
105 - Time in microseconds from start of frame to data in USB buffer
106 * - :cspan:`1` *Configuration*
110 - Size in bytes, include ID (v1:36, v3:40)
112 - Version of this structure. The documentation herein corresponds to
113 version xxx. The version number will be incremented when new fields are
116 - A bitmask of flags: see [4_] below
117 * - __u8 Hardware type
118 - Camera hardware version [5_]
120 - Camera hardware configuration [6_]
122 - Internal synchronisation
124 - Image format code [7_]
130 - Requested frame rate per second
132 - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
133 * - __u16 Calibration count (v3 only)
134 - Calibration counter, see [4_] below
135 * - __u8 GPIO input data (v3 only)
136 - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
137 * - __u32 Sub-preset info (v3 only)
138 - Sub-preset choice information, see [4_] below
139 * - __u8 reserved (v3 only)
144 [1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
148 [2] Depth Control flags specify which fields are valid: ::
152 0x00000004 Laser power
154 0x00000010 Exposure priority
157 0x00000080 Emitter mode
162 [3] Capture Timing flags specify which fields are valid: ::
164 0x00000001 Frame counter
165 0x00000002 Optical time
166 0x00000004 Readout time
167 0x00000008 Exposure time
168 0x00000010 Frame interval
169 0x00000020 Pipe latency
173 [4] Configuration flags specify which fields are valid: ::
175 0x00000001 Hardware type
184 0x00000200 GPIO Input Data
185 0x00000400 Sub-preset Info
196 [6] 8-bit camera hardware configuration bitfield: ::
203 [2] depthIsActive - has a laser projector
205 [4] Inertial Measurement Unit (IMU) presence
209 [6] 0: a projector, 1: an LED
214 [7] Image format codes per video streaming interface:
235 [8] The "Laser mode" has been replaced in version 3 by three different fields.
236 "Laser" has been renamed to "Emitter" as there are multiple technologies for
237 camera projectors. As we have another field for "Laser Power" we introduced
238 "LED Power" for extra emitter.
240 The "Laser mode" __u32 fields has been split into: ::
245 This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward
246 compatible with the same data format and they are supported. See [2_] for which
247 attributes are valid.
251 [9] LibRealSense SDK metadata source:
252 https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h