1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 2
3 .. _metadata: 3 .. _metadata:
4 4
5 ****************** 5 ******************
6 Metadata Interface 6 Metadata Interface
7 ****************** 7 ******************
8 8
9 Metadata refers to any non-image data that sup 9 Metadata refers to any non-image data that supplements video frames with
10 additional information. This may include stati 10 additional information. This may include statistics computed over the image,
11 frame capture parameters supplied by the image 11 frame capture parameters supplied by the image source or device specific
12 parameters for specifying how the device proce 12 parameters for specifying how the device processes images. This interface is
13 intended for transfer of metadata between the 13 intended for transfer of metadata between the userspace and the hardware and
14 control of that operation. 14 control of that operation.
15 15
16 The metadata interface is implemented on video 16 The metadata interface is implemented on video device nodes. The device can be
17 dedicated to metadata or can support both vide 17 dedicated to metadata or can support both video and metadata as specified in its
18 reported capabilities. 18 reported capabilities.
19 19
20 Querying Capabilities 20 Querying Capabilities
21 ===================== 21 =====================
22 22
23 Device nodes supporting the metadata capture i 23 Device nodes supporting the metadata capture interface set the
24 ``V4L2_CAP_META_CAPTURE`` flag in the ``device 24 ``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the
25 :c:type:`v4l2_capability` structure returned b 25 :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
26 ioctl. That flag means the device can capture 26 ioctl. That flag means the device can capture metadata to memory. Similarly,
27 device nodes supporting metadata output interf 27 device nodes supporting metadata output interface set the
28 ``V4L2_CAP_META_OUTPUT`` flag in the ``device_ 28 ``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of
29 :c:type:`v4l2_capability` structure. That flag 29 :c:type:`v4l2_capability` structure. That flag means the device can read
30 metadata from memory. 30 metadata from memory.
31 31
32 At least one of the read/write or streaming I/ 32 At least one of the read/write or streaming I/O methods must be supported.
33 33
34 34
35 Data Format Negotiation 35 Data Format Negotiation
36 ======================= 36 =======================
37 37
38 The metadata device uses the :ref:`format` ioc 38 The metadata device uses the :ref:`format` ioctls to select the capture format.
39 The metadata buffer content format is bound to 39 The metadata buffer content format is bound to that selected format. In addition
40 to the basic :ref:`format` ioctls, the :c:func 40 to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
41 supported as well. 41 supported as well.
42 42
43 To use the :ref:`format` ioctls applications s 43 To use the :ref:`format` ioctls applications set the ``type`` field of the
44 :c:type:`v4l2_format` structure to ``V4L2_BUF_ 44 :c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to
45 ``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:t 45 ``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta``
46 member of the ``fmt`` union as needed per the 46 member of the ``fmt`` union as needed per the desired operation. Both drivers
47 and applications must set the remainder of the 47 and applications must set the remainder of the :c:type:`v4l2_format` structure
48 to 0. 48 to 0.
49 49
50 Devices that capture metadata by line have the 50 Devices that capture metadata by line have the struct v4l2_fmtdesc
51 ``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for 51 ``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for :c:func:`VIDIOC_ENUM_FMT`. Such
52 devices can typically also :ref:`capture image 52 devices can typically also :ref:`capture image data <capture>`. This primarily
53 involves devices that receive the data from a 53 involves devices that receive the data from a different devices such as a camera
54 sensor. 54 sensor.
55 55
56 .. c:type:: v4l2_meta_format 56 .. c:type:: v4l2_meta_format
57 57
58 .. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5c 58 .. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}|
59 59
60 .. flat-table:: struct v4l2_meta_format 60 .. flat-table:: struct v4l2_meta_format
61 :header-rows: 0 61 :header-rows: 0
62 :stub-columns: 0 62 :stub-columns: 0
63 :widths: 1 1 2 63 :widths: 1 1 2
64 64
65 * - __u32 65 * - __u32
66 - ``dataformat`` 66 - ``dataformat``
67 - The data format, set by the applicatio 67 - The data format, set by the application. This is a little endian
68 :ref:`four character code <v4l2-fourcc 68 :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
69 in :ref:`meta-formats`. 69 in :ref:`meta-formats`.
70 * - __u32 70 * - __u32
71 - ``buffersize`` 71 - ``buffersize``
72 - Maximum buffer size in bytes required 72 - Maximum buffer size in bytes required for data. The value is set by the
73 driver. 73 driver.
74 * - __u32 74 * - __u32
75 - ``width`` 75 - ``width``
76 - Width of a line of metadata in Data Un 76 - Width of a line of metadata in Data Units. Valid when
77 :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_ 77 :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is set,
78 otherwise zero. See :c:func:`VIDIOC_EN 78 otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`.
79 * - __u32 79 * - __u32
80 - ``height`` 80 - ``height``
81 - Number of rows of metadata. Valid when 81 - Number of rows of metadata. Valid when :c:type`v4l2_fmtdesc` flag
82 ``V4L2_FMT_FLAG_META_LINE_BASED`` is s 82 ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, otherwise zero. See
83 :c:func:`VIDIOC_ENUM_FMT`. 83 :c:func:`VIDIOC_ENUM_FMT`.
84 * - __u32 84 * - __u32
85 - ``bytesperline`` 85 - ``bytesperline``
86 - Offset in bytes between the beginning 86 - Offset in bytes between the beginning of two consecutive lines. Valid
87 when :c:type`v4l2_fmtdesc` flag ``V4L2 87 when :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is
88 set, otherwise zero. See :c:func:`VIDI 88 set, otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.