Documentation/media/uapi/v4l/vidioc-g-crop.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_CROP:
   4
   5 **********************************
   6 ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
   7 **********************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct v4l2_crop *argp )
  19
  20 .. c:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp )
  21
  22
  23 Arguments
  24 =========
  25
  26 ``fd``
  27     File descriptor returned by :ref:`open() <func-open>`.
  28
  29 ``request``
  30     VIDIOC_G_CROP, VIDIOC_S_CROP
  31
  32 ``argp``
  33
  34
  35 Description
  36 ===========
  37
  38 To query the cropping rectangle size and position applications set the
  39 ``type`` field of a :ref:`struct v4l2_crop <v4l2-crop>` structure to the
  40 respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
  41 with a pointer to this structure. The driver fills the rest of the
  42 structure or returns the ``EINVAL`` error code if cropping is not supported.
  43
  44 To change the cropping rectangle applications initialize the ``type``
  45 and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a
  46 v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
  47 to this structure.
  48
  49 Do not use the multiplanar buffer types. Use
  50 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
  51 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
  52 ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
  53 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
  54
  55 The driver first adjusts the requested dimensions against hardware
  56 limits, i. e. the bounds given by the capture/output window, and it
  57 rounds to the closest possible values of horizontal and vertical offset,
  58 width and height. In particular the driver must round the vertical
  59 offset of the cropping rectangle to frame lines modulo two, such that
  60 the field order cannot be confused.
  61
  62 Second the driver adjusts the image size (the opposite rectangle of the
  63 scaling process, source or target depending on the data direction) to
  64 the closest size possible while maintaining the current horizontal and
  65 vertical scaling factor.
  66
  67 Finally the driver programs the hardware with the actual cropping and
  68 image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
  69 return the actual parameters. To query them applications must call
  70 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
  71 parameters are unsuitable the application may modify the cropping or
  72 image parameters and repeat the cycle until satisfactory parameters have
  73 been negotiated.
  74
  75 When cropping is not supported then no parameters are changed and
  76 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
  77
  78
  79 .. _v4l2-crop:
  80
  81 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  82
  83 .. flat-table:: struct v4l2_crop
  84     :header-rows:  0
  85     :stub-columns: 0
  86     :widths:       1 1 2
  87
  88
  89     -  .. row 1
  90
  91        -  __u32
  92
  93        -  ``type``
  94
  95        -  Type of the data stream, set by the application. Only these types
  96           are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
  97           ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
  98           ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
  99
 100     -  .. row 2
 101
 102        -  struct :ref:`v4l2_rect <v4l2-rect>`
 103
 104        -  ``c``
 105
 106        -  Cropping rectangle. The same co-ordinate system as for struct
 107           :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used.
 108
 109
 110 Return Value
 111 ============
 112
 113 On success 0 is returned, on error -1 and the ``errno`` variable is set
 114 appropriately. The generic error codes are described at the
 115 :ref:`Generic Error Codes <gen-errors>` chapter.