[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-enum-fmt.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_ENUM_FMT:

*********************
ioctl VIDIOC_ENUM_FMT
*********************

*man VIDIOC_ENUM_FMT(2)*

Enumerate image formats


Synopsis
========

.. c:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_ENUM_FMT

``argp``


Description
===========

To enumerate image formats applications initialize the ``type`` and
``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
the ``VIDIOC_ENUM_FMT`` ioctl with a pointer to this structure. Drivers
fill the rest of the structure or return an EINVAL error code. All
formats are enumerable by beginning at index zero and incrementing by
one until EINVAL is returned.

Note that after switching input or output the list of enumerated image
formats may be different.


.. _v4l2-fmtdesc:

.. flat-table:: struct v4l2_fmtdesc
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``index``

       -  Number of the format in the enumeration, set by the application.
          This is in no way related to the ``pixelformat`` field.

    -  .. row 2

       -  __u32

       -  ``type``

       -  Type of the data stream, set by the application. Only these types
          are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
          ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
          ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
          ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
          ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.

    -  .. row 3

       -  __u32

       -  ``flags``

       -  See :ref:`fmtdesc-flags`

    -  .. row 4

       -  __u8

       -  ``description``\ [32]

       -  Description of the format, a NUL-terminated ASCII string. This
          information is intended for the user, for example: "YUV 4:2:2".

    -  .. row 5

       -  __u32

       -  ``pixelformat``

       -  The image format identifier. This is a four character code as
          computed by the v4l2_fourcc() macro:

    -  .. row 6

       -  :cspan:`2`


          .. _v4l2-fourcc:
          .. code-block:: c

              #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))

          Several image formats are already defined by this specification in
          :ref:`pixfmt`. Note these codes are not the same as those used
          in the Windows world.

    -  .. row 7

       -  __u32

       -  ``reserved``\ [4]

       -  Reserved for future extensions. Drivers must set the array to
          zero.


.. _fmtdesc-flags:

.. flat-table:: Image Format Description Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_FMT_FLAG_COMPRESSED``

       -  0x0001

       -  This is a compressed format.

    -  .. row 2

       -  ``V4L2_FMT_FLAG_EMULATED``

       -  0x0002

       -  This format is not native to the device but emulated through
          software (usually libv4l2), where possible try to use a native
          format instead for better performance.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
    supported or the ``index`` is out of bounds.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_ENUM_FMT:
5377d91f MH	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	.. c: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 ``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	.. ------------------------------------------------------------------------------