VIDIOC_G_CROP·VIDIOC_S_CROP ioctl

목적, 호출 형식과 인자

`VIDIOC_G_CROP`은 현재 cropping rectangle의 크기와 위치를 조회하고, `VIDIOC_S_CROP`은 이를 설정하는 ioctl입니다.

조회 형식은 `int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)`, 설정 형식은 `int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)`입니다. `argp`는 stream type과 `v4l2_rect`를 담습니다.

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

.. _VIDIOC_G_CROP:

**********************************
ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
**********************************

Name
====

VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle

Synopsis
========

.. c:macro:: VIDIOC_G_CROP

``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)``

.. c:macro:: VIDIOC_S_CROP

``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)``

Arguments
=========

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

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

Cropping 조회·설정과 협상

현재 cropping rectangle을 조회하려면 `v4l2_crop.type`을 대상 buffer stream type으로 설정하고 `VIDIOC_G_CROP`을 호출합니다. 드라이버는 나머지 구조체를 채우며 cropping을 지원하지 않으면 본문 표현상 `EINVAL`을 반환합니다.

rectangle을 바꾸려면 `type`과 `v4l2_crop.c`의 `v4l2_rect`를 초기화해 `VIDIOC_S_CROP`을 호출합니다.

드라이버는 먼저 capture/output window가 정한 hardware bounds에 요청 크기를 맞추고, horizontal·vertical offset과 width·height를 가장 가까운 가능한 값으로 반올림합니다.

특히 field order가 혼동되지 않도록 cropping rectangle의 vertical offset은 frame line modulo 2 조건에 맞게 반올림해야 합니다.

그다음 데이터 방향에 따라 scaling의 반대쪽 rectangle인 source 또는 target image size를 현재 horizontal·vertical scaling factor를 유지하면서 가능한 가장 가까운 크기로 조정합니다.

마지막으로 실제 cropping과 image parameter를 hardware에 설정합니다. `VIDIOC_S_CROP`은 write-only이므로 실제 적용값을 반환하지 않으며, 응용 프로그램은 `VIDIOC_G_CROP`과 `VIDIOC_G_FMT`으로 결과를 조회해야 합니다.

결과가 적합하지 않으면 cropping 또는 image parameter를 수정해 만족스러운 값이 협상될 때까지 같은 cycle을 반복할 수 있습니다. 미지원이면 어떤 parameter도 바뀌지 않습니다.

로컬 원문은 미지원 시 본문에서 `EINVAL`을, Return Value 절에서 `ENODATA`를 명시합니다. 이 차이는 원문 그대로 보존하며 자동으로 하나의 errno로 정규화하지 않습니다.

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

To query the cropping rectangle size and position applications set the
``type`` field of a struct :c:type:`v4l2_crop` structure to the
respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
with a pointer to this structure. The driver fills the rest of the
structure or returns the ``EINVAL`` error code if cropping is not supported.

To change the cropping rectangle applications initialize the ``type``
and struct :c:type:`v4l2_rect` substructure named ``c`` of a
v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
to this structure.

The driver first adjusts the requested dimensions against hardware
limits, i. e. the bounds given by the capture/output window, and it
rounds to the closest possible values of horizontal and vertical offset,
width and height. In particular the driver must round the vertical
offset of the cropping rectangle to frame lines modulo two, such that
the field order cannot be confused.

Second the driver adjusts the image size (the opposite rectangle of the
scaling process, source or target depending on the data direction) to
the closest size possible while maintaining the current horizontal and
vertical scaling factor.

Finally the driver programs the hardware with the actual cropping and
image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
return the actual parameters. To query them applications must call
:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
parameters are unsuitable the application may modify the cropping or
image parameters and repeat the cycle until satisfactory parameters have
been negotiated.

When cropping is not supported then no parameters are changed and
:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.

v4l2_crop 구조체와 multiplanar 호환성

multiplanar buffer type에서는 역사적으로 `type` 해석이 일관되지 않았습니다. 일부 드라이버는 `_MPLANE` type만, 다른 드라이버는 끝에 `_MPLANE`이 없는 non-multiplanar type만 받았습니다.

kernel 4.13부터는 이 두 변형을 모두 허용합니다. 호환성이 필요한 응용 프로그램은 이 이력을 고려해야 합니다.

.. c:type:: v4l2_crop

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

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

    * - __u32
      - ``type``
      - Type of the data stream, set by the application. Only these types
	are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
	``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
	``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
    * - struct :c:type:`v4l2_rect`
      - ``c``
      - Cropping rectangle. The same co-ordinate system as for struct
	:c:type:`v4l2_cropcap` ``bounds`` is used.

.. note::
   Unfortunately in the case of multiplanar buffer types
   (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
   this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field
   should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
   other drivers only accepted a non-multiplanar buffer type (i.e. without the
   ``_MPLANE`` at the end).

   Starting with kernel 4.13 both variations are allowed.

반환값과 ENODATA

성공하면 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.

ENODATA
    Cropping is not supported for this input or output.