VIDIOC_CROPCAP ioctl

이름, 호출 형식과 인자

`VIDIOC_CROPCAP`은 비디오 크롭과 스케일링 능력에 관한 정보를 조회합니다. 호출 형식은 `int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터이고, `argp`는 응용 프로그램이 스트림 유형을 지정하고 드라이버가 나머지 정보를 채우는 `struct v4l2_cropcap`을 가리킵니다.

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

.. _VIDIOC_CROPCAP:

********************
ioctl VIDIOC_CROPCAP
********************

Name
====

VIDIOC_CROPCAP - Information about the video cropping and scaling abilities

Synopsis
========

.. c:macro:: VIDIOC_CROPCAP

``int ioctl(int fd, VIDIOC_CROPCAP, struct v4l2_cropcap *argp)``

Arguments
=========

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

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

조회 범위와 구현 조건

응용 프로그램은 이 ioctl로 크롭 한계와 영상의 픽셀 종횡비를 조회하고 스케일 배율을 계산합니다. `v4l2_cropcap.type`에 대상 버퍼 또는 스트림 유형을 넣어 호출하면 드라이버가 나머지 필드를 채웁니다.

결과는 비디오 표준을 바꾸지 않는 한 일정합니다. 입력 또는 출력을 전환할 때 비디오 표준도 암시적으로 바뀔 수 있으므로 그 뒤에는 capability를 다시 조회해야 합니다.

크롭, 스케일링 또는 비정사각형 픽셀을 지원하는 비디오 캡처·출력 장치와 overlay 장치는 이 ioctl을 구현해야 합니다.

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

Applications use this function to query the cropping limits, the pixel
aspect of images and to calculate scale factors. They set the ``type``
field of a v4l2_cropcap structure to the respective buffer (stream)
type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
structure. Drivers fill the rest of the structure. The results are
constant except when switching the video standard. Remember this switch
can occur implicit when switching the video input or output.

This ioctl must be implemented for video capture or output devices that
support cropping and/or scaling and/or have non-square pixels, and for
overlay devices.

v4l2_cropcap 필드

구조체는 응용 프로그램이 지정하는 스트림 유형, 크롭 가능한 전체 경계, 기본 크롭 사각형과 스케일링하지 않았을 때의 픽셀 종횡비를 담습니다.

`bounds`의 너비와 높이는 픽셀 단위이며 크롭 사각형은 이 범위를 넘을 수 없습니다. 아날로그 영역의 좌표 원점과 단위는 드라이버 작성자가 정할 수 있습니다. 정사각 픽셀을 가정하면 `defrect`는 NTSC의 640×480, PAL·SECAM의 768×576처럼 활성 영상 영역 가운데에 놓인 전체 화면 사각형이 될 수 있습니다.

크롭 좌표가 정사각 픽셀 기준이면 `pixelaspect`는 1/1입니다. 일반적인 비정사각 값은 PAL·SECAM 54/59, ITU-R BT.601 방식으로 샘플링한 NTSC 11/10입니다. 이 값은 실제 샘플링 주파수와 정사각 픽셀을 얻는 데 필요한 주파수의 비율입니다.

.. c:type:: v4l2_cropcap

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

.. flat-table:: struct v4l2_cropcap
    :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 :ref:`v4l2_rect <v4l2-rect-crop>`
      - ``bounds``
      - Defines the window within capturing or output is possible, this
	may exclude for example the horizontal and vertical blanking
	areas. The cropping rectangle cannot exceed these limits. Width
	and height are defined in pixels, the driver writer is free to
	choose origin and units of the coordinate system in the analog
	domain.
    * - struct :ref:`v4l2_rect <v4l2-rect-crop>`
      - ``defrect``
      - Default cropping rectangle, it shall cover the "whole picture".
	Assuming pixel aspect 1/1 this could be for example a 640 × 480
	rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
	centered over the active picture area. The same coordinate system
	as for ``bounds`` is used.
    * - struct :c:type:`v4l2_fract`
      - ``pixelaspect``
      - This is the pixel aspect (y / x) when no scaling is applied, the
	ratio of the actual sampling frequency and the frequency required
	to get square pixels.

	When cropping coordinates refer to square pixels, the driver sets
	``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
	SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].

.. note::
   Unfortunately in the case of multiplanar buffer types

멀티플레인 type 호환성 주의

멀티플레인 버퍼 유형에서는 역사적으로 `v4l2_cropcap.type`을 채우는 방법이 일관되지 않았습니다. 일부 드라이버는 이름 끝에 `_MPLANE`이 붙은 유형만 받았고, 다른 드라이버는 대응하는 비멀티플레인 유형만 받았습니다.

커널 4.13부터는 `V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`·`V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`과 대응하는 비멀티플레인 유형 양쪽 표현을 모두 허용합니다.

   (``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_cropcap` ``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.


.. _v4l2-rect-crop:

v4l2_rect 사각형 좌표

`left`와 `top`은 음수가 될 수 있는 signed 32비트 오프셋이고, `width`와 `height`는 음수가 될 수 없는 unsigned 32비트 크기입니다. 네 값은 모두 픽셀 단위입니다.

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

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

    * - __s32
      - ``left``
      - Horizontal offset of the top, left corner of the rectangle, in
	pixels.
    * - __s32
      - ``top``
      - Vertical offset of the top, left corner of the rectangle, in
	pixels.
    * - __u32
      - ``width``
      - Width of the rectangle, in pixels.
    * - __u32
      - ``height``
      - Height of the rectangle, in pixels.

Return Value

반환값과 오류

성공하면 0을 반환하고, 실패하면 -1과 적절한 `errno`를 반환합니다. 일반 오류 코드는 Generic Error Codes 절에 정의되어 있습니다.

============

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.

EINVAL
    The struct :c:type:`v4l2_cropcap` ``type`` is
    invalid.

ENODATA
    Cropping is not supported for this input or output.