Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 .. _v4l2-meta-fmt-d4xx:
   4
   5 *******************************
   6 V4L2_META_FMT_D4XX ('D4XX')
   7 *******************************
   8
   9 Intel D4xx UVC Cameras Metadata
  10
  11
  12 Description
  13 ===========
  14
  15 Intel D4xx (D435 and other) 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.
  23
  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.
  28
  29 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
  30 where 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
 198 Depth: ::
 199
 200   1 Z16
 201   2 Z
 202
 203 Left sensor: ::
 204
 205   1 Y8
 206   2 UYVY
 207   3 R8L8
 208   4 Calibration
 209   5 W10
 210
 211 Fish Eye sensor: ::
 212
 213   1 RAW8