Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
   4
   5 ***********************************
   6 ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
   7 ***********************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp )
  19     :name: VIDIOC_SUBDEV_ENUM_FRAME_SIZE
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`.
  30
  31
  32 Description
  33 ===========
  34
  35 This ioctl allows applications to enumerate all frame sizes supported by
  36 a sub-device on the given pad for the given media bus format. Supported
  37 formats can be retrieved with the
  38 :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
  39 ioctl.
  40
  41 To enumerate frame sizes applications initialize the ``pad``, ``which``
  42 , ``code`` and ``index`` fields of the struct
  43 :c:type:`v4l2_subdev_mbus_code_enum` and
  44 call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
  45 structure. Drivers fill the minimum and maximum frame sizes or return an
  46 EINVAL error code if one of the input parameters is invalid.
  47
  48 Sub-devices that only support discrete frame sizes (such as most
  49 sensors) will return one or more frame sizes with identical minimum and
  50 maximum values.
  51
  52 Not all possible sizes in given [minimum, maximum] ranges need to be
  53 supported. For instance, a scaler that uses a fixed-point scaling ratio
  54 might not be able to produce every frame size between the minimum and
  55 maximum values. Applications must use the
  56 :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
  57 sub-device for an exact supported frame size.
  58
  59 Available frame sizes may depend on the current 'try' formats at other
  60 pads of the sub-device, as well as on the current active links and the
  61 current values of V4L2 controls. See
  62 :ref:`VIDIOC_SUBDEV_G_FMT` for more
  63 information about try formats.
  64
  65
  66 .. c:type:: v4l2_subdev_frame_size_enum
  67
  68 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  69
  70 .. flat-table:: struct v4l2_subdev_frame_size_enum
  71     :header-rows:  0
  72     :stub-columns: 0
  73     :widths:       1 1 2
  74
  75     * - __u32
  76       - ``index``
  77       - Number of the format in the enumeration, set by the application.
  78     * - __u32
  79       - ``pad``
  80       - Pad number as reported by the media controller API.
  81     * - __u32
  82       - ``code``
  83       - The media bus format code, as defined in
  84         :ref:`v4l2-mbus-format`.
  85     * - __u32
  86       - ``min_width``
  87       - Minimum frame width, in pixels.
  88     * - __u32
  89       - ``max_width``
  90       - Maximum frame width, in pixels.
  91     * - __u32
  92       - ``min_height``
  93       - Minimum frame height, in pixels.
  94     * - __u32
  95       - ``max_height``
  96       - Maximum frame height, in pixels.
  97     * - __u32
  98       - ``which``
  99       - Frame sizes to be enumerated, from enum
 100         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
 101     * - __u32
 102       - ``reserved``\ [8]
 103       - Reserved for future extensions. Applications and drivers must set
 104         the array to zero.
 105
 106
 107 Return Value
 108 ============
 109
 110 On success 0 is returned, on error -1 and the ``errno`` variable is set
 111 appropriately. The generic error codes are described at the
 112 :ref:`Generic Error Codes <gen-errors>` chapter.
 113
 114 EINVAL
 115     The struct
 116     :c:type:`v4l2_subdev_frame_size_enum`
 117     ``pad`` references a non-existing pad, the ``code`` is invalid for
 118     the given pad or the ``index`` field is out of bounds.