영상 크롭, 삽입과 스케일링 - CROP API

CROP API의 범위와 source/target

레거시 CROP API는 대부분 더 새로운 `SELECTION API`로 대체됐으므로 일반적으로 새 API를 우선해야 합니다. 예외는 `VIDIOC_CROPCAP`으로 얻는 pixel aspect ratio이며 SELECTION API에는 대응 기능이 없습니다. 두 API 비교는 `selection-vs-crop` 절에서 다룹니다.

일부 캡처 장치는 입력 영상의 일부 영역만 샘플링하고 임의 크기로 축소·확대할 수 있습니다. 출력 장치는 애플리케이션 영상을 확대·축소해 비디오 신호의 임의 scan line과 수평 오프셋에 삽입할 수 있습니다.

애플리케이션은 CROP API로 비디오 신호의 영역을 선택하고 기본 영역과 하드웨어 한계를 조회합니다. 이름과 달리 `VIDIOC_CROPCAP`, `VIDIOC_G_CROP`, `VIDIOC_S_CROP`은 입력과 출력 장치 모두에 적용됩니다.

캡처 또는 overlay에서는 crop ioctl이 source 영역을 정하고 format ioctl이 target 영상 크기와 overlay 위치를 정합니다. 출력에서는 format이 source 영상 크기를, crop이 신호 속 삽입 target을 정합니다.

장치가 스케일링이나 G_CROP/S_CROP을 지원하지 않아도 source와 target 사각형은 개념적으로 존재하며 이때 크기와 필요한 위치는 고정됩니다. CROP 또는 SELECTION을 지원하는 모든 capture/output 장치는 CROPCAP도 지원해야 합니다.

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

.. _crop:

*****************************************************
Image Cropping, Insertion and Scaling -- the CROP API
*****************************************************

.. note::

   The CROP API is mostly superseded by the newer :ref:`SELECTION API
   <selection-api>`. The new API should be preferred in most cases,
   with the exception of pixel aspect ratio detection, which is
   implemented by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` and has no
   equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a
   comparison of the two APIs.

Some video capture devices can sample a subsection of the picture and
shrink or enlarge it to an image of arbitrary size. We call these
abilities cropping and scaling. Some video output devices can scale an
image up or down and insert it at an arbitrary scan line and horizontal
offset into a video signal.

Applications can use the following API to select an area in the video
signal, query the default area and the hardware limits.

.. note::

   Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
   :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
   <VIDIOC_G_CROP>` ioctls apply to input as well as output devices.

Scaling requires a source and a target. On a video capture or overlay
device the source is the video signal, and the cropping ioctls determine
the area actually sampled. The target are images read by the application
or overlaid onto the graphics screen. Their size (and position for an
overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls.

On a video output device the source are the images passed in by the
application, and their size is again negotiated with the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
ioctls, or may be encoded in a compressed video stream. The target is
the video signal, and the cropping ioctls determine the area where the
images are inserted.

Source and target rectangles are defined even if the device does not
support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
where applicable) will be fixed in this case.

.. note::

   All capture and output devices that support the CROP or SELECTION
   API will also support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`
   ioctl.

crop 구조체, 좌표와 기본 사각형

원문의 `crop.svg` 그림은 capture에서 신호의 일부를 잘라 target 영상으로 스케일하고, output에서는 source 영상을 target 사각형에 삽입하는 과정을 함께 나타냅니다.

캡처 `bounds`의 원점과 단위는 다양한 하드웨어를 수용하기 위해 규격이 강제하지 않습니다. 관례적으로 수평 좌표는 horizontal sync pulse 선두인 0H에 대한 unscaled sample 수를 사용합니다.

수직 좌표는 첫 field의 ITU-R line number를 사용하고, 두 field를 모두 캡처할 수 있는 드라이버는 그 값에 2를 곱합니다. 525선과 625선 체계의 번호 규칙은 각각 관련 VBI 절을 참조합니다.

현재 source 사각형은 CROPCAP과 같은 좌표계의 `struct v4l2_crop`으로 표현하며 완전히 bounds 안에 있어야 합니다. 드라이버는 정렬과 하드웨어 제한에 맞춰 요청한 위치·크기를 추가 보정할 수 있습니다.

`defrect`의 중심은 비디오 신호 active picture 영역 중심과 맞아야 하고 드라이버 작성자가 완전한 영상으로 판단하는 영역을 덮습니다. 드라이버는 최초 로드 때 source를 기본값으로 초기화하되 이후에는 자동으로 되돌리지 않습니다. 출력 장치에서는 같은 구조가 삽입 target을 정의합니다.

Cropping Structures
===================


.. _crop-scale:

.. kernel-figure:: crop.svg
    :alt:    crop.svg
    :align:  center

    Image Cropping, Insertion and Scaling

    The cropping, insertion and scaling process



For capture devices the coordinates of the top left corner, width and
height of the area which can be sampled is given by the ``bounds``
substructure of the struct :c:type:`v4l2_cropcap` returned
by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide
range of hardware this specification does not define an origin or units.
However by convention drivers should horizontally count unscaled samples
relative to 0H (the leading edge of the horizontal sync pulse, see
:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for
:ref:`625 lines <vbi-625>`), multiplied by two if the driver
can capture both fields.

The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by struct
:c:type:`v4l2_crop` using the same coordinate system as
struct :c:type:`v4l2_cropcap`. Applications can use the
:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>`
ioctls to get and set this rectangle. It must lie completely within the
capture boundaries and the driver may further adjust the requested size
and/or position according to hardware limitations.

Each capture device has a default source rectangle, given by the
``defrect`` substructure of struct
:c:type:`v4l2_cropcap`. The center of this rectangle
shall align with the center of the active picture area of the video
signal, and cover what the driver writer considers the complete picture.
Drivers shall reset the source rectangle to the default when the driver
is first loaded, but not later.

For output devices these structures and ioctls are used accordingly,
defining the *target* rectangle where the images will be inserted into
the video signal.

스케일링 제한과 사각형 보정 우선순위

하드웨어는 확대만 또는 축소만 가능하거나, 불연속 스케일 계수만 지원하거나, 수평·수직 능력이 다를 수 있습니다. 스케일링을 전혀 지원하지 않는 장치도 있습니다.

`v4l2_crop` 사각형 자체에 정렬 조건이 있을 수 있고 source와 target 모두 임의 상·하한을 가질 수 있습니다. 특히 crop의 최대 width/height가 CROPCAP `bounds`보다 작을 수 있으므로 드라이버는 실제 선택값을 반환해야 합니다.

애플리케이션은 원하는 영상 크기 또는 신호 영역의 우선순위에 따라 source와 target 중 어느 쪽이든 먼저 설정할 수 있습니다. 두 값을 함께 조정해야 한다면 마지막에 요청한 사각형을 우선하고 반대쪽을 보정하는 것이 원칙입니다. `VIDIOC_TRY_FMT`은 상태를 바꾸지 않으므로 전달된 요청 사각형만 보정합니다.

첫 예제의 기본 source 상한은 offset 0,0의 640x400입니다. 요청 target 300x225는 가장 가까운 16픽셀 배수 304x224가 되고, 2:1 수평 축소와 source 높이 상한을 만족하는 crop은 608x224가 됩니다. 224를 수직으로 두 배 한 448은 상한 400을 넘기 때문에 수직은 1:1입니다.

애플리케이션이 원래 aspect ratio에 더 가까운 source 608x456을 다시 요구하면 하드웨어 제한이 이를 608x384로 만들고 target도 304x192로 조정됩니다. 마지막 source 요청이 우선된 결과입니다.

Scaling Adjustments
===================

Video hardware can have various cropping, insertion and scaling
limitations. It may only scale up or down, support only discrete scaling
factors, or have different scaling abilities in horizontal and vertical
direction. Also it may not support scaling at all. At the same time the
struct :c:type:`v4l2_crop` rectangle may have to be aligned,
and both the source and target rectangles may have arbitrary upper and
lower size limits. In particular the maximum ``width`` and ``height`` in
struct :c:type:`v4l2_crop` may be smaller than the struct
:c:type:`v4l2_cropcap`. ``bounds`` area. Therefore, as
usual, drivers are expected to adjust the requested parameters and
return the actual values selected.

