From patchwork Thu Dec 17 08:40:15 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 7870531 X-Patchwork-Delegate: geert@linux-m68k.org Return-Path: X-Original-To: patchwork-linux-sh@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id EDADEBEEE5 for ; Thu, 17 Dec 2015 08:41:26 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 0B719203F3 for ; Thu, 17 Dec 2015 08:41:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 1B9532040F for ; Thu, 17 Dec 2015 08:41:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755429AbbLQIlV (ORCPT ); Thu, 17 Dec 2015 03:41:21 -0500 Received: from galahad.ideasonboard.com ([185.26.127.97]:44652 "EHLO galahad.ideasonboard.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933390AbbLQIlS (ORCPT ); Thu, 17 Dec 2015 03:41:18 -0500 Received: from avalon.ideasonboard.com (unknown [207.140.26.138]) by galahad.ideasonboard.com (Postfix) with ESMTPSA id CF54420395; Thu, 17 Dec 2015 09:41:14 +0100 (CET) From: Laurent Pinchart To: linux-media@vger.kernel.org Cc: linux-sh@vger.kernel.org Subject: [PATCH/RFC 37/48] DocBook: media: Document the subdev selection API Date: Thu, 17 Dec 2015 10:40:15 +0200 Message-Id: <1450341626-6695-38-git-send-email-laurent.pinchart+renesas@ideasonboard.com> X-Mailer: git-send-email 2.4.10 In-Reply-To: <1450341626-6695-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> References: <1450341626-6695-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> Sender: linux-sh-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-sh@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Now that the subdev crop API is considered obsolete, the selection API that replaces it deserves a full documentation instead of referring to the crop API documentation. Signed-off-by: Laurent Pinchart --- .../media/v4l/vidioc-subdev-g-selection.xml | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index c62a7360719b..9b59b49db0c3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -69,6 +69,43 @@ more information on how each selection target affects the image processing pipeline inside the subdevice. + To retrieve a current selection rectangle applications set the + pad field of a &v4l2-subdev-selection; to the + desired pad number as reported by the media API, the + which field to + V4L2_SUBDEV_FORMAT_ACTIVE and the + target to the target selection rectangle. They + then call the VIDIOC_SUBDEV_G_SELECTION ioctl with a + pointer to this structure. The driver fills the members of the + r field or returns &EINVAL; if the input + arguments are invalid, or if selection is not supported on the given pad. + + + To change a current selection rectangle applications set the + pad, which and + target fields and all members of the + r field. They then call the + VIDIOC_SUBDEV_S_SELECTION ioctl with a pointer to this + structure. The driver verifies the requested selection rectangle, adjusts it + based on the hardware capabilities and configures the device. Upon return + the &v4l2-subdev-selection; contains the current selection rectangle as + would be returned by a VIDIOC_SUBDEV_G_SELECTION call. + + + Applications can query the device capabilities by setting the + which to + V4L2_SUBDEV_FORMAT_TRY. When set, 'try' selection + rectangles are not applied to the device by the driver, but are mangled + exactly as active selection rectangles and stored in the sub-device file + handle. Two applications querying the same sub-device would thus not + interfere with each other. + + Drivers must not return an error solely because the requested + selection rectangle doesn't match the device capabilities. They must instead + modify the rectangle to match what the hardware can provide. The modified + selection rectangle should be as close as possible to the original request. + + Types of selection targets