1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _v4l2-meta-fmt-d4xx:
4
5*******************************
6V4L2_META_FMT_D4XX ('D4XX')
7*******************************
8
9Intel D4xx UVC Cameras Metadata
10
11
12Description
13===========
14
15Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
16payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
17means, that the private D4XX metadata, following the standard UVC header, is
18organised in blocks. D4XX cameras implement several standard block types,
19proposed by Microsoft, and several proprietary ones. Supported standard metadata
20types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
21and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
22document describes proprietary metadata types, used by D4xx cameras.
23
24V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
25V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
26payload header data. D4xx cameras use bulk transfers and only send one payload
27per frame, therefore their headers cannot be larger than 255 bytes.
28
29Below are proprietary Microsoft style metadata types, used by D4xx cameras,
30where all fields are in little endian order:
31
32.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
33
34
35.. flat-table:: D4xx metadata
36    :widths: 1 2
37    :header-rows:  1
38    :stub-columns: 0
39
40    * - **Field**
41      - **Description**
42    * - :cspan:`1` *Depth Control*
43    * - __u32 ID
44      - 0x80000000
45    * - __u32 Size
46      - Size in bytes (currently 56)
47    * - __u32 Version
48      - Version of this structure. The documentation herein corresponds to
49        version xxx. The version number will be incremented when new fields are
50        added.
51    * - __u32 Flags
52      - A bitmask of flags: see [2_] below
53    * - __u32 Gain
54      - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
55	capture the frame
56    * - __u32 Exposure
57      - Exposure time (in microseconds) used to capture the frame
58    * - __u32 Laser power
59      - Power of the laser LED 0-360, used for depth measurement
60    * - __u32 AE mode
61      - 0: manual; 1: automatic exposure
62    * - __u32 Exposure priority
63      - Exposure priority value: 0 - constant frame rate
64    * - __u32 AE ROI left
65      - Left border of the AE Region of Interest (all ROI values are in pixels
66	and lie between 0 and maximum width or height respectively)
67    * - __u32 AE ROI right
68      - Right border of the AE Region of Interest
69    * - __u32 AE ROI top
70      - Top border of the AE Region of Interest
71    * - __u32 AE ROI bottom
72      - Bottom border of the AE Region of Interest
73    * - __u32 Preset
74      - Preset selector value, default: 0, unless changed by the user
75    * - __u32 Laser mode
76      - 0: off, 1: on
77    * - :cspan:`1` *Capture Timing*
78    * - __u32 ID
79      - 0x80000001
80    * - __u32 Size
81      - Size in bytes (currently 40)
82    * - __u32 Version
83      - Version of this structure. The documentation herein corresponds to
84        version xxx. The version number will be incremented when new fields are
85        added.
86    * - __u32 Flags
87      - A bitmask of flags: see [3_] below
88    * - __u32 Frame counter
89      - Monotonically increasing counter
90    * - __u32 Optical time
91      - Time in microseconds from the beginning of a frame till its middle
92    * - __u32 Readout time
93      - Time, used to read out a frame in microseconds
94    * - __u32 Exposure time
95      - Frame exposure time in microseconds
96    * - __u32 Frame interval
97      - In microseconds = 1000000 / framerate
98    * - __u32 Pipe latency
99      - Time in microseconds from start of frame to data in USB buffer
100    * - :cspan:`1` *Configuration*
101    * - __u32 ID
102      - 0x80000002
103    * - __u32 Size
104      - Size in bytes (currently 40)
105    * - __u32 Version
106      - Version of this structure. The documentation herein corresponds to
107        version xxx. The version number will be incremented when new fields are
108        added.
109    * - __u32 Flags
110      - A bitmask of flags: see [4_] below
111    * - __u8 Hardware type
112      - Camera hardware version [5_]
113    * - __u8 SKU ID
114      - Camera hardware configuration [6_]
115    * - __u32 Cookie
116      - Internal synchronisation
117    * - __u16 Format
118      - Image format code [7_]
119    * - __u16 Width
120      - Width in pixels
121    * - __u16 Height
122      - Height in pixels
123    * - __u16 Framerate
124      - Requested frame rate per second
125    * - __u16 Trigger
126      - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
127
128.. _1:
129
130[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
131
132.. _2:
133
134[2] Depth Control flags specify which fields are valid: ::
135
136  0x00000001 Gain
137  0x00000002 Exposure
138  0x00000004 Laser power
139  0x00000008 AE mode
140  0x00000010 Exposure priority
141  0x00000020 AE ROI
142  0x00000040 Preset
143
144.. _3:
145
146[3] Capture Timing flags specify which fields are valid: ::
147
148  0x00000001 Frame counter
149  0x00000002 Optical time
150  0x00000004 Readout time
151  0x00000008 Exposure time
152  0x00000010 Frame interval
153  0x00000020 Pipe latency
154
155.. _4:
156
157[4] Configuration flags specify which fields are valid: ::
158
159  0x00000001 Hardware type
160  0x00000002 SKU ID
161  0x00000004 Cookie
162  0x00000008 Format
163  0x00000010 Width
164  0x00000020 Height
165  0x00000040 Framerate
166  0x00000080 Trigger
167  0x00000100 Cal count
168
169.. _5:
170
171[5] Camera model: ::
172
173  0 DS5
174  1 IVCAM2
175
176.. _6:
177
178[6] 8-bit camera hardware configuration bitfield: ::
179
180  [1:0] depthCamera
181	00: no depth
182	01: standard depth
183	10: wide depth
184	11: reserved
185  [2]   depthIsActive - has a laser projector
186  [3]   RGB presence
187  [4]   Inertial Measurement Unit (IMU) presence
188  [5]   projectorType
189	0: HPTG
190	1: Princeton
191  [6]   0: a projector, 1: an LED
192  [7]   reserved
193
194.. _7:
195
196[7] Image format codes per video streaming interface:
197
198Depth: ::
199
200  1 Z16
201  2 Z
202
203Left sensor: ::
204
205  1 Y8
206  2 UYVY
207  3 R8L8
208  4 Calibration
209  5 W10
210
211Fish Eye sensor: ::
212
213  1 RAW8
214