[PATCH v3 3/7] Documentation: Synchronise camera stack details
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Tue Aug 20 09:49:16 CEST 2024
Hi Dan,
On Tue, Aug 20, 2024 at 08:27:49AM +0100, Daniel Scally wrote:
> On 19/08/2024 22:15, Laurent Pinchart wrote:
> > 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?
libcamera is still under active development :-) I'd drop the sentence.
> > 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
> >> ------------
> >>
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list