VIDIOC_SUBDEV_G_CROP 및 VIDIOC_SUBDEV_S_CROP ioctl

목적, 호출 형식과 폐기 예정 경고

`VIDIOC_SUBDEV_G_CROP`과 `VIDIOC_SUBDEV_S_CROP`은 서브디바이스 pad의 crop 사각형을 조회하거나 설정합니다. `argp`는 `struct v4l2_subdev_crop`을 가리킵니다.

이 인터페이스는 obsolete 상태이며 향후 제거될 수 있습니다. 새 코드는 이를 대체한 selection API인 `VIDIOC_SUBDEV_G_SELECTION`을 사용해야 하고, `v4l2_subdev_crop` 구조체에는 새로운 확장이 허용되지 않습니다.

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

.. _VIDIOC_SUBDEV_G_CROP:

************************************************
ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
************************************************

Name
====

VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad

Synopsis
========

.. c:macro:: VIDIOC_SUBDEV_G_CROP

``int ioctl(int fd, VIDIOC_SUBDEV_G_CROP, struct v4l2_subdev_crop *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_CROP

``int ioctl(int fd, VIDIOC_SUBDEV_S_CROP, const struct v4l2_subdev_crop *argp)``

Arguments
=========

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

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

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

.. note::

    This is an :ref:`obsolete` interface and may be removed in the future. It is
    superseded by :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`. No new
    extensions to the :c:type:`v4l2_subdev_crop` structure will be accepted.

ACTIVE와 TRY crop 처리

현재 crop을 조회하려면 `pad`를 Media API가 보고한 번호로, `which`를 `V4L2_SUBDEV_FORMAT_ACTIVE`로 설정하고 G_CROP을 호출합니다. 드라이버는 `rect`를 채우며 인자가 잘못되거나 해당 pad가 crop을 지원하지 않으면 `EINVAL`을 반환합니다.

현재 crop을 바꾸려면 `pad`, `which`, `rect`의 모든 멤버를 설정해 S_CROP을 호출합니다. 드라이버는 요청을 검증하고 하드웨어가 제공할 수 있는 가장 가까운 사각형으로 조정해 장치에 적용하며, 호출 뒤 구조체에는 G_CROP으로 얻을 현재 값이 들어 있습니다.

`which = V4L2_SUBDEV_FORMAT_TRY`이면 사각형을 실제 장치에 적용하지 않습니다. ACTIVE와 같은 방식으로 조정한 결과를 해당 서브디바이스 파일 핸들에 저장하므로 서로 다른 응용 프로그램의 try 상태는 간섭하지 않습니다.

읽기 전용으로 등록된 서브디바이스 노드에서는 S_CROP이 TRY에만 허용됩니다. ACTIVE를 설정하려 하면 `EPERM`이 반환됩니다.

요청한 사각형이 capability와 정확히 맞지 않는다는 이유만으로 드라이버가 오류를 반환해서는 안 됩니다. 가능한 한 요청에 가까운 지원 사각형으로 수정해야 합니다.

To retrieve the current crop rectangle applications set the ``pad``
field of a struct :c:type:`v4l2_subdev_crop` to the
desired pad number as reported by the media API and the ``which`` field
to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
driver fills the members of the ``rect`` field or returns ``EINVAL`` error
code if the input arguments are invalid, or if cropping is not supported
on the given pad.

To change the current crop rectangle applications set both the ``pad``
and ``which`` fields and all members of the ``rect`` field. They then
call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
structure. The driver verifies the requested crop rectangle, adjusts it
based on the hardware capabilities and configures the device. Upon
return the struct :c:type:`v4l2_subdev_crop`
contains the current format as would be returned by a
``VIDIOC_SUBDEV_G_CROP`` call.

Applications can query the device capabilities by setting the ``which``
to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
applied to the device by the driver, but are mangled exactly as active
crop rectangles and stored in the sub-device file handle. Two
applications querying the same sub-device would thus not interact with
each other.

If the subdev device node has been registered in read-only mode, calls to
``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
variable is set to ``-EPERM``.

Drivers must not return an error solely because the requested crop
rectangle doesn't match the device capabilities. They must instead
modify the rectangle to match what the hardware can provide. The
modified format should be as close as possible to the original request.

struct v4l2_subdev_crop

.. c:type:: v4l2_subdev_crop

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

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

    * - __u32
      - ``pad``
      - Pad number as reported by the media framework.
    * - __u32
      - ``which``
      - Crop rectangle to get or set, from enum
	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
    * - struct :c:type:`v4l2_rect`
      - ``rect``
      - Crop rectangle boundaries, in pixels.
    * - __u32
      - ``stream``
      - Stream identifier.
    * - __u32
      - ``reserved``\ [7]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.

반환값과 오류

성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.

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.

EBUSY
    The crop rectangle can't be changed because the pad is currently
    busy. This can be caused, for instance, by an active video stream on
    the pad. The ioctl must not be retried without performing another
    action to fix the problem first. Only returned by
    ``VIDIOC_SUBDEV_S_CROP``

EINVAL
    The struct :c:type:`v4l2_subdev_crop` ``pad`` references a non-existing pad,
    the ``which`` field has an unsupported value, or cropping is not supported
    on the given subdev pad.

EPERM
    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.