Documentation/linux_tv/media/v4l/vidioc-enum-fmt.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUM_FMT:
   4
   5 *********************
   6 ioctl VIDIOC_ENUM_FMT
   7 *********************
   8
   9 *man VIDIOC_ENUM_FMT(2)*
  10
  11 Enumerate image formats
  12
  13
  14 Synopsis
  15 ========
  16
  17 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )
  18
  19 Arguments
  20 =========
  21
  22 ``fd``
  23     File descriptor returned by :ref:`open() <func-open>`.
  24
  25 ``request``
  26     VIDIOC_ENUM_FMT
  27
  28 ``argp``
  29
  30
  31 Description
  32 ===========
  33
  34 To enumerate image formats applications initialize the ``type`` and
  35 ``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
  36 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
  37 fill the rest of the structure or return an EINVAL error code. All
  38 formats are enumerable by beginning at index zero and incrementing by
  39 one until EINVAL is returned.
  40
  41 Note that after switching input or output the list of enumerated image
  42 formats may be different.
  43
  44
  45 .. _v4l2-fmtdesc:
  46
  47 .. flat-table:: struct v4l2_fmtdesc
  48     :header-rows:  0
  49     :stub-columns: 0
  50     :widths:       1 1 2
  51
  52
  53     -  .. row 1
  54
  55        -  __u32
  56
  57        -  ``index``
  58
  59        -  Number of the format in the enumeration, set by the application.
  60           This is in no way related to the ``pixelformat`` field.
  61
  62     -  .. row 2
  63
  64        -  __u32
  65
  66        -  ``type``
  67
  68        -  Type of the data stream, set by the application. Only these types
  69           are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
  70           ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
  71           ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
  72           ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
  73           ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
  74
  75     -  .. row 3
  76
  77        -  __u32
  78
  79        -  ``flags``
  80
  81        -  See :ref:`fmtdesc-flags`
  82
  83     -  .. row 4
  84
  85        -  __u8
  86
  87        -  ``description``\ [32]
  88
  89        -  Description of the format, a NUL-terminated ASCII string. This
  90           information is intended for the user, for example: "YUV 4:2:2".
  91
  92     -  .. row 5
  93
  94        -  __u32
  95
  96        -  ``pixelformat``
  97
  98        -  The image format identifier. This is a four character code as
  99           computed by the v4l2_fourcc() macro:
 100
 101     -  .. row 6
 102
 103        -  :cspan:`2`
 104
 105
 106           .. _v4l2-fourcc:
 107           .. code-block:: c
 108
 109               #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
 110
 111           Several image formats are already defined by this specification in
 112           :ref:`pixfmt`. Note these codes are not the same as those used
 113           in the Windows world.
 114
 115     -  .. row 7
 116
 117        -  __u32
 118
 119        -  ``reserved``\ [4]
 120
 121        -  Reserved for future extensions. Drivers must set the array to
 122           zero.
 123
 124
 125
 126 .. _fmtdesc-flags:
 127
 128 .. flat-table:: Image Format Description Flags
 129     :header-rows:  0
 130     :stub-columns: 0
 131     :widths:       3 1 4
 132
 133
 134     -  .. row 1
 135
 136        -  ``V4L2_FMT_FLAG_COMPRESSED``
 137
 138        -  0x0001
 139
 140        -  This is a compressed format.
 141
 142     -  .. row 2
 143
 144        -  ``V4L2_FMT_FLAG_EMULATED``
 145
 146        -  0x0002
 147
 148        -  This format is not native to the device but emulated through
 149           software (usually libv4l2), where possible try to use a native
 150           format instead for better performance.
 151
 152
 153
 154 Return Value
 155 ============
 156
 157 On success 0 is returned, on error -1 and the ``errno`` variable is set
 158 appropriately. The generic error codes are described at the
 159 :ref:`Generic Error Codes <gen-errors>` chapter.
 160
 161 EINVAL
 162     The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
 163     supported or the ``index`` is out of bounds.
 164
 165
 166 .. ------------------------------------------------------------------------------
 167 .. This file was automatically converted from DocBook-XML with the dbxml
 168 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 169 .. from the linux kernel, refer to:
 170 ..
 171 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 172 .. ------------------------------------------------------------------------------