Documentation: Rework docs.rst into introduction.rst
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. 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>
This commit is contained in:
Daniel Scally
Laurent Pinchart
parent
3fe819eecf
commit
860a3e3031
7 changed files with 136 additions and 72 deletions
|
|
@ -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 = []
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -14,12 +14,90 @@ Documentation
|
|||
|
||||
API <api-html/index>
|
||||
|
||||
API
|
||||
===
|
||||
What is libcamera?
|
||||
==================
|
||||
|
||||
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.
|
||||
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 the
|
||||
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, and 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:
|
||||
|
||||
.. 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
|
||||
|
||||
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, and you can find
|
||||
detailed information on how to do so in the
|
||||
:doc:`application writer's guide <guides/application-developer>`.
|
||||
|
||||
It is often 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 would
|
||||
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
|
||||
============
|
||||
|
|
@ -124,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
|
||||
25
Documentation/mali-c55.dot
Normal file
25
Documentation/mali-c55.dot
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
/* SPDX-License-Identifier: CC-BY-SA-4.0 */
|
||||
|
||||
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]
|
||||
}
|
||||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue