Documentation/media/uapi/v4l/dev-meta.rst

   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/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _metadata:
  11
  12 ******************
  13 Metadata Interface
  14 ******************
  15
  16 Metadata refers to any non-image data that supplements video frames with
  17 additional information. This may include statistics computed over the image,
  18 frame capture parameters supplied by the image source or device specific
  19 parameters for specifying how the device processes images. This interface is
  20 intended for transfer of metadata between the userspace and the hardware and
  21 control of that operation.
  22
  23 The metadata interface is implemented on video device nodes. The device can be
  24 dedicated to metadata or can support both video and metadata as specified in its
  25 reported capabilities.
  26
  27 Querying Capabilities
  28 =====================
  29
  30 Device 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`
  33 ioctl. That flag means the device can capture metadata to memory. Similarly,
  34 device 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
  37 metadata from memory.
  38
  39 At least one of the read/write or streaming I/O methods must be supported.
  40
  41
  42 Data Format Negotiation
  43 =======================
  44
  45 The metadata device uses the :ref:`format` ioctls to select the capture format.
  46 The metadata buffer content format is bound to that selected format. In addition
  47 to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
  48 supported as well.
  49
  50 To 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``
  53 member of the ``fmt`` union as needed per the desired operation. Both drivers
  54 and applications must set the remainder of the :c:type:`v4l2_format` structure
  55 to 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.