Applications can change the source or the target rectangle first, as
they may prefer a particular image size or a certain area in the video
signal. If the driver has to adjust both to satisfy hardware
limitations, the last requested rectangle shall take priority, and the
driver should preferably adjust the opposite one. The
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change
the driver state and therefore only adjust the requested rectangle.

Suppose scaling on a video capture device is restricted to a factor 1:1
or 2:1 in either direction and the target image size must be a multiple
of 16 × 16 pixels. The source cropping rectangle is set to defaults,
which are also the upper limit in this example, of 640 × 400 pixels at
offset 0, 0. An application requests an image size of 300 × 225 pixels,
assuming video will be scaled down from the "full picture" accordingly.
The driver sets the image size to the closest possible values 304 × 224,
then chooses the cropping rectangle closest to the requested size, that
is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
still valid, thus unmodified. Given the default cropping rectangle
reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can
easily propose another offset to center the cropping rectangle.

Now the application may insist on covering an area using a picture
aspect ratio closer to the original request, so it asks for a cropping
rectangle of 608 × 456 pixels. The present scaling factors limit
cropping to 640 × 384, so the driver returns the cropping size 608 × 384
and adjusts the image size to closest possible 304 × 192.

crop 상태 유지와 기본값 복원 예제

source와 target 사각형은 장치를 닫았다 다시 열어도 유지되어야 합니다. 따라서 단순 파이프 방식 I/O는 특별한 준비 없이 동작하지만, 고급 애플리케이션은 I/O 시작 전에 현재 파라미터가 적합한지 확인해야 합니다.

기본값 복원 예제는 VIDEO_CAPTURE 형식으로 CROPCAP을 조회하고 `crop.c = cropcap.defrect`를 설정한 뒤 S_CROP을 호출합니다. 크롭 미지원의 `EINVAL`만 무시하고 다른 오류는 실패로 처리합니다.

다른 장치 유형에 적용하려면 `V4L2_BUF_TYPE_VIDEO_CAPTURE`를 해당 buffer type으로 바꿔야 합니다.

Examples
========

Source and target rectangles shall remain unchanged across closing and
reopening a device, such that piping data into or out of a device will
work without special preparations. More advanced applications should
ensure the parameters are suitable before starting I/O.

.. note::

   On the next two examples, a video capture device is assumed;
   change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.

Example: Resetting the cropping parameters
==========================================

.. code-block:: c

    struct v4l2_cropcap cropcap;
    struct v4l2_crop crop;

    memset (&cropcap, 0, sizeof (cropcap));
    cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
    }

    memset (&crop, 0, sizeof (crop));
    crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    crop.c = cropcap.defrect;

    /* Ignore if cropping is not supported (EINVAL). */

    if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
	&& errno != EINVAL) {
	perror ("VIDIOC_S_CROP");
	exit (EXIT_FAILURE);
    }

단순 1/4 면적 축소 예제

단순 축소 예제는 먼저 crop 파라미터를 기본값으로 되돌리고 VIDEO_CAPTURE format을 준비합니다.

width와 height를 각각 `defrect.width >> 1`, `defrect.height >> 1`로 설정하여 가로·세로를 절반으로 줄이고 면적을 1/4로 만듭니다. 픽셀 형식은 `V4L2_PIX_FMT_YUYV`입니다.

`VIDIOC_S_FMT` 뒤에는 드라이버가 실제로 선택한 영상 크기와 배율, 스케일링 가능 여부를 반환 구조체에서 다시 확인할 수 있습니다.

Example: Simple downscaling
===========================

.. code-block:: c

    struct v4l2_cropcap cropcap;
    struct v4l2_format format;

    reset_cropping_parameters ();

    /* Scale down to 1/4 size of full picture. */

    memset (&format, 0, sizeof (format)); /* defaults */

    format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    format.fmt.pix.width = cropcap.defrect.width >> 1;
    format.fmt.pix.height = cropcap.defrect.height >> 1;
    format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;

    if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
	perror ("VIDIOC_S_FORMAT");
	exit (EXIT_FAILURE);
    }

    /* We could check the actual image size now, the actual scaling factor
       or if the driver can scale at all. */

