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