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