요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _VIDIOC_SUBDEV_G_SELECTION:
6
**********************************************************
7
ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
8
**********************************************************
10
Name
11
====
13
VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_SUBDEV_G_SELECTION
20
``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)``
22
.. c:macro:: VIDIOC_SUBDEV_S_SELECTION
24
``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)``
26
Arguments
27
=========
29
``fd``
30
File descriptor returned by :c:func:`open()`.
32
``argp``
33
Pointer to struct :c:type:`v4l2_subdev_selection`.
35
Description
36
===========
38
The selections are used to configure various image processing
39
functionality performed by the subdevs which affect the image size. This
40
currently includes cropping, scaling and composition.
42
The selection API replaces
43
:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
44
function of the crop API, and more, are supported by the selections API.
46
See :ref:`subdev` for more information on how each selection target
47
affects the image processing pipeline inside the subdevice.
49
If the subdev device node has been registered in read-only mode, calls to
50
``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
51
``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
52
variable is set to ``-EPERM``.
54
Types of selection targets
55
--------------------------
57
There are two types of selection targets: actual and bounds. The actual
58
targets are the targets which configure the hardware. The BOUNDS target
59
will return a rectangle that contain all possible actual rectangles.
61
Discovering supported features
62
------------------------------
64
To discover which targets are supported, the user can perform
65
``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
66
return ``EINVAL``.
68
Selection targets and flags are documented in
69
:ref:`v4l2-selections-common`.
71
.. c:type:: v4l2_subdev_selection
73
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
75
.. flat-table:: struct v4l2_subdev_selection
76
:header-rows: 0
77
:stub-columns: 0
78
:widths: 1 1 2
80
* - __u32
81
- ``which``
82
- Active or try selection, from enum
83
:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
84
* - __u32
85
- ``pad``
86
- Pad number as reported by the media framework.
87
* - __u32
88
- ``target``
89
- Target selection rectangle. See :ref:`v4l2-selections-common`.
90
* - __u32
91
- ``flags``
92
- Flags. See :ref:`v4l2-selection-flags`.
93
* - struct :c:type:`v4l2_rect`
94
- ``r``
95
- Selection rectangle, in pixels.
96
* - __u32
97
- ``stream``
98
- Stream identifier.
99
* - __u32
100
- ``reserved``\ [7]
101
- Reserved for future extensions. Applications and drivers must set
102
the array to zero.
104
Return Value
105
============
107
On success 0 is returned, on error -1 and the ``errno`` variable is set
108
appropriately. The generic error codes are described at the
109
:ref:`Generic Error Codes <gen-errors>` chapter.
111
EBUSY
112
The selection rectangle can't be changed because the pad is
113
currently busy. This can be caused, for instance, by an active video
114
stream on the pad. The ioctl must not be retried without performing
115
another action to fix the problem first. Only returned by
116
``VIDIOC_SUBDEV_S_SELECTION``
118
EINVAL
119
The struct :c:type:`v4l2_subdev_selection` ``pad`` references a
120
non-existing pad, the ``which`` field has an unsupported value, or the
121
selection target is not supported on the given subdev pad.
123
EPERM
124
The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
125
subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-34`VIDIOC_SUBDEV_G_SELECTION`과 `VIDIOC_SUBDEV_S_SELECTION`은 서브디바이스 pad의 selection 사각형을 조회하거나 설정합니다. `argp`는 `struct v4l2_subdev_selection`을 가리킵니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_SELECTION:
**********************************************************
ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
**********************************************************
Name
====
VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
Synopsis
========
.. c:macro:: VIDIOC_SUBDEV_G_SELECTION
``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)``
.. c:macro:: VIDIOC_SUBDEV_S_SELECTION
``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_selection`.
이미지 처리 대상과 기능 발견
35-70Selection은 crop, scaling, composition처럼 이미지 크기에 영향을 주는 서브디바이스 영상 처리 기능을 구성합니다. 구형 subdev crop API의 모든 기능과 그 이상의 대상을 지원하며 새 구현은 selection API를 사용해야 합니다.
읽기 전용으로 등록된 서브디바이스 노드에서 S_SELECTION은 `which = V4L2_SUBDEV_FORMAT_TRY`일 때만 유효합니다. ACTIVE 상태를 바꾸려 하면 `EPERM`입니다.
Selection target은 actual과 bounds 두 종류입니다. actual target은 실제 하드웨어 동작을 구성하고, BOUNDS target은 가능한 모든 actual 사각형을 포함하는 경계 사각형을 반환합니다.
지원 target을 발견하려면 각 후보에 G_SELECTION을 호출합니다. 지원하지 않는 target은 `EINVAL`을 반환하며, target과 flag의 상세 의미는 공통 selection 문서를 따릅니다.
유형하드웨어 효과반환 사각형
Actual target하드웨어 crop·scale·compose 동작을 구성현재 또는 요청된 실제 사각형
BOUNDS target직접 구성하지 않음가능한 모든 actual 사각형을 포함하는 경계
실제 구성값과 가능한 범위 정보를 구분합니다.
pad와 which 선택→확인할 target 지정→G_SELECTION 호출→성공하면 사각형과 flags 사용→EINVAL이면 해당 target 미지원 또는 입력 오류 확인
지원 여부는 G_SELECTION 결과로 확인합니다.
Description
===========
The selections are used to configure various image processing
functionality performed by the subdevs which affect the image size. This
currently includes cropping, scaling and composition.
The selection API replaces
:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
function of the crop API, and more, are supported by the selections API.
See :ref:`subdev` for more information on how each selection target
affects the image processing pipeline inside the subdevice.
If the subdev device node has been registered in read-only mode, calls to
``VIDIOC_SUBDEV_S_SELECTION`` 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``.
Types of selection targets
--------------------------
There are two types of selection targets: actual and bounds. The actual
targets are the targets which configure the hardware. The BOUNDS target
will return a rectangle that contain all possible actual rectangles.
Discovering supported features
------------------------------
To discover which targets are supported, the user can perform
``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
return ``EINVAL``.
Selection targets and flags are documented in
:ref:`v4l2-selections-common`.
struct v4l2_subdev_selection
71-103형식필드의미
`__u32``which`ACTIVE 또는 TRY selection 상태
`__u32``pad`Media framework가 보고한 pad 번호
`__u32``target`공통 selection target으로 정의된 사각형 종류
`__u32``flags`공통 selection flags
`struct v4l2_rect``r`픽셀 단위 selection 사각형
`__u32``stream`스트림 식별자
`__u32[7]``reserved[7]`향후 확장용이며 응용 프로그램과 드라이버가 모두 0으로 설정
상태, pad, target과 픽셀 사각형을 전달합니다.
.. c:type:: v4l2_subdev_selection
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
.. flat-table:: struct v4l2_subdev_selection
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u32
- ``which``
- Active or try selection, from enum
:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
* - __u32
- ``pad``
- Pad number as reported by the media framework.
* - __u32
- ``target``
- Target selection rectangle. See :ref:`v4l2-selections-common`.
* - __u32
- ``flags``
- Flags. See :ref:`v4l2-selection-flags`.
* - struct :c:type:`v4l2_rect`
- ``r``
- Selection rectangle, in pixels.
* - __u32
- ``stream``
- Stream identifier.
* - __u32
- ``reserved``\ [7]
- Reserved for future extensions. Applications and drivers must set
the array to zero.
반환값과 오류
104-125성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`EBUSY`활성 스트림 등으로 pad가 사용 중이라 사각형을 바꿀 수 없음. 다른 조치 없이 재시도하지 않으며 S_SELECTION만 반환
`EINVAL`pad가 없거나 which가 미지원이거나 해당 pad에서 target을 지원하지 않음
`EPERM`읽기 전용 서브디바이스에서 S_SELECTION으로 ACTIVE 상태를 변경하려 함
S_SELECTION 전용 상태 오류와 공통 입력 오류입니다.
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 selection 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_SELECTION``
EINVAL
The struct :c:type:`v4l2_subdev_selection` ``pad`` references a
non-existing pad, the ``which`` field has an unsupported value, or the
selection target is not supported on the given subdev pad.
EPERM
The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
요약·해설
vidioc-subdev-g-selection.rst:1-125G_SELECTION을 후보 target에 직접 호출하는 방식이 기능 탐색 절차이며, BOUNDS는 구성값이 아니라 가능한 actual 사각형 전체를 포함하는 경계입니다.