From patchwork Wed Jun 8 07:24:15 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 16180 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 21E57C326B for ; Wed, 8 Jun 2022 07:24:44 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id A89B465643; Wed, 8 Jun 2022 09:24:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1654673083; bh=ZerpC6qWLVXQO4+Oe2e1AGXdEBr8pAzdJmXxp8KMZW0=; 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=YtRAcv79PV6g+mwd5UM4XrazT8+KAVMwqwXENflkw8aNaSjvnhtv4dgTXhPqqJMVu 2Kraw6rlWCTI7G4xbamSk3HgTfEo3f1cqtIAsUlUwXvvINYIpCF5++mlGWlT6ulrge 5R9/xXxs6zWMTBZ+bv9WnPuQ3QFQZyNs2MFuqSzT5PRGoy4focvCjWBn4GC158TGp5 5HRn/TlG6umNZOgsQNsAx/rJPVIhyZgl1O2HRpyhqoau/2y2RiJV5ebMRdv1WW5Ypy iRm8iHrslmKw7jFj4xPA1yxw2OuUqflzhPPzF6AQy7U9urtS22zLkiAm/B9ZuLk9Sl LOYkiWx6hvBpQ== 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 D7EC965631 for ; Wed, 8 Jun 2022 09:24:40 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="iYX7o/hw"; 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 DBCAAA58; Wed, 8 Jun 2022 09:24:39 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1654673080; bh=ZerpC6qWLVXQO4+Oe2e1AGXdEBr8pAzdJmXxp8KMZW0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iYX7o/hwubMfB+s5nfR9zRPXHP7jSwzEcDrWnUGnGWq4BKnTPCGBsXu3dHVAAHnNG w7ZwxLfXubH1FHlwUAR4JGdXHDbuiQ2eJRdFoj69hTE9tg5TZwEc03oWHOEIICKbFb EO0Oi2a8k+YDFHW70q5GMy6tz+ZXb55Hmj0dID7E= To: libcamera-devel@lists.libcamera.org, David Plowman , Kieran Bingham , Laurent Pinchart , Jacopo Mondi Date: Wed, 8 Jun 2022 10:24:15 +0300 Message-Id: <20220608072418.13154-2-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220608072418.13154-1-tomi.valkeinen@ideasonboard.com> References: <20220608072418.13154-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v5 1/4] 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 Reviewed-by: Jacopo Mondi --- Documentation/index.rst | 1 + Documentation/meson.build | 1 + Documentation/python-bindings.rst | 69 +++++++++++++++++++++++++++++++ 3 files changed, 71 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..d59935ae --- /dev/null +++ b/Documentation/python-bindings.rst @@ -0,0 +1,69 @@ +.. 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 queue the completed requests internally 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 in 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.