From 9e9e6a78143bbb6cb9cffd29ab48d5f32def4e20 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Sat, 27 May 2017 05:12:40 -0300 Subject: [media] Doc*/media/uapi: fix control name V4L2_CID_EXPOSURE_BIAS does not exist, fix documentation. Signed-off-by: Pavel Machek Acked-by: Sakari Ailus Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/extended-controls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/media/uapi/v4l') diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index abb105724c05..76c5b1aeaadd 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -2019,7 +2019,7 @@ enum v4l2_exposure_auto_type - dynamically vary the frame rate. By default this feature is disabled (0) and the frame rate must remain constant. -``V4L2_CID_EXPOSURE_BIAS (integer menu)`` +``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)`` Determines the automatic exposure compensation, it is effective only when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``, ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in -- cgit From e744ee280311ac220930ae49417b79165c887a3a Mon Sep 17 00:00:00 2001 From: Ramesh Shanmugasundaram Date: Mon, 12 Jun 2017 10:26:17 -0300 Subject: [media] doc_rst: media: New SDR formats PC16, PC18 & PC20 This patch adds documentation for the three new SDR formats V4L2_SDR_FMT_PCU16BE V4L2_SDR_FMT_PCU18BE V4L2_SDR_FMT_PCU20BE Signed-off-by: Ramesh Shanmugasundaram Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../media/uapi/v4l/pixfmt-sdr-pcu16be.rst | 55 ++++++++++++++++++++++ .../media/uapi/v4l/pixfmt-sdr-pcu18be.rst | 55 ++++++++++++++++++++++ .../media/uapi/v4l/pixfmt-sdr-pcu20be.rst | 54 +++++++++++++++++++++ Documentation/media/uapi/v4l/sdr-formats.rst | 3 ++ 4 files changed, 167 insertions(+) create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst (limited to 'Documentation/media/uapi/v4l') diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst new file mode 100644 index 000000000000..2de1b1a0f517 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-PCU16BE: + +****************************** +V4L2_SDR_FMT_PCU16BE ('PC16') +****************************** + +Planar complex unsigned 16-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 16 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 16 bits, bit 15:2 (14 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[13:6]` + - I'\ :sub:`0[5:0]; B1[1:0]=pad` + - pad + - pad + * - start + 4: + - I'\ :sub:`1[13:6]` + - I'\ :sub:`1[5:0]; B1[1:0]=pad` + - pad + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[13:6]` + - Q'\ :sub:`0[5:0]; B1[1:0]=pad` + - pad + - pad + * - start + offset + 4: + - Q'\ :sub:`1[13:6]` + - Q'\ :sub:`1[5:0]; B1[1:0]=pad` + - pad + - pad diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst new file mode 100644 index 000000000000..da8b26bf6b95 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-PCU18BE: + +****************************** +V4L2_SDR_FMT_PCU18BE ('PC18') +****************************** + +Planar complex unsigned 18-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 18 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 18 bits, bit 17:2 (16 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[17:10]` + - I'\ :sub:`0[9:2]` + - I'\ :sub:`0[1:0]; B2[5:0]=pad` + - pad + * - start + 4: + - I'\ :sub:`1[17:10]` + - I'\ :sub:`1[9:2]` + - I'\ :sub:`1[1:0]; B2[5:0]=pad` + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[17:10]` + - Q'\ :sub:`0[9:2]` + - Q'\ :sub:`0[1:0]; B2[5:0]=pad` + - pad + * - start + offset + 4: + - Q'\ :sub:`1[17:10]` + - Q'\ :sub:`1[9:2]` + - Q'\ :sub:`1[1:0]; B2[5:0]=pad` + - pad diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst new file mode 100644 index 000000000000..5499eed39477 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- +.. _V4L2-SDR-FMT-PCU20BE: + +****************************** +V4L2_SDR_FMT_PCU20BE ('PC20') +****************************** + +Planar complex unsigned 20-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 20 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 20 bits, bit 19:2 (18 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[19:12]` + - I'\ :sub:`0[11:4]` + - I'\ :sub:`0[3:0]; B2[3:0]=pad` + - pad + * - start + 4: + - I'\ :sub:`1[19:12]` + - I'\ :sub:`1[11:4]` + - I'\ :sub:`1[3:0]; B2[3:0]=pad` + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[19:12]` + - Q'\ :sub:`0[11:4]` + - Q'\ :sub:`0[3:0]; B2[3:0]=pad` + - pad + * - start + offset + 4: + - Q'\ :sub:`1[19:12]` + - Q'\ :sub:`1[11:4]` + - Q'\ :sub:`1[3:0]; B2[3:0]=pad` + - pad diff --git a/Documentation/media/uapi/v4l/sdr-formats.rst b/Documentation/media/uapi/v4l/sdr-formats.rst index f863c08f1add..2037f5bad727 100644 --- a/Documentation/media/uapi/v4l/sdr-formats.rst +++ b/Documentation/media/uapi/v4l/sdr-formats.rst @@ -17,3 +17,6 @@ These formats are used for :ref:`SDR ` interface only. pixfmt-sdr-cs08 pixfmt-sdr-cs14le pixfmt-sdr-ru12le + pixfmt-sdr-pcu16be + pixfmt-sdr-pcu18be + pixfmt-sdr-pcu20be -- cgit From e72cb0e79475b0d26625e802846e281a84304c07 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 8 Jun 2017 16:59:58 -0300 Subject: [media] v4l: ctrls: Add a control for digital gain Add V4L2_CID_DIGITAL_GAIN to control explicitly digital gain. We already have analogue gain control which the digital gain control complements. Typically higher quality images are obtained using analogue gain only as the digital gain does not add information to the image (rather it may remove it). Signed-off-by: Sakari Ailus Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/extended-controls.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation/media/uapi/v4l') diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 76c5b1aeaadd..9acc9cad49e2 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -3021,6 +3021,13 @@ Image Process Control IDs The video deinterlacing mode (such as Bob, Weave, ...). The menu items are driver specific and are documented in :ref:`v4l-drivers`. +``V4L2_CID_DIGITAL_GAIN (integer)`` + Digital gain is the value by which all colour components + are multiplied by. Typically the digital gain applied is the + control value divided by e.g. 0x100, meaning that to get no + digital gain the control value needs to be 0x100. The no-gain + configuration is also typically the default. + .. _dv-controls: -- cgit From 371f94490ea97e1bf766ba0d33ffb62f5f5a4ed1 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 9 Jun 2017 10:15:50 -0300 Subject: [media] v4l: controls: Improve documentation for V4L2_CID_GAIN Elaborate the differences between V4L2_CID_GAIN and gain-type specific V4L2_CID_DIGITAL_GAIN and V4L2_CID_ANALOGUE_GAIN. Signed-off-by: Sakari Ailus Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/control.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/media/uapi/v4l') diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index 51112badb804..c1e6adbe83d7 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -137,6 +137,12 @@ Control IDs ``V4L2_CID_GAIN`` ``(integer)`` Gain control. + Primarily used to control gain on e.g. TV tuners but also on + webcams. Most devices control only digital gain with this control + but on some this could include analogue gain as well. Devices that + recognise the difference between digital and analogue gain use + controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. -- cgit From 8780f1d9d696c7f466a0ff2a2016476a7ebf42b6 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 8 May 2017 11:35:06 -0300 Subject: [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 Reviewed-by: Sylwester Nawrocki Acked-by: Sakari Ailus [hans.verkuil@cisco.com: 4.14 -> 4.13 since this would go in for 4.13 after all] Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/vidioc-cropcap.rst | 23 ++++++++++++---------- Documentation/media/uapi/v4l/vidioc-g-crop.rst | 22 ++++++++++++--------- .../media/uapi/v4l/vidioc-g-selection.rst | 22 +++++++++++---------- 3 files changed, 38 insertions(+), 29 deletions(-) (limited to 'Documentation/media/uapi/v4l') 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 ` - ``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 ` 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 ============ -- cgit