summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/userspace-api/media/v4l/metafmt-d4xx.rst')
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-d4xx.rst252
1 files changed, 252 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst
new file mode 100644
index 000000000000..541836074f94
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst
@@ -0,0 +1,252 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _v4l2-meta-fmt-d4xx:
+
+*******************************
+V4L2_META_FMT_D4XX ('D4XX')
+*******************************
+
+Intel D4xx UVC Cameras Metadata
+
+
+Description
+===========
+
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
+payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
+means, that the private D4XX metadata, following the standard UVC header, is
+organised in blocks. D4XX cameras implement several standard block types,
+proposed by Microsoft, and several proprietary ones. Supported standard metadata
+types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
+and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
+document describes proprietary metadata types, used by D4xx cameras.
+
+V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
+V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
+payload header data. D4xx cameras use bulk transfers and only send one payload
+per frame, therefore their headers cannot be larger than 255 bytes.
+
+This document implements Intel Configuration version 3 [9_].
+
+Below are proprietary Microsoft style metadata types, used by D4xx cameras,
+where all fields are in little endian order:
+
+.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
+
+
+.. flat-table:: D4xx metadata
+ :widths: 1 2
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - **Field**
+ - **Description**
+ * - :cspan:`1` *Depth Control*
+ * - __u32 ID
+ - 0x80000000
+ * - __u32 Size
+ - Size in bytes, include ID (all protocol versions: 60)
+ * - __u32 Version
+ - Version of this structure. The documentation herein covers versions 1,
+ 2 and 3. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [2_] below
+ * - __u32 Gain
+ - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
+ capture the frame
+ * - __u32 Exposure
+ - Exposure time (in microseconds) used to capture the frame
+ * - __u32 Laser power
+ - Power of the laser LED 0-360, used for depth measurement
+ * - __u32 AE mode
+ - 0: manual; 1: automatic exposure
+ * - __u32 Exposure priority
+ - Exposure priority value: 0 - constant frame rate
+ * - __u32 AE ROI left
+ - Left border of the AE Region of Interest (all ROI values are in pixels
+ and lie between 0 and maximum width or height respectively)
+ * - __u32 AE ROI right
+ - Right border of the AE Region of Interest
+ * - __u32 AE ROI top
+ - Top border of the AE Region of Interest
+ * - __u32 AE ROI bottom
+ - Bottom border of the AE Region of Interest
+ * - __u32 Preset
+ - Preset selector value, default: 0, unless changed by the user
+ * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+ - 0: off, 1: on, same as __u32 Laser mode for v1
+ * - __u8 RFU byte (v3 only)
+ - Spare byte for future use
+ * - __u16 LED Power (v3 only)
+ - Led power value 0-360 (F416 SKU)
+ * - :cspan:`1` *Capture Timing*
+ * - __u32 ID
+ - 0x80000001
+ * - __u32 Size
+ - Size in bytes, include ID (all protocol versions: 40)
+ * - __u32 Version
+ - Version of this structure. The documentation herein corresponds to
+ version xxx. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [3_] below
+ * - __u32 Frame counter
+ - Monotonically increasing counter
+ * - __u32 Optical time
+ - Time in microseconds from the beginning of a frame till its middle
+ * - __u32 Readout time
+ - Time, used to read out a frame in microseconds
+ * - __u32 Exposure time
+ - Frame exposure time in microseconds
+ * - __u32 Frame interval
+ - In microseconds = 1000000 / framerate
+ * - __u32 Pipe latency
+ - Time in microseconds from start of frame to data in USB buffer
+ * - :cspan:`1` *Configuration*
+ * - __u32 ID
+ - 0x80000002
+ * - __u32 Size
+ - Size in bytes, include ID (v1:36, v3:40)
+ * - __u32 Version
+ - Version of this structure. The documentation herein corresponds to
+ version xxx. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [4_] below
+ * - __u8 Hardware type
+ - Camera hardware version [5_]
+ * - __u8 SKU ID
+ - Camera hardware configuration [6_]
+ * - __u32 Cookie
+ - Internal synchronisation
+ * - __u16 Format
+ - Image format code [7_]
+ * - __u16 Width
+ - Width in pixels
+ * - __u16 Height
+ - Height in pixels
+ * - __u16 Framerate
+ - Requested frame rate per second
+ * - __u16 Trigger
+ - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+ * - __u16 Calibration count (v3 only)
+ - Calibration counter, see [4_] below
+ * - __u8 GPIO input data (v3 only)
+ - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+ * - __u32 Sub-preset info (v3 only)
+ - Sub-preset choice information, see [4_] below
+ * - __u8 reserved (v3 only)
+ - RFU byte.
+
+.. _1:
+
+[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
+
+.. _2:
+
+[2] Depth Control flags specify which fields are valid: ::
+
+ 0x00000001 Gain
+ 0x00000002 Exposure
+ 0x00000004 Laser power
+ 0x00000008 AE mode
+ 0x00000010 Exposure priority
+ 0x00000020 AE ROI
+ 0x00000040 Preset
+ 0x00000080 Emitter mode
+ 0x00000100 LED Power
+
+.. _3:
+
+[3] Capture Timing flags specify which fields are valid: ::
+
+ 0x00000001 Frame counter
+ 0x00000002 Optical time
+ 0x00000004 Readout time
+ 0x00000008 Exposure time
+ 0x00000010 Frame interval
+ 0x00000020 Pipe latency
+
+.. _4:
+
+[4] Configuration flags specify which fields are valid: ::
+
+ 0x00000001 Hardware type
+ 0x00000002 SKU ID
+ 0x00000004 Cookie
+ 0x00000008 Format
+ 0x00000010 Width
+ 0x00000020 Height
+ 0x00000040 Framerate
+ 0x00000080 Trigger
+ 0x00000100 Cal count
+ 0x00000200 GPIO Input Data
+ 0x00000400 Sub-preset Info
+
+.. _5:
+
+[5] Camera model: ::
+
+ 0 DS5
+ 1 IVCAM2
+
+.. _6:
+
+[6] 8-bit camera hardware configuration bitfield: ::
+
+ [1:0] depthCamera
+ 00: no depth
+ 01: standard depth
+ 10: wide depth
+ 11: reserved
+ [2] depthIsActive - has a laser projector
+ [3] RGB presence
+ [4] Inertial Measurement Unit (IMU) presence
+ [5] projectorType
+ 0: HPTG
+ 1: Princeton
+ [6] 0: a projector, 1: an LED
+ [7] reserved
+
+.. _7:
+
+[7] Image format codes per video streaming interface:
+
+Depth: ::
+
+ 1 Z16
+ 2 Z
+
+Left sensor: ::
+
+ 1 Y8
+ 2 UYVY
+ 3 R8L8
+ 4 Calibration
+ 5 W10
+
+Fish Eye sensor: ::
+
+ 1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" has been replaced in version 3 by three different fields.
+"Laser" has been renamed to "Emitter" as there are multiple technologies for
+camera projectors. As we have another field for "Laser Power" we introduced
+"LED Power" for extra emitter.
+
+The "Laser mode" __u32 fiels has been split into: ::
+ 1 __u8 Emitter mode
+ 2 __u8 RFU byte
+ 3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward
+compatible with the same data format and they are supported. See [2_] for which
+attributes are valid.
+
+.. _9:
+
+[9] LibRealSense SDK metadata source:
+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h