mirror of
https://git.libcamera.org/libcamera/libcamera.git
synced 2025-07-12 14:59:44 +03:00
182bdadd0f
Add a new .rst file referencing the documentation contents. This file is then included in each documentation page so that we can enhance the Documentation pages on the libcamera website using it. As we do not want the appearance of the libcamera in-tree Documentation to change just yet, disable the new class using the sphinx theme's CSS. To facilitate easier distinguishing between "normal" and documentation pages on the website we want to add a "documentation" class to the content of all such pages. Since this new file will be included on each documentation page it is convenient to add the new directive here - do so. As the website uses different CSS to libcamera, move the contents on docs.rst a little so that the directive at the end of the contents block applies correctly. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
72 lines
2.5 KiB
ReStructuredText
72 lines
2.5 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
.. include:: documentation-contents.rst
|
|
|
|
.. _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.
|