From 9fe75aac380bb0399756a14d14f29346a020a647 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 13 Jun 2012 16:01:10 -0300 Subject: [PATCH] [media] v4l: Unify selection flags documentation As for the selection targets, the selection flags are now the same on V4L2 and V4L2 subdev interfaces. Also document them so. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/dev-subdev.xml | 6 +- .../DocBook/media/v4l/selection-api.xml | 6 +- .../DocBook/media/v4l/selections-common.xml | 226 ++++++++++++------ .../DocBook/media/v4l/vidioc-g-selection.xml | 27 +-- .../media/v4l/vidioc-subdev-g-selection.xml | 39 +-- 5 files changed, 159 insertions(+), 145 deletions(-) diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index afeb196adce5..a3d9dd093268 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -323,10 +323,10 @@ The drivers should always use the closest possible rectangle the user requests on all selection targets, unless specifically told otherwise. - V4L2_SUBDEV_SEL_FLAG_SIZE_GE and - V4L2_SUBDEV_SEL_FLAG_SIZE_LE flags may be + V4L2_SEL_FLAG_GE and + V4L2_SEL_FLAG_LE flags may be used to round the image size either up or down. + linkend="v4l2-selection-flags" />
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index 24dec10259d2..e7ed5077834d 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -55,7 +55,7 @@ cropping and composing rectangles have the same size.
- See for more + See for more information.
@@ -74,7 +74,7 @@ cropping/composing rectangles may have to be aligned, and both the source and the sink may have arbitrary upper and lower size limits. Therefore, as usual, drivers are expected to adjust the requested parameters and return the actual values selected. An application can control the rounding behaviour using constraint flags . +linkend="v4l2-selection-flags"> constraint flags .
@@ -117,7 +117,7 @@ the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the bounding limits. Moreover, the driver can perform other adjustments according to hardware limitations. The application can control rounding behaviour using - constraint flags . + constraint flags . For capture devices the default composing rectangle is queried using V4L2_SEL_TGT_COMPOSE_DEFAULT . It is usually equal to the diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index 6728688d28df..b6618709ee7a 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -1,6 +1,6 @@
- Selection targets + Common selection definitions While the V4L2 selection API and V4L2 subdev @@ -10,83 +10,155 @@ sub-device's pad. On the V4L2 interface the selection rectangles refer to the in-memory pixel format. - The precise meaning of the selection targets may thus be - affected on which of the two interfaces they are used. + This section defines the common definitions of the + selection interfaces on the two APIs. - - Selection target definitions - - - - - - - &cs-def; - - - Target name - id - Definition - Valid for V4L2 - Valid for V4L2 subdev - - - - - V4L2_SEL_TGT_CROP - 0x0000 - Crop rectangle. Defines the cropped area. - Yes - Yes - - - V4L2_SEL_TGT_CROP_DEFAULT - 0x0001 - Suggested cropping rectangle that covers the "whole picture". - Yes - No - - - V4L2_SEL_TGT_CROP_BOUNDS - 0x0002 - Bounds of the crop rectangle. All valid crop - rectangles fit inside the crop bounds rectangle. - - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE - 0x0100 - Compose rectangle. Used to configure scaling - and composition. - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE_DEFAULT - 0x0101 - Suggested composition rectangle that covers the "whole picture". - Yes - No - - - V4L2_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Bounds of the compose rectangle. All valid compose - rectangles fit inside the compose bounds rectangle. - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE_PADDED - 0x0103 - The active area and all padding pixels that are inserted or +
+ + Selection targets + + The precise meaning of the selection targets may be + dependent on which of the two interfaces they are used. + +
+ Selection target definitions + + + + + + + &cs-def; + + + Target name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev + + + + + V4L2_SEL_TGT_CROP + 0x0000 + Crop rectangle. Defines the cropped area. + Yes + Yes + + + V4L2_SEL_TGT_CROP_DEFAULT + 0x0001 + Suggested cropping rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_CROP_BOUNDS + 0x0002 + Bounds of the crop rectangle. All valid crop + rectangles fit inside the crop bounds rectangle. + + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE + 0x0100 + Compose rectangle. Used to configure scaling + and composition. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_DEFAULT + 0x0101 + Suggested composition rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_COMPOSE_BOUNDS + 0x0102 + Bounds of the compose rectangle. All valid compose + rectangles fit inside the compose bounds rectangle. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_PADDED + 0x0103 + The active area and all padding pixels that are inserted or modified by hardware. - Yes - No + Yes + No + + + +
+ +
+ +
+ + Selection flags + + + Selection flag definitions + + + + + + + &cs-def; + + + Flag name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev - - -
+ + + + V4L2_SEL_FLAG_GE + (1 << 0) + Suggest the driver it should choose greater or + equal rectangle (in size) than was requested. Albeit the + driver may choose a lesser size, it will only do so due to + hardware limitations. Without this flag (and + V4L2_SEL_FLAG_LE) the + behaviour is to choose the closest possible + rectangle. + Yes + Yes + + + V4L2_SEL_FLAG_LE + (1 << 1) + Suggest the driver it + should choose lesser or equal rectangle (in size) than was + requested. Albeit the driver may choose a greater size, it + will only do so due to hardware limitations. + Yes + Yes + + + V4L2_SEL_FLAG_KEEP_CONFIG + (1 << 2) + The configuration should not be propagated to any + further processing steps. If this flag is not given, the + configuration is propagated inside the subdevice to all + further processing steps. + No + Yes + + + + + +
+
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index c6f83257ecee..f76d8a6d9b92 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -154,32 +154,9 @@ exist no rectangle that satisfies the constraints. - Selection targets are documented in Selection targets and flags are documented in . - - - Selection constraint flags - - &cs-def; - - - V4L2_SEL_FLAG_GE - 0x00000001 - Indicates that the adjusted rectangle must contain the original - &v4l2-selection; r rectangle. - - - V4L2_SEL_FLAG_LE - 0x00000002 - Indicates that the adjusted rectangle must be inside the original - &v4l2-rect; r rectangle. - - - -
- -
Size adjustments with constraint flags. @@ -216,7 +193,7 @@ exist no rectangle that satisfies the constraints. __u32 flags Flags controlling the selection rectangle adjustments, refer to - selection flags. + selection flags. &v4l2-rect; diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index ace147806e48..f33cc814a01d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -87,44 +87,9 @@ EINVAL.
- Selection targets are documented in Selection targets and flags are documented in . - - V4L2 subdev selection flags - - &cs-def; - - - V4L2_SUBDEV_SEL_FLAG_SIZE_GE - (1 << 0) Suggest the driver it - should choose greater or equal rectangle (in size) than - was requested. Albeit the driver may choose a lesser size, - it will only do so due to hardware limitations. Without - this flag (and - V4L2_SUBDEV_SEL_FLAG_SIZE_LE) the - behaviour is to choose the closest possible - rectangle. - - - V4L2_SUBDEV_SEL_FLAG_SIZE_LE - (1 << 1) Suggest the driver it - should choose lesser or equal rectangle (in size) than was - requested. Albeit the driver may choose a greater size, it - will only do so due to hardware limitations. - - - V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG - (1 << 2) - The configuration should not be propagated to any - further processing steps. If this flag is not given, the - configuration is propagated inside the subdevice to all - further processing steps. - - - -
- struct <structname>v4l2_subdev_selection</structname> @@ -151,7 +116,7 @@ __u32 flags Flags. See - . + . &v4l2-rect; -- 2.20.1