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>
Add a basic doc for the Python bindings. While not really proper
documentation yet, the file and the examples should give enough guidance
for users who are somewhat familiar with libcamera.
Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
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 IPU3 is documented using Doxygen within the code.
Include the IPU3 IPA as part of the doxygen build sources. This will
ideally be split to its own 'section' of the doxygen output.
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Jean-Michel Hautbois <jeanmichel.hautbois@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@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>
Since meson v0.49.0, join_paths() is equivalent to '/' hence,
drop and replace it with '/' short-hand in meson files.
This commit does not introduce any functional changes.
Signed-off-by: Umang Jain <umang.jain@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Document the feature an image sensor driver has to provide to be
fully libcamera-compliant.
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
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>
Add guide for tracepoints, including how to define and use them.
Signed-off-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
This way if the user enables the documentation and the dependencies are
missing the configure fails.
Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Ricardo Ribalda <ricardo@ribalda.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Doxygen depends on dot to generate the documentation. Make this
dependency explicit on the meson file.
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Ricardo Ribalda <ricardo@ribalda.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>
Provide a tutorial and walk through guide for writing an applications
with libcamera.
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>
Switch IPA communication to the plain C API. As the IPAInterface class
is easier to use for pipeline handlers than a plain C API, retain it and
add an IPAContextWrapper that translate between the C++ and the C APIs.
On the IPA module side usage of IPAInterface may be desired for IPAs
implemented in C++ that want to link to libcamera. For those IPAs, a new
IPAInterfaceWrapper helper class is introduced to wrap the IPAInterface
implemented internally by the IPA module into an ipa_context,
ipa_context_ops and ipa_callback_ops.
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
The ipa includes are located in include/libcamera/ipa/. This gives an
incorrect impression that they are a sub-part of the rest of the
libcamera API, while they are the API towards the IPA the same way that
include/libcamera/ contains the API towards applications. To clarify
this, move them to include/ipa/.
The IPA headers are however still part of libcamera, so installing them
to ${prefix}/include/ipa/ would make little sense. To fix this, move the
application facing API to ${prefix}/include/libcamera/libcamera/ when
installed, and the IPA to ${prefix}/include/libcamera/ipa/. When major
versions of libcamera will be released, they could then be installed
side by side in ${prefix}/include/libcamera-${version}/.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Move the introduction content from the index.rst to the README.rst so
that it can also be found quickly from the top level.
Include the README.rst directly into the index.rst to continue serving
it as the front page material.
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Commit b817bcec6b ("libcamera: Auto generate version information")
generates version information in order to automatically include it
various locations (Sphinx and Doxygen documentation, libcamera::version
variable available at runtime, and version.h available at compile time).
Unfortunately this causes lots of unnecessary rebuilds when modifying
the git tree state, which hinders development.
The problem is caused by the generated version.h being listed as a
dependency for the whole libcamera. This is required as meson (to the
best of my knowledge) doesn't provide a way to explicitly specify the
dependency of a single object file (camera_manager.o in this case, as
camera_manager.cpp is the only consumer of the generated version string)
on the custom target used to generate version.h. The dependency can't be
automatically detected at build time, like dependencies on normal
headers that are generated by parsing the source, because the version.h
header may not exist yet. The build could then fail in a racy way.
This change attempts at solving the issue by generating a version.cpp
instead of a version.h to set the git-based version. This minimises the
number of files that need to be rebuild when then git tree state
changes, while retaining the main purpose of the original automatic
version generation, the ability to access the git-based version string
at runtime. We however lose the ability to access git-based version
information at build time in an application building against libcamera,
but there is no expected use case for this.
The version string is moved from the libcamera namespace to the
CameraManager class in order to avoid including version.h inside
libcamera (in version.cpp and in camera_manager.cpp), which would create
dependencies causing more rebuild steps, as described above.
On the other hand, major, minor and patch level version numbers are
useful at build time. This commit changes the generation of version.h in
order to add three macros named LIBCAMERA_VERSION_MAJOR,
LIBCAMERA_VERSION_MINOR and LIBCAMERA_VERSION_PATCH for this purpose.
version.h is not included by any other libcamera header or source file,
and thus doesn't force a rebuild of the library.
The Sphinx and Doxygen documentation keep their git-based version
information, which is set during the configuration of the build and then
doesn't track git commits. We may want to investigate how to improve
this, but given that git-based version for the documentation has very
few use cases outside of tagging nightly builds, this isn't considered
an issue at the moment.
The documentation install directory now uses the base version string, in
order to avoid increasing the number of documentation directories
needlessly. This shouldn't cause any issue as the API should not change
without a change to the version number.
The version number generation and handling code now also standardises
the version variables to not start with a 'v' prefix in meson, in order
to simplify their handling. The prefix is added when generating the
relevant files.
Note that we go back to specifying the fallback version in the main
meson.build, in the call to the project() function. For the time being I
believe this should be a good compromise to avoid unnecessary
recompilation, and moving the fallback version to a different file for
tarball releases can be built on top of this.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
The doc_install_dir is longer than 80 chars. Wrap it accordingly.
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Generate a version string, and provide a global string object which
allows applications to interrogate the current libcamera version
information.
The version header is automatically updated by meson on each build.
The string roughly follows the semver [0] conventions of
major.minor.patch-label as a value.
[0] https://semver.org/
A script (utils/gen-version.sh) is provided which is modelled upon the
processing from autoconf's git-version-gen. The gen-version.sh script
will look for tags in the form vX.Y as starting points for the version
string. While the repository does not have any matching tags, v0.0 will
be assumed, resulting in versions with both major and minor being set to
'0', and the patch count resulting from the number of patches in the
history to that point.
Finally, a uniquely identifying shortened hash is provided from git:
v0.0.509+0ec0edf7
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Consistently go for 4 spaces indentation, and always put a space between
the colon in argument lists, as per the examples from the meson
documentation.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Building the documentation reports warnings,
WARNING: Project targetting '>= 0.40' but tried to use feature introduced in '0.50.0': install arg in configure_file
WARNING: Project specifies a minimum meson_version '>= 0.40' but uses features which were added in newer versions:
* 0.50.0: {'install arg in configure_file'}
Due to the usage of the directive configure_file { install: false } in
Documentation/meason.build which is introduced in meson 0.50. As we do
not wish to install the Doxyfile no install_dir is set so there is no
need to explicitly state that it should not be installed. Silence the
warning by dropping the install directive.
Fixes: 53c4d4c34f ("Documentation: Generate source code documentation using Doxygen")
Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
The output of the sphinx-build for our documentation is overly verbose.
Reduce this output to warnings and errors with the '-q' quiet option.
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
The documentation is copied mostly verbatim from the website, with small
modifications to the ascii art diagrams to make them compile.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Extend the documentation build system to automatically generate
documentation from source code using Doxygen. This is currently separate
from the sphinx documentation, and should be integrated using the
breathe (and possibly exhale) extensions.
As the Documentation/meson.build file needs to reference the variables
holding the source files, move the Documentation directory to the end of
the subdirs() in the top-level meson.build.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Use the datadir option to select the directory in which to install
documentation. This defaults to $prefix/share so this doesn't introduce
any change in the default case.
While at it use join_paths() to join patch components instead of
hardcoding the / separator.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
The custom_target() function accepts an install_dir parameter. Along
with setting install to true, this can be used to replace the
install_subdir() function.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Utilise sphinx-build to generate documentation in HTML form, and
populate with some initial content.
An initial conf.py is generated from sphinx-quickstart and answering
initial questions.
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
