Metadata 인터페이스

Metadata 전송과 capability

metadata는 비디오 frame을 추가 정보로 보완하는 모든 비영상 데이터를 뜻합니다. 영상에서 계산한 통계, image source가 제공하는 frame capture parameter, 장치가 영상을 처리하는 방식을 지정하는 device-specific parameter 등이 포함됩니다.

이 인터페이스는 userspace와 hardware 사이에서 metadata를 전송하고 그 동작을 제어하기 위한 것입니다. video device node가 metadata 전용일 수도 있고, 보고된 capability에 따라 video와 metadata를 함께 지원할 수도 있습니다.

metadata capture를 지원하는 node는 `VIDIOC_QUERYCAP`이 반환하는 `struct v4l2_capability.device_caps`에 `V4L2_CAP_META_CAPTURE`를 설정합니다. 이는 장치가 metadata를 memory로 capture할 수 있다는 뜻입니다.

metadata output을 지원하는 node는 같은 필드에 `V4L2_CAP_META_OUTPUT`을 설정하며, 이는 장치가 memory에서 metadata를 읽을 수 있다는 뜻입니다. read/write 또는 streaming I/O 방식 중 적어도 하나를 지원해야 합니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _metadata:

******************
Metadata Interface
******************

Metadata refers to any non-image data that supplements video frames with
additional information. This may include statistics computed over the image,
frame capture parameters supplied by the image source or device specific
parameters for specifying how the device processes images. This interface is
intended for transfer of metadata between the userspace and the hardware and
control of that operation.

The metadata interface is implemented on video device nodes. The device can be
dedicated to metadata or can support both video and metadata as specified in its
reported capabilities.

Querying Capabilities
=====================

Device nodes supporting the metadata capture interface set the
``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the
:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
ioctl. That flag means the device can capture metadata to memory. Similarly,
device nodes supporting metadata output interface set the
``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of
:c:type:`v4l2_capability` structure. That flag means the device can read
metadata from memory.

At least one of the read/write or streaming I/O methods must be supported.

Metadata format 협상과 line-based flag

metadata 장치는 format ioctl로 capture format을 선택하며 metadata buffer 내용의 형식은 이 선택에 묶입니다. 기본 format ioctl뿐 아니라 `VIDIOC_ENUM_FMT`도 반드시 지원해야 합니다.

format ioctl을 사용할 때 애플리케이션은 `struct v4l2_format.type`을 `V4L2_BUF_TYPE_META_CAPTURE` 또는 `V4L2_BUF_TYPE_META_OUTPUT`으로 설정하고, 원하는 동작에 따라 `fmt` union의 `struct v4l2_meta_format meta` 멤버를 사용합니다. driver와 애플리케이션 모두 v4l2_format 구조체의 나머지를 0으로 설정해야 합니다.

line 단위로 metadata를 capture하는 장치는 `VIDIOC_ENUM_FMT`의 `struct v4l2_fmtdesc`에 `V4L2_FMT_FLAG_META_LINE_BASED` flag를 설정합니다. 이런 장치는 보통 image data도 함께 capture할 수 있으며, camera sensor 같은 다른 장치에서 데이터를 받는 유형이 주 대상입니다.

Data Format Negotiation
=======================

The metadata device uses the :ref:`format` ioctls to select the capture format.
The metadata buffer content format is bound to that selected format. In addition
to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
supported as well.

To use the :ref:`format` ioctls applications set the ``type`` field of the
:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to
``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta``
member of the ``fmt`` union as needed per the desired operation. Both drivers
and applications must set the remainder of the :c:type:`v4l2_format` structure
to 0.

Devices that capture metadata by line have the struct v4l2_fmtdesc
``V4L2_FMT_FLAG_META_LINE_BASED`` flag set for :c:func:`VIDIOC_ENUM_FMT`. Such
devices can typically also :ref:`capture image data <capture>`. This primarily
involves devices that receive the data from a different devices such as a camera
sensor.

struct v4l2_meta_format

`struct v4l2_meta_format`은 metadata fourcc, 필요한 최대 buffer 크기와 line-based layout을 표현합니다.

.. c:type:: v4l2_meta_format

.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}|

.. flat-table:: struct v4l2_meta_format
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``dataformat``
      - The data format, set by the application. This is a little endian
        :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
        in :ref:`meta-formats`.
    * - __u32
      - ``buffersize``
      - Maximum buffer size in bytes required for data. The value is set by the
        driver.
    * - __u32
      - ``width``
      - Width of a line of metadata in Data Units. Valid when
	:c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is set,
	otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`.
    * - __u32
      - ``height``
      - Number of rows of metadata. Valid when :c:type`v4l2_fmtdesc` flag
	``V4L2_FMT_FLAG_META_LINE_BASED`` is set, otherwise zero. See
	:c:func:`VIDIOC_ENUM_FMT`.
    * - __u32
      - ``bytesperline``
      - Offset in bytes between the beginning of two consecutive lines. Valid
	when :c:type`v4l2_fmtdesc` flag ``V4L2_FMT_FLAG_META_LINE_BASED`` is
	set, otherwise zero. See :c:func:`VIDIOC_ENUM_FMT`.