[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-subdev-enum-frame-size.rst

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

.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:

***********************************
ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
***********************************

*man VIDIOC_SUBDEV_ENUM_FRAME_SIZE(2)*

Enumerate media bus frame sizes


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )

Arguments
=========

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

``request``
    VIDIOC_SUBDEV_ENUM_FRAME_SIZE

``argp``


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

This ioctl allows applications to enumerate all frame sizes supported by
a sub-device on the given pad for the given media bus format. Supported
formats can be retrieved with the
:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
ioctl.

To enumerate frame sizes applications initialize the ``pad``, ``which``
, ``code`` and ``index`` fields of the struct
:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
structure. Drivers fill the minimum and maximum frame sizes or return an
EINVAL error code if one of the input parameters is invalid.

Sub-devices that only support discrete frame sizes (such as most
sensors) will return one or more frame sizes with identical minimum and
maximum values.

Not all possible sizes in given [minimum, maximum] ranges need to be
supported. For instance, a scaler that uses a fixed-point scaling ratio
might not be able to produce every frame size between the minimum and
maximum values. Applications must use the
:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
sub-device for an exact supported frame size.

Available frame sizes may depend on the current 'try' formats at other
pads of the sub-device, as well as on the current active links and the
current values of V4L2 controls. See
:ref:`VIDIOC_SUBDEV_G_FMT` for more
information about try formats.


.. _v4l2-subdev-frame-size-enum:

.. flat-table:: struct v4l2_subdev_frame_size_enum
    :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.

    -  .. row 2

       -  __u32

       -  ``pad``

       -  Pad number as reported by the media controller API.

    -  .. row 3

       -  __u32

       -  ``code``

       -  The media bus format code, as defined in
	  :ref:`v4l2-mbus-format`.

    -  .. row 4

       -  __u32

       -  ``min_width``

       -  Minimum frame width, in pixels.

    -  .. row 5

       -  __u32

       -  ``max_width``

       -  Maximum frame width, in pixels.

    -  .. row 6

       -  __u32

       -  ``min_height``

       -  Minimum frame height, in pixels.

    -  .. row 7

       -  __u32

       -  ``max_height``

       -  Maximum frame height, in pixels.

    -  .. row 8

       -  __u32

       -  ``which``

       -  Frame sizes to be enumerated, from enum
	  :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.

    -  .. row 9

       -  __u32

       -  ``reserved``\ [8]

       -  Reserved for future extensions. Applications and drivers must set
	  the array to zero.


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