0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _metadata:
0004
0005 ******************
0006 Metadata Interface
0007 ******************
0008
0009 Metadata refers to any non-image data that supplements video frames with
0010 additional information. This may include statistics computed over the image,
0011 frame capture parameters supplied by the image source or device specific
0012 parameters for specifying how the device processes images. This interface is
0013 intended for transfer of metadata between the userspace and the hardware and
0014 control of that operation.
0015
0016 The metadata interface is implemented on video device nodes. The device can be
0017 dedicated to metadata or can support both video and metadata as specified in its
0018 reported capabilities.
0019
0020 Querying Capabilities
0021 =====================
0022
0023 Device nodes supporting the metadata capture interface set the
0024 ``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the
0025 :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
0026 ioctl. That flag means the device can capture metadata to memory. Similarly,
0027 device nodes supporting metadata output interface set the
0028 ``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of
0029 :c:type:`v4l2_capability` structure. That flag means the device can read
0030 metadata from memory.
0031
0032 At least one of the read/write or streaming I/O methods must be supported.
0033
0034
0035 Data Format Negotiation
0036 =======================
0037
0038 The metadata device uses the :ref:`format` ioctls to select the capture format.
0039 The metadata buffer content format is bound to that selected format. In addition
0040 to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
0041 supported as well.
0042
0043 To use the :ref:`format` ioctls applications set the ``type`` field of the
0044 :c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to
0045 ``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta``
0046 member of the ``fmt`` union as needed per the desired operation. Both drivers
0047 and applications must set the remainder of the :c:type:`v4l2_format` structure
0048 to 0.
0049
0050 .. c:type:: v4l2_meta_format
0051
0052 .. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}|
0053
0054 .. flat-table:: struct v4l2_meta_format
0055 :header-rows: 0
0056 :stub-columns: 0
0057 :widths: 1 1 2
0058
0059 * - __u32
0060 - ``dataformat``
0061 - The data format, set by the application. This is a little endian
0062 :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
0063 in :ref:`meta-formats`.
0064 * - __u32
0065 - ``buffersize``
0066 - Maximum buffer size in bytes required for data. The value is set by the
0067 driver.
