Patch Detail
Show a patch.
GET /api/1.1/patches/8441/?format=api
{ "id": 8441, "url": "https://patchwork.libcamera.org/api/1.1/patches/8441/?format=api", "web_url": "https://patchwork.libcamera.org/patch/8441/", "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": "<20200626111732.62852-1-chris@gregariousmammal.com>", "date": "2020-06-26T11:17:32", "name": "[libcamera-devel] Create libcamera overview and gloassry", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "2433f7f5aeecc93aa6734508af848eb911bd616d", "submitter": { "id": 55, "url": "https://patchwork.libcamera.org/api/1.1/people/55/?format=api", "name": "Chris Chinchilla", "email": "chris@gregariousmammal.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/8441/mbox/", "series": [ { "id": 1045, "url": "https://patchwork.libcamera.org/api/1.1/series/1045/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=1045", "date": "2020-06-26T11:17:32", "name": "[libcamera-devel] Create libcamera overview and gloassry", "version": 1, "mbox": "https://patchwork.libcamera.org/series/1045/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/8441/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/8441/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 7B212C2E66\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 26 Jun 2020 11:17:47 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id EC83D609C8;\n\tFri, 26 Jun 2020 13:17:46 +0200 (CEST)", "from mail-ej1-x644.google.com (mail-ej1-x644.google.com\n\t[IPv6:2a00:1450:4864:20::644])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id A7FA5603BB\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 26 Jun 2020 13:17:45 +0200 (CEST)", "by mail-ej1-x644.google.com with SMTP id mb16so8998945ejb.4\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 26 Jun 2020 04:17:45 -0700 (PDT)", "from localhost.localdomain ([185.199.104.22])\n\tby smtp.gmail.com with ESMTPSA id\n\ta1sm12779638ejk.125.2020.06.26.04.17.43\n\t(version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128);\n\tFri, 26 Jun 2020 04:17:44 -0700 (PDT)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=gregariousmammal.com\n\theader.i=@gregariousmammal.com header.b=\"Ub3ihk5p\"; \n\tdkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=gregariousmammal.com; s=google;\n\th=from:to:cc:subject:date:message-id:mime-version\n\t:content-transfer-encoding;\n\tbh=irNRd0B2mrVcBqwbLL8Cgb6opUpKBL4iro9phtcZ+fE=;\n\tb=Ub3ihk5pjcozYyC1It3wI+cyzMl6mz1VDLykYntuQV2Z3sOBlknpxb3OYVRKXuk48w\n\tTFXB2w+nmN2KKazlc4J5z1PYhkL7tQWOPlQsNNs1TQti+PUFmF+90i5PGMmm85SEvBGt\n\tGq1XwlQXptm43UbpeTL/hDP6pD0Sm97UAACqyLnSMsjkwBjq3GPqD5S8tFt1VIYVyXjJ\n\trfrFSDXh0KqIuEgCg3KhEgx/tIJwcLu2jf/JiBtz4XvL058VeSszTIX+sCNalBjV9bTj\n\t3vIHxths09uJv/x3h/LYZznBEfRVGnnVde2NtkImZB+sO60V1DuBSDi0okm8d2DW/rJH\n\twFEg==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version\n\t:content-transfer-encoding;\n\tbh=irNRd0B2mrVcBqwbLL8Cgb6opUpKBL4iro9phtcZ+fE=;\n\tb=aHCYR7BW8O9z97F/kifV3Qgf5bHfLwhGEp3a1HP/m3UZttREBd/PQwCwW0GoPKMGeG\n\tVbWSFKd5SXXQArZSG4cdgdL/GxSnXMiE0sFlgJhmQ7olfKmBicX7HMwar9NCqFI2bWKr\n\tF0nzLifw0Kepa0r8UCP2XX4n6pcFGpji082JWLszNV9WIZ9Pw/MF+o9ynkFKg7jdCziX\n\t3ayH6VcJ8Csl7K3NibQWlshnRDa2OIMR+/P3IO8wIR3E0eZL7bdeFULqnpWa8/BEICeM\n\t4B2i0ZHCzD1uWH49fvhLZIPBIymmJjOL9Hbproe0YSalOr4DFEs8VSbIwnmkbXnKcDh6\n\tP75g==", "X-Gm-Message-State": "AOAM530xWwnnpZXW0n4hZXDqZUPlCMsERNPc4Vv2BPb3S4PP9u+PS/tN\n\tIsfx3GZ4ANUT/Th353buePIhtolKy+Im3A==", "X-Google-Smtp-Source": "ABdhPJx1UCC1AO9k1FBfjPY+ovM3cnQTtRtQkFe44Ucgq9wnTcXvTL9Ac/fnoFxnvE9Bc2IUXResxA==", "X-Received": "by 2002:a17:906:2f0d:: with SMTP id\n\tv13mr2021161eji.220.1593170264605; \n\tFri, 26 Jun 2020 04:17:44 -0700 (PDT)", "From": "chris@gregariousmammal.com", "To": "libcamera-devel@lists.libcamera.org", "Date": "Fri, 26 Jun 2020 13:17:32 +0200", "Message-Id": "<20200626111732.62852-1-chris@gregariousmammal.com>", "X-Mailer": "git-send-email 2.27.0", "MIME-Version": "1.0", "Subject": "[libcamera-devel] [PATCH] Create libcamera overview and gloassry", "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>", "Cc": "Chris Chinchilla <chris@gregariousmammal.com>", "Content-Type": "text/plain; charset=\"utf-8\"", "Content-Transfer-Encoding": "base64", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "From: Chris Chinchilla <chris@gregariousmammal.com>\n\nCreates a libcamera overview guide and glossary to give new developers an idea of why they should use libcamera, its architecture, and features it offers.\n\nSigned-off-by: Chris Chinchilla <chris@gregariousmammal.com>\n---\n Documentation/introduction.rst | 195 +++++++++++++++++++++++++++++++++\n 1 file changed, 195 insertions(+)\n create mode 100644 Documentation/introduction.rst", "diff": "diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst\nnew file mode 100644\nindex 0000000..0539e60\n--- /dev/null\n+++ b/Documentation/introduction.rst\n@@ -0,0 +1,195 @@\n+An introduction to libcamera\n+============================\n+\n+The Video for Linux 2 (`V4L2 <https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html>`_) API provides kernel drivers for devices that provide and manipulate\n+images and video. However, Linux was missing a convenient way for application developers to take \n+advantage of these kernel drivers in userspace. Vendors of devices that provide image input sources \n+referred to as “image signal processors” (ISPs) sometimes contribute open-source V4L2 drivers. \n+However, ISPs vary so much, it’s a hard task for developers to write portable ISP-based\n+applications.\n+\n+The libcamera library aims to fill this gap by providing a complete userspace camera \n+stack for Linux-based systems that supports a wide variety of ISPs, including systems with multiple ISPs attached.\n+\n+The library currently supports:\n+\n+- Hardware\n+\n+ - Intel IPU3\n+ - Rockchip RK3399\n+ - RaspberryPi 3 and 4\n+ - USB video device class (UVC) cameras\n+ - Virtual media controller (vimc) driver\n+\n+- Software\n+\n+ - Other Linux-kernel-based operating systems (such as Android and ChromeOS)\n+ - Image enhancement algorithms\n+ - A V4L2 compatibility layer\n+\n+The library provides a public API for managing ISPs, frame capture, video streams, frame and \n+request metadata, events and callbacks, image processing, and more.\n+\n+Where libcamera sits in the camera stack\n+----------------------------------------\n+\n+The libcamera library sits in userspace, just on top of the kernel drivers that directly interact \n+with hardware and the V4L2 family of APIs (Media Controller, V4L2 Video Device, and V4L2 sub-device APIs).\n+\n+When using libcamera in a camera stack, it is the core component, taking control of all camera \n+devices, and exposing a native C++ API to upper layers of the framework. Other language bindings are coming soon.\n+\n+Compatibility Layers\n+~~~~~~~~~~~~~~~~~~~~\n+\n+In a layer above the core framework are compatibility libraries to help existing applications and their developers.\n+\n+V4L2 Compatibility Layer\n+^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+To emulate high-level V4L2 camera devices and capture all access to camera devices, libcamera uses \n+a shared library. The shared library is transparent to libcamera-based applications and injected \n+into a process address space using dynamic linking with ``LD_PRELOAD``.\n+\n+The compatibility layer exposes camera device features on a best-effort basis and aims for the \n+level of features traditionally available from a UVC camera designed for video conferencing.\n+\n+Android Camera HAL\n+^^^^^^^^^^^^^^^^^^\n+\n+The libcamera library offers Android camera support through a generic `hardware abstraction layer (HAL) <https://source.android.com/devices/camera/camera3_requests_hal>`_ implementation. \n+The HAL focuses on supporting features required by Android that are missing from libcamera, such as JPEG encoding.\n+\n+The Android camera HAL implementation initially targets the ``LIMITED``\n+`hardware level <https://source.android.com/devices/camera/versioning#camera_api2>`_,\n+with support for the ``FULL`` level then gradually implemented.\n+\n+gstreamer element\n+^^^^^^^^^^^^^^^^^\n+\n+The library provides `a gstreamer element <https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html?gi-language=c>`_ for routing libcamera data to gstreamer for processing.\n+\n+libcamera Architecture\n+----------------------\n+\n+The libcamera library exposes one unified API, but behind that is built from a \n+set of specific components for each supported device, components for different \n+functionalities, and helpers for those components.\n+\n+Camera Devices Manager\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+Provides access and manages all cameras on a system. It enumerates cameras at \n+build and runtime and supports a hotplug notification mechanism.\n+\n+There is only ever one instance of the Camera Devices Manager running per application.\n+\n+`Read the Camera Manager API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html>`_\n+\n+Camera Device\n+~~~~~~~~~~~~~\n+\n+A camera device is a device capable of producing one or more image streams from \n+a single image source and can include multiple identical camera devices.\n+\n+The libcamera library represents a camera device to the upper layers of the library. \n+It exposes full control of the device through the public API, making it the highest \n+level object libcamera exposes, and the object that all other API operations interact \n+with from configuration to capture.\n+\n+`Read the Camera API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1Camera.html>`_\n+\n+Frame controls\n+^^^^^^^^^^^^^^\n+\n+Depending on the capabilities of a camera device and the hardware it is connected \n+to, libcamera supports controlling capture parameters for each stream on a per-frame basis.\n+\n+These controls include auto exposure, gain, brightness, contrast, lux, white balance, color temperature, and saturation.\n+\n+`Read the Control API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1Control.html>`_\n+\n+Pipeline Handler\n+~~~~~~~~~~~~~~~~\n+\n+A pipeline handler is a private API that manages the pipelines exposed by the kernel \n+drivers through the Media Controller and V4L2 APIs.\n+\n+Each supported camera device has its own pipeline handler component, which hides \n+and abstracts device-specific details, providing what the rest of the library \n+needs to interact with a device.\n+\n+A pipeline handler manages most aspects of interacting with a camera device including:\n+\n+- acquiring use of the camera device\n+- frame controls\n+- pipelines and stream configuration\n+- the data the camera produces, and the buffers it needs to hold the data\n+- creating requests applications need to access camera data\n+\n+A pipeline handler is part of the libcamera codebase, and hardware vendors generally need to create them.\n+\n+`Read the PipelineHandler API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html>`_\n+\n+Image Processing Algorithms\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+An image processing algorithm (IPA) component is a private API that implements \n+3A (Auto-Exposure, Auto-White Balance, and Auto-Focus) algorithms.\n+\n+Each supported camera device has its own IPA component that runs on the CPU and \n+interacts with the kernel camera devices to control hardware image processing \n+based on the parameters supplied by upper layers, and helps maintain state, \n+closing the control loop of the ISP.\n+\n+An IPA component can be part of the libcamera code base, in which case the same \n+license covers it, or provided externally as an open-source or closed-source component.\n+\n+.. TODO: Better in the IPA guide?\n+\n+The component is sandboxed and can only interact with libcamera through specifically \n+marked APIs. A component has no direct access to kernel camera devices, and dmabuf \n+instances explicitly passed to the component control its access to image data and \n+metadata. The component should run in a process separate from the main libcamera \n+process, and has a restricted view of the system, including no access to networking APIs\n+and limited access to file systems.\n+\n+The sandboxing mechanism isn’t defined by libcamera. Platform vendors need to provide sandboxing \n+mechanisms as a plugin.\n+\n+To support this security and sandboxing model, libcamera provides an IPC mechanism \n+for an IPA and Pipeline Handler to communicate, but developers need to create the \n+API themselves. Platform vendors can also use any other IPC mechanism that supports \n+passing file descriptors.\n+\n+3A and Image Enhancement Algorithms\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+Camera devices should implement auto exposure, auto gain, and auto white balance, \n+and those that include a focus lens should also implement autofocus.\n+\n+Vendors can implement these algorithms in hardware or firmware outside of libcamera, \n+or in an IPA component.\n+\n+\n+.. TODO: Add link to guide when completed\n+\n+Helpers and Support Classes\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+.. TODO: Feel like this is implied in other places of the doc\n+\n+To help developers create device-specific pipeline handlers and image processing \n+algorithms, libcamera provides helpers and support classes that sit on top of the \n+Media Controller and V4L2 APIs.\n+\n+Glossary\n+--------\n+\n+- **ISP**: Image Signal Processor.\n+- **SoC**: System on a Chip.\n+- **Media controller API**: `The Linux Kernel API <https://www.kernel.org/doc/html/v4.10/media/uapi/mediactl/media-controller-intro.html>`_ that handles audio and video input and output.\n+- **V4L2**: `Video for Linux API version 2 <https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html>`_. Device drivers and API for video capture on Linux.\n+- **UVC camera**: `USB Video Class <https://en.wikipedia.org/wiki/USB_video_device_class>`_ that describes devices capable of streaming video.\n+- **3A**: Common algorithms used by camera devices for auto-exposure, auto-white balance and auto-focus).\n+- **IPC**: `Inter-process communications based protocol <https://en.wikipedia.org/wiki/Inter-process_communication>`_.\n", "prefixes": [ "libcamera-devel" ] }