Debian Codegraph @

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

raw
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`.