Extended Controls API

확장 제어가 필요한 이유

초기 V4L2 control mechanism은 brightness나 saturation 같은 사용자 설정을 위해 설계됐습니다. 그러나 큰 API 가운데 각 드라이버가 일부만 구현하는 복잡한 기능에도 이 모델이 유용하다는 점이 드러났습니다.

Extended Control API의 직접적인 계기는 MPEG encoding API였습니다. MPEG 표준은 크고 hardware encoder마다 구현하는 부분집합이 다릅니다. 또한 표준은 결과 stream의 형식만 정의하므로 실제 encoding 방법에 관한 많은 parameter는 MPEG chip별로 달라집니다. 기존 control API에 부족한 기능을 보충해 extended control mechanism이 만들어졌습니다.

처음에는 MPEG encoding을 대상으로 했지만 현재는 Camera Controls, FM Transmitter Controls 등 여러 class가 같은 API를 사용합니다.

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

.. _extended-controls:

*********************
Extended Controls API
*********************


Introduction
============

The control mechanism as originally designed was meant to be used for
user settings (brightness, saturation, etc). However, it turned out to
be a very useful model for implementing more complicated driver APIs
where each driver implements only a subset of a larger API.

The MPEG encoding API was the driving force behind designing and
implementing this extended control mechanism: the MPEG standard is quite
large and the currently supported hardware MPEG encoders each only
implement a subset of this standard. Further more, many parameters
relating to how the video is encoded into an MPEG stream are specific to
the MPEG encoding chip since the MPEG standard only defines the format
of the resulting MPEG stream, not how the video is actually encoded into
that format.

Unfortunately, the original control API lacked some features needed for
these new uses and so it was extended into the (not terribly originally
named) extended control API.

Even though the MPEG encoding API was the first effort to use the
Extended Control API, nowadays there are also other classes of Extended
Controls, such as Camera Controls and FM Transmitter Controls. The
Extended Controls API as well as all Extended Controls classes are
described in the following text.

제어 배열과 compound type

`VIDIOC_G_EXT_CTRLS`, `VIDIOC_S_EXT_CTRLS`, `VIDIOC_TRY_EXT_CTRLS`는 하나의 control만 다루는 `VIDIOC_G_CTRL`과 `VIDIOC_S_CTRL`과 달리 control 배열에 작동합니다. 여러 control을 원자적으로 바꿔야 하는 경우를 지원하기 위한 설계입니다.

세 ioctl은 `v4l2_ext_controls` 포인터를 받습니다. 이 구조체는 control 배열 포인터, 배열 원소 수와 control class를 포함합니다. `V4L2_CTRL_CLASS_USER`는 구형 `VIDIOC_S_CTRL`로도 설정할 수 있는 user control을, `V4L2_CTRL_CLASS_CODEC`은 codec 관련 control을 묶습니다. 배열의 모든 control은 지정한 한 class에 속해야 하며 그렇지 않으면 오류입니다.

`count == 0`인 빈 배열을 전달하면 지정한 control class의 지원 여부만 검사할 수 있습니다. 배열 원소 `v4l2_ext_control`은 `v4l2_control`과 비슷하지만 64-bit 값과 pointer도 전달할 수 있습니다.

Pointer 지원 덕분에 N-dimensional array와 structure 같은 compound control을 정의할 수 있습니다. 열거할 때 `V4L2_CTRL_FLAG_NEXT_COMPOUND`를 지정해야 compound control이 보이며, 이런 control은 program 방식으로만 사용하는 것이 적절합니다. `VIDIOC_QUERY_EXT_CTRL`은 기존 `VIDIOC_QUERYCTRL`보다 많은 정보를 노출하고 여러 원소를 가진 N-dimensional array의 차원도 제공합니다.

Control의 유연성 때문에 application은 `VIDIOC_QUERYCTRL`로 드라이버가 해당 control을 지원하는지와 유효 범위를 반드시 확인해야 합니다. `V4L2_CTRL_TYPE_MENU`에는 지원하지 않는 index가 있을 수 있고 이때 `VIDIOC_QUERYMENU`는 오류를 반환합니다. 모든 control 값은 machine endianness를 사용합니다.

The Extended Control API
========================

Three new ioctls are available:
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
on arrays of controls (as opposed to the
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
control). This is needed since it is often required to atomically change
several controls at once.

Each of the new ioctls expects a pointer to a struct
:c:type:`v4l2_ext_controls`. This structure
contains a pointer to the control array, a count of the number of
controls in that array and a control class. Control classes are used to
group similar controls into a single class. For example, control class
``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls
relating to codecs.

All controls in the control array must belong to the specified control
class. An error is returned if this is not the case.

It is also possible to use an empty control array (``count`` == 0) to check
whether the specified control class is supported.

The control array is a struct
:c:type:`v4l2_ext_control` array. The
struct :c:type:`v4l2_ext_control` is very similar to
struct :c:type:`v4l2_control`, except for the fact that
it also allows for 64-bit values and pointers to be passed.

Since the struct :c:type:`v4l2_ext_control` supports
pointers it is now also possible to have controls with compound types
such as N-dimensional arrays and/or structures. You need to specify the
``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
be able to see such compound controls. In other words, these controls
with compound types should only be used programmatically.

Since such compound controls need to expose more information about
themselves than is possible with :ref:`VIDIOC_QUERYCTRL <VIDIOC_QUERYCTRL>`
the :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
particular, this ioctl gives the dimensions of the N-dimensional array if
this control consists of more than one element.

.. note::

   #. It is important to realize that due to the flexibility of controls it is
      necessary to check whether the control you want to set actually is
      supported in the driver and what the valid range of values is. So use
      :ref:`VIDIOC_QUERYCTRL` to check this.

   #. It is possible that some of the menu indices in a control of
      type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
      will return an error). A good example is the list of supported MPEG
      audio bitrates. Some drivers only support one or two bitrates, others
      support a wider range.

All controls use machine endianness.

열거와 control panel 구성

권장 열거 방식은 `VIDIOC_QUERYCTRL`과 `V4L2_CTRL_FLAG_NEXT_CTRL`을 함께 사용하는 것입니다. 최초 ID를 flag만 설정한 값으로 두면 ioctl이 그보다 큰 첫 control ID를 반환합니다. 매 반복에서 반환된 ID에 flag를 다시 OR하고, 더 큰 ID가 없으면 오류로 반복이 끝납니다.

특정 class만 열거하려면 초기 ID를 class와 `NEXT_CTRL` flag의 OR로 두고, `V4L2_CTRL_ID2CLASS(qctrl.id)`가 원하는 class와 달라지는 순간 반복을 종료합니다. 원문의 두 C 예제는 전체 열거와 codec class 한정 열거를 각각 보여 줍니다.

Driver가 extended control을 지원하지 않으면 `NEXT_CTRL`과 함께 쓴 `VIDIOC_QUERYCTRL`이 실패하므로 구형 전체 열거 방법으로 돌아가야 합니다. 지원한다면 driver-private control까지 모두 열거된다는 것이 보장됩니다.

GUI control panel은 같은 방식으로 모든 control을 순회해 만들 수 있습니다. 각 class는 `V4L2_CTRL_TYPE_CTRL_CLASS` type의 control로 시작하고, `VIDIOC_QUERYCTRL`이 반환한 class 이름을 tab 제목으로 쓸 수 있습니다. `v4l2_queryctrl.flags`에는 control 동작 방식에 관한 hint도 들어 있습니다.

Enumerating Extended Controls
=============================

The recommended way to enumerate over the extended controls is by using
:ref:`VIDIOC_QUERYCTRL` in combination with the
``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:


.. code-block:: c

    struct v4l2_queryctrl qctrl;

    qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
    while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
	/* ... */
	qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
    }

The initial control ID is set to 0 ORed with the
``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
return the first control with a higher ID than the specified one. When
no such controls are found an error is returned.

If you want to get all controls within a specific control class, then
you can set the initial ``qctrl.id`` value to the control class and add
an extra check to break out of the loop when a control of another
control class is found:


.. code-block:: c

    qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL;
    while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
	if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC)
	    break;
	/* ... */
	qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
    }

The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
and are not actually part of the ID. The remaining 28 bits form the
control ID, of which the most significant 12 bits define the control
class and the least significant 16 bits identify the control within the
control class. It is guaranteed that these last 16 bits are always
non-zero for controls. The range of 0x1000 and up are reserved for
driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
the control class ID based on a control ID.

If the driver does not support extended controls, then
``VIDIOC_QUERYCTRL`` will fail when used in combination with
``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
control should be used (see :ref:`enum_all_controls`). But if it is
supported, then it is guaranteed to enumerate over all controls,
including driver-private controls.


Creating Control Panels
=======================

It is possible to create control panels for a graphical user interface
where the user can select the various controls. Basically you will have
to iterate over all controls using the method described above. Each
control class starts with a control of type
``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
of this control class which can be used as the title of a tab page
within a control panel.

The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
contains hints on the behavior of the control. See the
:ref:`VIDIOC_QUERYCTRL` documentation for more
details.