diff options
| -rw-r--r-- | Documentation/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/meson.build | 1 | ||||
| -rw-r--r-- | Documentation/python-bindings.rst | 70 |
3 files changed, 72 insertions, 0 deletions
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 <environment_variables> Sensor driver requirements <sensor_driver_requirements> Lens driver requirements <lens_driver_requirements> + Python Bindings <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..bac5cd34 --- /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 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. |