[PATCH v3 6/7] Documentation: Rework docs.rst into introduction.rst
Daniel Scally
dan.scally at ideasonboard.com
Mon Aug 19 18:09:20 CEST 2024
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
+'Linux media' subsystem and provides a set of application programming interfaces
+known collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_
+APIs which provide an interface to interact and control media devices.
+
+.. _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
+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:
+
+.. 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
+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
+can find detailed information on how to do so in the
+:doc:`application writer's guide <guides/application-developer>`. It may be more
+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
+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
+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 @@
+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',
--
2.34.1
More information about the libcamera-devel
mailing list