From 955f645aea04f3130d39c7889e2c5bd7f6d638a3 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Mon, 12 Dec 2011 18:17:25 -0300 Subject: [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 --- .../media/v4l/vidioc-subdev-g-selection.xml | 228 +++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml (limited to 'Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml') 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. + + + + + -- cgit v1.2.3