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