Re: [PATCH v5 09/35] v4l: Add subdev selections documentation
Hi Sylwester, Thanks for the comment! On Thu, Mar 15, 2012 at 10:55:25AM +0100, Sylwester Nawrocki wrote: ... > > + > > + > > + __u32 > > + which > > + Active or try selection, from > > + &v4l2-subdev-format-whence;. > > + > > + > > + __u32 > > + pad > > + Pad number as reported by the media framework. > > + > > + > > + __u32 > > + target > > + Target selection rectangle. See > > + .. > > + > > + > > + __u32 > > + flags > > + Flags. See > > + . > > + > > + > > + &v4l2-rect; > > + rect > > + Crop rectangle boundaries, in pixels. > > Shouldn't it be "Selection rectangle, in pixels." ? Indeed. Fixed and pushed to my git.linuxtv.org tree. Nothing changes in the pull req so I won't send a new one. :-) Cheers, -- Sakari Ailus e-mail: sakari.ai...@iki.fi jabber/XMPP/Gmail: sai...@retiisi.org.uk -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v5 09/35] v4l: Add subdev selections documentation
Hi Sakari, On 03/06/2012 05:32 PM, Sakari Ailus wrote: > Add documentation for V4L2 subdev selection API. This changes also > experimental V4L2 subdev API so that scaling now works through selection API > only. > > Signed-off-by: Sakari Ailus > --- > Documentation/DocBook/media/Makefile |4 +- > Documentation/DocBook/media/v4l/compat.xml |9 + > Documentation/DocBook/media/v4l/dev-subdev.xml | 202 +++-- > Documentation/DocBook/media/v4l/v4l2.xml | 17 ++- > .../media/v4l/vidioc-subdev-g-selection.xml| 228 > > 5 files changed, 433 insertions(+), 27 deletions(-) > cre ate mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml [snip] > diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml > b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml > new file mode 100644 > index 000..9164b85 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml > @@ -0,0 +1,228 @@ > + > + > +ioctl VIDIOC_SUBDEV_G_SELECTION, > VIDIOC_SUBDEV_S_SELECTION > +&manvol; > + > + > + > +VIDIOC_SUBDEV_G_SELECTION > +VIDIOC_SUBDEV_S_SELECTION > +Get or set selection rectangles on a subdev pad > + > + > + > + > + > + int ioctl > + int fd > + int request > + struct v4l2_subdev_selection > *argp > + > + > + > + > + > +Arguments > + > + > + > + fd > + > + &fd; > + > + > + > + request > + > + VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION > + > + > + > + argp > + > + > + > + > + > + > + > + > +Description > + > + > + Experimental > + This is an experimental > + interface and may change in the future. > + > + > +The selections are used to configure various image > +processing functionality performed by the subdevs which affect the > +image size. This currently includes cropping, scaling and > +composition. > + > +The selection API replaces +linkend="vidioc-subdev-g-crop">the old subdev crop API. All > +the function of the crop API, and more, are supported by the > +selections API. > + > +See for > +more information on how each selection target affects the image > +processing pipeline inside the subdevice. > + > + > + Types of selection targets > + > + There are two types of selection targets: active and bounds. > + The ACTIVE targets are the targets which configure the hardware. > + The BOUNDS target will return a rectangle that contain all > + possible ACTIVE rectangles. > + > + > + > + Discovering supported features > + > + To discover which targets are supported, the user can > + perform VIDIOC_SUBDEV_G_SELECTION on them. > + Any unsupported target will return > + EINVAL. > + > + > + > + V4L2 subdev selection targets > + > +&cs-def; > + > + > + V4L2_SUBDEV_SEL_TGT_CROP_ACTIVE > + 0x > + Active 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_ACTIVE > + 0x0100 > + Active 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. > + > + > + > + > + > + > + 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. > + > + > + > + > + > + > + s
Re: [PATCH v5 09/35] v4l: Add subdev selections documentation
Hi Michael, Thanks for the comments. On Wed, Mar 07, 2012 at 09:53:42AM +0100, Michael Jones wrote: > Hi Sakari, > > Hopefully it's not too late to make a few minor suggestions. > > On 03/06/2012 05:32 PM, Sakari Ailus wrote: > >Add documentation for V4L2 subdev selection API. This changes also > >experimental V4L2 subdev API so that scaling now works through selection API > >only. > > > >Signed-off-by: Sakari Ailus > [snip] > >+ > >+On sink pads, cropping is applied relatively to the > > s/relatively/relative/ > > >+ current pad format. The pad format represents the image size as > >+ received by the sub-device from the previous block in the > >+ pipeline, and the crop rectangle represents the sub-image that > >+ will be transmitted further inside the sub-device for > >+ processing. > [snip] > >+On source pads, cropping is similar to sink pads, with the > >+ exception that the source size from which the cropping is > >+ performed, is the COMPOSE rectangle on the sink pad. In both > >+ sink and source pads, the crop rectangle must be entirely > >+ containted inside the source image size for the crop > > s/containted/contained/ > > >+ operation. > >+ > >+The drivers should always use the closest possible > >+ rectangle the user requests on all selection targets, unless > >+ specificly told otherwise. > > s/specificly/specifically/ > > >+V4L2_SUBDEV_SEL_FLAG_SIZE_GE and > >+V4L2_SUBDEV_SEL_FLAG_SIZE_LE flags may be > >+ used to round the image size either up or down. >+ linkend="v4l2-subdev-selection-flags"> > >+ > > [snip] > > >+V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG flag. This > >+ flag causes that no propagation of the changes are allowed in > >+ any circumstances. This may also cause the accessed rectangle to > > "This flag causes that" sounds ungrammatical. I suggest: "This flag > causes no propagation of the changes to be allowed under any > circumstances." Applied all of them. Cheers, -- Sakari Ailus e-mail: sakari.ai...@iki.fi jabber/XMPP/Gmail: sai...@retiisi.org.uk -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v5 09/35] v4l: Add subdev selections documentation
Hi Sakari, Hopefully it's not too late to make a few minor suggestions. On 03/06/2012 05:32 PM, Sakari Ailus wrote: Add documentation for V4L2 subdev selection API. This changes also experimental V4L2 subdev API so that scaling now works through selection API only. Signed-off-by: Sakari Ailus [snip] + +On sink pads, cropping is applied relatively to the s/relatively/relative/ + current pad format. The pad format represents the image size as + received by the sub-device from the previous block in the + pipeline, and the crop rectangle represents the sub-image that + will be transmitted further inside the sub-device for + processing. [snip] +On source pads, cropping is similar to sink pads, with the + exception that the source size from which the cropping is + performed, is the COMPOSE rectangle on the sink pad. In both + sink and source pads, the crop rectangle must be entirely + containted inside the source image size for the crop s/containted/contained/ + operation. + +The drivers should always use the closest possible + rectangle the user requests on all selection targets, unless + specificly told otherwise. s/specificly/specifically/ +V4L2_SUBDEV_SEL_FLAG_SIZE_GE and +V4L2_SUBDEV_SEL_FLAG_SIZE_LE flags may be + used to round the image size either up or down. + [snip] +V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG flag. This + flag causes that no propagation of the changes are allowed in + any circumstances. This may also cause the accessed rectangle to "This flag causes that" sounds ungrammatical. I suggest: "This flag causes no propagation of the changes to be allowed under any circumstances." [snip] Michael MATRIX VISION GmbH, Talstrasse 16, DE-71570 Oppenweiler Registergericht: Amtsgericht Stuttgart, HRB 271090 Geschaeftsfuehrer: Gerhard Thullner, Werner Armingeon, Uwe Furtner, Erhard Meier -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v5 09/35] v4l: Add subdev selections documentation
Hi Sakari, Thanks for the patch. On Tuesday 06 March 2012 18:32:50 Sakari Ailus wrote: > Add documentation for V4L2 subdev selection API. This changes also > experimental V4L2 subdev API so that scaling now works through selection API > only. > > Signed-off-by: Sakari Ailus Acked-by: Laurent Pinchart (pending a possible rename of ACTIVE to something else) -- Regards, Laurent Pinchart -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 09/35] v4l: Add subdev selections documentation
Add documentation for V4L2 subdev selection API. This changes also experimental V4L2 subdev API so that scaling now works through selection API only. Signed-off-by: Sakari Ailus --- Documentation/DocBook/media/Makefile |4 +- Documentation/DocBook/media/v4l/compat.xml |9 + Documentation/DocBook/media/v4l/dev-subdev.xml | 202 +++-- Documentation/DocBook/media/v4l/v4l2.xml | 17 ++- .../media/v4l/vidioc-subdev-g-selection.xml| 228 5 files changed, 433 insertions(+), 27 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 6628b4b..3625209 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -70,6 +70,8 @@ IOCTLS = \ VIDIOC_SUBDEV_ENUM_MBUS_CODE \ VIDIOC_SUBDEV_ENUM_FRAME_SIZE \ VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \ + VIDIOC_SUBDEV_G_SELECTION \ + VIDIOC_SUBDEV_S_SELECTION \ TYPES = \ $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \ @@ -193,7 +195,7 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)cp $(OBJIMGFILES) $(MEDIA_OBJ_DIR)/media_api + $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 8cd5c96..603fa4ad 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2407,6 +2407,11 @@ details. Added integer menus, the new type will be V4L2_CTRL_TYPE_INTEGER_MENU. + + Added selection API for V4L2 subdev interface: + &VIDIOC-SUBDEV-G-SELECTION; and + &VIDIOC-SUBDEV-S-SELECTION;. + @@ -2523,6 +2528,10 @@ ioctls. Selection API. + + Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION; + and &VIDIOC-SUBDEV-S-SELECTION; ioctls. + diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 0916a73..f4c623e 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -76,11 +76,12 @@ format means the combination of media bus data format, frame width and frame height. -Image formats are typically negotiated on video capture and output -devices using the cropping and scaling ioctls. -The driver is responsible for configuring every block in the video pipeline -according to the requested format at the pipeline input and/or -output. +Image formats are typically negotiated on video capture and +output devices using the format and selection ioctls. The +driver is responsible for configuring every block in the video +pipeline according to the requested format at the pipeline input +and/or output. For complex devices, such as often found in embedded systems, identical image sizes at the output of a pipeline can be achieved using @@ -276,11 +277,11 @@ - Cropping and scaling + Selections: cropping, scaling and composition Many sub-devices support cropping frames on their input or output pads (or possible even on both). Cropping is used to select the area of - interest in an image, typically on a video sensor or video decoder. It can + interest in an image, typically on an image sensor or a video decoder. It can also be used as part of digital zoom implementations to select the area of the image that will be scaled up. @@ -288,26 +289,179 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - The crop rectangle is retrieved and set using the - &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad - formats, drivers store try and active crop rectangles. The format - negotiation mechanism applies to crop settings as well. - - On input pads, cropping is applied relatively to the current pad - format. The pad format represents the image size as received by the - sub-device from the previous block in the pipeline, and the crop rectangle - represents the sub-image that will be transmitted further inside the - sub-device for processing. The crop rectangle be entirely containted - inside the input image size. - - Input crop rectangle are reset to their default value when the input - image format is modified. Drivers should use the input image size as the - crop rectangle default value, but hardware req