출력 삽입 영역 선택 예제

출력 예제는 `V4L2_BUF_TYPE_VIDEO_OUTPUT`으로 CROPCAP의 기본 target 사각형을 조회합니다.

기본 사각형의 width와 height를 절반으로 나누고, 줄어든 폭·높이의 절반만큼 left와 top을 증가시켜 원래 영역 중앙에 50% 크기의 출력을 배치합니다.

계산한 target은 S_CROP으로 설정하며 크롭 미지원 `EINVAL`만 무시합니다. 이 절에서 crop은 잘라낼 capture source가 아니라 비디오 신호 속 출력 삽입 영역입니다.

로컬 v6.18.37 원문의 호출은 `VIDIOC_CROPCAP;`처럼 세미콜론이 포함된 표기를 사용합니다. 원문과 줄 좌표는 그대로 보존했으며, 실제 C 코드로 사용할 때는 ioctl 요청 상수 `VIDIOC_CROPCAP`을 사용해야 합니다.

Example: Selecting an output area
=================================

.. note:: This example assumes an output device.

.. code-block:: c

    struct v4l2_cropcap cropcap;
    struct v4l2_crop crop;

    memset (&cropcap, 0, sizeof (cropcap));
    cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;

    if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
    }

    memset (&crop, 0, sizeof (crop));

    crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
    crop.c = cropcap.defrect;

    /* Scale the width and height to 50 % of their original size
       and center the output. */

    crop.c.width /= 2;
    crop.c.height /= 2;
    crop.c.left += crop.c.width / 2;
    crop.c.top += crop.c.height / 2;

    /* Ignore if cropping is not supported (EINVAL). */

    if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
	&& errno != EINVAL) {
	perror ("VIDIOC_S_CROP");
	exit (EXIT_FAILURE);
    }

현재 배율과 pixel aspect 계산

마지막 예제는 VIDEO_CAPTURE 장치에서 CROPCAP, 현재 crop, 현재 format을 조회해 드라이버가 적용한 수평·수직 배율과 표시용 pixel aspect를 계산합니다.

G_CROP이 크롭 미지원 `EINVAL`을 반환하면 현재 crop 대신 `cropcap.defrect`를 사용합니다. 다른 오류는 치명적으로 처리합니다.

ITU-R BT.601 계열 장치는 정사각 픽셀을 캡처하지 않으므로 컴퓨터 모니터에 표시할 때 계산한 aspect를 사용해 가로 크기를 조정해야 합니다.

로컬 원문은 format type 대입을 `format.fmt.type`으로 표기합니다. 원문은 변경하지 않았으며, 실제 `struct v4l2_format` 사용 시 type 필드 위치를 헤더 정의와 대조해야 합니다.

Example: Current scaling factor and pixel aspect
================================================

.. note:: This example assumes a video capture device.

.. code-block:: c

    struct v4l2_cropcap cropcap;
    struct v4l2_crop crop;
    struct v4l2_format format;
    double hscale, vscale;
    double aspect;
    int dwidth, dheight;

    memset (&cropcap, 0, sizeof (cropcap));
    cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
    }

    memset (&crop, 0, sizeof (crop));
    crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
	if (errno != EINVAL) {
	    perror ("VIDIOC_G_CROP");
	    exit (EXIT_FAILURE);
	}

	/* Cropping not supported. */
	crop.c = cropcap.defrect;
    }

    memset (&format, 0, sizeof (format));
    format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
	perror ("VIDIOC_G_FMT");
	exit (EXIT_FAILURE);
    }

    /* The scaling applied by the driver. */

    hscale = format.fmt.pix.width / (double) crop.c.width;
    vscale = format.fmt.pix.height / (double) crop.c.height;

    aspect = cropcap.pixelaspect.numerator /
	 (double) cropcap.pixelaspect.denominator;
    aspect = aspect * hscale / vscale;

    /* Devices following ITU-R BT.601 do not capture
       square pixels. For playback on a computer monitor
       we should scale the images to this size. */

    dwidth = format.fmt.pix.width / aspect;
    dheight = format.fmt.pix.height;