Patch Detail
Show a patch.
GET /api/1.1/patches/15584/?format=api
{ "id": 15584, "url": "https://patchwork.libcamera.org/api/1.1/patches/15584/?format=api", "web_url": "https://patchwork.libcamera.org/patch/15584/", "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": "<20220329114302.53952-1-dev.kwang.son@gmail.com>", "date": "2022-03-29T11:43:02", "name": "[libcamera-devel,RFC] Documentation: Replace internal guide tree", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "60e991067fb4c8c78e5f7fc2325362cfa87ceb94", "submitter": { "id": 115, "url": "https://patchwork.libcamera.org/api/1.1/people/115/?format=api", "name": "Kwang Son", "email": "dev.kwang.son@gmail.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/15584/mbox/", "series": [ { "id": 3013, "url": "https://patchwork.libcamera.org/api/1.1/series/3013/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=3013", "date": "2022-03-29T11:43:02", "name": "[libcamera-devel,RFC] Documentation: Replace internal guide tree", "version": 1, "mbox": "https://patchwork.libcamera.org/series/3013/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/15584/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/15584/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 BB141C3256\n\tfor <parsemail@patchwork.libcamera.org>;\n\tTue, 29 Mar 2022 11:43:10 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 0995F65635;\n\tTue, 29 Mar 2022 13:43:10 +0200 (CEST)", "from mail-pl1-x632.google.com (mail-pl1-x632.google.com\n\t[IPv6:2607:f8b0:4864:20::632])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 341CC60135\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 29 Mar 2022 13:43:09 +0200 (CEST)", "by mail-pl1-x632.google.com with SMTP id n18so17358767plg.5\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 29 Mar 2022 04:43:09 -0700 (PDT)", "from localhost.localdomain ([121.165.1.209])\n\tby smtp.gmail.com with ESMTPSA id\n\tz16-20020aa78890000000b004fad8469f88sm19534252pfe.38.2022.03.29.04.43.04\n\tfor <libcamera-devel@lists.libcamera.org>\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tTue, 29 Mar 2022 04:43:05 -0700 (PDT)" ], "DKIM-Signature": [ "v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1648554190;\n\tbh=nJzrQL4cba1Yll1s3ddQq3zLbsdbXTw6bU0GIEbojSw=;\n\th=To:Date:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post:\n\tList-Help:List-Subscribe:From:Reply-To:From;\n\tb=DimRs1d3g34XUdaE5xp5az17XAeV7ZrNfORJEEeZSyqmqiv2N55xIs2QwMzNeyfqS\n\t9zkJHK1NPTOAoz+3h4Bryrn/VPiGl+ZuCXM+sFZxSWGSaJ8ATAeZfK8tyOMwGkZeMT\n\trr4res/jQOvltS6GhZZer6pSH4kE9yDYPpwTplLQQM3vMV0d/Rylm6JgiZd4mdDIb6\n\tqKbmZITldTHWHar0DRpvZNnFyqBeK5A99KDtV1WNpCPDS7+gLUZ2ZPFpjc3Aq2DP2y\n\tRAQs96E1JL4s2gGxzDd1Jj/qfiPzlgnSC6APoTScVbCInQOoQrYvnyFzFy/JRHGOiw\n\tEnI53sZ9M+Y4Q==", "v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;\n\th=from:to:subject:date:message-id:mime-version\n\t:content-transfer-encoding;\n\tbh=5+mH4v/62PrKs81fAl8r2tesXzVDnwIslNiftUUDEo0=;\n\tb=LLUk4Z3bmLchs/nByYpPyhSJ8g16jvHDU8zaE3Rzmotxk3zS8XNlpdUXcyLBJhR1YI\n\tbfaecUpUpxx1DGdWMqzraaqH4Wfn14ADfIdHtBUaNkgIrhWkiGqSufhouwVl78rW5vFu\n\t9Sca0yP6N4wwkFSg0YJzQyXokbDLbQVZ/LmrCx/m1BVA9YPLTfPyAiIPHLr/dnMyvyaM\n\tqpO8GxuIK9YEJEr/btFkoyVNMBT6PIcDWIvec1Jk7jWZpp2VpgJW1h0F2STmdwaYTMG9\n\tfiDevQSISWip2TTCqoSe1kfDBpO3naSh/7zqlReuVHFOt37WAir/RVHJ/l/bZrSfFkCM\n\tMgjQ==" ], "Authentication-Results": "lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=gmail.com header.i=@gmail.com\n\theader.b=\"LLUk4Z3b\"; dkim-atps=neutral", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20210112;\n\th=x-gm-message-state:from:to:subject:date:message-id:mime-version\n\t:content-transfer-encoding;\n\tbh=5+mH4v/62PrKs81fAl8r2tesXzVDnwIslNiftUUDEo0=;\n\tb=K7KboG9zuosm9L7B2iOuiLWMvTA+9ux9anRGlCaWoUbcCL8++MImVxA7PzxFxQSuwa\n\tTHoCzW5sMH7RfykbLMc59fco/gTgq/8vprE2HIuWHRkG5eLevcSVCR8HjsaylwXT3Uhi\n\t8V2+O25NOYLjY2JJOl/N3nGGKCbyr3sQbDiE391wcT4JGMXtY3ycPksNeBgU/VUelOE0\n\tN1xq2kYa8AgfB76j9CuBC32QSaIOTlF7kszVpl1kfXfxKsjRLYpGcJSlQfCIw2FX3YE0\n\tqjrDzuk9yLmTG9MdUIkQq9IPF/xf1G9A7O/TatwHLjOTS87JkAlgZzfA3YFdrPdh1Awr\n\t/Lnw==", "X-Gm-Message-State": "AOAM531/2/vCJGorB8s5OAWw9cLksJ3bSR/r5CqTJMOpMH8BXQlvsBsA\n\tkhEKw9mHfKDjgRttXLfpMCQz8rym4Q6rYQ==", "X-Google-Smtp-Source": "ABdhPJyJwsVKisW//Jji3IJd9b4A7XYhBcQ63g495va08AAX7IpiFM4Pi/vRoTHOTP6fUhh+WBYC7Q==", "X-Received": "by 2002:a17:902:b70c:b0:156:16f0:cbfe with SMTP id\n\td12-20020a170902b70c00b0015616f0cbfemr7731182pls.152.1648554186440; \n\tTue, 29 Mar 2022 04:43:06 -0700 (PDT)", "To": "libcamera-devel@lists.libcamera.org", "Date": "Tue, 29 Mar 2022 20:43:02 +0900", "Message-Id": "<20220329114302.53952-1-dev.kwang.son@gmail.com>", "X-Mailer": "git-send-email 2.25.1", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [RFC PATCH] Documentation: Replace internal guide\n\ttree", "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>", "From": "Kwang Son via libcamera-devel <libcamera-devel@lists.libcamera.org>", "Reply-To": "Kwang Son <dev.kwang.son@gmail.com>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "Internal guide child of top tree so it's can not shown on official\nsite[1]. Change tree hierarchy so docs can contain interal libcamera\nwriter's guide.\n\n[1] https://www.libcamera.org/docs.html\n\nSigned-off-by: Kwang Son <dev.kwang.son@gmail.com>\n---\n Documentation/api-html/index.rst | 2 +\n Documentation/docs.rst | 397 +-------------------------\n Documentation/index.rst | 11 +-\n Documentation/libcamera-developer.rst | 15 +\n Documentation/overview.rst | 395 +++++++++++++++++++++++++\n 5 files changed, 418 insertions(+), 402 deletions(-)\n create mode 100644 Documentation/libcamera-developer.rst\n create mode 100644 Documentation/overview.rst", "diff": "diff --git a/Documentation/api-html/index.rst b/Documentation/api-html/index.rst\nindex 9e630fc0..380cfe25 100644\n--- a/Documentation/api-html/index.rst\n+++ b/Documentation/api-html/index.rst\n@@ -2,6 +2,8 @@\n \n .. _api:\n \n+:orphan:\n+\n API\n ===\n \ndiff --git a/Documentation/docs.rst b/Documentation/docs.rst\nindex a6e8a59a..65a1959d 100644\n--- a/Documentation/docs.rst\n+++ b/Documentation/docs.rst\n@@ -1,400 +1,13 @@\n .. SPDX-License-Identifier: CC-BY-SA-4.0\n \n-.. contents::\n- :local:\n-\n *************\n Documentation\n *************\n \n .. toctree::\n- :hidden:\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-\n-Feature Requirements\n-====================\n-\n-Device enumeration\n-------------------\n-\n-The library shall support enumerating all camera devices available in the\n-system, including both fixed cameras and hotpluggable cameras. It shall\n-support cameras plugged and unplugged after the initialization of the\n-library, and shall offer a mechanism to notify applications of camera plug\n-and unplug.\n-\n-The following types of cameras shall be supported:\n-\n-* Internal cameras designed for point-and-shoot still image and video\n- capture usage, either controlled directly by the CPU, or exposed through\n- an internal USB bus as a UVC device.\n-\n-* External UVC cameras designed for video conferencing usage.\n-\n-Other types of camera, including analog cameras, depth cameras, thermal\n-cameras, external digital picture or movie cameras, are out of scope for\n-this project.\n-\n-A hardware device that includes independent camera sensors, such as front\n-and back sensors in a phone, shall be considered as multiple camera devices\n-for the purpose of this library.\n-\n-Independent Camera Devices\n---------------------------\n-\n-When multiple cameras are present in the system and are able to operate\n-independently from each other, the library shall expose them as multiple\n-camera devices and support parallel operation without any additional usage\n-restriction apart from the limitations inherent to the hardware (such as\n-memory bandwidth, CPU usage or number of CSI-2 receivers for instance).\n-\n-Independent processes shall be able to use independent cameras devices\n-without interfering with each other. A single camera device shall be\n-usable by a single process at a time.\n-\n-Multiple streams support\n-------------------------\n-\n-The library shall support multiple video streams running in parallel\n-for each camera device, within the limits imposed by the system.\n-\n-Per frame controls\n-------------------\n-\n-The library shall support controlling capture parameters for each stream\n-on a per-frame basis, on a best effort basis based on the capabilities of the\n-hardware and underlying software stack (including kernel drivers and\n-firmware). It shall apply capture parameters to the frame they target, and\n-report the value of the parameters that have effectively been used for each\n-captured frame.\n-\n-When a camera device supports multiple streams, the library shall allow both\n-control of each stream independently, and control of multiple streams\n-together. Streams that are controlled together shall be synchronized. No\n-synchronization is required for streams controlled independently.\n-\n-Capability Enumeration\n-----------------------\n-\n-The library shall expose capabilities of each camera device in a way that\n-allows applications to discover those capabilities dynamically. Applications\n-shall be allowed to cache capabilities for as long as they are using the\n-library. If capabilities can change at runtime, the library shall offer a\n-mechanism to notify applications of such changes. Applications shall not\n-cache capabilities in long term storage between runs.\n-\n-Capabilities shall be discovered dynamically at runtime from the device when\n-possible, and may come, in part or in full, from platform configuration\n-data.\n-\n-Device Profiles\n----------------\n-\n-The library may define different camera device profiles, each with a minimum\n-set of required capabilities. Applications may use those profiles to quickly\n-determine the level of features exposed by a device without parsing the full\n-list of capabilities. Camera devices may implement additional capabilities\n-on top of the minimum required set for the profile they expose.\n-\n-3A and Image Enhancement Algorithms\n------------------------------------\n-\n-The camera devices shall implement auto exposure, auto gain and auto white\n-balance. Camera devices that include a focus lens shall implement auto\n-focus. Additional image enhancement algorithms, such as noise reduction or\n-video stabilization, may be implemented.\n-\n-All algorithms may be implemented in hardware or firmware outside of the\n-library, or in software in the library. They shall all be controllable by\n-applications.\n-\n-The library shall be architectured to isolate the 3A and image enhancement\n-algorithms in a component with a documented API, respectively called the 3A\n-component and the 3A API. The 3A API shall be stable, and shall allow both\n-open-source and closed-source implementations of the 3A component.\n-\n-The library may include statically-linked open-source 3A components, and\n-shall support dynamically-linked open-source and closed-source 3A\n-components.\n-\n-Closed-source 3A Component Sandboxing\n--------------------------------------\n-\n-For security purposes, it may be desired to run closed-source 3A components\n-in a separate process. The 3A API would in such a case be transported over\n-IPC. The 3A API shall make it possible to use any IPC mechanism that\n-supports passing file descriptors.\n-\n-The library may implement an IPC mechanism, and shall support third-party\n-platform-specific IPC mechanisms through the implementation of a\n-platform-specific 3A API wrapper. No modification to the library shall be\n-needed to use such third-party IPC mechanisms.\n-\n-The 3A component shall not directly access any device node on the system.\n-Such accesses shall instead be performed through the 3A API. The library\n-shall validate all accesses and restrict them to what is absolutely required\n-by 3A components.\n-\n-V4L2 Compatibility Layer\n-------------------------\n-\n-The project shall support traditional V4L2 application through an additional\n-libcamera wrapper library. The wrapper library shall trap all accesses to\n-camera devices through `LD_PRELOAD`, and route them through libcamera to\n-emulate a high-level V4L2 camera device. It shall expose camera device\n-features on a best-effort basis, and aim for the level of features\n-traditionally available from a UVC camera designed for video conferencing.\n-\n-Android Camera HAL v3 Compatibility\n------------------------------------\n-\n-The library API shall expose all the features required to implement an\n-Android Camera HAL v3 on top of libcamera. Some features of the HAL may be\n-omitted as long as they can be implemented separately in the HAL, such as\n-JPEG encoding, or YUV reprocessing.\n-\n-\n-Camera Stack\n-============\n-\n-::\n-\n- a c / +-------------+ +-------------+ +-------------+ +-------------+\n- p a | | Native | | Framework | | Native | | Android |\n- p t | | V4L2 | | Application | | libcamera | | Camera |\n- l i | | Application | | (gstreamer) | | Application | | Framework |\n- i o \\ +-------------+ +-------------+ +-------------+ +-------------+\n- n ^ ^ ^ ^\n- | | | |\n- l a | | | |\n- i d v v | v\n- b a / +-------------+ +-------------+ | +-------------+\n- c p | | V4L2 | | Camera | | | Android |\n- a t | | Compat. | | Framework | | | Camera |\n- m a | | | | (gstreamer) | | | HAL |\n- e t \\ +-------------+ +-------------+ | +-------------+\n- r i ^ ^ | ^\n- a o | | | |\n- n | | | |\n- / | ,................................................\n- | | ! : Language : !\n- l f | | ! : Bindings : !\n- i r | | ! : (optional) : !\n- b a | | \\...............................................'\n- c m | | | | |\n- a e | | | | |\n- m w | v v v v\n- e o | +----------------------------------------------------------------+\n- r r | | |\n- a k | | libcamera |\n- | | |\n- \\ +----------------------------------------------------------------+\n- ^ ^ ^\n- Userspace | | |\n- ------------------------ | ---------------- | ---------------- | ---------------\n- Kernel | | |\n- v v v\n- +-----------+ +-----------+ +-----------+\n- | Media | <--> | Video | <--> | V4L2 |\n- | Device | | Device | | Subdev |\n- +-----------+ +-----------+ +-----------+\n-\n-The camera stack comprises four software layers. From bottom to top:\n-\n-* The kernel drivers control the camera hardware and expose a\n- low-level interface to userspace through the Linux kernel V4L2\n- family of APIs (Media Controller API, V4L2 Video Device API and\n- V4L2 Subdev API).\n-\n-* The libcamera framework is the core part of the stack. It\n- handles all control of the camera devices in its core component,\n- libcamera, and exposes a native C++ API to upper layers. Optional\n- language bindings allow interfacing to libcamera from other\n- programming languages.\n-\n- Those components live in the same source code repository and\n- all together constitute the libcamera framework.\n-\n-* The libcamera adaptation is an umbrella term designating the\n- components that interface to libcamera in other frameworks.\n- Notable examples are a V4L2 compatibility layer, a gstreamer\n- libcamera element, and an Android camera HAL implementation based\n- on libcamera.\n-\n- Those components can live in the libcamera project source code\n- in separate repositories, or move to their respective project's\n- repository (for instance the gstreamer libcamera element).\n-\n-* The applications and upper level frameworks are based on the\n- libcamera framework or libcamera adaptation, and are outside of\n- the scope of the libcamera project.\n-\n-\n-libcamera Architecture\n-======================\n-\n-::\n-\n- ---------------------------< libcamera Public API >---------------------------\n- ^ ^\n- | |\n- v v\n- +-------------+ +-------------------------------------------------+\n- | Camera | | Camera Device |\n- | Devices | | +---------------------------------------------+ |\n- | Manager | | | Device-Agnostic | |\n- +-------------+ | | | |\n- ^ | | +------------------------+ |\n- | | | | ~~~~~~~~~~~~~~~~~~~~~ |\n- | | | | { +---------------+ } |\n- | | | | } | ////Image//// | { |\n- | | | | <-> | /Processing// | } |\n- | | | | } | /Algorithms// | { |\n- | | | | { +---------------+ } |\n- | | | | ~~~~~~~~~~~~~~~~~~~~~ |\n- | | | | ======================== |\n- | | | | +---------------+ |\n- | | | | | //Pipeline/// | |\n- | | | | <-> | ///Handler/// | |\n- | | | | | ///////////// | |\n- | | +--------------------+ +---------------+ |\n- | | Device-Specific |\n- | +-------------------------------------------------+\n- | ^ ^\n- | | |\n- v v v\n- +--------------------------------------------------------------------+\n- | Helpers and Support Classes |\n- | +-------------+ +-------------+ +-------------+ +-------------+ |\n- | | MC & V4L2 | | Buffers | | Sandboxing | | Plugins | |\n- | | Support | | Allocator | | IPC | | Manager | |\n- | +-------------+ +-------------+ +-------------+ +-------------+ |\n- | +-------------+ +-------------+ |\n- | | Pipeline | | ... | |\n- | | Runner | | | |\n- | +-------------+ +-------------+ |\n- +--------------------------------------------------------------------+\n-\n- /// Device-Specific Components\n- ~~~ Sandboxing\n-\n-While offering a unified API towards upper layers, and presenting\n-itself as a single library, libcamera isn't monolithic. It exposes\n-multiple components through its public API, is built around a set of\n-separate helpers internally, uses device-specific components and can\n-load dynamic plugins.\n-\n-Camera Devices Manager\n- The Camera Devices Manager provides a view of available cameras\n- in the system. It performs cold enumeration and runtime camera\n- management, and supports a hotplug notification mechanism in its\n- public API.\n-\n- To avoid the cost associated with cold enumeration of all devices\n- at application start, and to arbitrate concurrent access to camera\n- devices, the Camera Devices Manager could later be split to a\n- separate service, possibly with integration in platform-specific\n- device management.\n-\n-Camera Device\n- The Camera Device represents a camera device to upper layers. It\n- exposes full control of the device through the public API, and is\n- thus the highest level object exposed by libcamera.\n-\n- Camera Device instances are created by the Camera Devices\n- Manager. An optional function to create new instances could be exposed\n- through the public API to speed up initialization when the upper\n- layer knows how to directly address camera devices present in the\n- system.\n-\n-Pipeline Handler\n- The Pipeline Handler manages complex pipelines exposed by the kernel drivers\n- through the Media Controller and V4L2 APIs. It abstracts pipeline handling to\n- hide device-specific details to the rest of the library, and implements both\n- pipeline configuration based on stream configuration, and pipeline runtime\n- execution and scheduling when needed by the device.\n-\n- This component is device-specific and is part of the libcamera code base. As\n- such it is covered by the same free software license as the rest of libcamera\n- and needs to be contributed upstream by device vendors. The Pipeline Handler\n- lives in the same process as the rest of the library, and has access to all\n- helpers and kernel camera-related devices.\n-\n-Image Processing Algorithms\n- Together with the hardware image processing and hardware statistics\n- collection, the Image Processing Algorithms implement 3A (Auto-Exposure,\n- Auto-White Balance and Auto-Focus) and other algorithms. They run on the CPU\n- and interact with the kernel camera devices to control hardware image\n- processing based on the parameters supplied by upper layers, closing the\n- control loop of the ISP.\n-\n- This component is device-specific and is loaded as an external plugin. It can\n- be part of the libcamera code base, in which case it is covered by the same\n- license, or provided externally as an open-source or closed-source component.\n-\n- The component is sandboxed and can only interact with libcamera through\n- internal APIs specifically marked as such. In particular it will have no\n- direct access to kernel camera devices, and all its accesses to image and\n- metadata will be mediated by dmabuf instances explicitly passed to the\n- component. The component must be prepared to run in a process separate from\n- the main libcamera process, and to have a very restricted view of the system,\n- including no access to networking APIs and limited access to file systems.\n-\n- The sandboxing mechanism isn't defined by libcamera. One example\n- implementation will be provided as part of the project, and platforms vendors\n- will be able to provide their own sandboxing mechanism as a plugin.\n-\n- libcamera should provide a basic implementation of Image Processing\n- Algorithms, to serve as a reference for the internal API. Device vendors are\n- expected to provide a full-fledged implementation compatible with their\n- Pipeline Handler. One goal of the libcamera project is to create an\n- environment in which the community will be able to compete with the\n- closed-source vendor binaries and develop a high quality open source\n- implementation.\n-\n-Helpers and Support Classes\n- While Pipeline Handlers are device-specific, implementations are expected to\n- share code due to usage of identical APIs towards the kernel camera drivers\n- and the Image Processing Algorithms. This includes without limitation handling\n- of the MC and V4L2 APIs, buffer management through dmabuf, and pipeline\n- discovery, configuration and scheduling. Such code will be factored out to\n- helpers when applicable.\n-\n- Other parts of libcamera will also benefit from factoring code out to\n- self-contained support classes, even if such code is present only once in the\n- code base, in order to keep the source code clean and easy to read. This\n- should be the case for instance for plugin management.\n-\n-\n-V4L2 Compatibility Layer\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-V4L2 camera devices. It is injected in a process address space through\n-`LD_PRELOAD` and is completely transparent for applications.\n-\n-The compatibility layer exposes camera device features on a best-effort basis,\n-and aims for the level of features traditionally available from a UVC camera\n-designed for video conferencing.\n-\n-\n-Android Camera HAL\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-features required by Android and missing from libcamera, such as JPEG encoding\n-support.\n+ :maxdepth: 2\n \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+ Overview <overview>\n+ Developer Guide <guides/introduction>\n+ libcamera Writer's Guide <libcamera-developer>\n+ Application Writer's Guide <guides/application-developer>\n\\ No newline at end of file\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex 0ee10044..22c8d2c3 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -12,13 +12,4 @@\n Home <self>\n Docs <docs>\n Contribute <contributing>\n- Getting Started <getting-started>\n-\n- Developer Guide <guides/introduction>\n- Application Writer's Guide <guides/application-developer>\n- Pipeline Handler Writer's Guide <guides/pipeline-handler>\n- IPA Writer's guide <guides/ipa>\n- Tracing guide <guides/tracing>\n- Environment variables <environment_variables>\n- Sensor driver requirements <sensor_driver_requirements>\n- Lens driver requirements <lens_driver_requirements>\n+ Getting Started <getting-started>\n\\ No newline at end of file\ndiff --git a/Documentation/libcamera-developer.rst b/Documentation/libcamera-developer.rst\nnew file mode 100644\nindex 00000000..3dd56a49\n--- /dev/null\n+++ b/Documentation/libcamera-developer.rst\n@@ -0,0 +1,15 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+**************************\n+libcamera Writer's Guide\n+**************************\n+\n+.. toctree::\n+ :maxdepth: 1\n+\n+ Pipeline Handler Writer's Guide <guides/pipeline-handler>\n+ IPA Writer's guide <guides/ipa>\n+ Tracing guide <guides/tracing>\n+ Environment variables <environment_variables>\n+ Sensor driver requirements <sensor_driver_requirements>\n+ Lens driver requirements <lens_driver_requirements>\n\\ No newline at end of file\ndiff --git a/Documentation/overview.rst b/Documentation/overview.rst\nnew file mode 100644\nindex 00000000..c7cc1a68\n--- /dev/null\n+++ b/Documentation/overview.rst\n@@ -0,0 +1,395 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+.. contents::\n+ :local:\n+\n+*************\n+Overview\n+*************\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+\n+Feature Requirements\n+====================\n+\n+Device enumeration\n+------------------\n+\n+The library shall support enumerating all camera devices available in the\n+system, including both fixed cameras and hotpluggable cameras. It shall\n+support cameras plugged and unplugged after the initialization of the\n+library, and shall offer a mechanism to notify applications of camera plug\n+and unplug.\n+\n+The following types of cameras shall be supported:\n+\n+* Internal cameras designed for point-and-shoot still image and video\n+ capture usage, either controlled directly by the CPU, or exposed through\n+ an internal USB bus as a UVC device.\n+\n+* External UVC cameras designed for video conferencing usage.\n+\n+Other types of camera, including analog cameras, depth cameras, thermal\n+cameras, external digital picture or movie cameras, are out of scope for\n+this project.\n+\n+A hardware device that includes independent camera sensors, such as front\n+and back sensors in a phone, shall be considered as multiple camera devices\n+for the purpose of this library.\n+\n+Independent Camera Devices\n+--------------------------\n+\n+When multiple cameras are present in the system and are able to operate\n+independently from each other, the library shall expose them as multiple\n+camera devices and support parallel operation without any additional usage\n+restriction apart from the limitations inherent to the hardware (such as\n+memory bandwidth, CPU usage or number of CSI-2 receivers for instance).\n+\n+Independent processes shall be able to use independent cameras devices\n+without interfering with each other. A single camera device shall be\n+usable by a single process at a time.\n+\n+Multiple streams support\n+------------------------\n+\n+The library shall support multiple video streams running in parallel\n+for each camera device, within the limits imposed by the system.\n+\n+Per frame controls\n+------------------\n+\n+The library shall support controlling capture parameters for each stream\n+on a per-frame basis, on a best effort basis based on the capabilities of the\n+hardware and underlying software stack (including kernel drivers and\n+firmware). It shall apply capture parameters to the frame they target, and\n+report the value of the parameters that have effectively been used for each\n+captured frame.\n+\n+When a camera device supports multiple streams, the library shall allow both\n+control of each stream independently, and control of multiple streams\n+together. Streams that are controlled together shall be synchronized. No\n+synchronization is required for streams controlled independently.\n+\n+Capability Enumeration\n+----------------------\n+\n+The library shall expose capabilities of each camera device in a way that\n+allows applications to discover those capabilities dynamically. Applications\n+shall be allowed to cache capabilities for as long as they are using the\n+library. If capabilities can change at runtime, the library shall offer a\n+mechanism to notify applications of such changes. Applications shall not\n+cache capabilities in long term storage between runs.\n+\n+Capabilities shall be discovered dynamically at runtime from the device when\n+possible, and may come, in part or in full, from platform configuration\n+data.\n+\n+Device Profiles\n+---------------\n+\n+The library may define different camera device profiles, each with a minimum\n+set of required capabilities. Applications may use those profiles to quickly\n+determine the level of features exposed by a device without parsing the full\n+list of capabilities. Camera devices may implement additional capabilities\n+on top of the minimum required set for the profile they expose.\n+\n+3A and Image Enhancement Algorithms\n+-----------------------------------\n+\n+The camera devices shall implement auto exposure, auto gain and auto white\n+balance. Camera devices that include a focus lens shall implement auto\n+focus. Additional image enhancement algorithms, such as noise reduction or\n+video stabilization, may be implemented.\n+\n+All algorithms may be implemented in hardware or firmware outside of the\n+library, or in software in the library. They shall all be controllable by\n+applications.\n+\n+The library shall be architectured to isolate the 3A and image enhancement\n+algorithms in a component with a documented API, respectively called the 3A\n+component and the 3A API. The 3A API shall be stable, and shall allow both\n+open-source and closed-source implementations of the 3A component.\n+\n+The library may include statically-linked open-source 3A components, and\n+shall support dynamically-linked open-source and closed-source 3A\n+components.\n+\n+Closed-source 3A Component Sandboxing\n+-------------------------------------\n+\n+For security purposes, it may be desired to run closed-source 3A components\n+in a separate process. The 3A API would in such a case be transported over\n+IPC. The 3A API shall make it possible to use any IPC mechanism that\n+supports passing file descriptors.\n+\n+The library may implement an IPC mechanism, and shall support third-party\n+platform-specific IPC mechanisms through the implementation of a\n+platform-specific 3A API wrapper. No modification to the library shall be\n+needed to use such third-party IPC mechanisms.\n+\n+The 3A component shall not directly access any device node on the system.\n+Such accesses shall instead be performed through the 3A API. The library\n+shall validate all accesses and restrict them to what is absolutely required\n+by 3A components.\n+\n+V4L2 Compatibility Layer\n+------------------------\n+\n+The project shall support traditional V4L2 application through an additional\n+libcamera wrapper library. The wrapper library shall trap all accesses to\n+camera devices through `LD_PRELOAD`, and route them through libcamera to\n+emulate a high-level V4L2 camera device. It shall expose camera device\n+features on a best-effort basis, and aim for the level of features\n+traditionally available from a UVC camera designed for video conferencing.\n+\n+Android Camera HAL v3 Compatibility\n+-----------------------------------\n+\n+The library API shall expose all the features required to implement an\n+Android Camera HAL v3 on top of libcamera. Some features of the HAL may be\n+omitted as long as they can be implemented separately in the HAL, such as\n+JPEG encoding, or YUV reprocessing.\n+\n+\n+Camera Stack\n+============\n+\n+::\n+\n+ a c / +-------------+ +-------------+ +-------------+ +-------------+\n+ p a | | Native | | Framework | | Native | | Android |\n+ p t | | V4L2 | | Application | | libcamera | | Camera |\n+ l i | | Application | | (gstreamer) | | Application | | Framework |\n+ i o \\ +-------------+ +-------------+ +-------------+ +-------------+\n+ n ^ ^ ^ ^\n+ | | | |\n+ l a | | | |\n+ i d v v | v\n+ b a / +-------------+ +-------------+ | +-------------+\n+ c p | | V4L2 | | Camera | | | Android |\n+ a t | | Compat. | | Framework | | | Camera |\n+ m a | | | | (gstreamer) | | | HAL |\n+ e t \\ +-------------+ +-------------+ | +-------------+\n+ r i ^ ^ | ^\n+ a o | | | |\n+ n | | | |\n+ / | ,................................................\n+ | | ! : Language : !\n+ l f | | ! : Bindings : !\n+ i r | | ! : (optional) : !\n+ b a | | \\...............................................'\n+ c m | | | | |\n+ a e | | | | |\n+ m w | v v v v\n+ e o | +----------------------------------------------------------------+\n+ r r | | |\n+ a k | | libcamera |\n+ | | |\n+ \\ +----------------------------------------------------------------+\n+ ^ ^ ^\n+ Userspace | | |\n+ ------------------------ | ---------------- | ---------------- | ---------------\n+ Kernel | | |\n+ v v v\n+ +-----------+ +-----------+ +-----------+\n+ | Media | <--> | Video | <--> | V4L2 |\n+ | Device | | Device | | Subdev |\n+ +-----------+ +-----------+ +-----------+\n+\n+The camera stack comprises four software layers. From bottom to top:\n+\n+* The kernel drivers control the camera hardware and expose a\n+ low-level interface to userspace through the Linux kernel V4L2\n+ family of APIs (Media Controller API, V4L2 Video Device API and\n+ V4L2 Subdev API).\n+\n+* The libcamera framework is the core part of the stack. It\n+ handles all control of the camera devices in its core component,\n+ libcamera, and exposes a native C++ API to upper layers. Optional\n+ language bindings allow interfacing to libcamera from other\n+ programming languages.\n+\n+ Those components live in the same source code repository and\n+ all together constitute the libcamera framework.\n+\n+* The libcamera adaptation is an umbrella term designating the\n+ components that interface to libcamera in other frameworks.\n+ Notable examples are a V4L2 compatibility layer, a gstreamer\n+ libcamera element, and an Android camera HAL implementation based\n+ on libcamera.\n+\n+ Those components can live in the libcamera project source code\n+ in separate repositories, or move to their respective project's\n+ repository (for instance the gstreamer libcamera element).\n+\n+* The applications and upper level frameworks are based on the\n+ libcamera framework or libcamera adaptation, and are outside of\n+ the scope of the libcamera project.\n+\n+\n+libcamera Architecture\n+======================\n+\n+::\n+\n+ ---------------------------< libcamera Public API >---------------------------\n+ ^ ^\n+ | |\n+ v v\n+ +-------------+ +-------------------------------------------------+\n+ | Camera | | Camera Device |\n+ | Devices | | +---------------------------------------------+ |\n+ | Manager | | | Device-Agnostic | |\n+ +-------------+ | | | |\n+ ^ | | +------------------------+ |\n+ | | | | ~~~~~~~~~~~~~~~~~~~~~ |\n+ | | | | { +---------------+ } |\n+ | | | | } | ////Image//// | { |\n+ | | | | <-> | /Processing// | } |\n+ | | | | } | /Algorithms// | { |\n+ | | | | { +---------------+ } |\n+ | | | | ~~~~~~~~~~~~~~~~~~~~~ |\n+ | | | | ======================== |\n+ | | | | +---------------+ |\n+ | | | | | //Pipeline/// | |\n+ | | | | <-> | ///Handler/// | |\n+ | | | | | ///////////// | |\n+ | | +--------------------+ +---------------+ |\n+ | | Device-Specific |\n+ | +-------------------------------------------------+\n+ | ^ ^\n+ | | |\n+ v v v\n+ +--------------------------------------------------------------------+\n+ | Helpers and Support Classes |\n+ | +-------------+ +-------------+ +-------------+ +-------------+ |\n+ | | MC & V4L2 | | Buffers | | Sandboxing | | Plugins | |\n+ | | Support | | Allocator | | IPC | | Manager | |\n+ | +-------------+ +-------------+ +-------------+ +-------------+ |\n+ | +-------------+ +-------------+ |\n+ | | Pipeline | | ... | |\n+ | | Runner | | | |\n+ | +-------------+ +-------------+ |\n+ +--------------------------------------------------------------------+\n+\n+ /// Device-Specific Components\n+ ~~~ Sandboxing\n+\n+While offering a unified API towards upper layers, and presenting\n+itself as a single library, libcamera isn't monolithic. It exposes\n+multiple components through its public API, is built around a set of\n+separate helpers internally, uses device-specific components and can\n+load dynamic plugins.\n+\n+Camera Devices Manager\n+ The Camera Devices Manager provides a view of available cameras\n+ in the system. It performs cold enumeration and runtime camera\n+ management, and supports a hotplug notification mechanism in its\n+ public API.\n+\n+ To avoid the cost associated with cold enumeration of all devices\n+ at application start, and to arbitrate concurrent access to camera\n+ devices, the Camera Devices Manager could later be split to a\n+ separate service, possibly with integration in platform-specific\n+ device management.\n+\n+Camera Device\n+ The Camera Device represents a camera device to upper layers. It\n+ exposes full control of the device through the public API, and is\n+ thus the highest level object exposed by libcamera.\n+\n+ Camera Device instances are created by the Camera Devices\n+ Manager. An optional function to create new instances could be exposed\n+ through the public API to speed up initialization when the upper\n+ layer knows how to directly address camera devices present in the\n+ system.\n+\n+Pipeline Handler\n+ The Pipeline Handler manages complex pipelines exposed by the kernel drivers\n+ through the Media Controller and V4L2 APIs. It abstracts pipeline handling to\n+ hide device-specific details to the rest of the library, and implements both\n+ pipeline configuration based on stream configuration, and pipeline runtime\n+ execution and scheduling when needed by the device.\n+\n+ This component is device-specific and is part of the libcamera code base. As\n+ such it is covered by the same free software license as the rest of libcamera\n+ and needs to be contributed upstream by device vendors. The Pipeline Handler\n+ lives in the same process as the rest of the library, and has access to all\n+ helpers and kernel camera-related devices.\n+\n+Image Processing Algorithms\n+ Together with the hardware image processing and hardware statistics\n+ collection, the Image Processing Algorithms implement 3A (Auto-Exposure,\n+ Auto-White Balance and Auto-Focus) and other algorithms. They run on the CPU\n+ and interact with the kernel camera devices to control hardware image\n+ processing based on the parameters supplied by upper layers, closing the\n+ control loop of the ISP.\n+\n+ This component is device-specific and is loaded as an external plugin. It can\n+ be part of the libcamera code base, in which case it is covered by the same\n+ license, or provided externally as an open-source or closed-source component.\n+\n+ The component is sandboxed and can only interact with libcamera through\n+ internal APIs specifically marked as such. In particular it will have no\n+ direct access to kernel camera devices, and all its accesses to image and\n+ metadata will be mediated by dmabuf instances explicitly passed to the\n+ component. The component must be prepared to run in a process separate from\n+ the main libcamera process, and to have a very restricted view of the system,\n+ including no access to networking APIs and limited access to file systems.\n+\n+ The sandboxing mechanism isn't defined by libcamera. One example\n+ implementation will be provided as part of the project, and platforms vendors\n+ will be able to provide their own sandboxing mechanism as a plugin.\n+\n+ libcamera should provide a basic implementation of Image Processing\n+ Algorithms, to serve as a reference for the internal API. Device vendors are\n+ expected to provide a full-fledged implementation compatible with their\n+ Pipeline Handler. One goal of the libcamera project is to create an\n+ environment in which the community will be able to compete with the\n+ closed-source vendor binaries and develop a high quality open source\n+ implementation.\n+\n+Helpers and Support Classes\n+ While Pipeline Handlers are device-specific, implementations are expected to\n+ share code due to usage of identical APIs towards the kernel camera drivers\n+ and the Image Processing Algorithms. This includes without limitation handling\n+ of the MC and V4L2 APIs, buffer management through dmabuf, and pipeline\n+ discovery, configuration and scheduling. Such code will be factored out to\n+ helpers when applicable.\n+\n+ Other parts of libcamera will also benefit from factoring code out to\n+ self-contained support classes, even if such code is present only once in the\n+ code base, in order to keep the source code clean and easy to read. This\n+ should be the case for instance for plugin management.\n+\n+\n+V4L2 Compatibility Layer\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+V4L2 camera devices. It is injected in a process address space through\n+`LD_PRELOAD` and is completely transparent for applications.\n+\n+The compatibility layer exposes camera device features on a best-effort basis,\n+and aims for the level of features traditionally available from a UVC camera\n+designed for video conferencing.\n+\n+\n+Android Camera HAL\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+features required by Android and missing from libcamera, such as JPEG encoding\n+support.\n+\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", "prefixes": [ "libcamera-devel", "RFC" ] }