0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _v4l2-meta-fmt-d4xx:
0004
0005 *******************************
0006 V4L2_META_FMT_D4XX ('D4XX')
0007 *******************************
0008
0009 Intel D4xx UVC Cameras Metadata
0010
0011
0012 Description
0013 ===========
0014
0015 Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
0016 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
0017 means, that the private D4XX metadata, following the standard UVC header, is
0018 organised in blocks. D4XX cameras implement several standard block types,
0019 proposed by Microsoft, and several proprietary ones. Supported standard metadata
0020 types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
0021 and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
0022 document describes proprietary metadata types, used by D4xx cameras.
0023
0024 V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
0025 V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
0026 payload header data. D4xx cameras use bulk transfers and only send one payload
0027 per frame, therefore their headers cannot be larger than 255 bytes.
0028
0029 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
0030 where all fields are in little endian order:
0031
0032 .. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
0033
0034
0035 .. flat-table:: D4xx metadata
0036 :widths: 1 2
0037 :header-rows: 1
0038 :stub-columns: 0
0039
0040 * - **Field**
0041 - **Description**
0042 * - :cspan:`1` *Depth Control*
0043 * - __u32 ID
0044 - 0x80000000
0045 * - __u32 Size
0046 - Size in bytes (currently 56)
0047 * - __u32 Version
0048 - Version of this structure. The documentation herein corresponds to
0049 version xxx. The version number will be incremented when new fields are
0050 added.
0051 * - __u32 Flags
0052 - A bitmask of flags: see [2_] below
0053 * - __u32 Gain
0054 - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
0055 capture the frame
0056 * - __u32 Exposure
0057 - Exposure time (in microseconds) used to capture the frame
0058 * - __u32 Laser power
0059 - Power of the laser LED 0-360, used for depth measurement
0060 * - __u32 AE mode
0061 - 0: manual; 1: automatic exposure
0062 * - __u32 Exposure priority
0063 - Exposure priority value: 0 - constant frame rate
0064 * - __u32 AE ROI left
0065 - Left border of the AE Region of Interest (all ROI values are in pixels
0066 and lie between 0 and maximum width or height respectively)
0067 * - __u32 AE ROI right
0068 - Right border of the AE Region of Interest
0069 * - __u32 AE ROI top
0070 - Top border of the AE Region of Interest
0071 * - __u32 AE ROI bottom
0072 - Bottom border of the AE Region of Interest
0073 * - __u32 Preset
0074 - Preset selector value, default: 0, unless changed by the user
0075 * - __u32 Laser mode
0076 - 0: off, 1: on
0077 * - :cspan:`1` *Capture Timing*
0078 * - __u32 ID
0079 - 0x80000001
0080 * - __u32 Size
0081 - Size in bytes (currently 40)
0082 * - __u32 Version
0083 - Version of this structure. The documentation herein corresponds to
0084 version xxx. The version number will be incremented when new fields are
0085 added.
0086 * - __u32 Flags
0087 - A bitmask of flags: see [3_] below
0088 * - __u32 Frame counter
0089 - Monotonically increasing counter
0090 * - __u32 Optical time
0091 - Time in microseconds from the beginning of a frame till its middle
0092 * - __u32 Readout time
0093 - Time, used to read out a frame in microseconds
0094 * - __u32 Exposure time
0095 - Frame exposure time in microseconds
0096 * - __u32 Frame interval
0097 - In microseconds = 1000000 / framerate
0098 * - __u32 Pipe latency
0099 - Time in microseconds from start of frame to data in USB buffer
0100 * - :cspan:`1` *Configuration*
0101 * - __u32 ID
0102 - 0x80000002
0103 * - __u32 Size
0104 - Size in bytes (currently 40)
0105 * - __u32 Version
0106 - Version of this structure. The documentation herein corresponds to
0107 version xxx. The version number will be incremented when new fields are
0108 added.
0109 * - __u32 Flags
0110 - A bitmask of flags: see [4_] below
0111 * - __u8 Hardware type
0112 - Camera hardware version [5_]
0113 * - __u8 SKU ID
0114 - Camera hardware configuration [6_]
0115 * - __u32 Cookie
0116 - Internal synchronisation
0117 * - __u16 Format
0118 - Image format code [7_]
0119 * - __u16 Width
0120 - Width in pixels
0121 * - __u16 Height
0122 - Height in pixels
0123 * - __u16 Framerate
0124 - Requested frame rate per second
0125 * - __u16 Trigger
0126 - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
0127
0128 .. _1:
0129
0130 [1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
0131
0132 .. _2:
0133
0134 [2] Depth Control flags specify which fields are valid: ::
0135
0136 0x00000001 Gain
0137 0x00000002 Exposure
0138 0x00000004 Laser power
0139 0x00000008 AE mode
0140 0x00000010 Exposure priority
0141 0x00000020 AE ROI
0142 0x00000040 Preset
0143
0144 .. _3:
0145
0146 [3] Capture Timing flags specify which fields are valid: ::
0147
0148 0x00000001 Frame counter
0149 0x00000002 Optical time
0150 0x00000004 Readout time
0151 0x00000008 Exposure time
0152 0x00000010 Frame interval
0153 0x00000020 Pipe latency
0154
0155 .. _4:
0156
0157 [4] Configuration flags specify which fields are valid: ::
0158
0159 0x00000001 Hardware type
0160 0x00000002 SKU ID
0161 0x00000004 Cookie
0162 0x00000008 Format
0163 0x00000010 Width
0164 0x00000020 Height
0165 0x00000040 Framerate
0166 0x00000080 Trigger
0167 0x00000100 Cal count
0168
0169 .. _5:
0170
0171 [5] Camera model: ::
0172
0173 0 DS5
0174 1 IVCAM2
0175
0176 .. _6:
0177
0178 [6] 8-bit camera hardware configuration bitfield: ::
0179
0180 [1:0] depthCamera
0181 00: no depth
0182 01: standard depth
0183 10: wide depth
0184 11: reserved
0185 [2] depthIsActive - has a laser projector
0186 [3] RGB presence
0187 [4] Inertial Measurement Unit (IMU) presence
0188 [5] projectorType
0189 0: HPTG
0190 1: Princeton
0191 [6] 0: a projector, 1: an LED
0192 [7] reserved
0193
0194 .. _7:
0195
0196 [7] Image format codes per video streaming interface:
0197
0198 Depth: ::
0199
0200 1 Z16
0201 2 Z
0202
0203 Left sensor: ::
0204
0205 1 Y8
0206 2 UYVY
0207 3 R8L8
0208 4 Calibration
0209 5 W10
0210
0211 Fish Eye sensor: ::
0212
0213 1 RAW8
