Add a table with the list of camera sensors currently supported by
libcamera. Similar to the ISP feature matrix, this too is a living
document, and will be updated as support for more sensors is added.
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Jai Luthra <jai.luthra@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Add a new living document presenting a matrix of image processing
feature support across all currently supported platforms in libcamera.
This will hopefuly help in answering questions like is HDR supported
with Software ISP or is Auto Focus supported on Raspberry Pi?
This matrix will be regularly updated as new features and platforms are
added.
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
Signed-off-by: Jai Luthra <jai.luthra@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
The public and internal Doxygen API documentation is compiled and
installed in api-html and internal-api-html directories respectively.
The '-html' suffix doesn't provide any value, and the asymmetry between
the names can be confusing. Rename the directories to public-api and
internal-api respectively.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
The libcamera documentation comprises two parts: pages generated by
Sphinx into the Documentation/html/ directory within the build tree, and
API reference documentation generated by Doxygen into
Documentation/internal-api-html/ and Documentation/api-html/. The two
parts are generated separately, but link to each other.
From Sphinx to Doxygen, we use the doxylink extension for Sphinx to
generate links to the Doxygen pages corresponding to API elements. The
extension needs to be configured with the paths to the Doxygen
documentation, which are set based on the html/, api-html/ and
internal-api-html/ directories being placed side by side in the same
parent directory.
Furthermore, we also want to link to the API documentation from the
Sphinx toctree. As toctrees can only link to pages within the Sphinx
documents tree (or to http URLs), we have placeholder .rst documents for
api-html and internal-api-html in the Sphinx documentation tree. Those
generate the Documentation/html/internal-api-html/index.html and
Documentation/html/api-html/index.html placeholder files in the build
tree.
The other way around, the API documentation's introduction pagelinks to
Sphinx pages using relative paths. Those paths are hardcoded based on
the api-html/ and internal-api-html/ directories being children of the
html/ directory.
This results in links being broken in different ways in the build tree,
as well as in the installation directory: the toctree links direct to
the placeholder pages within the html/ directory instead of the Doxygen
documentation in sibling directories, and the Doxygen introduction links
to Sphinx are simply broken. When publishing documentation on the
website we work around those issues by overriding conf.py with a custom
version and moving the api-html/ and internal-api-html/ directories to
the html/ directory.
Fixing this is surprisingly difficult. The toctree links can't be
changed to point to a path outside of the Sphinx document tree as this
isn't supported by Sphinx. Using http URLs would link to the
libcamera.org website inside of local documentation, which isn't
acceptable. It may be possible to develop a Sphinx extension to patch
the toctree after it gets parsed, but that would be complex and likely
fragile. Modifying the install path of the Doxygen documentation to
html/api-html/ and html/internal-api-html/ causes issues as the Sphinx
documentation will then overwrite the Doxygen index.html files with the
placeholder indexes. Creating symlinks from html/api-html/ to api-html/
in the installation directory causes similar problems if 'meson install'
is run twice. Creating the symlinks in the build directory (which was
attempted with a custom Sphinx extension) is also a no-go: starting with
meson v1.8.0, installing symlinks to directories causes an exception due
to a bug in meson.
The right solution is probably to investigate usage of the doxysphinx
extension. As that's no small amount of work, let's start with a
non-perfect but simple improvement: configure doxylink based on the
api-html/ and internal-api-html/ directories being children of the
Sphinx html/ documentation, and move those two API documentation
directories to html/ during installation with a post-install script.
This fixes links in the installation directory. Links in the build
directory remain broken, with the toctree links and the links from
Doxygen to Sphinx being broken already, and the links to API elements
through doxylink now being broken too. This is considered as an
acceptable compromise and an overall improvement. The installation
directory is more important, as in the build tree people also have
access to sources. Application developers in particular are less likely
to read documentation from the libcamera build tree, they may not even
have a copy of the libcamera source tree.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
Our current theme doesn't handle many of the rst features (namely notes,
proper code highlighting, font formatting). The sphinx book theme
provides a unobtrusive design which makes the documentation way more fun
to read. The branding is minimal. The libcamera logo is included and
theme colors are set to the libcamera blue.
To get meson/sphinx to successfully compile the docs the package
"python3-sphinx-book-theme" needs to be installed (at least on debian
based systems).
Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
When checking the version of the sphinxcontrib.doxylink module, the
Python interpreter used by Sphinx must be used, as that's where the
module will be imported from. Using the meson python_installation object
for this purpose is incorrect, as it's meant to access the Python
installation of the host machine, not the system Python interpreter on
the build machine.
For instance, when cross-compiling libcamera against a Buildroot
environment, and pointing meson in the cross-file to the build machine
Python interpreter from Buildroot, the meson python module will refer to
the latter, while Sphinx will use the former.
Fix this by using python3 directly.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
The paths of the doxygen tag files for sphinxcontrib-doxygen must be
absolute or relative the the current working directory. However, when
libcamera is built as a subproject, the current working directory
is the top-level build directory. Thus the paths for the tag files
will not be correct.
Fix that by using `configure_file()` to generate the final sphinx
configuration with the appropriate paths queried from meson.
Fixes: 0382d215db ("Documentation: Use Sphinx doxylink to generate links to doxygen")
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
The libcamera Sphinx documentation needs to link to the API
documentation generated by Doxygen. The links currently point to the
documentation hosted on the official https://libcamera.org/ website.
This causes multiple issues:
- Doxygen generates URLs with MD5 hashes of function signatures, making
the link targets unstable.
- When testing documentation builds that include API changes, links to
new API elements will be broken.
- The generated documentation can't be browsed offline.
Fix this by using the Sphinx doxylink extension. This allows specifying
link targets as class and function names, with the link being
automatically generated using the same MD5 hashing as Doxygen. The root
of the link target is configured in a central location, which defaults
to the build directory and can be overridden to point to the libcamera
website when pushing the documentation.
This commit only introduces the infrastructure to use doxylink. Manual
links will be replaced separately.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
The internal documentation is a superset of the public one, so make the
`doxygen-internal` target depend on the public input files. Otherwise
the internal documentation is not rebuilt if a "public" file changes.
Before:
$ touch src/libcamera/camera.cpp
$ ninja -C build -v
# ...
[6/116] /usr/bin/doxygen Documentation/Doxyfile-public
# ...
After:
$ touch src/libcamera/camera.cpp
$ ninja -C build -v
# ...
[6/117] /usr/bin/doxygen Documentation/Doxyfile-public
# ...
[9/117] /usr/bin/doxygen Documentation/Doxyfile-internal
# ...
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Commit aba567338b ("Documentation: Move all dependencies into
features") did an incomplete migration of the documentation boolean
option into a documentation feature.
If sphinx-build-3 binary is found on the host system, the documentation
is built, regardless of the value of the feature option.
This makes sure that sphinx-build-3 presence is only checked if the
documentation feature is not disabled (which is the default, as it's
"auto" by default).
This is essential for reproducibility for build systems where
sphinx-build-3 may or may not be present when libcamera is built, and
also to declutter the generated package if documentation isn't desired.
Fixes: aba567338b ("Documentation: Move all dependencies into features")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Tested-by: Quentin Schulz <quentin.schulz@cherry.de>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
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>
In preparation for including more of the Documentation for libcamera
on the website, break out the libcamera Architecture and Feature
Requirements sections of docs.rst file into separate files for each
section. Add all of the new files to documentation-contents.rst so
they're included on the website too.
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>
Add a new .rst file referencing the documentation contents. This file
is then included in each documentation page so that we can enhance
the Documentation pages on the libcamera website using it. As we do
not want the appearance of the libcamera in-tree Documentation to
change just yet, disable the new class using the sphinx theme's CSS.
To facilitate easier distinguishing between "normal" and
documentation pages on the website we want to add a "documentation"
class to the content of all such pages. Since this new file will be
included on each documentation page it is convenient to add the new
directive here - do so. As the website uses different CSS to
libcamera, move the contents on docs.rst a little so that the
directive at the end of the contents block applies correctly.
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>
The API reference pages generated by Doxygen are comprehensive, but
therefore quite overwhelming for application developers who will
likely never need to use the majority of the library's objects. To
reduce the complexity of the documentation, split it into two runs of
doxygen.
The first run of doxygen is for the public API. We pass a specific list
of source files to parse, which is built from the arrays of public
headers and sources in meson build files. This ensures that we only
generate the documentation for code from those files.
A custom Python script is needed to add the list of input files to
Doxyfile, as several of the objects included in the header and source
array are custom_tgt objects, which can't be handled as strings to
populate a variable in the configuration data.
The headers defining the Extensible and Object classes (class.h and
object.h respectively), as well as the corresponding source files, are
excluded from the public API documentation despite being referenced in
the meson public headers and sources arrays. This is due to the fact
that public API classes inherit from Extensible and Object, making the
Extensible and Object classes part of the public ABI. Those two base
classes are however implementation details and must not be accessed
directly by application code.
The second run of doxygen is for the internal API. This contains
documentation for all of the library's objects as it currently does.
This set will now be output into build/Documentation/internal-api-html.
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
Co-developed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
A new Doxygen warning introduced in a recent commit went unnoticed, both
in manual tests and in CI. Unlike C/C++ warnings that are treated as
errors, we don't fail the build with Doxygen warnings. This is due to
the fact that the libcamera documentation compiles cleanly only with quite
recent versions of Doxygen. Enabling the WARN_AS_ERROR Doxygen option
unconditionally could bother many users.
To improve the situation, add a meson option to treat Doxygen warnings
as errors. The option is disabled by default, preserving the current
behaviour, and will be enabled in CI builds.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Meson uses tags to sort installed files in categories, and makes it
possible to install a subset of the files using the '--tags' argument to
'meson install'. This is typically used by distributions to split the
runtime, development and documentation files into separate packages.
By default, meson tries to guess the correct tag for installed files,
but can't always do so properly. Mark the install targets that meson
can't guess with the correct install_tag.
As the feature has been introduced in meson 0.60, bump the minimum meson
version. The latest LTS release of all major distributions that
libcamera currently targets ship a recent enough meson version.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Now that libcamera has an official code of conduct, mention it in the
'contributing' document with a clear indication that all community
members are expected to follow the code of conduct.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Introduce a documentation page about the 'camera sensor model'
implemented by libcamera.
The camera sensor model serves to provide to applications a reference
description of the processing steps that take place in a camera sensor
in order to precisely control the sensor configuration through the
forthcoming SensorConfiguration class.
Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
The meson style, which libcamera follows, recommends a space before
colons in function parameters. Fix the style violations through the
project.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Umang Jain <umang.jain@ideasonboard.com>
libcamera creates a config.h file with predefined macros, and instructs
the compiler to include it implicitly with the -include argument.
Doxygen has no support for implicit inclusion of headers, but has a
PREDEFINED configuration option for its preprocessor that lists
predefined macros. Populate it with the values from the config_h
configuration data object that is used for generate the config.h file,
to ensure that documentation matches the configuration options libcamera
has been built with.
Bump the minimum meson version to 0.57 to use cfg_data.keys().
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Currently, doxygen is run by ninja in the top-level build directory,
therefore the "Documentation" folder is always created there. However,
when libcamera is built as a subproject, it should not touch the
top-level build directory because it can cause conflicts and because
the documentation won't be created where meson thinks it will be, so
the "doxygen" target will always be dirty and installation will fail.
Signed-off-by: Barnabás Pőcze <pobrn@protonmail.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
When the IPU3 pipeline handler is disabled, the corresponding IPA module
isn't compiled, which results in the meson ipu3_ipa_sources variable to
be undefined. The variable is used unconditionally as part of the
Doxygen inputs, so Meson complains at configuration time that it is
undefined.
Fix it by including the IPU3 IPA documentation in the Doxygen build only
when the IPU3 pipeline handler is enabled.
Fixes: 45dd519889 ("Documentation: Include IPU3 in Doxygen build")
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
The libcamera-base.so will feature internal support functionality
that is utilised by libcamera, and can be shared in other places.
This new library provides a layer beneath libcamera which provides
common abstractions to internal objects.
A pkg-config file is generated and named libcamera-base.pc which allows
components such as external IPA modules to link directly to this library
if they need. Normal applications will reference this library through
the Requires: statement provided by the libcamera.pc package
configuration, and linkage will be handled automatically through the
pkg-config mechanisms.
No code is moved to this library yet, this patch only introduces the
framework, construction and linkage.
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Hirokazu Honda <hiroh@chromium.org>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Moving the core.mojom documentation to its corresponding .cpp file
(core_ipa_interface.cpp). This will allow Doxygen to generate the
documentation for IPABuffer, IPASettings and IPAStream structures.
Since the .mojom files are placed in include/ directory, the .cpp file
will live in $sourcedir/src/libcamera/ipa/ - which can also contain
documentation for other mojom generated IPA interfaces in subsequent
commit.
Also hide the constructors in generated IPA interface from doxygen,
via #ifndef __DOXYGEN__. These constructors provide no major value in
documenting them, instead will spew out doxygen warnings during the
build.
Signed-off-by: Umang Jain <umang.jain@ideasonboard.com>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Describe the environment variables used in libcamera, excluded
variables are `LIBCAMERA_IPA_FORCE_C_API` and `LIBCAMERA_IPA_PROXY_PATH`,
the former because it is likely to be removed and the later because
it has no current use-case.
Add a brief explanation for the IPA configuration and IPA modules.
List all the available Log levels and categories and add a short guide
on how to use them for debugging.
Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@gmail.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Introduce a pipeline-handler writers guide to provide a walk through of
the steps and concepts required to implement a new Pipeline Handler.
Signed-off-by: Chris Chinchilla <chris@gregariousmammal.com>
[Reflow/Rework, update to mainline API]
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
[Further reworks and review]
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Create an introduction and overview for new developers to libcamera.
Provide an overview of the Camera Stack, and Architecture of libcamera
and introduce the main concepts of libcamera.
Signed-off-by: Chris Chinchilla <chris@gregariousmammal.com>
[Kieran: Rework/Reflow, add diagrams, licensing]
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
The list of public, IPA and internal header files are stored in three
meson variables, named libcamera_api, libcamera_ipa_api and
libcamera_headers respectively. The lack of uniformity is a bit
confusing. Fix it by renaming those variables to
libcamera_public_headers, libcamera_ipa_headers and
libcamera_internal_headers.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
In an attempt to clarify the license terms of all files in the libcamera
project, the build system files deserve particular attention. While they
describe how the binaries are created, they are not themselves
transformed into any part of binary distributions of the software, and
thus don't influence the copyright on the binary packages. They are
however subject to copyright, and thus influence the distribution terms
of the source packages.
Most of the meson.build files would not meet the threshold of
originality criteria required for copyright protection. Some of the more
complex meson.build files may be eligible for copyright protection. To
avoid any ambiguity and uncertainty, state our intent to not assert
copyrights on the build system files by putting them in the public
domain with the CC0-1.0 license.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Acked-by: Giulio Benetti <giulio.benetti@micronovasrl.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Acked-by: Naushir Patuck <naush@raspberrypi.com>
Acked-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
Acked-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Acked-by: Paul Elder <paul.elder@ideasonboard.com>
Acked-by: Show Liu <show.liu@linaro.org>
Sphinx provides a run-target to verify external links specified in the
documentation. This requires an active connection to be able to validate
the links.
Add a meson target to integrate the linkcheck facility into our build
and test system.
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Jai Luthra
Laurent Pinchart
Milan Zamazal
Stefan Klug
Barnabás Pőcze
Quentin Schulz
Paul Elder
Daniel Scally
Hans de Goede
Jacopo Mondi
Barnabás Pőcze
Tomi Valkeinen
Han-Lin Chen
Kieran Bingham
Umang Jain
Jacopo Mondi
Sebastian Fricke
Ricardo Ribalda
Chris Chinchilla