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 50Devices that capture metadata by line have the struct v4l2_fmtdesc 51``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for :c:func:`VIDIOC_ENUM_FMT`. Such 52devices can typically also :ref:`capture image data <capture>`. This primarily 53involves devices that receive the data from a different devices such as a camera 54sensor. 55 56.. c:type:: v4l2_meta_format 57 58.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| 59 60.. flat-table:: struct v4l2_meta_format 61 :header-rows: 0 62 :stub-columns: 0 63 :widths: 1 1 2 64 65 * - __u32 66 - ``dataformat`` 67 - The data format, set by the application. This is a little endian 68 :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats 69 in :ref:`meta-formats`. 70 * - __u32 71 - ``buffersize`` 72 - Maximum buffer size in bytes required for data. The value is set by the 73 driver. 74 * - __u32 75 - ``width`` 76 - Width of a line of metadata in Data Units. Valid when 77 :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, 78 otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. 79 * - __u32 80 - ``height`` 81 - Number of rows of metadata. Valid when :c:type`v4l2_fmtdesc` flag 82 ``V4L2_FMT_FLAG_META_LINE_BASED`` is set, otherwise zero. See 83 :c:func:`VIDIOC_ENUM_FMT`. 84 * - __u32 85 - ``bytesperline`` 86 - Offset in bytes between the beginning of two consecutive lines. Valid 87 when :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is 88 set, otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`. 89