Documentation/userspace-api/media/v4l/dev-meta.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 .. _metadata:
   4
   5 ******************
   6 Metadata Interface
   7 ******************
   8
   9 Metadata refers to any non-image data that supplements video frames with
  10 additional information. This may include statistics computed over the image,
  11 frame capture parameters supplied by the image source or device specific
  12 parameters for specifying how the device processes images. This interface is
  13 intended for transfer of metadata between the userspace and the hardware and
  14 control of that operation.
  15
  16 The metadata interface is implemented on video device nodes. The device can be
  17 dedicated to metadata or can support both video and metadata as specified in its
  18 reported capabilities.
  19
  20 Querying Capabilities
  21 =====================
  22
  23 Device 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`
  26 ioctl. That flag means the device can capture metadata to memory. Similarly,
  27 device 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
  30 metadata from memory.
  31
  32 At least one of the read/write or streaming I/O methods must be supported.
  33
  34
  35 Data Format Negotiation
  36 =======================
  37
  38 The metadata device uses the :ref:`format` ioctls to select the capture format.
  39 The metadata buffer content format is bound to that selected format. In addition
  40 to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
  41 supported as well.
  42
  43 To 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``
  46 member of the ``fmt`` union as needed per the desired operation. Both drivers
  47 and applications must set the remainder of the :c:type:`v4l2_format` structure
  48 to 0.
  49
  50 .. c:type:: v4l2_meta_format
  51
  52 .. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}|
  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.