Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_SUBDEV_G_SELECTION:
   4
   5 **********************************************************
   6 ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
   7 **********************************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp )
  19     :name: VIDIOC_SUBDEV_G_SELECTION
  20
  21 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp )
  22     :name: VIDIOC_SUBDEV_S_SELECTION
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <func-open>`.
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37 The selections are used to configure various image processing
  38 functionality performed by the subdevs which affect the image size. This
  39 currently includes cropping, scaling and composition.
  40
  41 The selection API replaces
  42 :ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
  43 function of the crop API, and more, are supported by the selections API.
  44
  45 See :ref:`subdev` for more information on how each selection target
  46 affects the image processing pipeline inside the subdevice.
  47
  48
  49 Types of selection targets
  50 --------------------------
  51
  52 There are two types of selection targets: actual and bounds. The actual
  53 targets are the targets which configure the hardware. The BOUNDS target
  54 will return a rectangle that contain all possible actual rectangles.
  55
  56
  57 Discovering supported features
  58 ------------------------------
  59
  60 To discover which targets are supported, the user can perform
  61 ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
  62 return ``EINVAL``.
  63
  64 Selection targets and flags are documented in
  65 :ref:`v4l2-selections-common`.
  66
  67
  68 .. c:type:: v4l2_subdev_selection
  69
  70 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  71
  72 .. flat-table:: struct v4l2_subdev_selection
  73     :header-rows:  0
  74     :stub-columns: 0
  75     :widths:       1 1 2
  76
  77     * - __u32
  78       - ``which``
  79       - Active or try selection, from enum
  80         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  81     * - __u32
  82       - ``pad``
  83       - Pad number as reported by the media framework.
  84     * - __u32
  85       - ``target``
  86       - Target selection rectangle. See :ref:`v4l2-selections-common`.
  87     * - __u32
  88       - ``flags``
  89       - Flags. See :ref:`v4l2-selection-flags`.
  90     * - struct :c:type:`v4l2_rect`
  91       - ``r``
  92       - Selection rectangle, in pixels.
  93     * - __u32
  94       - ``reserved``\ [8]
  95       - Reserved for future extensions. Applications and drivers must set
  96         the array to zero.
  97
  98
  99 Return Value
 100 ============
 101
 102 On success 0 is returned, on error -1 and the ``errno`` variable is set
 103 appropriately. The generic error codes are described at the
 104 :ref:`Generic Error Codes <gen-errors>` chapter.
 105
 106 EBUSY
 107     The selection rectangle can't be changed because the pad is
 108     currently busy. This can be caused, for instance, by an active video
 109     stream on the pad. The ioctl must not be retried without performing
 110     another action to fix the problem first. Only returned by
 111     ``VIDIOC_SUBDEV_S_SELECTION``
 112
 113 EINVAL
 114     The struct :c:type:`v4l2_subdev_selection`
 115     ``pad`` references a non-existing pad, the ``which`` field
 116     references a non-existing format, or the selection target is not
 117     supported on the given subdev pad.