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