1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _metadata: 5 6****************** 7Metadata Interface 8****************** 9 10Metadata refers to any non-image data that supplements video frames with 11additional information. This may include statistics computed over the image, 12frame capture parameters supplied by the image source or device specific 13parameters for specifying how the device processes images. This interface is 14intended for transfer of metadata between the userspace and the hardware and 15control of that operation. 16 17The metadata interface is implemented on video device nodes. The device can be 18dedicated to metadata or can support both video and metadata as specified in its 19reported capabilities. 20 21Querying Capabilities 22===================== 23 24Device nodes supporting the metadata capture interface set the 25``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the 26:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP` 27ioctl. That flag means the device can capture metadata to memory. Similarly, 28device nodes supporting metadata output interface set the 29``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of 30:c:type:`v4l2_capability` structure. That flag means the device can read 31metadata from memory. 32 33At least one of the read/write or streaming I/O methods must be supported. 34 35 36Data Format Negotiation 37======================= 38 39The metadata device uses the :ref:`format` ioctls to select the capture format. 40The metadata buffer content format is bound to that selected format. In addition 41to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be 42supported as well. 43 44To use the :ref:`format` ioctls applications set the ``type`` field of the 45:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to 46``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta`` 47member of the ``fmt`` union as needed per the desired operation. Both drivers 48and applications must set the remainder of the :c:type:`v4l2_format` structure 49to 0. 50 51Devices that capture metadata by line have the struct v4l2_fmtdesc 52``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for :c:func:`VIDIOC_ENUM_FMT`. Such 53devices can typically also :ref:`capture image data <capture>`. This primarily 54involves devices that receive the data from a different devices such as a camera 55sensor. 56 57.. c:type:: v4l2_meta_format 58 59.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| 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 * - __u32 76 - ``width`` 77 - Width of a line of metadata in Data Units. Valid when 78 :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, 79 otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. 80 * - __u32 81 - ``height`` 82 - Number of rows of metadata. Valid when :c:type`v4l2_fmtdesc` flag 83 ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, otherwise zero. See 84 :c:func:`VIDIOC_ENUM_FMT`. 85 * - __u32 86 - ``bytesperline`` 87 - Offset in bytes between the beginning of two consecutive lines. Valid 88 when :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is 89 set, otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. 90