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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_ENUM_FMT:
  11
  12 *********************
  13 ioctl VIDIOC_ENUM_FMT
  14 *********************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_ENUM_FMT - Enumerate image formats
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp )
  26     :name: VIDIOC_ENUM_FMT
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_fmtdesc`.
  37
  38
  39 Description
  40 ===========
  41
  42 To enumerate image formats applications initialize the ``type`` and
  43 ``index`` field of struct :c:type:`v4l2_fmtdesc` and call
  44 the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
  45 fill the rest of the structure or return an ``EINVAL`` error code. All
  46 formats are enumerable by beginning at index zero and incrementing by
  47 one until ``EINVAL`` is returned.
  48
  49 .. note::
  50
  51    After switching input or output the list of enumerated image
  52    formats may be different.
  53
  54
  55 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  56
  57 .. c:type:: v4l2_fmtdesc
  58
  59 .. flat-table:: struct v4l2_fmtdesc
  60     :header-rows:  0
  61     :stub-columns: 0
  62     :widths:       1 1 2
  63
  64     * - __u32
  65       - ``index``
  66       - Number of the format in the enumeration, set by the application.
  67         This is in no way related to the ``pixelformat`` field.
  68     * - __u32
  69       - ``type``
  70       - Type of the data stream, set by the application. Only these types
  71         are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
  72         ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
  73         ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
  74         ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
  75         ``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
  76         ``V4L2_BUF_TYPE_SDR_CAPTURE``,
  77         ``V4L2_BUF_TYPE_SDR_OUTPUT`` and
  78         ``V4L2_BUF_TYPE_META_CAPTURE``.
  79         See :c:type:`v4l2_buf_type`.
  80     * - __u32
  81       - ``flags``
  82       - See :ref:`fmtdesc-flags`
  83     * - __u8
  84       - ``description``\ [32]
  85       - Description of the format, a NUL-terminated ASCII string. This
  86         information is intended for the user, for example: "YUV 4:2:2".
  87     * - __u32
  88       - ``pixelformat``
  89       - The image format identifier. This is a four character code as
  90         computed by the v4l2_fourcc() macro:
  91     * - :cspan:`2`
  92
  93         .. _v4l2-fourcc:
  94
  95         ``#define v4l2_fourcc(a,b,c,d)``
  96
  97         ``(((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))``
  98
  99         Several image formats are already defined by this specification in
 100         :ref:`pixfmt`.
 101
 102         .. attention::
 103
 104            These codes are not the same as those used
 105            in the Windows world.
 106     * - __u32
 107       - ``reserved``\ [4]
 108       - Reserved for future extensions. Drivers must set the array to
 109         zero.
 110
 111
 112
 113 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 114
 115 .. _fmtdesc-flags:
 116
 117 .. flat-table:: Image Format Description Flags
 118     :header-rows:  0
 119     :stub-columns: 0
 120     :widths:       3 1 4
 121
 122     * - ``V4L2_FMT_FLAG_COMPRESSED``
 123       - 0x0001
 124       - This is a compressed format.
 125     * - ``V4L2_FMT_FLAG_EMULATED``
 126       - 0x0002
 127       - This format is not native to the device but emulated through
 128         software (usually libv4l2), where possible try to use a native
 129         format instead for better performance.
 130     * - ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
 131       - 0x0004
 132       - The hardware decoder for this compressed bytestream format (aka coded
 133         format) is capable of parsing a continuous bytestream. Applications do
 134         not need to parse the bytestream themselves to find the boundaries
 135         between frames/fields. This flag can only be used in combination with
 136         the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed
 137         formats only. This flag is valid for stateful decoders only.
 138     * - ``V4L2_FMT_FLAG_DYN_RESOLUTION``
 139       - 0x0008
 140       - Dynamic resolution switching is supported by the device for this
 141         compressed bytestream format (aka coded format). It will notify the user
 142         via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video
 143         parameters are detected. This flag can only be used in combination
 144         with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
 145         compressed formats only. It is also only applies to stateful codecs.
 146
 147
 148 Return Value
 149 ============
 150
 151 On success 0 is returned, on error -1 and the ``errno`` variable is set
 152 appropriately. The generic error codes are described at the
 153 :ref:`Generic Error Codes <gen-errors>` chapter.
 154
 155 EINVAL
 156     The struct :c:type:`v4l2_fmtdesc` ``type`` is not
 157     supported or the ``index`` is out of bounds.