[PATCH v3 6/7] Documentation: Rework docs.rst into introduction.rst
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Tue Aug 20 01:17:41 CEST 2024
Hi Dan,
Thank you for the patch.
On Mon, Aug 19, 2024 at 05:09:20PM +0100, Daniel Scally wrote:
> docs.rst is the landing page for the documentation from the libcamera
> website, but isn't particularly introductory. Move much of the content
> from guides/introduction.rst to docs.rst, which will serve as the new
> introductory page. Remove guides/introduction.rst.
>
> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
> ---
> Changes since v2:
>
> - Renamed docs.rst to introduction.rst
> - Switched to use graphviz extension instead of including an SVG file
> directly.
> - Quite a bit of re-wording
> - Kept the camera stack section instead of libcamera architecture
>
> Changes since v1:
>
> - Removed deleted file from meson's docs_sources array.
>
> Documentation/conf.py | 3 +
> Documentation/documentation-contents.rst | 1 -
> Documentation/guides/introduction.rst | 62 -----------
> Documentation/index.rst | 3 +-
> Documentation/{docs.rst => introduction.rst} | 110 ++++++++++++++++++-
> Documentation/mali-c55.dot | 23 ++++
> Documentation/meson.build | 4 +-
> 7 files changed, 133 insertions(+), 73 deletions(-)
> delete mode 100644 Documentation/guides/introduction.rst
> rename Documentation/{docs.rst => introduction.rst} (54%)
> create mode 100644 Documentation/mali-c55.dot
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 325f2759..089f114c 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -37,8 +37,11 @@ author = u'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund'
> # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> # ones.
> extensions = [
> + 'sphinx.ext.graphviz'
> ]
>
> +graphviz_output_format = 'svg'
> +
> # Add any paths that contain templates here, relative to this directory.
> templates_path = []
>
> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
> index c7b78c43..c14389bc 100644
> --- a/Documentation/documentation-contents.rst
> +++ b/Documentation/documentation-contents.rst
> @@ -9,7 +9,6 @@
> * :doc:`/environment_variables`
> * :doc:`/feature_requirements`
> * :doc:`/guides/application-developer`
> - * :doc:`/guides/introduction`
> * :doc:`/guides/ipa`
> * :doc:`/guides/pipeline-handler`
> * :doc:`/guides/tracing`
> diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
> deleted file mode 100644
> index 12d1b7d4..00000000
> --- a/Documentation/guides/introduction.rst
> +++ /dev/null
> @@ -1,62 +0,0 @@
> -.. SPDX-License-Identifier: CC-BY-SA-4.0
> -
> -.. include:: ../documentation-contents.rst
> -
> -Developers guide to libcamera
> -=============================
> -
> -The Linux kernel handles multimedia devices through the 'Linux media' subsystem
> -and provides a set of APIs (application programming interfaces) known
> -collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_ API
> -which provide an interface to interact and control media devices.
> -
> -Included in this subsystem are drivers for camera sensors, CSI2 (Camera
> -Serial Interface) receivers, and ISPs (Image Signal Processors)
> -
> -The usage of these drivers to provide a functioning camera stack is a
> -responsibility that lies in userspace which is commonly implemented separately
> -by vendors without a common architecture or API for application developers.
> -
> -libcamera provides a complete camera stack for Linux based systems to abstract
> -functionality desired by camera application developers and process the
> -configuration of hardware and image control algorithms required to obtain
> -desirable results from the camera.
> -
> -.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
> -.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
> -
> -
> -In this developers guide the `Licensing`_ requirements of the project are
> -detailed.
> -
> -This introduction is followed by a walkthrough tutorial to newcomers wishing to
> -support a new platform with the `Pipeline Handler Writers Guide`_ and for those
> -looking to make use of the libcamera native API an `Application Writers Guide`_
> -provides a tutorial of the key APIs exposed by libcamera.
> -
> -.. _Pipeline Handler Writers Guide: pipeline-handler.html
> -.. _Application Writers Guide: application-developer.html
> -
> -.. TODO: Correctly link to the other articles of the guide
> -
> -Licensing
> ----------
> -
> -The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
> -Handlers are a part of the libcamera code base and need to be contributed
> -upstream by device vendors. IPA modules included in libcamera are covered by a
> -free software license, however third-parties may develop IPA modules outside of
> -libcamera and distribute them under a closed-source license, provided they do
> -not include source code from the libcamera project.
> -
> -The libcamera project itself contains multiple libraries, applications and
> -utilities. Licenses are expressed through SPDX tags in text-based files that
> -support comments, and through the .reuse/dep5 file otherwise. A copy of all
> -licenses are stored in the LICENSES directory, and a full summary of the
> -licensing used throughout the project can be found in the COPYING.rst document.
> -
> -Applications which link dynamically against libcamera and use only the public
> -API are an independent work of the authors and have no license restrictions
> -imposed upon them from libcamera.
> -
> -.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 95c80b4e..3a790352 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -10,13 +10,12 @@
> :caption: Contents:
>
> Home <self>
> - Docs <docs>
> + Introduction <introduction>
> Contribute <contributing>
> Getting Started <getting-started>
>
> Application Writer's Guide <guides/application-developer>
> Camera Sensor Model <camera-sensor-model>
> - Developer Guide <guides/introduction>
> Environment variables <environment_variables>
> Feature Requirements <feature_requirements>
> IPA Writer's guide <guides/ipa>
> diff --git a/Documentation/docs.rst b/Documentation/introduction.rst
> similarity index 54%
> rename from Documentation/docs.rst
> rename to Documentation/introduction.rst
> index 1f0d12c0..a4994e3c 100644
> --- a/Documentation/docs.rst
> +++ b/Documentation/introduction.rst
> @@ -14,12 +14,88 @@ Documentation
>
> API <api-html/index>
>
> -API
> -===
> -
> -The libcamera API is extensively documented using Doxygen. The :ref:`API
> -nightly build <api>` contains the most up-to-date API documentation, built from
> -the latest master branch.
> +What is libcamera?
> +==================
> +
> +libcamera is an open source complex camera support library for Linux, Android
> +and ChromeOS. The library interfaces with Linux kernel device drivers and
> +provides an intuitive API to developers in order to simplify the complexity
> +involved in capturing images from complex cameras on Linux systems.
> +
> +What is a "complex camera"?
> +===========================
> +
> +A modern "camera" tends to infact be several different pieces of hardware which
> +must all be controlled together in order to produce and capture images of
> +appropriate quality. A hardware pipeline typically consists of a camera sensor
> +that captures raw frames and transmits them on a bus, a receiver that decodes
> +the bus signals, and an image signal processor that processes raw frames to
> +produce usable images in a standard format. The Linux kernel handles these multimedia devices through the
Line wrap ?
> +'Linux media' subsystem and provides a set of application programming interfaces
> +known collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_
s/as V4L2/as the V4L2/
> +APIs which provide an interface to interact and control media devices.
s/APIs/APIs,/
> +
> +.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html
> +.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html
> +
> +Included in this subsystem are drivers for camera sensors, CSI2 (Camera
> +Serial Interface) receivers, and ISPs (Image Signal Processors).
> +
> +The usage of these drivers to provide a functioning camera stack is a
> +responsibility that lies in userspace which is commonly implemented separately
The sentence is long, maybe
s/ which/, and/
> +by vendors without a common architecture or API for application developers. This
> +adds a lot of complexity to the task, particularly when considering that the
> +differences in hardware pipelines and their representation in the kernel's APIs
> +often necessitate bespoke handling.
> +
> +What is libcamera for?
> +======================
> +
> +libcamera provides a complete camera stack for Linux-based systems to abstract
> +the configuration of hardware and image control algorithms required to obtain
> +desirable results from the camera through the kernel's APIs, reducing those
> +operations to a simple and consistent method for developers. In short instead of
> +having to deal with this:
> +
> +.. graphviz:: mali-c55.dot
> +
> +You can instead simply deal with this:
s/You/you/
s/with this/with/
> +
> +.. code-block:: python
> +
> + >>> import libcamera as lc
> + >>> camera_manager = lc.CameraManager.singleton()
> + [0:15:59.582029920] [504] INFO Camera camera_manager.cpp:313 libcamera v0.3.0+182-01e57380
> + >>> for camera in camera_manager.cameras:
> + ... print(f' - {camera.id}')
> + ...
> + - mali-c55 tpg
> + - imx415 1-001a
> +
> +And the library handles the rest for you. These documentary pages give more
s/And the/The/
> +information on the internal workings of libcamera (and the kernel camera stack
> +that lies behind it) as well as guidance on using libcamera in an application or
> +extending the library with support for your hardware (through the pipeline
> +handler and IPA module writer's guides).
> +
> +How should I use it?
> +====================
> +
> +There are a few ways you might want to use libcamera, depending on your
> +application. It's always possible to use the library directly of course, and you
s/ of course//
> +can find detailed information on how to do so in the
> +:doc:`application writer's guide <guides/application-developer>`.
I may break to a separate paragraph here.
> It may be more
A bit stronger maybe:
s/may/can/
or even "It is often more appropriate"
> +appropriate to use one of the frameworks with libcamera support. For example an
> +application powering an embedded media device incorporating capture, encoding
> +and streaming of both video and audio might benefit from using `GStreamer`_, for
s/might/would/ or 'could'
> +which libcamera provides a plugin. Similarly an application for user-facing
> +devices like a laptop would likely benefit accessing cameras through the XDG
> +camera portal and `pipewire`_, which brings the advantages of resource sharing
> +(multiple applications accessing the stream at the same time) and access
> +control.
> +
> +.. _GStreamer: https://gstreamer.freedesktop.org/
> +.. _pipewire: https://pipewire.org/
>
> Camera Stack
> ============
> @@ -126,3 +202,25 @@ Native libcamera API
> followed in the :doc:`Application writer's guide </guides/application-developer>`
>
> .. _GStreamer element: https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html
> +
> +Licensing
> +=========
> +
> +The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline
s/core,/core/
> +Handlers are a part of the libcamera code base and need to be contributed
> +upstream by device vendors. IPA modules included in libcamera are covered by a
> +free software license, however third-parties may develop IPA modules outside of
> +libcamera and distribute them under a closed-source license, provided they do
> +not include source code from the libcamera project.
> +
> +The libcamera project itself contains multiple libraries, applications and
> +utilities. Licenses are expressed through SPDX tags in text-based files that
> +support comments, and through the .reuse/dep5 file otherwise. A copy of all
> +licenses are stored in the LICENSES directory, and a full summary of the
> +licensing used throughout the project can be found in the COPYING.rst document.
> +
> +Applications which link dynamically against libcamera and use only the public
> +API are an independent work of the authors and have no license restrictions
> +imposed upon them from libcamera.
> +
> +.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html
> diff --git a/Documentation/mali-c55.dot b/Documentation/mali-c55.dot
> new file mode 100644
> index 00000000..0b59a488
> --- /dev/null
> +++ b/Documentation/mali-c55.dot
> @@ -0,0 +1,23 @@
Please add a license here.
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> +digraph board {
> + rankdir=TB
> + n00000001 [label="{{} | mali-c55 tpg\n/dev/v4l-subdev0 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
> + n00000001:port0 -> n00000003:port0 [style=dashed]
> + n00000003 [label="{{<port0> 0 | <port4> 4} | mali-c55 isp\n/dev/v4l-subdev1 | {<port1> 1 | <port2> 2 | <port3> 3}}", shape=Mrecord, style=filled, fillcolor=green]
> + n00000003:port1 -> n00000009:port0 [style=bold]
> + n00000003:port2 -> n00000009:port2 [style=bold]
> + n00000003:port1 -> n0000000d:port0 [style=bold]
> + n00000003:port3 -> n0000001c
> + n00000009 [label="{{<port0> 0 | <port2> 2} | mali-c55 resizer fr\n/dev/v4l-subdev2 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> + n00000009:port1 -> n00000010
> + n0000000d [label="{{<port0> 0} | mali-c55 resizer ds\n/dev/v4l-subdev3 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> + n0000000d:port1 -> n00000014
> + n00000010 [label="mali-c55 fr\n/dev/video0", shape=box, style=filled, fillcolor=yellow]
> + n00000014 [label="mali-c55 ds\n/dev/video1", shape=box, style=filled, fillcolor=yellow]
> + n00000018 [label="mali-c55 3a params\n/dev/video2", shape=box, style=filled, fillcolor=yellow]
> + n00000018 -> n00000003:port4
> + n0000001c [label="mali-c55 3a stats\n/dev/video3", shape=box, style=filled, fillcolor=yellow]
> + n00000030 [label="{{<port0> 0} | lte-csi2-rx\n/dev/v4l-subdev4 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
> + n00000030:port1 -> n00000003:port0
> + n00000035 [label="{{} | imx415 1-001a\n/dev/v4l-subdev5 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
> + n00000035:port0 -> n00000030:port0 [style=bold]
> +}
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 54788d6d..36ffae23 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -128,18 +128,18 @@ if sphinx.found()
> 'coding-style.rst',
> 'conf.py',
> 'contributing.rst',
> - 'docs.rst',
> 'documentation-contents.rst',
> 'environment_variables.rst',
> 'feature_requirements.rst',
> 'guides/application-developer.rst',
> - 'guides/introduction.rst',
> 'guides/ipa.rst',
> 'guides/pipeline-handler.rst',
> 'guides/tracing.rst',
> 'index.rst',
> + 'introduction.rst',
> 'lens_driver_requirements.rst',
> 'libcamera_architecture.rst',
> + 'mali-c55.dot',
> 'python-bindings.rst',
> 'sensor_driver_requirements.rst',
> 'software-isp-benchmarking.rst',
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list