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

   1 .. -*- coding: utf-8; mode: rst -*-
   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 or frame capture parameters supplied by the image source. This interface is
  12 intended for transfer of metadata to userspace and control of that operation.
  13
  14 The metadata interface is implemented on video capture device nodes. The device
  15 can be dedicated to metadata or can implement both video and metadata capture
  16 as specified in its reported capabilities.
  17
  18 Querying Capabilities
  19 =====================
  20
  21 Device nodes supporting the metadata interface set the ``V4L2_CAP_META_CAPTURE``
  22 flag in the ``device_caps`` field of the
  23 :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
  24 ioctl. That flag means the device can capture metadata to memory.
  25
  26 At least one of the read/write or streaming I/O methods must be supported.
  27
  28
  29 Data Format Negotiation
  30 =======================
  31
  32 The metadata device uses the :ref:`format` ioctls to select the capture format.
  33 The metadata buffer content format is bound to that selected format. In addition
  34 to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
  35 supported as well.
  36
  37 To use the :ref:`format` ioctls applications set the ``type`` field of the
  38 :c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` and use the
  39 :c:type:`v4l2_meta_format` ``meta`` member of the ``fmt`` union as needed per
  40 the desired operation. Both drivers and applications must set the remainder of
  41 the :c:type:`v4l2_format` structure to 0.
  42
  43 .. _v4l2-meta-format:
  44
  45 .. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}|
  46
  47 .. flat-table:: struct v4l2_meta_format
  48     :header-rows:  0
  49     :stub-columns: 0
  50     :widths:       1 1 2
  51
  52     * - __u32
  53       - ``dataformat``
  54       - The data format, set by the application. This is a little endian
  55         :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
  56         in :ref:`meta-formats`.
  57     * - __u32
  58       - ``buffersize``
  59       - Maximum buffer size in bytes required for data. The value is set by the
  60         driver.