From 1d44b6f3fcf6058fb7c960b7558766967e8028f7 Mon Sep 17 00:00:00 2001 From: Anton Arapov Date: Tue, 7 Aug 2012 11:21:50 +0200 Subject: fedora kernel: 222b075b3ff0d9e88aa9353e3c80667756ed7361 Signed-off-by: Anton Arapov --- Documentation/DocBook/media/v4l/dev-subdev.xml | 202 ++++++++++++++++++++++--- 1 file changed, 178 insertions(+), 24 deletions(-) (limited to 'Documentation/DocBook/media/v4l/dev-subdev.xml') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 0916a7343a1..4afcbbec5ed 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 requirements may prevent this. - + As for pad formats, drivers store try and active + rectangles for the selection targets of ACTUAL type . + + 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. + + 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;. + + 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. +
- Cropping behaviour on output pads is not defined. +
+ +
+ 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; -- cgit