From aeda3e7c6524956c616040f4265f16343b3edd83 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 31 May 2012 19:51:05 -0300 Subject: [media] v4l: Correct create_bufs documentation Patch id 6016af82eafcb6e086a8f2a2197b46029a843d68 ("[media] v4l2: use __u32 rather than enums in ioctl() structs") unintentionally changes the type of the format field in struct v4l2_create_buffers from struct v4l2_format to __u32. Revert that change. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 765549ff8a7..7cf3116c2cc 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -108,10 +108,9 @@ information. /> - __u32 + &v4l2-format; format - Filled in by the application, preserved by the driver. - See . + Filled in by the application, preserved by the driver. __u32 -- cgit v1.2.3 From e4cca4edbce693238ba4d75269db082f34da48bb Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 28 May 2012 07:30:28 -0300 Subject: [media] v4l2 spec: document the new v4l2_tuner capabilities Update the spec with the new capabilities and specify new error codes for S_HW_FREQ_SEEK. Signed-off-by: Hans Verkuil Acked-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-frequency.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 12 ++++++++++++ .../DocBook/media/v4l/vidioc-s-hw-freq-seek.xml | 18 +++++++++++++++--- 3 files changed, 33 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 69c178a4d20..40e58a42eb2 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -135,6 +135,12 @@ bounds or the value in the type field is wrong. + + EBUSY + + A hardware seek is in progress. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 62a1aa200a3..95d5371c170 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -275,6 +275,18 @@ can or must be switched. (B/G PAL tuners for example are typically not see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only V4L2_TUNER_ANALOG_TV tuners can have this capability. + + V4L2_TUNER_CAP_HWSEEK_BOUNDED + 0x0004 + If set, then this tuner supports the hardware seek functionality + where the seek stops when it reaches the end of the frequency range. + + + V4L2_TUNER_CAP_HWSEEK_WRAP + 0x0008 + If set, then this tuner supports the hardware seek functionality + where the seek wraps around when it reaches the end of the frequency range. + V4L2_TUNER_CAP_STEREO 0x0010 diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index 407dfceb71f..f4db44d0d95 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -58,6 +58,9 @@ To do this applications initialize the tuner, call the VIDIOC_S_HW_FREQ_SEEK ioctl with a pointer to this structure. + If an error is returned, then the original frequency will + be restored. + This ioctl is supported if the V4L2_CAP_HW_FREQ_SEEK capability is set. @@ -87,7 +90,10 @@ field and the &v4l2-tuner; index field. __u32 wrap_around - If non-zero, wrap around when at the end of the frequency range, else stop seeking. + If non-zero, wrap around when at the end of the frequency range, else stop seeking. + The &v4l2-tuner; capability field will tell you what the + hardware supports. + __u32 @@ -118,9 +124,15 @@ wrong. - EAGAIN + ENODATA + + The hardware seek found no channels. + + + + EBUSY - The ioctl timed-out. Try again. + Another hardware seek is already in progress. -- cgit v1.2.3 From efcf5bdac839f0dc9dc39ed1ad9fe2dbab49d00a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 28 May 2012 07:42:54 -0300 Subject: [media] V4L2 spec: clarify a few modulator issues Signed-off-by: Hans Verkuil Acked-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/common.xml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 4101aeb5654..b91d25313b6 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -464,14 +464,14 @@ The type field of the respective tuner field contains the index number of the tuner. - Radio devices have exactly one tuner with index zero, no + Radio input devices have exactly one tuner with index zero, no video inputs. To query and change tuner properties applications use the &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The &v4l2-tuner; returned by VIDIOC_G_TUNER also contains signal status information applicable when the tuner of the -current video input, or a radio tuner is queried. Note that +current video or radio input is queried. Note that VIDIOC_S_TUNER does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the @@ -491,8 +491,17 @@ the modulator. The type field of the respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is set to V4L2_OUTPUT_TYPE_MODULATOR and its modulator field contains the index number -of the modulator. This specification does not define radio output -devices. +of the modulator. + + Radio output devices have exactly one modulator with index +zero, no video outputs. + + A video or radio device cannot support both a tuner and a +modulator. Two separate device nodes will have to be used for such +hardware, one that supports the tuner functionality and one that supports +the modulator functionality. The reason is a limitation with the +&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency +is for a tuner or a modulator. To query and change modulator properties applications use the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that -- cgit v1.2.3 From f7dd6c247f4318c47677a659dbb4622cc5da0690 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 31 May 2012 05:09:08 -0300 Subject: [media] V4L2 Spec: fix typo: NTSC -> NRSC Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 7c49facecd2..1078e45f189 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -194,7 +194,7 @@ in the frequency range from 87,5 to 108,0 MHz National Radio Systems Committee (http://www.nrscstandards.org) - NTSC-4: United States RBDS Standard + NRSC-4: United States RBDS Standard -- cgit v1.2.3 From 2b719d7baf490e24ce7d817c6337b7c87fda84c1 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 2 May 2012 09:40:03 -0300 Subject: [media] v4l: drop v4l2_buffer.input and V4L2_BUF_FLAG_INPUT Remove input field in struct v4l2_buffer and flag V4L2_BUF_FLAG_INPUT which tells the former is valid. The flag is used by no driver currently. Also change the documentation accordingly. Signed-off-by: Sakari Ailus Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 ++++++++++++ Documentation/DocBook/media/v4l/io.xml | 19 +++++-------------- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 9 +++------ 3 files changed, 20 insertions(+), 20 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ea42ef82494..a8b37493040 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2458,6 +2458,18 @@ details. +
+ V4L2 in Linux 3.5 + + + Replaced input in + v4l2_buffer by + reserved2 and removed + V4L2_BUF_FLAG_INPUT. + + +
+
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index fd6aca2922b..1885cc0755c 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -683,14 +683,12 @@ memory, set by the application. See for details. __u32 - input + reserved2 - Some video capture drivers support rapid and -synchronous video input changes, a function useful for example in -video surveillance applications. For this purpose applications set the -V4L2_BUF_FLAG_INPUT flag, and this field to the -number of a video input as in &v4l2-input; field -index. + A place holder for future extensions and custom +(driver defined) buffer types +V4L2_BUF_TYPE_PRIVATE and higher. Applications +should set this to 0. __u32 @@ -921,13 +919,6 @@ previous key frame. The timecode field is valid. Drivers set or clear this flag when the VIDIOC_DQBUF ioctl is called. - - - V4L2_BUF_FLAG_INPUT - 0x0200 - The input field is valid. -Applications set or clear this flag before calling the -VIDIOC_QBUF ioctl. V4L2_BUF_FLAG_PREPARED diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 9caa49af580..77ff5be0809 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -71,12 +71,9 @@ initialize the bytesused, field and timestamp fields, see for details. -Applications must also set flags to 0. If a driver -supports capturing from specific video inputs and you want to specify a video -input, then flags should be set to -V4L2_BUF_FLAG_INPUT and the field -input must be initialized to the desired input. -The reserved field must be set to 0. When using +Applications must also set flags to 0. +The reserved2 and +reserved fields must be set to 0. When using the multi-planar API, the m.planes field must contain a userspace pointer to a filled-in array of &v4l2-plane; and the length -- cgit v1.2.3 From 5d44f5e3e388739f017a74e73dab2a995673915f Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 22 Jun 2012 05:47:30 -0300 Subject: [media] Spec: document CREATE_BUFS behavior if count == 0 Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a2474ecb574..5e73b1c8d09 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -97,7 +97,13 @@ information. __u32 count - The number of buffers requested or granted. + The number of buffers requested or granted. If count == 0, then + VIDIOC_CREATE_BUFS will set index + to the current number of created buffers, and it will check the validity of + memory and format.type. + If those are invalid -1 is returned and errno is set to &EINVAL;, + otherwise VIDIOC_CREATE_BUFS returns 0. It will + never set errno to &EBUSY; in this particular case. __u32 -- cgit v1.2.3 From c133482300113b3b71fa4a1fd2118531e765b36a Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Sun, 20 May 2012 11:17:12 -0300 Subject: [media] V4L: Remove "_ACTIVE" from the selection target name definitions This patch drops the _ACTIVE part from the selection target names as a prerequisite to unify the selection target names across the subdev and regular video node API. The meaning of V4L2_SEL_TGT_*_ACTIVE and V4L2_SUBDEV_SEL_TGT_*_ACTUAL selection targets is logically the same. Different names add to confusion where both APIs are used in a single driver or an application. For some system configurations different names may lead to interoperability issues. For backwards compatibility V4L2_SEL_TGT_CROP_ACTIVE and V4L2_SEL_TGT_COMPOSE_ACTIVE are defined as aliases to V4L2_SEL_TGT_CROP and V4L2_SEL_TGT_COMPOSE. These aliases will be removed after deprecation period, according to Documentation/feature-removal-schedule.txt. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Acked-by: Laurent Pinchart Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/selection-api.xml | 24 +++++++++++----------- .../DocBook/media/v4l/vidioc-g-selection.xml | 15 +++++++------- 2 files changed, 20 insertions(+), 19 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index b299e477935..ac013e50e0b 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -91,7 +91,7 @@ top/left corner at position (0,0) . The rectangle's coordinates are expressed in pixels. The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by the V4L2_SEL_TGT_CROP_ACTIVE +the area actually sampled, is given by the V4L2_SEL_TGT_CROP target. It uses the same coordinate system as V4L2_SEL_TGT_CROP_BOUNDS . The active cropping area must lie completely inside the capture boundaries. The driver may further adjust the @@ -111,7 +111,7 @@ height are equal to the image size set by VIDIOC_S_FMT . The part of a buffer into which the image is inserted by the hardware is -controlled by the V4L2_SEL_TGT_COMPOSE_ACTIVE target. +controlled by the V4L2_SEL_TGT_COMPOSE target. The rectangle's coordinates are also expressed in the same coordinate system as the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the @@ -125,7 +125,7 @@ bounding rectangle. The part of a buffer that is modified by the hardware is given by V4L2_SEL_TGT_COMPOSE_PADDED . It contains all pixels -defined using V4L2_SEL_TGT_COMPOSE_ACTIVE plus all +defined using V4L2_SEL_TGT_COMPOSE plus all padding data modified by hardware during insertion process. All pixels outside this rectangle must not be changed by the hardware. The content of pixels that lie inside the padded area but outside active area is @@ -153,7 +153,7 @@ specified using VIDIOC_S_FMT ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given by the - V4L2_SEL_TGT_CROP_ACTIVE . Its coordinates are expressed + V4L2_SEL_TGT_CROP . Its coordinates are expressed in in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware @@ -165,7 +165,7 @@ bounding rectangle. The part of a video signal or graphics display where the image is inserted by the hardware is controlled by -V4L2_SEL_TGT_COMPOSE_ACTIVE target. The rectangle's coordinates +V4L2_SEL_TGT_COMPOSE target. The rectangle's coordinates are expressed in pixels. The composing rectangle must lie completely inside the bounds rectangle. The driver must adjust the area to fit to the bounding limits. Moreover, the driver can perform other adjustments according to @@ -184,7 +184,7 @@ such a padded area is driver-dependent feature not covered by this document. Driver developers are encouraged to keep padded rectangle equal to active one. The padded target is accessed by the V4L2_SEL_TGT_COMPOSE_PADDED identifier. It must contain all pixels from the -V4L2_SEL_TGT_COMPOSE_ACTIVE target. +V4L2_SEL_TGT_COMPOSE target.
@@ -193,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE_ACTIVE target. Scaling control An application can detect if scaling is performed by comparing the width -and the height of rectangles obtained using V4L2_SEL_TGT_CROP_ACTIVE - and V4L2_SEL_TGT_COMPOSE_ACTIVE targets. If +and the height of rectangles obtained using V4L2_SEL_TGT_CROP + and V4L2_SEL_TGT_COMPOSE targets. If these are not equal then the scaling is applied. The application can compute the scaling ratios using these values. @@ -252,7 +252,7 @@ area) ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); if (ret) exit(-1); - sel.target = V4L2_SEL_TGT_CROP_ACTIVE; + sel.target = V4L2_SEL_TGT_CROP; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) exit(-1); @@ -281,7 +281,7 @@ area) r.left = sel.r.width / 4; r.top = sel.r.height / 4; sel.r = r; - sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE; + sel.target = V4L2_SEL_TGT_COMPOSE; sel.flags = V4L2_SEL_FLAG_LE; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) @@ -298,11 +298,11 @@ V4L2_BUF_TYPE_VIDEO_OUTPUT for other devices &v4l2-selection; compose = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_COMPOSE_ACTIVE, + .target = V4L2_SEL_TGT_COMPOSE, }; &v4l2-selection; crop = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_CROP_ACTIVE, + .target = V4L2_SEL_TGT_CROP, }; double hscale, vscale; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index bb04eff75f4..6376e57ff57 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -65,8 +65,8 @@ Do not use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE . Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is setting the value of &v4l2-selection; target field -to V4L2_SEL_TGT_CROP_ACTIVE ( -V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table V4L2_SEL_TGT_CROP ( +V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional targets. The flags and reserved fields of &v4l2-selection; are ignored and they must be filled @@ -86,8 +86,8 @@ use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE . Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is setting the value of &v4l2-selection; target to -V4L2_SEL_TGT_CROP_ACTIVE ( -V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table V4L2_SEL_TGT_CROP ( +V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional targets. The &v4l2-rect; r rectangle need to be set to the desired active area. Field &v4l2-selection; reserved @@ -161,7 +161,7 @@ exist no rectangle that satisfies the constraints. &cs-def; - V4L2_SEL_TGT_CROP_ACTIVE + V4L2_SEL_TGT_CROP 0x0000 The area that is currently cropped by hardware. @@ -176,7 +176,7 @@ exist no rectangle that satisfies the constraints.Limits for the cropping rectangle. - V4L2_SEL_TGT_COMPOSE_ACTIVE + V4L2_SEL_TGT_COMPOSE 0x0100 The area to which data is composed by hardware. @@ -193,7 +193,8 @@ exist no rectangle that satisfies the constraints. V4L2_SEL_TGT_COMPOSE_PADDED 0x0103 - The active area and all padding pixels that are inserted or modified by hardware. + The active area and all padding pixels that are inserted or + modified by hardware. -- cgit v1.2.3 From 1ec0ed083988ae433305d7f4158fda8c3a1a23b9 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 17 May 2012 17:50:45 -0300 Subject: [media] v4l: Remove "_ACTUAL" from subdev selection API target definition names The string "_ACTUAL" does not say anything more about the target names. Drop it. V4L2 selection API was changed by "V4L: Remove "_ACTIVE" from the selection target name definitions" by Sylwester Nawrocki. This patch does the same for the V4L2 subdev API. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/dev-subdev.xml | 28 +++++++++++----------- .../media/v4l/vidioc-subdev-g-selection.xml | 12 +++++----- 2 files changed, 20 insertions(+), 20 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 4afcbbec5ed..e88d5ea8f82 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -289,9 +289,9 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - As for pad formats, drivers store try and active - rectangles for the selection targets of ACTUAL type . + As for pad formats, drivers store try and active rectangles for + the selection targets . On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ Scaling support is optional. When supported by a subdev, the crop rectangle on the subdev's sink pad is scaled to the size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using V4L2_SUBDEV_SEL_COMPOSE_ACTUAL + using V4L2_SUBDEV_SEL_TGT_COMPOSE selection target on the same pad. If the subdev supports scaling but not composing, the top and left values are not used and must always be set to zero. @@ -333,22 +333,22 @@ Types of selection targets
- ACTUAL targets + Actual targets - ACTUAL targets reflect the actual hardware configuration - at any point of time. There is a BOUNDS target - corresponding to every ACTUAL. + Actual targets (without a postfix) reflect the actual + hardware configuration at any point of time. There is a BOUNDS + target corresponding to every actual target.
BOUNDS targets - BOUNDS targets is the smallest rectangle that contains - all valid ACTUAL rectangles. It may not be possible to set the - ACTUAL rectangle as large as the BOUNDS rectangle, however. - This may be because e.g. a sensor's pixel array is not - rectangular but cross-shaped or round. The maximum size may - also be smaller than the BOUNDS rectangle. + BOUNDS targets is the smallest rectangle that contains all + valid actual rectangles. It may not be possible to set the actual + rectangle as large as the BOUNDS rectangle, however. This may be + because e.g. a sensor's pixel array is not rectangular but + cross-shaped or round. The maximum size may also be smaller than the + BOUNDS rectangle.
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 208e9f0da3f..4c44808ab25 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -72,10 +72,10 @@
Types of selection targets - There are two types of selection targets: actual and bounds. - The ACTUAL targets are the targets which configure the hardware. - The BOUNDS target will return a rectangle that contain all - possible ACTUAL rectangles. + There are two types of selection targets: actual and bounds. The + actual targets are the targets which configure the hardware. The BOUNDS + target will return a rectangle that contain all possible actual + rectangles.
@@ -93,7 +93,7 @@ &cs-def;
- V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL + V4L2_SUBDEV_SEL_TGT_CROP 0x0000 Actual crop. Defines the cropping performed by the processing step. @@ -104,7 +104,7 @@ Bounds of the crop rectangle. - V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL + V4L2_SUBDEV_SEL_TGT_COMPOSE 0x0100 Actual compose rectangle. Used to configure scaling on sink pads and composition on source pads. -- cgit v1.2.3 From 64b9ce83a446277d3ffdb5e25e9aeb66442da2a9 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 1 Jun 2012 13:56:53 -0300 Subject: [media] v4l: Common documentation for selection targets Both V4L2 and V4L2 subdev interface have very similar selection APIs with differences foremost related to in-memory and media bus formats. However, the selection targets are the same for both. Most targets are and in the future will likely continue to be more the same than with any differences. Thus it makes sense to unify the documentation of the targets. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 9 ++- Documentation/DocBook/media/v4l/dev-subdev.xml | 12 +-- Documentation/DocBook/media/v4l/selection-api.xml | 6 +- .../DocBook/media/v4l/selections-common.xml | 92 ++++++++++++++++++++++ Documentation/DocBook/media/v4l/v4l2.xml | 5 ++ .../DocBook/media/v4l/vidioc-g-selection.xml | 54 ++----------- .../media/v4l/vidioc-subdev-g-selection.xml | 34 +------- 7 files changed, 119 insertions(+), 93 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/selections-common.xml (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index a8b37493040..97b895151bb 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2377,10 +2377,11 @@ that used it. It was originally scheduled for removal in 2.6.35. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace. - Add selection API for extended control over cropping and -composing. Does not affect the compatibility of current drivers and -applications. See selection API for -details. + Add selection API for extended control over cropping + and composing. Does not affect the compatibility of current + drivers and applications. See selection API for + details. diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index e88d5ea8f82..afeb196adce 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -276,7 +276,7 @@ -
+
Selections: cropping, scaling and composition Many sub-devices support cropping frames on their input or output @@ -289,9 +289,9 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - As for pad formats, drivers store try and active rectangles for - the selection targets . + As for pad formats, drivers store try and active + rectangles for the selection targets . On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ Scaling support is optional. When supported by a subdev, the crop rectangle on the subdev's sink pad is scaled to the size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using V4L2_SUBDEV_SEL_TGT_COMPOSE + using V4L2_SEL_TGT_COMPOSE selection target on the same pad. If the subdev supports scaling but not composing, the top and left values are not used and must always be set to zero. @@ -362,7 +362,7 @@ performed by the user: the changes made will be propagated to any subsequent stages. If this behaviour is not desired, the user must set - V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG flag. This + V4L2_SEL_FLAG_KEEP_CONFIG flag. This flag causes no propagation of the changes are allowed in any circumstances. This may also cause the accessed rectangle to be adjusted by the driver, depending on the properties of the diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index ac013e50e0b..24dec10259d 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -53,11 +53,11 @@ cropping and composing rectangles have the same size. -For complete list of the available selection targets see table -
+ See for more + information. +
Configuration diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml new file mode 100644 index 00000000000..6728688d28d --- /dev/null +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -0,0 +1,92 @@ +
+ + Selection targets + + While the V4L2 selection + API and V4L2 subdev + selection APIs are very similar, there's one fundamental + difference between the two. On sub-device API, the selection + rectangle refers to the media bus format, and is bound to a + 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. + +
+ 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 + + + +
+ diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 008c2d73a48..36bafc48e03 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -589,6 +589,11 @@ and discussions on the V4L mailing list. &sub-write; + + Common definitions for V4L2 and V4L2 subdev interfaces + &sub-selections-common; + + Video For Linux Two Header File &sub-videodev2-h; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index 6376e57ff57..c6f83257ece 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -67,7 +67,7 @@ Do not use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target field to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The flags and reserved fields of &v4l2-selection; are ignored and they must be filled with zeros. The driver fills the rest of the structure or @@ -88,7 +88,7 @@ use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The &v4l2-rect; r rectangle need to be set to the desired active area. Field &v4l2-selection; reserved is ignored and must be filled with zeros. The driver may adjust @@ -154,52 +154,8 @@ exist no rectangle that satisfies the constraints. - - - Selection targets. - - &cs-def; - - - V4L2_SEL_TGT_CROP - 0x0000 - The area that is currently cropped by hardware. - - - V4L2_SEL_TGT_CROP_DEFAULT - 0x0001 - Suggested cropping rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_CROP_BOUNDS - 0x0002 - Limits for the cropping rectangle. - - - V4L2_SEL_TGT_COMPOSE - 0x0100 - The area to which data is composed by hardware. - - - V4L2_SEL_TGT_COMPOSE_DEFAULT - 0x0101 - Suggested composing rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Limits for the composing rectangle. - - - V4L2_SEL_TGT_COMPOSE_PADDED - 0x0103 - The active area and all padding pixels that are inserted or - modified by hardware. - - - -
- + Selection targets are documented in . @@ -253,7 +209,7 @@ exist no rectangle that satisfies the constraints. __u32 target - Used to select between cropping + Used to select between cropping and composing rectangles. diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 4c44808ab25..ace147806e4 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -87,36 +87,8 @@ EINVAL. -
- V4L2 subdev selection targets - - &cs-def; - - - V4L2_SUBDEV_SEL_TGT_CROP - 0x0000 - Actual crop. Defines the cropping - performed by the processing step. - - - V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS - 0x0002 - Bounds of the crop rectangle. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE - 0x0100 - Actual compose rectangle. Used to configure scaling - on sink pads and composition on source pads. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Bounds of the compose rectangle. - - - -
+ Selection targets are documented in . V4L2 subdev selection flags @@ -173,7 +145,7 @@ __u32targetTarget selection rectangle. See - .. + . __u32 -- cgit v1.2.3 From 9fe75aac380bb0399756a14d14f29346a020a647 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 13 Jun 2012 16:01:10 -0300 Subject: [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 --- Documentation/DocBook/media/v4l/dev-subdev.xml | 6 +- Documentation/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(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index afeb196adce..a3d9dd09326 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 24dec10259d..e7ed5077834 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 6728688d28d..b6618709ee7 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 c6f83257ece..f76d8a6d9b9 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 ace147806e4..f33cc814a01 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; -- cgit v1.2.3 From 9a70d980d038e27828db92cef235fabfb618c77d Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 15 Jun 2012 10:22:25 -0300 Subject: [media] v4l: Correct conflicting V4L2 subdev selection API documentation The API reference documents that the KEEP_CONFIG flag tells the configuration should not be propagated by the driver whereas the interface documentation (dev-subdev.xml) prohibited any changes to the rest of the pipeline. Resolve the conflict by changing the API reference to disallow changes. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/selections-common.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index b6618709ee7..7502f784b8c 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -148,7 +148,7 @@ V4L2_SEL_FLAG_KEEP_CONFIG (1 << 2) - The configuration should not be propagated to any + The configuration must 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. -- cgit v1.2.3