diff options
author | Hans Verkuil <hans.verkuil@cisco.com> | 2017-05-08 11:35:06 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-06-23 09:22:17 -0300 |
commit | 8780f1d9d696c7f466a0ff2a2016476a7ebf42b6 (patch) | |
tree | 2ee66411a8c138081ae0103705b0ab265419a3ec /Documentation/media/uapi/v4l | |
parent | eaec420f530d376d6bb6e547a741203344619f47 (diff) |
[media] media/uapi/v4l: clarify cropcap/crop/selection behavior
Unfortunately the use of 'type' was inconsistent for multiplanar
buffer types. Starting with 4.13 both the normal and _MPLANE variants
are allowed, thus making it possible to write sensible code.
Yes, we messed up :-(
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
[hans.verkuil@cisco.com: 4.14 -> 4.13 since this would go in for 4.13 after all]
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/v4l')
-rw-r--r-- | Documentation/media/uapi/v4l/vidioc-cropcap.rst | 23 | ||||
-rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-crop.rst | 22 | ||||
-rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-selection.rst | 22 |
3 files changed, 38 insertions, 29 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst index f21a69b554e1..0f80d5ca2643 100644 --- a/Documentation/media/uapi/v4l/vidioc-cropcap.rst +++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst @@ -39,17 +39,10 @@ structure. Drivers fill the rest of the structure. The results are constant except when switching the video standard. Remember this switch can occur implicit when switching the video input or output. -Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. - This ioctl must be implemented for video capture or output devices that support cropping and/or scaling and/or have non-square pixels, and for overlay devices. - .. c:type:: v4l2_cropcap .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -62,9 +55,9 @@ overlay devices. * - __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_OUTPUT`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. + 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 :c:type:`v4l2_buf_type` and the note above. * - struct :ref:`v4l2_rect <v4l2-rect-crop>` - ``bounds`` - Defines the window within capturing or output is possible, this @@ -90,6 +83,16 @@ overlay devices. ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`]. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_cropcap` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + .. _v4l2-rect-crop: diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst index 56a36340f565..13771ee3e94a 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-crop.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst @@ -45,12 +45,6 @@ and struct :c:type:`v4l2_rect` substructure named ``c`` of a v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer to this structure. -Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. - The driver first adjusts the requested dimensions against hardware limits, i. e. the bounds given by the capture/output window, and it rounds to the closest possible values of horizontal and vertical offset, @@ -87,14 +81,24 @@ When cropping is not supported then no parameters are changed and * - __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_OUTPUT`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. + 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 :c:type:`v4l2_buf_type` and the note above. * - struct :c:type:`v4l2_rect` - ``c`` - Cropping rectangle. The same co-ordinate system as for struct :c:type:`v4l2_cropcap` ``bounds`` is used. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + Return Value ============ diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst index deb1f6fb473b..09923b86ec5d 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst @@ -42,11 +42,7 @@ The ioctls are used to query and configure selection rectangles. To query the cropping (composing) rectangle set struct :c:type:`v4l2_selection` ``type`` field to the -respective buffer type. Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +respective buffer type. The next step is setting the value of struct :c:type:`v4l2_selection` ``target`` field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table :ref:`v4l2-selections-common` or :ref:`selection-api` for @@ -64,11 +60,7 @@ pixels. To change the cropping (composing) rectangle set the struct :c:type:`v4l2_selection` ``type`` field to the -respective buffer type. Do not use multiplanar buffers. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +respective buffer type. The next step is setting the value of struct :c:type:`v4l2_selection` ``target`` to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table :ref:`v4l2-selections-common` or :ref:`selection-api` for additional @@ -169,6 +161,16 @@ Selection targets and flags are documented in - Reserved fields for future use. Drivers and applications must zero this array. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + Return Value ============ |