From patchwork Mon May 30 14:27:18 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 16119 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B9C12C3276 for ; Mon, 30 May 2022 14:27:54 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 4096C65653; Mon, 30 May 2022 16:27:54 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1653920874; bh=O4WPfISxap1qo2Aw7PecJQiEt5HvyOlR1XhKIk0NQgk=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=PeSLrdIJ2SafyY0G2v5A7+1cAdYSkA2qzZw5eHZpNUMLdlygj1/89ilcnn05D7BXk xwiDLUYwCKPlvu+LPDhs8x3cuiYhqSwSYJpYsg1QWo+HECoE4GzpcZMrw1nuRgfYUL ndjf5Idqr94krknjdoZh5xnSLi1kGzOzcWTB3ktI4Lxac8GW2p9jmoDzYRr8c/65IV t7kUDngCV1FmkqYERnN5OemQ9gYODlNjrh4mYqlQU5Fx1FoSWE4yFdF4ycBPu8o285 fOvByihps7OABQyRQ2tcEVaod4onA0DyFA/a177QdarnnI0ceCi3e/HqhCNytOMnKo zgA8KuaGLKYNg== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 68E3965635 for ; Mon, 30 May 2022 16:27:45 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="FoZ1ud/v"; dkim-atps=neutral Received: from deskari.lan (91-156-85-209.elisa-laajakaista.fi [91.156.85.209]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id D20A718ED; Mon, 30 May 2022 16:27:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1653920865; bh=O4WPfISxap1qo2Aw7PecJQiEt5HvyOlR1XhKIk0NQgk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FoZ1ud/vMZlI/ZIBPTCpHAtqVDtcLK/QdGpamOq3SVMtber7Ual+LKB7a/o1o+hBU tGbNIwg0QdkdUS+daN8WMVM4mWNpX8+UEBnYXtdOKwugt/ndUgR8PM24mnriQma76a 3l60mep0OaYfhNCywLTOukIyShQwrz9GnJK6a0xI= To: libcamera-devel@lists.libcamera.org, David Plowman , Kieran Bingham , Laurent Pinchart , Jacopo Mondi Date: Mon, 30 May 2022 17:27:18 +0300 Message-Id: <20220530142722.57618-13-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220530142722.57618-1-tomi.valkeinen@ideasonboard.com> References: <20220530142722.57618-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v4 12/16] Documentation: Add python-bindings.rst X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Tomi Valkeinen via libcamera-devel From: Tomi Valkeinen Reply-To: Tomi Valkeinen Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Add a basic doc for the Python bindings. While not really proper documentation yet, the file and the examples should give enough guidance for users who are somewhat familiar with libcamera. Signed-off-by: Tomi Valkeinen Reviewed-by: Laurent Pinchart --- Documentation/index.rst | 1 + Documentation/meson.build | 1 + Documentation/python-bindings.rst | 70 +++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 Documentation/python-bindings.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index 0ee10044..43d8b017 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -22,3 +22,4 @@ Environment variables Sensor driver requirements Lens driver requirements + Python Bindings diff --git a/Documentation/meson.build b/Documentation/meson.build index 8e2eacc6..7695bcb1 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -67,6 +67,7 @@ if sphinx.found() 'guides/tracing.rst', 'index.rst', 'lens_driver_requirements.rst', + 'python-bindings.rst', 'sensor_driver_requirements.rst', '../README.rst', ] diff --git a/Documentation/python-bindings.rst b/Documentation/python-bindings.rst new file mode 100644 index 00000000..cfa9ec10 --- /dev/null +++ b/Documentation/python-bindings.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. _python-bindings: + +Python Bindings for libcamera +============================= + +*WARNING* The bindings are under work, and the API will change. + +Differences to the C++ API +-------------------------- + +As a rule of thumb the bindings try to follow the C++ API when possible. This +chapter lists the differences. + +Mostly these differences fall under two categories: + +1. Differences caused by the inherent differences between C++ and Python. +These differences are usually caused by the use of threads or differences in +C++ vs Python memory management. + +2. Differences caused by the code being work-in-progress. It's not always +trivial to create a binding in a satisfying way, and the current bindings +contain simplified versions of the C++ API just to get forward. These +differences are expected to eventually go away. + +Coding Style +------------ + +The C++ code for the bindings follows the libcamera coding style as much as +possible. Note that the indentation does not quite follow the clang-format +style, as clang-format makes a mess of the style used. + +The API visible to the Python side follows the Python style as much as possible. + +This means that e.g. ``Camera::generateConfiguration`` maps to +``Camera.generate_configuration``. + +CameraManager +------------- + +The Python API provides a singleton CameraManager via ``CameraManager.singleton()``. +There is no need to start or stop the CameraManager. + +Handling Completed Requests +--------------------------- + +The Python bindings do not expose the ``Camera::requestCompleted`` signal +directly as the signal is invoked from another thread and it has real-time +constraints. Instead the bindings will internally queue the completed +requests and use an eventfd to inform the user that there are completed +requests. + +The user can wait on the eventfd, and upon getting an event, use +``CameraManager.get_ready_requests()`` to clear the eventfd event and to get +the completed requests. + +Controls & Properties +--------------------- + +The classes related to controls and properties are rather complex to implement +directly in the Python bindings. There are some simplifications on the Python +bindings: + +- There is no ControlValue class. Python objects are automatically converted + to ControlValues and vice versa. +- There is no ControlList class. A python dict with ControlId keys and python + object values is used instead. +- There is no ControlInfoMap class. A python dict with ControlId keys and + ControlInfo values is used instead.