VIDIOC_G_ENC_INDEX ioctl

목적, 호출 형식과 인자

`VIDIOC_G_ENC_INDEX`는 압축 비디오 스트림의 메타데이터를 가져오는 ioctl입니다. 압축 데이터를 직접 디코딩하지 않고도 그림 경계와 시간 정보를 이용해 스트림의 특정 지점으로 임의 접근할 때 사용합니다.

호출 형식은 `int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)`입니다. `fd`는 `open()`이 반환한 파일 디스크립터이고, `argp`는 드라이버가 인덱스 결과를 채울 `struct v4l2_enc_idx`를 가리킵니다.

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

.. _VIDIOC_G_ENC_INDEX:

************************
ioctl VIDIOC_G_ENC_INDEX
************************

Name
====

VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream

Synopsis
========

.. c:macro:: VIDIOC_G_ENC_INDEX

``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_enc_idx`.

인덱스 읽기, 버퍼와 지원 범위

이 ioctl은 현재 같은 애플리케이션 또는 다른 애플리케이션이 드라이버에서 읽고 있는 압축 비디오 스트림에 관한 메타데이터를 제공합니다. 따라서 스트림 소비 주체와 인덱스 소비 주체가 반드시 같을 필요는 없습니다.

애플리케이션이 `v4l2_enc_idx` 포인터로 호출하면, 성공 시 드라이버가 `entry` 배열을 채우고 기록한 원소 수를 `entries`에 저장하며 내부 인덱스 버퍼 용량을 `entries_cap`에 설정합니다.

`entry`의 각 원소는 한 picture의 메타데이터입니다. 한 호출은 드라이버 버퍼에서 최대 `V4L2_ENC_IDX_ENTRIES`개를 읽습니다. 드라이버가 보관할 수 있는 총 항목 수 `entries_cap`은 이 상수보다 작거나 클 수 있지만 0일 수는 없습니다.

애플리케이션이 메타데이터를 제때 읽지 않으면 가장 오래된 항목부터 유실됩니다. 버퍼가 비어 있거나 캡처·인코딩이 진행 중이 아니면 오류 대신 `entries = 0`으로 돌아옵니다.

현재 이 ioctl은 MPEG-2 program stream과 MPEG-2 video elementary stream에 대해서만 정의되어 있습니다. 다른 컨테이너나 코덱 스트림에 같은 의미가 자동으로 보장되지는 않습니다.

Description
===========

The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
video stream the same or another application currently reads from the
driver, which is useful for random access into the stream without
decoding it.

To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
pointer to a struct :c:type:`v4l2_enc_idx`. On success
the driver fills the ``entry`` array, stores the number of elements
written in the ``entries`` field, and initializes the ``entries_cap``
field.

Each element of the ``entry`` array contains meta data about one
picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
to ``entries_cap`` entries. This number can be lower or higher than
``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
read the meta data in time the oldest entries will be lost. When the
buffer is empty or no capturing/encoding is in progress, ``entries``
will be zero.

Currently this ioctl is only defined for MPEG-2 program streams and
video elementary streams.

struct v4l2_enc_idx

`entries`는 이번 호출에서 유효한 배열 원소의 개수이고 `entries_cap`은 드라이버 내부 큐의 전체 보관 능력입니다. 두 값을 혼동하면 배열 범위를 잘못 해석하거나 큐 유실 위험을 잘못 추정할 수 있습니다.

`entry` 배열은 각 원소의 `offset`이 작은 것부터 큰 순서로 정렬됩니다. 애플리케이션은 `entries`까지만 읽어야 하며 배열의 나머지 슬롯을 유효한 결과로 간주하면 안 됩니다.

.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}|

.. c:type:: v4l2_enc_idx

.. flat-table:: struct v4l2_enc_idx
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 3 8

    * - __u32
      - ``entries``
      - The number of entries the driver stored in the ``entry`` array.
    * - __u32
      - ``entries_cap``
      - The number of entries the driver can buffer. Must be greater than
	zero.
    * - __u32
      - ``reserved``\ [4]
      - Reserved for future extensions. Drivers must set the
	array to zero.
    * - struct :c:type:`v4l2_enc_idx_entry`
      - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
      - Meta data about a compressed video stream. Each element of the
	array corresponds to one picture, sorted in ascending order by
	their ``offset``.

struct v4l2_enc_idx_entry

`offset`은 압축 비디오 스트림의 시작을 기준으로 계산합니다. MPEG-2 program stream에서는 MPEG-2 Part 1의 PES packet header 시작, video elementary stream에서는 MPEG-2 Part 2의 picture header 시작을 가리킵니다.

인코더가 정지하면 드라이버는 `offset`을 0으로 재설정합니다. 따라서 여러 인코딩 세션의 인덱스를 결합할 때는 세션 경계를 별도로 관리해야 합니다.

`pts`는 33비트 Presentation Time Stamp이지만 저장 필드는 `__u64`입니다. `length`로 그림의 바이트 범위를 계산하고, `flags`에서 아래 마스크를 적용해 I·P·B 부호화 형식을 판별합니다.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_enc_idx_entry

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

    * - __u64
      - ``offset``
      - The offset in bytes from the beginning of the compressed video
	stream to the beginning of this picture, that is a *PES packet
	header* as defined in :ref:`mpeg2part1` or a *picture header* as
	defined in :ref:`mpeg2part2`. When the encoder is stopped, the
	driver resets the offset to zero.
    * - __u64
      - ``pts``
      - The 33 bit *Presentation Time Stamp* of this picture as defined in
	:ref:`mpeg2part1`.
    * - __u32
      - ``length``
      - The length of this picture in bytes.
    * - __u32
      - ``flags``
      - Flags containing the coding type of this picture, see
	:ref:`enc-idx-flags`.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions. Drivers must set the array to
	zero.

인덱스 항목 플래그

부호화 형식을 읽을 때는 `flags & V4L2_ENC_IDX_FRAME_MASK`를 계산합니다. 결과가 각각 `V4L2_ENC_IDX_FRAME_I`, `V4L2_ENC_IDX_FRAME_P`, `V4L2_ENC_IDX_FRAME_B`인지 비교하면 됩니다.

I picture는 화면 내부 정보로 부호화되고, P picture는 이전 참조 화면을 예측에 사용하며, B picture는 양방향 예측을 사용합니다. 인덱스를 이용한 임의 접근 지점은 이러한 의존 관계도 함께 고려해야 합니다.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _enc-idx-flags:

.. flat-table:: Index Entry Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_ENC_IDX_FRAME_I``
      - 0x00
      - This is an Intra-coded picture.
    * - ``V4L2_ENC_IDX_FRAME_P``
      - 0x01
      - This is a Predictive-coded picture.
    * - ``V4L2_ENC_IDX_FRAME_B``
      - 0x02
      - This is a Bidirectionally predictive-coded picture.
    * - ``V4L2_ENC_IDX_FRAME_MASK``
      - 0x0F
      - *AND* the flags field with this mask to obtain the picture coding
	type.

반환값

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 적절히 설정합니다. 이 문서는 별도 전용 오류를 열거하지 않으며 Generic Error Codes 장의 공통 오류가 적용됩니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.