From patchwork Tue May 24 11:46:05 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 16019 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 E14D4C326D for ; Tue, 24 May 2022 11:46:51 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 9765465689; Tue, 24 May 2022 13:46:51 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1653392811; bh=Ed51yMM7FH3fIuTwVwblqVMwAFno1yWPdeEfEuUFOKM=; 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=aR+ivw5CTyi4nJCgdg5pqjQW6iwOYiI3uG8kIRWbs7sGl1ft3u+DgFzBlNwxbJQTX GUN5SS24isXBoZChd87eRdOm6S9f4jaEJ/9RNg84b/Op31DbxivszJAuc4zxYbBCJW rfXpE5u0B/fqdCL7ttdsJfnlgNs/YYvew5lD0L3nP3wBSkOn4sqgmcfEFC4YUe8xeX 0MofGFXVtLpLfaCNuQcBw0Qn9KHfu788dguSVaIL5C0jQE3AHnFbF5ox1GhjLBbia6 oq06Mg44Rg7Y0rhy/h8pwy4paoEGB+fkgob2QwqK+o/zQrLLUug4YCv8+r6Tfca/FA IQb12seKB4QwQ== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5D5786567A for ; Tue, 24 May 2022 13:46:37 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="HUhx8KvI"; 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 CB2EF8DC; Tue, 24 May 2022 13:46:36 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1653392797; bh=Ed51yMM7FH3fIuTwVwblqVMwAFno1yWPdeEfEuUFOKM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HUhx8KvIMnJmzbtinj+V+r2VQCcXudXTcceUVx2CE4AHKwqfpp8KK7bjuwuVIUhLb c9kaL7E4GdHlNAYTtx3K9oB+bcIl2EGfDpiuenlWKvgMrKQHPeqqFXDpg+kahd479G bhxY4/dwNPBWyg66D214ku8PtMHNDLRXD9ebNvtQ= To: libcamera-devel@lists.libcamera.org, David Plowman , Kieran Bingham , Laurent Pinchart , Jacopo Mondi Date: Tue, 24 May 2022 14:46:05 +0300 Message-Id: <20220524114610.41848-15-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220524114610.41848-1-tomi.valkeinen@ideasonboard.com> References: <20220524114610.41848-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 14/19] py: Add README.md 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 README for the Python bindings. While not a proper doc, the README and the examples should give enough guidance for users who are somewhat familiar with libcamera. Signed-off-by: Tomi Valkeinen Reviewed-by: Laurent Pinchart --- src/py/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 src/py/README.md diff --git a/src/py/README.md b/src/py/README.md new file mode 100644 index 00000000..0a763030 --- /dev/null +++ b/src/py/README.md @@ -0,0 +1,61 @@ +# 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 Python side follows 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 does 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.read_event() to clear the eventfd event and +CameraManager.get_ready_requests() 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. +