1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_G_SELECTION: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab******************************************** 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION 854f38fcaSMauro Carvalho Chehab******************************************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_G_SELECTION 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_S_SELECTION 2354f38fcaSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)`` 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabArguments 2754f38fcaSMauro Carvalho Chehab========= 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho Chehab``fd`` 30407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho Chehab``argp`` 3354f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_selection`. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDescription 3654f38fcaSMauro Carvalho Chehab=========== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabThe ioctls are used to query and configure selection rectangles. 3954f38fcaSMauro Carvalho Chehab 4054f38fcaSMauro Carvalho ChehabTo query the cropping (composing) rectangle set struct 4154f38fcaSMauro Carvalho Chehab:c:type:`v4l2_selection` ``type`` field to the 4254f38fcaSMauro Carvalho Chehabrespective buffer type. The next step is setting the 4354f38fcaSMauro Carvalho Chehabvalue of struct :c:type:`v4l2_selection` ``target`` 4454f38fcaSMauro Carvalho Chehabfield to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer 4554f38fcaSMauro Carvalho Chehabto table :ref:`v4l2-selections-common` or :ref:`selection-api` for 4654f38fcaSMauro Carvalho Chehabadditional targets. The ``flags`` and ``reserved`` fields of struct 4754f38fcaSMauro Carvalho Chehab:c:type:`v4l2_selection` are ignored and they must be 4854f38fcaSMauro Carvalho Chehabfilled with zeros. The driver fills the rest of the structure or returns 4954f38fcaSMauro Carvalho ChehabEINVAL error code if incorrect buffer type or target was used. If 5054f38fcaSMauro Carvalho Chehabcropping (composing) is not supported then the active rectangle is not 5154f38fcaSMauro Carvalho Chehabmutable and it is always equal to the bounds rectangle. Finally, the 5254f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_rect` ``r`` rectangle is filled with 5354f38fcaSMauro Carvalho Chehabthe current cropping (composing) coordinates. The coordinates are 5454f38fcaSMauro Carvalho Chehabexpressed in driver-dependent units. The only exception are rectangles 5554f38fcaSMauro Carvalho Chehabfor images in raw formats, whose coordinates are always expressed in 5654f38fcaSMauro Carvalho Chehabpixels. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho ChehabTo change the cropping (composing) rectangle set the struct 5954f38fcaSMauro Carvalho Chehab:c:type:`v4l2_selection` ``type`` field to the 6054f38fcaSMauro Carvalho Chehabrespective buffer type. The next step is setting the 6154f38fcaSMauro Carvalho Chehabvalue of struct :c:type:`v4l2_selection` ``target`` to 6254f38fcaSMauro Carvalho Chehab``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table 6354f38fcaSMauro Carvalho Chehab:ref:`v4l2-selections-common` or :ref:`selection-api` for additional 6454f38fcaSMauro Carvalho Chehabtargets. The struct :c:type:`v4l2_rect` ``r`` rectangle need 6554f38fcaSMauro Carvalho Chehabto be set to the desired active area. Field struct 6654f38fcaSMauro Carvalho Chehab:c:type:`v4l2_selection` ``reserved`` is ignored and 6754f38fcaSMauro Carvalho Chehabmust be filled with zeros. The driver may adjust coordinates of the 6854f38fcaSMauro Carvalho Chehabrequested rectangle. An application may introduce constraints to control 6954f38fcaSMauro Carvalho Chehabrounding behaviour. The struct :c:type:`v4l2_selection` 7054f38fcaSMauro Carvalho Chehab``flags`` field must be set to one of the following: 7154f38fcaSMauro Carvalho Chehab 7254f38fcaSMauro Carvalho Chehab- ``0`` - The driver can adjust the rectangle size freely and shall 7354f38fcaSMauro Carvalho Chehab choose a crop/compose rectangle as close as possible to the requested 7454f38fcaSMauro Carvalho Chehab one. 7554f38fcaSMauro Carvalho Chehab 7654f38fcaSMauro Carvalho Chehab- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the 7754f38fcaSMauro Carvalho Chehab rectangle. The original rectangle must lay inside the adjusted one. 7854f38fcaSMauro Carvalho Chehab 7954f38fcaSMauro Carvalho Chehab- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the 8054f38fcaSMauro Carvalho Chehab rectangle. The adjusted rectangle must lay inside the original one. 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho Chehab- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the 8354f38fcaSMauro Carvalho Chehab size exactly the same as in the requested rectangle. 8454f38fcaSMauro Carvalho Chehab 8554f38fcaSMauro Carvalho ChehabPlease refer to :ref:`sel-const-adjust`. 8654f38fcaSMauro Carvalho Chehab 8754f38fcaSMauro Carvalho ChehabThe driver may have to adjusts the requested dimensions against hardware 8854f38fcaSMauro Carvalho Chehablimits and other parts as the pipeline, i.e. the bounds given by the 8954f38fcaSMauro Carvalho Chehabcapture/output window or TV display. The closest possible values of 9054f38fcaSMauro Carvalho Chehabhorizontal and vertical offset and sizes are chosen according to 9154f38fcaSMauro Carvalho Chehabfollowing priority: 9254f38fcaSMauro Carvalho Chehab 9354f38fcaSMauro Carvalho Chehab1. Satisfy constraints from struct 9454f38fcaSMauro Carvalho Chehab :c:type:`v4l2_selection` ``flags``. 9554f38fcaSMauro Carvalho Chehab 9654f38fcaSMauro Carvalho Chehab2. Adjust width, height, left, and top to hardware limits and 9754f38fcaSMauro Carvalho Chehab alignments. 9854f38fcaSMauro Carvalho Chehab 9954f38fcaSMauro Carvalho Chehab3. Keep center of adjusted rectangle as close as possible to the 10054f38fcaSMauro Carvalho Chehab original one. 10154f38fcaSMauro Carvalho Chehab 10254f38fcaSMauro Carvalho Chehab4. Keep width and height as close as possible to original ones. 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho Chehab5. Keep horizontal and vertical offset as close as possible to original 10554f38fcaSMauro Carvalho Chehab ones. 10654f38fcaSMauro Carvalho Chehab 10754f38fcaSMauro Carvalho ChehabOn success the struct :c:type:`v4l2_rect` ``r`` field 10854f38fcaSMauro Carvalho Chehabcontains the adjusted rectangle. When the parameters are unsuitable the 10954f38fcaSMauro Carvalho Chehabapplication may modify the cropping (composing) or image parameters and 11054f38fcaSMauro Carvalho Chehabrepeat the cycle until satisfactory parameters have been negotiated. If 11154f38fcaSMauro Carvalho Chehabconstraints flags have to be violated at then ``ERANGE`` is returned. The 11254f38fcaSMauro Carvalho Chehaberror indicates that *there exist no rectangle* that satisfies the 11354f38fcaSMauro Carvalho Chehabconstraints. 11454f38fcaSMauro Carvalho Chehab 11554f38fcaSMauro Carvalho ChehabSelection targets and flags are documented in 11654f38fcaSMauro Carvalho Chehab:ref:`v4l2-selections-common`. 11754f38fcaSMauro Carvalho Chehab 11854f38fcaSMauro Carvalho Chehab.. _sel-const-adjust: 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho Chehab.. kernel-figure:: constraints.svg 12154f38fcaSMauro Carvalho Chehab :alt: constraints.svg 12254f38fcaSMauro Carvalho Chehab :align: center 12354f38fcaSMauro Carvalho Chehab 12454f38fcaSMauro Carvalho Chehab Size adjustments with constraint flags. 12554f38fcaSMauro Carvalho Chehab 12654f38fcaSMauro Carvalho Chehab Behaviour of rectangle adjustment for different constraint flags. 12754f38fcaSMauro Carvalho Chehab 12854f38fcaSMauro Carvalho Chehab 12954f38fcaSMauro Carvalho Chehab 13054f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_selection 13154f38fcaSMauro Carvalho Chehab 132*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 13354f38fcaSMauro Carvalho Chehab 13454f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_selection 13554f38fcaSMauro Carvalho Chehab :header-rows: 0 13654f38fcaSMauro Carvalho Chehab :stub-columns: 0 13754f38fcaSMauro Carvalho Chehab :widths: 1 1 2 13854f38fcaSMauro Carvalho Chehab 13954f38fcaSMauro Carvalho Chehab * - __u32 14054f38fcaSMauro Carvalho Chehab - ``type`` 14154f38fcaSMauro Carvalho Chehab - Type of the buffer (from enum 14254f38fcaSMauro Carvalho Chehab :c:type:`v4l2_buf_type`). 14354f38fcaSMauro Carvalho Chehab * - __u32 14454f38fcaSMauro Carvalho Chehab - ``target`` 14554f38fcaSMauro Carvalho Chehab - Used to select between 14654f38fcaSMauro Carvalho Chehab :ref:`cropping and composing rectangles <v4l2-selections-common>`. 14754f38fcaSMauro Carvalho Chehab * - __u32 14854f38fcaSMauro Carvalho Chehab - ``flags`` 14954f38fcaSMauro Carvalho Chehab - Flags controlling the selection rectangle adjustments, refer to 15054f38fcaSMauro Carvalho Chehab :ref:`selection flags <v4l2-selection-flags>`. 15154f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_rect` 15254f38fcaSMauro Carvalho Chehab - ``r`` 15354f38fcaSMauro Carvalho Chehab - The selection rectangle. 15454f38fcaSMauro Carvalho Chehab * - __u32 15554f38fcaSMauro Carvalho Chehab - ``reserved[9]`` 15654f38fcaSMauro Carvalho Chehab - Reserved fields for future use. Drivers and applications must zero 15754f38fcaSMauro Carvalho Chehab this array. 15854f38fcaSMauro Carvalho Chehab 15954f38fcaSMauro Carvalho Chehab.. note:: 16054f38fcaSMauro Carvalho Chehab Unfortunately in the case of multiplanar buffer types 16154f38fcaSMauro Carvalho Chehab (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) 16254f38fcaSMauro Carvalho Chehab this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field 16354f38fcaSMauro Carvalho Chehab should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while 16454f38fcaSMauro Carvalho Chehab other drivers only accepted a non-multiplanar buffer type (i.e. without the 16554f38fcaSMauro Carvalho Chehab ``_MPLANE`` at the end). 16654f38fcaSMauro Carvalho Chehab 16754f38fcaSMauro Carvalho Chehab Starting with kernel 4.13 both variations are allowed. 16854f38fcaSMauro Carvalho Chehab 16954f38fcaSMauro Carvalho ChehabReturn Value 17054f38fcaSMauro Carvalho Chehab============ 17154f38fcaSMauro Carvalho Chehab 17254f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 17354f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 17454f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 17554f38fcaSMauro Carvalho Chehab 17654f38fcaSMauro Carvalho ChehabEINVAL 17754f38fcaSMauro Carvalho Chehab Given buffer type ``type`` or the selection target ``target`` is not 17854f38fcaSMauro Carvalho Chehab supported, or the ``flags`` argument is not valid. 17954f38fcaSMauro Carvalho Chehab 18054f38fcaSMauro Carvalho ChehabERANGE 18154f38fcaSMauro Carvalho Chehab It is not possible to adjust struct :c:type:`v4l2_rect` 18254f38fcaSMauro Carvalho Chehab ``r`` rectangle to satisfy all constraints given in the ``flags`` 18354f38fcaSMauro Carvalho Chehab argument. 18454f38fcaSMauro Carvalho Chehab 18554f38fcaSMauro Carvalho ChehabENODATA 18654f38fcaSMauro Carvalho Chehab Selection is not supported for this input or output. 18754f38fcaSMauro Carvalho Chehab 18854f38fcaSMauro Carvalho ChehabEBUSY 18954f38fcaSMauro Carvalho Chehab It is not possible to apply change of the selection rectangle at the 19054f38fcaSMauro Carvalho Chehab moment. Usually because streaming is in progress. 191