diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-crop.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-crop.rst | 119 |
1 files changed, 0 insertions, 119 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst deleted file mode 100644 index 1eff59dc5f35..000000000000 --- a/Documentation/media/uapi/v4l/vidioc-g-crop.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDIOC_G_CROP: - -********************************** -ioctl VIDIOC_G_CROP, VIDIOC_S_CROP -********************************** - -Name -==== - -VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, VIDIOC_G_CROP, struct v4l2_crop *argp ) - :name: VIDIOC_G_CROP - -.. c:function:: int ioctl( int fd, VIDIOC_S_CROP, const struct v4l2_crop *argp ) - :name: VIDIOC_S_CROP - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() <func-open>`. - -``argp`` - Pointer to struct :c:type:`v4l2_crop`. - - -Description -=========== - -To query the cropping rectangle size and position applications set the -``type`` field of a struct :c:type:`v4l2_crop` structure to the -respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl -with a pointer to this structure. The driver fills the rest of the -structure or returns the ``EINVAL`` error code if cropping is not supported. - -To change the cropping rectangle applications initialize the ``type`` -and struct :c:type:`v4l2_rect` substructure named ``c`` of a -v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer -to this structure. - -The driver first adjusts the requested dimensions against hardware -limits, i. e. the bounds given by the capture/output window, and it -rounds to the closest possible values of horizontal and vertical offset, -width and height. In particular the driver must round the vertical -offset of the cropping rectangle to frame lines modulo two, such that -the field order cannot be confused. - -Second the driver adjusts the image size (the opposite rectangle of the -scaling process, source or target depending on the data direction) to -the closest size possible while maintaining the current horizontal and -vertical scaling factor. - -Finally the driver programs the hardware with the actual cropping and -image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not -return the actual parameters. To query them applications must call -:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the -parameters are unsuitable the application may modify the cropping or -image parameters and repeat the cycle until satisfactory parameters have -been negotiated. - -When cropping is not supported then no parameters are changed and -:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code. - - -.. c:type:: v4l2_crop - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct v4l2_crop - :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 :c:type:`v4l2_rect` - - ``c`` - - Cropping rectangle. The same co-ordinate system as for struct - :c:type:`v4l2_cropcap` ``bounds`` is used. - -.. note:: - Unfortunately in the case of multiplanar buffer types - (``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_crop` ``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. - - -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. - -ENODATA - Cropping is not supported for this input or output. |