1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_ENUM_FRAMESIZES: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab**************************** 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_ENUM_FRAMESIZES 854f38fcaSMauro Carvalho Chehab**************************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_ENUM_FRAMESIZES 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)`` 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho ChehabArguments 2354f38fcaSMauro Carvalho Chehab========= 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho Chehab``fd`` 26407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho Chehab``argp`` 2954f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_frmsizeenum` 3054f38fcaSMauro Carvalho Chehab that contains an index and pixel format and receives a frame width 3154f38fcaSMauro Carvalho Chehab and height. 3254f38fcaSMauro Carvalho Chehab 3354f38fcaSMauro Carvalho ChehabDescription 3454f38fcaSMauro Carvalho Chehab=========== 3554f38fcaSMauro Carvalho Chehab 3654f38fcaSMauro Carvalho ChehabThis ioctl allows applications to enumerate all frame sizes (i. e. width 3754f38fcaSMauro Carvalho Chehaband height in pixels) that the device supports for the given pixel 3854f38fcaSMauro Carvalho Chehabformat. 3954f38fcaSMauro Carvalho Chehab 4054f38fcaSMauro Carvalho ChehabThe supported pixel formats can be obtained by using the 4154f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_ENUM_FMT` function. 4254f38fcaSMauro Carvalho Chehab 4354f38fcaSMauro Carvalho ChehabThe return value and the content of the ``v4l2_frmsizeenum.type`` field 4454f38fcaSMauro Carvalho Chehabdepend on the type of frame sizes the device supports. Here are the 4554f38fcaSMauro Carvalho Chehabsemantics of the function for the different cases: 4654f38fcaSMauro Carvalho Chehab 4754f38fcaSMauro Carvalho Chehab- **Discrete:** The function returns success if the given index value 4854f38fcaSMauro Carvalho Chehab (zero-based) is valid. The application should increase the index by 4954f38fcaSMauro Carvalho Chehab one for each call until ``EINVAL`` is returned. The 5054f38fcaSMauro Carvalho Chehab ``v4l2_frmsizeenum.type`` field is set to 5154f38fcaSMauro Carvalho Chehab ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the 5254f38fcaSMauro Carvalho Chehab ``discrete`` member is valid. 5354f38fcaSMauro Carvalho Chehab 5454f38fcaSMauro Carvalho Chehab- **Step-wise:** The function returns success if the given index value 5554f38fcaSMauro Carvalho Chehab is zero and ``EINVAL`` for any other index value. The 5654f38fcaSMauro Carvalho Chehab ``v4l2_frmsizeenum.type`` field is set to 5754f38fcaSMauro Carvalho Chehab ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the 5854f38fcaSMauro Carvalho Chehab ``stepwise`` member is valid. 5954f38fcaSMauro Carvalho Chehab 6054f38fcaSMauro Carvalho Chehab- **Continuous:** This is a special case of the step-wise type above. 6154f38fcaSMauro Carvalho Chehab The function returns success if the given index value is zero and 6254f38fcaSMauro Carvalho Chehab ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type`` 6354f38fcaSMauro Carvalho Chehab field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of 6454f38fcaSMauro Carvalho Chehab the union only the ``stepwise`` member is valid and the 6554f38fcaSMauro Carvalho Chehab ``step_width`` and ``step_height`` values are set to 1. 6654f38fcaSMauro Carvalho Chehab 6754f38fcaSMauro Carvalho ChehabWhen the application calls the function with index zero, it must check 6854f38fcaSMauro Carvalho Chehabthe ``type`` field to determine the type of frame size enumeration the 6954f38fcaSMauro Carvalho Chehabdevice supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does 7054f38fcaSMauro Carvalho Chehabit make sense to increase the index value to receive more frame sizes. 7154f38fcaSMauro Carvalho Chehab 7254f38fcaSMauro Carvalho Chehab.. note:: 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho Chehab The order in which the frame sizes are returned has no special 7554f38fcaSMauro Carvalho Chehab meaning. In particular does it not say anything about potential default 7654f38fcaSMauro Carvalho Chehab format sizes. 7754f38fcaSMauro Carvalho Chehab 7854f38fcaSMauro Carvalho ChehabApplications can assume that the enumeration data does not change 7954f38fcaSMauro Carvalho Chehabwithout any interaction from the application itself. This means that the 8054f38fcaSMauro Carvalho Chehabenumeration data is consistent if the application does not perform any 8154f38fcaSMauro Carvalho Chehabother ioctl calls while it runs the frame size enumeration. 8254f38fcaSMauro Carvalho Chehab 8354f38fcaSMauro Carvalho ChehabStructs 8454f38fcaSMauro Carvalho Chehab======= 8554f38fcaSMauro Carvalho Chehab 8654f38fcaSMauro Carvalho ChehabIn the structs below, *IN* denotes a value that has to be filled in by 8754f38fcaSMauro Carvalho Chehabthe application, *OUT* denotes values that the driver fills in. The 8854f38fcaSMauro Carvalho Chehabapplication should zero out all members except for the *IN* fields. 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_frmsize_discrete 9154f38fcaSMauro Carvalho Chehab 9254f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_frmsize_discrete 9354f38fcaSMauro Carvalho Chehab :header-rows: 0 9454f38fcaSMauro Carvalho Chehab :stub-columns: 0 9554f38fcaSMauro Carvalho Chehab :widths: 1 1 2 9654f38fcaSMauro Carvalho Chehab 9754f38fcaSMauro Carvalho Chehab * - __u32 9854f38fcaSMauro Carvalho Chehab - ``width`` 9954f38fcaSMauro Carvalho Chehab - Width of the frame [pixel]. 10054f38fcaSMauro Carvalho Chehab * - __u32 10154f38fcaSMauro Carvalho Chehab - ``height`` 10254f38fcaSMauro Carvalho Chehab - Height of the frame [pixel]. 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho Chehab 10554f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_frmsize_stepwise 10654f38fcaSMauro Carvalho Chehab 10754f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_frmsize_stepwise 10854f38fcaSMauro Carvalho Chehab :header-rows: 0 10954f38fcaSMauro Carvalho Chehab :stub-columns: 0 11054f38fcaSMauro Carvalho Chehab :widths: 1 1 2 11154f38fcaSMauro Carvalho Chehab 11254f38fcaSMauro Carvalho Chehab * - __u32 11354f38fcaSMauro Carvalho Chehab - ``min_width`` 11454f38fcaSMauro Carvalho Chehab - Minimum frame width [pixel]. 11554f38fcaSMauro Carvalho Chehab * - __u32 11654f38fcaSMauro Carvalho Chehab - ``max_width`` 11754f38fcaSMauro Carvalho Chehab - Maximum frame width [pixel]. 11854f38fcaSMauro Carvalho Chehab * - __u32 11954f38fcaSMauro Carvalho Chehab - ``step_width`` 12054f38fcaSMauro Carvalho Chehab - Frame width step size [pixel]. 12154f38fcaSMauro Carvalho Chehab * - __u32 12254f38fcaSMauro Carvalho Chehab - ``min_height`` 12354f38fcaSMauro Carvalho Chehab - Minimum frame height [pixel]. 12454f38fcaSMauro Carvalho Chehab * - __u32 12554f38fcaSMauro Carvalho Chehab - ``max_height`` 12654f38fcaSMauro Carvalho Chehab - Maximum frame height [pixel]. 12754f38fcaSMauro Carvalho Chehab * - __u32 12854f38fcaSMauro Carvalho Chehab - ``step_height`` 12954f38fcaSMauro Carvalho Chehab - Frame height step size [pixel]. 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho Chehab 13254f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_frmsizeenum 13354f38fcaSMauro Carvalho Chehab 134*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}| 13554f38fcaSMauro Carvalho Chehab 13654f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_frmsizeenum 13754f38fcaSMauro Carvalho Chehab :header-rows: 0 13854f38fcaSMauro Carvalho Chehab :stub-columns: 0 13954f38fcaSMauro Carvalho Chehab 14054f38fcaSMauro Carvalho Chehab * - __u32 14154f38fcaSMauro Carvalho Chehab - ``index`` 14254f38fcaSMauro Carvalho Chehab - IN: Index of the given frame size in the enumeration. 14354f38fcaSMauro Carvalho Chehab * - __u32 14454f38fcaSMauro Carvalho Chehab - ``pixel_format`` 14554f38fcaSMauro Carvalho Chehab - IN: Pixel format for which the frame sizes are enumerated. 14654f38fcaSMauro Carvalho Chehab * - __u32 14754f38fcaSMauro Carvalho Chehab - ``type`` 14854f38fcaSMauro Carvalho Chehab - OUT: Frame size type the device supports. 14954f38fcaSMauro Carvalho Chehab * - union { 15054f38fcaSMauro Carvalho Chehab - (anonymous) 15154f38fcaSMauro Carvalho Chehab - OUT: Frame size with the given index. 15254f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_frmsize_discrete` 15354f38fcaSMauro Carvalho Chehab - ``discrete`` 15454f38fcaSMauro Carvalho Chehab - 15554f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_frmsize_stepwise` 15654f38fcaSMauro Carvalho Chehab - ``stepwise`` 15754f38fcaSMauro Carvalho Chehab - 15854f38fcaSMauro Carvalho Chehab * - } 15954f38fcaSMauro Carvalho Chehab - 16054f38fcaSMauro Carvalho Chehab - 16154f38fcaSMauro Carvalho Chehab * - __u32 16254f38fcaSMauro Carvalho Chehab - ``reserved[2]`` 16354f38fcaSMauro Carvalho Chehab - Reserved space for future use. Must be zeroed by drivers and 16454f38fcaSMauro Carvalho Chehab applications. 16554f38fcaSMauro Carvalho Chehab 16654f38fcaSMauro Carvalho Chehab 16754f38fcaSMauro Carvalho ChehabEnums 16854f38fcaSMauro Carvalho Chehab===== 16954f38fcaSMauro Carvalho Chehab 17054f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_frmsizetypes 17154f38fcaSMauro Carvalho Chehab 172*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| 17354f38fcaSMauro Carvalho Chehab 17454f38fcaSMauro Carvalho Chehab.. flat-table:: enum v4l2_frmsizetypes 17554f38fcaSMauro Carvalho Chehab :header-rows: 0 17654f38fcaSMauro Carvalho Chehab :stub-columns: 0 17754f38fcaSMauro Carvalho Chehab :widths: 3 1 4 17854f38fcaSMauro Carvalho Chehab 17954f38fcaSMauro Carvalho Chehab * - ``V4L2_FRMSIZE_TYPE_DISCRETE`` 18054f38fcaSMauro Carvalho Chehab - 1 18154f38fcaSMauro Carvalho Chehab - Discrete frame size. 18254f38fcaSMauro Carvalho Chehab * - ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` 18354f38fcaSMauro Carvalho Chehab - 2 18454f38fcaSMauro Carvalho Chehab - Continuous frame size. 18554f38fcaSMauro Carvalho Chehab * - ``V4L2_FRMSIZE_TYPE_STEPWISE`` 18654f38fcaSMauro Carvalho Chehab - 3 18754f38fcaSMauro Carvalho Chehab - Step-wise defined frame size. 18854f38fcaSMauro Carvalho Chehab 18954f38fcaSMauro Carvalho ChehabReturn Value 19054f38fcaSMauro Carvalho Chehab============ 19154f38fcaSMauro Carvalho Chehab 19254f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 19354f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 19454f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 195