From patchwork Fri May 27 14:44:28 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 16083 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 7F1F4C326D for ; Fri, 27 May 2022 14:45:24 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 1543A6564A; Fri, 27 May 2022 16:45:24 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1653662724; bh=k7Le+XS6rpj2VkjjYXVlhnP5FKg9Q20/vIYaMFUH6WQ=; 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=qxRljEObcG5aJ9Dyrlw8g4Am0LsjjYfdHxakYgxisyXn8mVdElQLu9roNyq/1zB1i tmA857P1I5paz9mOjbxD41yr5KOO5m7kmhYK7wFPu8rf7VVrLf4r4mxhyNJWSsHTXH 7bURZVNKhPB23h7nBMmAJZMWT+Vm45RKfRf3PSPpXt9TjoCM7FaT7VM1RMEb3PhOak Mgq0kDN26Zt3RUsm1bN4bbrr3g2N50DRrqzuHoM+F8goQ35KEyypjC9wVrs4OX3QIV w3JYEerI2NqBEEJX9GpCHwFAkffKR0IedcbqIthmh36NDZpzPJhOSRu+3daVbhnR+E cGUQtaBZllASg== 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 3B89065634 for ; Fri, 27 May 2022 16:45:10 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="pXwr1K4U"; 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 A52B71248; Fri, 27 May 2022 16:45:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1653662710; bh=k7Le+XS6rpj2VkjjYXVlhnP5FKg9Q20/vIYaMFUH6WQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pXwr1K4UQ344VM2zKDggc9+7X6MKQR69tvfHVCY5uWoah/72JAJ2YBCgAu59fProu VYvJGcZ1D+oUIOQYAQvFjoaebyRsRWN4gSwrdvd69gWAe6ElIfkBnx705IPBG9KSDe YHAuJvQ9DDAB9DRs+oco8XarF+t5NKqpNsH2K+sY= To: libcamera-devel@lists.libcamera.org, David Plowman , Kieran Bingham , Laurent Pinchart , Jacopo Mondi Date: Fri, 27 May 2022 17:44:28 +0300 Message-Id: <20220527144447.94891-12-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220527144447.94891-1-tomi.valkeinen@ideasonboard.com> References: <20220527144447.94891-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 11/30] 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 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 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..74a8cd9f --- /dev/null +++ b/src/py/README.md @@ -0,0 +1,60 @@ +# 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.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.