[{"id":30856,"web_url":"https://patchwork.libcamera.org/comment/30856/","msgid":"<20240818230122.GD15356@pendragon.ideasonboard.com>","date":"2024-08-18T23:01:22","subject":"Re: [PATCH v2 6/7] Documentation: Expand introductory content on\n\tdocs.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 Thu, Aug 15, 2024 at 09:29:43AM +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 <dan.scally@ideasonboard.com>\n> ---\n> Changes since v1:\n> \n> \t- Removed deleted file from meson's docs_sources array.\n> \n>  Documentation/c55.svg                    | 175 +++++++++++++++++++++++\n>  Documentation/docs.rst                   | 128 ++++++++++++++++-\n>  Documentation/documentation-contents.rst |   1 -\n>  Documentation/guides/introduction.rst    |  78 ----------\n>  Documentation/index.rst                  |   1 -\n>  Documentation/meson.build                |   1 -\n>  6 files changed, 296 insertions(+), 88 deletions(-)\n>  create mode 100644 Documentation/c55.svg\n>  delete mode 100644 Documentation/guides/introduction.rst\n> \n> diff --git a/Documentation/c55.svg b/Documentation/c55.svg\n> new file mode 100644\n> index 00000000..9dbd52bb\n> --- /dev/null\n> +++ b/Documentation/c55.svg\n> @@ -0,0 +1,175 @@\n> +<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n> +<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n> + \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n> +<!-- Generated by graphviz version 2.43.0 (0)\n> + -->\n\nSphinx has a graphviz extension. I've tested it locally and it works\nquite nicely, with the following diff:\n\ndiff --git a/Documentation/conf.py b/Documentation/conf.py\nindex 325f27591cfb..1f087c14e744 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\ndiff --git a/Documentation/docs.rst b/Documentation/docs.rst\nindex c495fa61e40e..1cf2f4d6c744 100644\n--- a/Documentation/docs.rst\n+++ b/Documentation/docs.rst\n@@ -58,7 +58,7 @@ 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-.. figure:: c55.svg\n+.. graphviz:: mali-c55.dot\n\n You can instead simply deal with this::\n\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 1c982ba6f862..c8433f33c0a4 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -139,6 +139,7 @@ if sphinx.found()\n         'guides/tracing.rst',\n         'index.rst',\n         'lens_driver_requirements.rst',\n+        'mali-c55.dot',\n         'python-bindings.rst',\n         'sensor_driver_requirements.rst',\n         'software-isp-benchmarking.rst',\n\n(and c55.svg replaced with mali-c55.dot).\n\nAdding the .dot file to the docs_sources isn't a requirement specific to\n.dot input files, the .svg should have been added there too.\n\nThe sphinx extension is part of the base sphinx package on Debian, so\nusing it should be fine.\n\n[snip]\n\n> diff --git a/Documentation/docs.rst b/Documentation/docs.rst\n> index d65b2b4f..c495fa61 100644\n> --- a/Documentation/docs.rst\n> +++ b/Documentation/docs.rst\n> @@ -14,12 +14,87 @@ Documentation\n>  \n>     API <api-html/index>\n>  \n> -API\n> -===\n> +What is libcamera exactly?\n\nI would drop \"exactly\".\n\n> +==========================\n> +\n> +libcamera is an open source complex camera support library for Linux. The\n\nTo match the Doxygen documentation, the README.rst file and the website,\nyou should write \"for Linux, Android and ChromeOS\".\n\n> +library interfaces with Linux kernel uAPIs implemented by device drivers and\n\nI'd write \"with Linux kernel device drivers\"\n\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's a \"complex camera\"?\n\n\"What is\"\n\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 capture images. For example the\n> +pipeline might consist of a camera sensor which actually records the data, a\n> +receiver which accepts those data transmitted from the camera sensor and an\n> +image signal processor which processes those data into a useful image in an\n> +accepted format.\n\nI like the storyline here, but I think I would make this paragraph a bit\nclearer:\n\nA modern \"camera\" tends to infact be several different pieces of hardware which\nmust all be controlled together in order to produce and capture images of\nappropriate quality. A hardware pipeline typically consists of a camera sensor\nthat captures raw frames and transmits them on a bus, a receiver that decodes\nthe bus signals, and an image signal processor that processes raw frames to\nproduce usable images in a standard format.\n\n> The Linux kernel handles these multimedia devices through the\n> +'Linux media' subsystem and provides a set of APIs (application programming\n\ns/APIs (/\n\n> +interfaces) known collectively as V4L2 (`Video for Linux 2`_) and the\n> +`Media Controller`_ API which provide an interface to interact and control media\n\ns/API/APIs/\n\n(to avoid repeating \"API\").\n\n> +devices.\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\ns/$/./\n\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. 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 necessitates bespoke handling.\n\ns/necessitates/necessitate/ if the subject is differences.\n\n> +\n> +What is libcamera for?\n> +======================\n>  \n> -The libcamera API is extensively documented using Doxygen. The :ref:`API\n> -nightly build <api>` contains the most up-to-date API documentation, built from\n> -the latest master branch.\n> +libcamera provides a complete camera stack for Linux based systems to abstract\n\ns/Linux based/Linux-based/\n\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> +.. figure:: c55.svg\n> +\n> +You can instead simply deal with this::\n> +\n\nLet's get syntax highlighting:\n\nYou can instead simply deal with this:\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> +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> +can find detailed information on how to do so in the\n> +:doc:`application writer's guide <guides/application-developer>`. It may be more\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/gstreamer/GStreamer/\ns/ (/, /\n\n> +which libcamera provides a plugin). Similarly an application for user-facing\n\ns/)//\n\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\nShould you mention the Android camera HAL and V4L2 compatibility layer\nhere ?\n\n> +\n> +.. _gstreamer: https://gstreamer.freedesktop.org/\n> +.. _pipewire: https://pipewire.org/\n\nSo far I think it's a nice introduction, but I believe the rest belongs\nto a different page. Actually it depends on what audience we target the\nmain page for. The two main options I can think of are libcamera users\n(I put applications developers and system integrators in this category\nfor now), and libcamera developers. I'm leaning towards the former, in\nwhich case I think it would make sense to move the contents of the\ncamera_stack.rst page here, and move the internal architecture to a separate\npage.\n\n>  \n>  libcamera Architecture\n>  ======================\n> @@ -177,7 +252,7 @@ Helpers and Support Classes\n>  \n>  \n>  V4L2 Compatibility Layer\n> -------------------------\n> +========================\n>  \n>  V4L2 compatibility is achieved through a shared library that traps all\n>  accesses to camera devices and routes them to libcamera to emulate high-level\n> @@ -190,7 +265,7 @@ designed for video conferencing.\n>  \n>  \n>  Android Camera HAL\n> -------------------\n> +==================\n>  \n>  Camera support for Android is achieved through a generic Android\n>  camera HAL implementation on top of libcamera. The HAL will implement internally\n> @@ -200,3 +275,42 @@ support.\n>  The Android camera HAL implementation will initially target the\n>  LIMITED hardware level, with support for the FULL level then being gradually\n>  implemented.\n\n\nThe description of the compat layers duplicates the text in\ncamera_stack.rst. Moving the whole stack description here will fix that.\n\n> +\n> +Platform Support\n> +================\n> +\n> +The library currently supports the following hardware platforms specifically\n> +with dedicated pipeline handlers:\n> +\n> +   -  Arm Mali-C55 (mali-c55)\n\nI think you can use a single space after the '-'.\n\n> +   -  Intel IPU3 (ipu3)\n\n   -  NXP i.MX8MP (imx8-isi and rkisp1)\n\n> +   -  Rockchip RK3399 (rkisp1)\n> +   -  RaspberryPi 3 and 4 (rpi/vc4)\n\n   - Raspberry Pi 3, 4 and zero (rpi/vc4)\n\n> +\n> +Furthermore, generic platform support is provided for the following:\n> +\n> +   -  USB video device class cameras (uvcvideo)\n> +   -  iMX7, Allwinner Sun6i (simple)\n\nIPU6 works too. There are also other platforms supported by the simple\npipeline handler.\n\nIf we move the architecture to a separate document, there will be no\nmention of pipeline handlers here anymore. This text could be reworked\nto list platforms from a user point of view, maybe based on the level of\nsupport they have (with ISP, with software ISP, without ISP, ...).\n\nYou're mainly moving contents here, so this could be done in a separate\npatch.\n\n> +   -  Virtual media controller driver for test use cases (vimc)\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\nThis section feels a bit out-of-place, but I don't have a better\nsuggestion for now.\n\n> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst\n> index 613366d1..d978b704 100644\n> --- a/Documentation/documentation-contents.rst\n> +++ b/Documentation/documentation-contents.rst\n> @@ -10,7 +10,6 @@\n>     * :doc:`/environment_variables`\n>     * :doc:`/feature_requirements`\n>     * :doc:`/guides/application-developer`\n> -   * :doc:`/guides/introduction`\n\nI would also rename docs.rst to introduction.rst now that it has become\nan introduction.\n\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 e419eb9d..00000000\n> --- a/Documentation/guides/introduction.rst\n> +++ /dev/null\n> @@ -1,78 +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 current `Platform Support`_ is detailed, as well as\n> -an overview of the `Licensing`_ requirements of the project.\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> -Platform Support\n> -----------------\n> -\n> -The library currently supports the following hardware platforms specifically\n> -with dedicated pipeline handlers:\n> -\n> -   -  Intel IPU3 (ipu3)\n> -   -  Rockchip RK3399 (rkisp1)\n> -   -  RaspberryPi 3 and 4 (rpi/vc4)\n> -\n> -Furthermore, generic platform support is provided for the following:\n> -\n> -   -  USB video device class cameras (uvcvideo)\n> -   -  iMX7, Allwinner Sun6i (simple)\n> -   -  Virtual media controller driver for test use cases (vimc)\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 59416906..6d7d2ca3 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -17,7 +17,6 @@\n>     Application Writer's Guide <guides/application-developer>\n>     Camera Sensor Model <camera-sensor-model>\n>     Camera Stack <camera_stack>\n> -   Developer Guide <guides/introduction>\n>     Environment variables <environment_variables>\n>     Feature Requirements <feature_requirements>\n>     IPA Writer's guide <guides/ipa>\n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 74cffc11..32642f32 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -134,7 +134,6 @@ if sphinx.found()\n>          'environment_variables.rst',\n>  \t'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',","headers":{"Return-Path":"<libcamera-devel-bounces@lists.libcamera.org>","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 CD142C323E\n\tfor <parsemail@patchwork.libcamera.org>;\n\tSun, 18 Aug 2024 23:01:53 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 747EE633BD;\n\tMon, 19 Aug 2024 01:01:52 +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 3436963382\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tMon, 19 Aug 2024 01:01:50 +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 1C04D2D5;\n\tMon, 19 Aug 2024 01:00:49 +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=\"i0ohwP13\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1724022049;\n\tbh=1LWlZMMM+VrDME50xzwSTF4NlWTdvsYdYNCAKiww2lY=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=i0ohwP13yfM2fc6Of8STkwBhWMoNm5EP0LkijHSfEGC9Q1S/Wtt056yCz+82Hc1tu\n\tbOyVrD80GzZeJh+v4ext8adaqfplc8VH27mQyg72uCIHaMPsA679WcCU9+nIYjq4zV\n\taFwgbG4KrqMC1U5Pce182VSLEUjkFAvApQjeFl9g=","Date":"Mon, 19 Aug 2024 02:01:22 +0300","From":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","To":"Daniel Scally <dan.scally@ideasonboard.com>","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH v2 6/7] Documentation: Expand introductory content on\n\tdocs.rst","Message-ID":"<20240818230122.GD15356@pendragon.ideasonboard.com>","References":"<20240815082944.170109-1-dan.scally@ideasonboard.com>\n\t<20240815082944.170109-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":"<20240815082944.170109-7-dan.scally@ideasonboard.com>","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"}}]