Commit | Line | Data |
---|---|---|
82559ac0 MCC |
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 | ||
fb9ffa6a LP |
10 | .. _metadata: |
11 | ||
12 | ****************** | |
13 | Metadata Interface | |
14 | ****************** | |
15 | ||
16 | Metadata refers to any non-image data that supplements video frames with | |
934a040b SA |
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. | |
fb9ffa6a | 22 | |
934a040b SA |
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. | |
fb9ffa6a LP |
26 | |
27 | Querying Capabilities | |
28 | ===================== | |
29 | ||
934a040b SA |
30 | Device nodes supporting the metadata capture interface set the |
31 | ``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the | |
fb9ffa6a | 32 | :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP` |
934a040b SA |
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. | |
fb9ffa6a LP |
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 | |
934a040b SA |
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. | |
fb9ffa6a | 56 | |
003aedae | 57 | .. c:type:: v4l2_meta_format |
fb9ffa6a | 58 | |
70b074df MCC |
59 | .. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| |
60 | ||
fb9ffa6a LP |
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. |