^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_G_CROP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) **********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) **********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) .. c:macro:: VIDIOC_G_CROP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ``int ioctl(int fd, VIDIOC_G_CROP, struct v4l2_crop *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) .. c:macro:: VIDIOC_S_CROP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``int ioctl(int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Pointer to struct :c:type:`v4l2_crop`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) To query the cropping rectangle size and position applications set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ``type`` field of a struct :c:type:`v4l2_crop` structure to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) with a pointer to this structure. The driver fills the rest of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) structure or returns the ``EINVAL`` error code if cropping is not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) To change the cropping rectangle applications initialize the ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) and struct :c:type:`v4l2_rect` substructure named ``c`` of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) to this structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) The driver first adjusts the requested dimensions against hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) limits, i. e. the bounds given by the capture/output window, and it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) rounds to the closest possible values of horizontal and vertical offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) width and height. In particular the driver must round the vertical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) offset of the cropping rectangle to frame lines modulo two, such that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) the field order cannot be confused.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Second the driver adjusts the image size (the opposite rectangle of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) scaling process, source or target depending on the data direction) to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) the closest size possible while maintaining the current horizontal and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) vertical scaling factor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Finally the driver programs the hardware with the actual cropping and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) return the actual parameters. To query them applications must call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) parameters are unsuitable the application may modify the cropping or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) image parameters and repeat the cycle until satisfactory parameters have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) been negotiated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) When cropping is not supported then no parameters are changed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) .. c:type:: v4l2_crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) .. flat-table:: struct v4l2_crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) - Type of the data stream, set by the application. Only these types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) * - struct :c:type:`v4l2_rect`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) - ``c``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) - Cropping rectangle. The same co-ordinate system as for struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) :c:type:`v4l2_cropcap` ``bounds`` is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Unfortunately in the case of multiplanar buffer types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) other drivers only accepted a non-multiplanar buffer type (i.e. without the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) ``_MPLANE`` at the end).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Starting with kernel 4.13 both variations are allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ENODATA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Cropping is not supported for this input or output.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags