1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _metadata:
4
5******************
6Metadata Interface
7******************
8
9Metadata refers to any non-image data that supplements video frames with
10additional information. This may include statistics computed over the image,
11frame capture parameters supplied by the image source or device specific
12parameters for specifying how the device processes images. This interface is
13intended for transfer of metadata between the userspace and the hardware and
14control of that operation.
15
16The metadata interface is implemented on video device nodes. The device can be
17dedicated to metadata or can support both video and metadata as specified in its
18reported capabilities.
19
20Querying Capabilities
21=====================
22
23Device nodes supporting the metadata capture interface set the
24``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the
25:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
26ioctl. That flag means the device can capture metadata to memory. Similarly,
27device nodes supporting metadata output interface set the
28``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of
29:c:type:`v4l2_capability` structure. That flag means the device can read
30metadata from memory.
31
32At least one of the read/write or streaming I/O methods must be supported.
33
34
35Data Format Negotiation
36=======================
37
38The metadata device uses the :ref:`format` ioctls to select the capture format.
39The metadata buffer content format is bound to that selected format. In addition
40to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
41supported as well.
42
43To use the :ref:`format` ioctls applications set the ``type`` field of the
44:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to
45``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta``
46member of the ``fmt`` union as needed per the desired operation. Both drivers
47and applications must set the remainder of the :c:type:`v4l2_format` structure
48to 0.
49
50.. c:type:: v4l2_meta_format
51
52.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}|
53
54.. flat-table:: struct v4l2_meta_format
55    :header-rows:  0
56    :stub-columns: 0
57    :widths:       1 1 2
58
59    * - __u32
60      - ``dataformat``
61      - The data format, set by the application. This is a little endian
62        :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
63        in :ref:`meta-formats`.
64    * - __u32
65      - ``buffersize``
66      - Maximum buffer size in bytes required for data. The value is set by the
67        driver.
68