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 .. flat-table:: D4xx metadata
  40     :widths: 1 4
  41     :header-rows:  1
  42     :stub-columns: 0
  43
  44     * - Field
  45       - Description
  46     * - :cspan:`1` *Depth Control*
  47     * - __u32 ID
  48       - 0x80000000
  49     * - __u32 Size
  50       - Size in bytes (currently 56)
  51     * - __u32 Version
  52       - Version of this structure. The documentation herein corresponds to
  53         version xxx. The version number will be incremented when new fields are
  54         added.
  55     * - __u32 Flags
  56       - A bitmask of flags: see [2_] below
  57     * - __u32 Gain
  58       - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
  59         capture the frame
  60     * - __u32 Exposure
  61       - Exposure time (in microseconds) used to capture the frame
  62     * - __u32 Laser power
  63       - Power of the laser LED 0-360, used for depth measurement
  64     * - __u32 AE mode
  65       - 0: manual; 1: automatic exposure
  66     * - __u32 Exposure priority
  67       - Exposure priority value: 0 - constant frame rate
  68     * - __u32 AE ROI left
  69       - Left border of the AE Region of Interest (all ROI values are in pixels
  70         and lie between 0 and maximum width or height respectively)
  71     * - __u32 AE ROI right
  72       - Right border of the AE Region of Interest
  73     * - __u32 AE ROI top
  74       - Top border of the AE Region of Interest
  75     * - __u32 AE ROI bottom
  76       - Bottom border of the AE Region of Interest
  77     * - __u32 Preset
  78       - Preset selector value, default: 0, unless changed by the user
  79     * - __u32 Laser mode
  80       - 0: off, 1: on
  81     * - :cspan:`1` *Capture Timing*
  82     * - __u32 ID
  83       - 0x80000001
  84     * - __u32 Size
  85       - Size in bytes (currently 40)
  86     * - __u32 Version
  87       - Version of this structure. The documentation herein corresponds to
  88         version xxx. The version number will be incremented when new fields are
  89         added.
  90     * - __u32 Flags
  91       - A bitmask of flags: see [3_] below
  92     * - __u32 Frame counter
  93       - Monotonically increasing counter
  94     * - __u32 Optical time
  95       - Time in microseconds from the beginning of a frame till its middle
  96     * - __u32 Readout time
  97       - Time, used to read out a frame in microseconds
  98     * - __u32 Exposure time
  99       - Frame exposure time in microseconds
 100     * - __u32 Frame interval
 101       - In microseconds = 1000000 / framerate
 102     * - __u32 Pipe latency
 103       - Time in microseconds from start of frame to data in USB buffer
 104     * - :cspan:`1` *Configuration*
 105     * - __u32 ID
 106       - 0x80000002
 107     * - __u32 Size
 108       - Size in bytes (currently 40)
 109     * - __u32 Version
 110       - Version of this structure. The documentation herein corresponds to
 111         version xxx. The version number will be incremented when new fields are
 112         added.
 113     * - __u32 Flags
 114       - A bitmask of flags: see [4_] below
 115     * - __u8 Hardware type
 116       - Camera hardware version [5_]
 117     * - __u8 SKU ID
 118       - Camera hardware configuration [6_]
 119     * - __u32 Cookie
 120       - Internal synchronisation
 121     * - __u16 Format
 122       - Image format code [7_]
 123     * - __u16 Width
 124       - Width in pixels
 125     * - __u16 Height
 126       - Height in pixels
 127     * - __u16 Framerate
 128       - Requested frame rate per second
 129     * - __u16 Trigger
 130       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
 131
 132 .. _1:
 133
 134 [1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
 135
 136 .. _2:
 137
 138 [2] Depth Control flags specify which fields are valid: ::
 139
 140   0x00000001 Gain
 141   0x00000002 Exposure
 142   0x00000004 Laser power
 143   0x00000008 AE mode
 144   0x00000010 Exposure priority
 145   0x00000020 AE ROI
 146   0x00000040 Preset
 147
 148 .. _3:
 149
 150 [3] Capture Timing flags specify which fields are valid: ::
 151
 152   0x00000001 Frame counter
 153   0x00000002 Optical time
 154   0x00000004 Readout time
 155   0x00000008 Exposure time
 156   0x00000010 Frame interval
 157   0x00000020 Pipe latency
 158
 159 .. _4:
 160
 161 [4] Configuration flags specify which fields are valid: ::
 162
 163   0x00000001 Hardware type
 164   0x00000002 SKU ID
 165   0x00000004 Cookie
 166   0x00000008 Format
 167   0x00000010 Width
 168   0x00000020 Height
 169   0x00000040 Framerate
 170   0x00000080 Trigger
 171   0x00000100 Cal count
 172
 173 .. _5:
 174
 175 [5] Camera model: ::
 176
 177   0 DS5
 178   1 IVCAM2
 179
 180 .. _6:
 181
 182 [6] 8-bit camera hardware configuration bitfield: ::
 183
 184   [1:0] depthCamera
 185         00: no depth
 186         01: standard depth
 187         10: wide depth
 188         11: reserved
 189   [2]   depthIsActive - has a laser projector
 190   [3]   RGB presence
 191   [4]   Inertial Measurement Unit (IMU) presence
 192   [5]   projectorType
 193         0: HPTG
 194         1: Princeton
 195   [6]   0: a projector, 1: an LED
 196   [7]   reserved
 197
 198 .. _7:
 199
 200 [7] Image format codes per video streaming interface:
 201
 202 Depth: ::
 203
 204   1 Z16
 205   2 Z
 206
 207 Left sensor: ::
 208
 209   1 Y8
 210   2 UYVY
 211   3 R8L8
 212   4 Calibration
 213   5 W10
 214
 215 Fish Eye sensor: ::
 216
 217   1 RAW8