From 955f645aea04f3130d39c7889e2c5bd7f6d638a3 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Mon, 12 Dec 2011 18:17:25 -0300 Subject: [PATCH] [media] 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 Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/Makefile | 4 +- Documentation/DocBook/media/v4l/compat.xml | 9 + .../DocBook/media/v4l/dev-subdev.xml | 198 +++++++++++++-- Documentation/DocBook/media/v4l/v4l2.xml | 15 +- .../media/v4l/vidioc-subdev-g-selection.xml | 228 ++++++++++++++++++ 5 files changed, 430 insertions(+), 24 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 6628b4b9cac4..362520992ced 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 d881520e1a54..0fc74ca81f0f 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2417,6 +2417,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;. + @@ -2533,6 +2538,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 0916a7343a16..4afcbbec5eda 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. + As for pad formats, drivers store try and active + rectangles for the selection targets of ACTUAL type . - 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. + On sink pads, cropping is applied relative 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. - 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 requirements may prevent this. - + The scaling operation changes the size of the image by + scaling it to new dimensions. The scaling ratio isn't specified + explicitly, but is implied from the original and scaled image + sizes. Both sizes are represented by &v4l2-rect;. - Cropping behaviour on output pads is not defined. + 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 + 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. + + 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 + contained inside the source image size for the crop + operation. + + 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 + used to round the image size either up or down. +
+ +
+ Types of selection targets + +
+ ACTUAL targets + + ACTUAL targets reflect the actual hardware configuration + at any point of time. There is a BOUNDS target + corresponding to every ACTUAL. +
+ +
+ 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. +
+ +
+ Order of configuration and format propagation + + Inside subdevs, the order of image processing steps will + always be from the sink pad towards the source pad. This is also + reflected in the order in which the configuration must be + 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 + 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 + underlying hardware. + + The coordinates to a step always refer to the actual size + of the previous step. The exception to this rule is the source + compose rectangle, which refers to the sink compose bounds + rectangle --- if it is supported by the hardware. + + + Sink pad format. The user configures the sink pad + format. This format defines the parameters of the image the + entity receives through the pad for further processing. + + Sink pad actual crop selection. The sink pad crop + defines the crop performed to the sink pad format. + + Sink pad actual compose selection. The size of the + sink pad compose rectangle defines the scaling ratio compared + to the size of the sink pad crop rectangle. The location of + the compose rectangle specifies the location of the actual + sink compose rectangle in the sink compose bounds + rectangle. + + Source pad actual crop selection. Crop on the source + pad defines crop performed to the image in the sink compose + bounds rectangle. + + Source pad format. The source pad format defines the + output pixel format of the subdev, as well as the other + parameters with the exception of the image width and height. + Width and height are defined by the size of the source pad + actual crop selection. + + + Accessing any of the above rectangles not supported by the + subdev will return EINVAL. Any rectangle + referring to a previous unsupported rectangle coordinates will + instead refer to the previous supported rectangle. For example, + if sink crop is not supported, the compose selection will refer + to the sink pad format dimensions instead. + +
+ Image processing in subdevs: simple crop example + + + + + +
+ + In the above example, the subdev supports cropping on its + sink pad. To configure it, the user sets the media bus format on + the subdev's sink pad. Now the actual crop rectangle can be set + on the sink pad --- the location and size of this rectangle + reflect the location and size of a rectangle to be cropped from + the sink format. The size of the sink crop rectangle will also + be the size of the format of the subdev's source pad. + +
+ Image processing in subdevs: scaling with multiple sources + + + + + +
+ + In this example, the subdev is capable of first cropping, + then scaling and finally cropping for two source pads + individually from the resulting scaled image. The location of + the scaled image in the cropped image is ignored in sink compose + target. Both of the locations of the source crop rectangles + refer to the sink scaling rectangle, independently cropping an + area at location specified by the source crop rectangle from + it. + +
+ Image processing in subdevs: scaling and composition + with multiple sinks and sources + + + + + +
+ + The subdev driver supports two sink pads and two source + pads. The images from both of the sink pads are individually + cropped, then scaled and further composed on the composition + bounds rectangle. From that, two independent streams are cropped + and sent out of the subdev from the source pads. + +
+ &sub-subdev-formats; diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 864ba5d6873d..fbf808d242f7 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -96,6 +96,17 @@ Remote Controller chapter. + + + Sakari + Ailus + Subdev selections API. + +
+ sakari.ailus@iki.fi +
+ + @@ -131,7 +142,8 @@ applications. --> 3.5 2012-04-02 sa - Added V4L2_CTRL_TYPE_INTEGER_MENU. + Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev + selections API. @@ -548,6 +560,7 @@ and discussions on the V4L mailing list. &sub-subdev-g-crop; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; + &sub-subdev-g-selection; &sub-subscribe-event; &sub-mmap; 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 000000000000..208e9f0da3f3 --- /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 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: 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. +
+ +
+ 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_ACTUAL + 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_ACTUAL + 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. + + + +
+ + + 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> + + &cs-str; + + + __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 + Selection rectangle, in pixels. + + + __u32 + reserved[8] + Reserved for future extensions. Applications and drivers must + set the array to zero. + + + +
+ + + + + &return-value; + + + + EBUSY + + The selection rectangle can't be changed because the + pad is currently busy. This can be caused, for instance, by + an active video stream on the pad. The ioctl must not be + retried without performing another action to fix the problem + first. Only returned by + VIDIOC_SUBDEV_S_SELECTION + + + + EINVAL + + The &v4l2-subdev-selection; + pad references a non-existing + pad, the which field references a + non-existing format, or the selection target is not + supported on the given subdev pad. + + + + +