Patch Detail
Show a patch.
GET /api/1.1/patches/20963/?format=api
{ "id": 20963, "url": "https://patchwork.libcamera.org/api/1.1/patches/20963/?format=api", "web_url": "https://patchwork.libcamera.org/patch/20963/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/1.1/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20240820130740.568243-7-dan.scally@ideasonboard.com>", "date": "2024-08-20T13:07:37", "name": "[v4,6/9] Documentation: Rework docs.rst into introduction.rst", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "a6f0f74872e98f542b48b09745c86890469223d6", "submitter": { "id": 156, "url": "https://patchwork.libcamera.org/api/1.1/people/156/?format=api", "name": "Dan Scally", "email": "dan.scally@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/20963/mbox/", "series": [ { "id": 4528, "url": "https://patchwork.libcamera.org/api/1.1/series/4528/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=4528", "date": "2024-08-20T13:07:31", "name": "Documentation improvements", "version": 4, "mbox": "https://patchwork.libcamera.org/series/4528/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/20963/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/20963/checks/", "tags": {}, "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 63BE4BDB13\n\tfor <parsemail@patchwork.libcamera.org>;\n\tTue, 20 Aug 2024 13:08:16 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 2D118633D0;\n\tTue, 20 Aug 2024 15:08:09 +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 83019633B2\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 20 Aug 2024 15:07:55 +0200 (CEST)", "from mail.ideasonboard.com\n\t(cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 7619B6BE;\n\tTue, 20 Aug 2024 15:06:53 +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=\"AxXGe3Bc\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1724159213;\n\tbh=WSgKwzPTa+FnWzCYtXqWmHd3OPQf7wtkqj8ywX6Wv4c=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=AxXGe3Bc2Gsy+StYeN4cm93EmwMovmpfZZtGclZeCQSv35lZXsHP2xYUXqrX6U/5W\n\t1dpVSHzRg34WJjEBPbxN4QDP8+XjcercjAG9CylCktpoy9YItLgIc7pGwXPE3i0WRT\n\tjmW3b3nDkwdDSAahKnQIyD4GJPiiycQtVXHbzV/I=", "From": "Daniel Scally <dan.scally@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Cc": "Daniel Scally <dan.scally@ideasonboard.com>,\n\tLaurent Pinchart <laurent.pinchart@ideasonboard.com>", "Subject": "[PATCH v4 6/9] Documentation: Rework docs.rst into introduction.rst", "Date": "Tue, 20 Aug 2024 14:07:37 +0100", "Message-Id": "<20240820130740.568243-7-dan.scally@ideasonboard.com>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20240820130740.568243-1-dan.scally@ideasonboard.com>", "References": "<20240820130740.568243-1-dan.scally@ideasonboard.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "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>" }, "content": "docs.rst is the landing page for the documentation from the libcamera\nwebsite, but isn't particularly introductory. Move much of the content\nfrom guides/introduction.rst to docs.rst, which will serve as the new\nintroductory page. Remove guides/introduction.rst.\n\nReviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\nSigned-off-by: Daniel Scally <dan.scally@ideasonboard.com>\n---\nChanges since v3:\n\n\t- Minor changes to wording.\n\nChanges 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\nChanges 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} | 112 ++++++++++++++++++-\n Documentation/mali-c55.dot | 25 +++++\n Documentation/meson.build | 4 +-\n 7 files changed, 137 insertions(+), 73 deletions(-)\n delete mode 100644 Documentation/guides/introduction.rst\n rename Documentation/{docs.rst => introduction.rst} (53%)\n create mode 100644 Documentation/mali-c55.dot", "diff": "diff --git a/Documentation/conf.py b/Documentation/conf.py\nindex 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 \ndiff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst\nindex 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`\ndiff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst\ndeleted file mode 100644\nindex 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\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex 95c80b4e..3a790352 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -10,13 +10,12 @@\n :caption: Contents:\n \n Home <self>\n- Docs <docs>\n+ Introduction <introduction>\n Contribute <contributing>\n Getting Started <getting-started>\n \n Application Writer's Guide <guides/application-developer>\n Camera Sensor Model <camera-sensor-model>\n- Developer Guide <guides/introduction>\n Environment variables <environment_variables>\n Feature Requirements <feature_requirements>\n IPA Writer's guide <guides/ipa>\ndiff --git a/Documentation/docs.rst b/Documentation/introduction.rst\nsimilarity index 53%\nrename from Documentation/docs.rst\nrename to Documentation/introduction.rst\nindex 67875ac1..8f96c65f 100644\n--- a/Documentation/docs.rst\n+++ b/Documentation/introduction.rst\n@@ -14,12 +14,90 @@ Documentation\n \n API <api-html/index>\n \n-API\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+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\n+multimedia devices through the 'Linux media' subsystem and provides a set of\n+application programming interfaces known collectively as the\n+V4L2 (`Video for Linux 2`_) and the `Media Controller`_ APIs, which provide an\n+interface to interact and control media 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+\n+The usage of these drivers to provide a functioning camera stack is a\n+responsibility that lies in userspace, and 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 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:\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+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, and you can find\n+detailed information on how to do so in the\n+:doc:`application writer's guide <guides/application-developer>`.\n+\n+It is often more appropriate to use one of the frameworks with libcamera\n+support. For example an application powering an embedded media device\n+incorporating capture, encoding and streaming of both video and audio would\n+benefit from using `GStreamer`_, for which libcamera provides a plugin.\n+Similarly an application for user-facing devices like a laptop would likely\n+benefit accessing cameras through the XDG camera portal and `pipewire`_, which\n+brings the advantages of resource sharing (multiple applications accessing the\n+stream at the same time) and access control.\n+\n+.. _GStreamer: https://gstreamer.freedesktop.org/\n+.. _pipewire: https://pipewire.org/\n \n Camera Stack\n ============\n@@ -124,3 +202,25 @@ Native libcamera API\n followed in the :doc:`Application writer's guide </guides/application-developer>`\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+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\ndiff --git a/Documentation/mali-c55.dot b/Documentation/mali-c55.dot\nnew file mode 100644\nindex 00000000..7bfc44c0\n--- /dev/null\n+++ b/Documentation/mali-c55.dot\n@@ -0,0 +1,25 @@\n+/* SPDX-License-Identifier: CC-BY-SA-4.0 */\n+\n+digraph board {\n+ rankdir=TB\n+ n00000001 [label=\"{{} | mali-c55 tpg\\n/dev/v4l-subdev0 | {<port0> 0}}\", shape=Mrecord, style=filled, fillcolor=green]\n+ n00000001:port0 -> n00000003:port0 [style=dashed]\n+ 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]\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=\"{{<port0> 0 | <port2> 2} | mali-c55 resizer fr\\n/dev/v4l-subdev2 | {<port1> 1}}\", shape=Mrecord, style=filled, fillcolor=green]\n+ n00000009:port1 -> n00000010\n+ n0000000d [label=\"{{<port0> 0} | mali-c55 resizer ds\\n/dev/v4l-subdev3 | {<port1> 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=\"{{<port0> 0} | lte-csi2-rx\\n/dev/v4l-subdev4 | {<port1> 1}}\", shape=Mrecord, style=filled, fillcolor=green]\n+ n00000030:port1 -> n00000003:port0\n+ n00000035 [label=\"{{} | imx415 1-001a\\n/dev/v4l-subdev5 | {<port0> 0}}\", shape=Mrecord, style=filled, fillcolor=green]\n+ n00000035:port0 -> n00000030:port0 [style=bold]\n+}\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 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',\n", "prefixes": [ "v4", "6/9" ] }