[PATCH v3 3/7] Documentation: Synchronise camera stack details
Dan Scally
dan.scally at ideasonboard.com
Tue Aug 20 09:27:49 CEST 2024
Hi Laurent
On 19/08/2024 22:15, Laurent Pinchart wrote:
> Hi Dan,
>
> Thank you for the patch.
>
> On Mon, Aug 19, 2024 at 05:09:17PM +0100, Daniel Scally wrote:
>> There are two near-duplicate instances of the camera stack details
>> in the Documentation, in docs.rst and guides/introduction.rst. Remove
>> them from guides/introduction.rst, with the exception of the
>> explanations of the V4L2 Compatibility Layer and the Android HAL
>> which are moved to the Camera Stack section in docs.rst. The Docs
>> page already had its own separate version of those details but they
>> are distinct and seemingly out of date - remove them.
>>
>> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
>> ---
>> Changes since v2:
>>
>> - Refocused this patch to focus on camera stack section instead of the
>> libcamera architecture section. Dropped the R-b.
>>
>> Changes since v1:
>>
>> - None
>>
>>
>> Documentation/docs.rst | 56 +++++++------
>> Documentation/guides/introduction.rst | 109 +-------------------------
>> 2 files changed, 31 insertions(+), 134 deletions(-)
>>
>> diff --git a/Documentation/docs.rst b/Documentation/docs.rst
>> index 5871961c..0eacc924 100644
>> --- a/Documentation/docs.rst
>> +++ b/Documentation/docs.rst
>> @@ -239,6 +239,36 @@ The camera stack comprises four software layers. From bottom to top:
>> libcamera framework or libcamera adaptation, and are outside of
>> the scope of the libcamera project.
>>
>> +V4L2 Compatibility Layer
>> + V4L2 compatibility is achieved through a shared library that traps all
>> + accesses to camera devices and routes them to libcamera to emulate high-level
>> + V4L2 camera devices. It is injected in a process address space through
>> + ``LD_PRELOAD`` and is completely transparent for applications.
>> +
>> + The compatibility layer exposes camera device features on a best-effort basis,
>> + and aims for the level of features traditionally available from a UVC camera
>> + designed for video conferencing.
>> +
>> +Android Camera HAL
>> + Camera support for Android is achieved through a generic Android camera HAL
>> + implementation on top of libcamera. The HAL implements features required by
>> + Android and out of scope from libcamera, such as JPEG encoding support.
>> +
>> + This component is used to provide support for ChromeOS platforms
> s/$/./
>
>> +
>> +GStreamer element (gstlibcamerasrc)
>> + A `GStreamer element`_ is provided to allow capture from libcamera supported
>> + devices through GStreamer pipelines, and connect to other elements for further
>> + processing.
>> +
>> + Development of this element is ongoing and is limited to a single stream.
> This isn't true anymore, we now support multiple streams. This can be
> addressed in a separate patch, it's easier to review refactorings
> separately from documentation updates.
Is the rest of the sentence worth retaining? Is the GStreamer element still under active development?
>
> Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
>
>> +
>> +Native libcamera API
>> + Applications can make use of the libcamera API directly using the C++
>> + API. An example application and walkthrough using the libcamera API can be
>> + followed in the :doc:`Application writer's guide </guides/application-developer>`
>> +
>> +.. _GStreamer element: https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html
>>
>> libcamera Architecture
>> ======================
>> @@ -374,29 +404,3 @@ Helpers and Support Classes
>> self-contained support classes, even if such code is present only once in the
>> code base, in order to keep the source code clean and easy to read. This
>> should be the case for instance for plugin management.
>> -
>> -
>> -V4L2 Compatibility Layer
>> -------------------------
>> -
>> -V4L2 compatibility is achieved through a shared library that traps all
>> -accesses to camera devices and routes them to libcamera to emulate high-level
>> -V4L2 camera devices. It is injected in a process address space through
>> -`LD_PRELOAD` and is completely transparent for applications.
>> -
>> -The compatibility layer exposes camera device features on a best-effort basis,
>> -and aims for the level of features traditionally available from a UVC camera
>> -designed for video conferencing.
>> -
>> -
>> -Android Camera HAL
>> -------------------
>> -
>> -Camera support for Android is achieved through a generic Android
>> -camera HAL implementation on top of libcamera. The HAL will implement internally
>> -features required by Android and missing from libcamera, such as JPEG encoding
>> -support.
>> -
>> -The Android camera HAL implementation will initially target the
>> -LIMITED hardware level, with support for the FULL level then being gradually
>> -implemented.
>> diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
>> index 8368bd4a..d1e67654 100644
>> --- a/Documentation/guides/introduction.rst
>> +++ b/Documentation/guides/introduction.rst
>> @@ -26,8 +26,7 @@ desirable results from the camera.
>> .. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
>>
>>
>> -In this developers guide, we will explore the `Camera Stack`_ and how it is
>> -can be visualised at a high level, and explore the internal `Architecture`_ of
>> +In this developers guide, we will explore the internal `Architecture`_ of
>> the libcamera library with its components. The current `Platform Support`_ is
>> detailed, as well as an overview of the `Licensing`_ requirements of the
>> project.
>> @@ -42,112 +41,6 @@ provides a tutorial of the key APIs exposed by libcamera.
>>
>> .. TODO: Correctly link to the other articles of the guide
>>
>> -Camera Stack
>> -------------
>> -
>> -The libcamera library is implemented in userspace, and makes use of underlying
>> -kernel drivers that directly interact with hardware.
>> -
>> -Applications can make use of libcamera through the native `libcamera API`_'s or
>> -through an adaptation layer integrating libcamera into a larger framework.
>> -
>> -.. _libcamera API: https://www.libcamera.org/api-html/index.html
>> -
>> -::
>> -
>> - Application Layer
>> - / +--------------+ +--------------+ +--------------+ +--------------+
>> - | | Native | | Framework | | Native | | Android |
>> - | | V4L2 | | Application | | libcamera | | Camera |
>> - | | Application | | (gstreamer) | | Application | | Framework |
>> - \ +--------------+ +--------------+ +--------------+ +--------------+
>> -
>> - ^ ^ ^ ^
>> - | | | |
>> - | | | |
>> - v v | v
>> - Adaptation Layer |
>> - / +--------------+ +--------------+ | +--------------+
>> - | | V4L2 | | gstreamer | | | Android |
>> - | | Compatibility| | element | | | Camera |
>> - | | (preload) | |(libcamerasrc)| | | HAL |
>> - \ +--------------+ +--------------+ | +--------------+
>> - |
>> - ^ ^ | ^
>> - | | | |
>> - | | | |
>> - v v v v
>> - libcamera Framework
>> - / +--------------------------------------------------------------------+
>> - | | |
>> - | | libcamera |
>> - | | |
>> - \ +--------------------------------------------------------------------+
>> -
>> - ^ ^ ^
>> - Userspace | | |
>> - --------------------- | ---------------- | ---------------- | ---------------
>> - Kernel | | |
>> - v v v
>> -
>> - +-----------+ +-----------+ +-----------+
>> - | Media | <--> | Video | <--> | V4L2 |
>> - | Device | | Device | | Subdev |
>> - +-----------+ +-----------+ +-----------+
>> -
>> -The camera stack comprises of four software layers. From bottom to top:
>> -
>> -* The kernel drivers control the camera hardware and expose a low-level
>> - interface to userspace through the Linux kernel V4L2 family of APIs
>> - (Media Controller API, V4L2 Video Device API and V4L2 Subdev API).
>> -
>> -* The libcamera framework is the core part of the stack. It handles all control
>> - of the camera devices in its core component, libcamera, and exposes a native
>> - C++ API to upper layers.
>> -
>> -* The libcamera adaptation layer is an umbrella term designating the components
>> - that interface to libcamera in other frameworks. Notable examples are the V4L2
>> - compatibility layer, the gstreamer libcamera element, and the Android camera
>> - HAL implementation based on libcamera which are provided as a part of the
>> - libcamera project.
>> -
>> -* The applications and upper level frameworks are based on the libcamera
>> - framework or libcamera adaptation, and are outside of the scope of the
>> - libcamera project, however example native applications (cam, qcam) are
>> - provided for testing.
>> -
>> -
>> -V4L2 Compatibility Layer
>> - V4L2 compatibility is achieved through a shared library that traps all
>> - accesses to camera devices and routes them to libcamera to emulate high-level
>> - V4L2 camera devices. It is injected in a process address space through
>> - ``LD_PRELOAD`` and is completely transparent for applications.
>> -
>> - The compatibility layer exposes camera device features on a best-effort basis,
>> - and aims for the level of features traditionally available from a UVC camera
>> - designed for video conferencing.
>> -
>> -Android Camera HAL
>> - Camera support for Android is achieved through a generic Android camera HAL
>> - implementation on top of libcamera. The HAL implements features required by
>> - Android and out of scope from libcamera, such as JPEG encoding support.
>> -
>> - This component is used to provide support for ChromeOS platforms
>> -
>> -GStreamer element (gstlibcamerasrc)
>> - A `GStreamer element`_ is provided to allow capture from libcamera supported
>> - devices through GStreamer pipelines, and connect to other elements for further
>> - processing.
>> -
>> - Development of this element is ongoing and is limited to a single stream.
>> -
>> -Native libcamera API
>> - Applications can make use of the libcamera API directly using the C++
>> - API. An example application and walkthrough using the libcamera API can be
>> - followed in the `Application Writers Guide`_
>> -
>> -.. _GStreamer element: https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html
>> -
>> Architecture
>> ------------
>>
More information about the libcamera-devel
mailing list