Documentation/userspace-api/media/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/userspace-api/media/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