From patchwork Fri Aug 9 14:53:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20867 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 029E4C324E for ; Fri, 9 Aug 2024 14:53:32 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5E1A6633CB; Fri, 9 Aug 2024 16:53:32 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="uWtQ7OTf"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5F20663394 for ; Fri, 9 Aug 2024 16:53:21 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 1AEF2B7E; Fri, 9 Aug 2024 16:52:27 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723215147; bh=eebjkyPAXBkaW+fuc1VOWTvQ9ym2eDZVluqugpRanvg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uWtQ7OTfqIbIpirILx/xmV9Nq5zPcelHaRGWrC1a/qCNv6aGqwEhSY60oAa93nn25 So+1esxO4pe2lynq00p+av7exWjNCiAwLY2I+GkRbhd/qAjlTB4GYEY2RZU7J6PhJb etf8xn3t0ZYzZF4mRXmjaEd+ESBS3sfNv3OzEcOU= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH 6/7] Documentation: Expand introductory content on docs.rst Date: Fri, 9 Aug 2024 15:53:03 +0100 Message-Id: <20240809145304.537551-7-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240809145304.537551-1-dan.scally@ideasonboard.com> References: <20240809145304.537551-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" docs.rst is the landing page for the documentation from the libcamera website, but isn't particularly introductory. Move much of the content from guides/introduction.rst to docs.rst and expand on it - this will serve as the new introductory page. Reformat the other section headers in docs.rst so they're a match. Remove guides/introduction.rst. Signed-off-by: Daniel Scally --- Documentation/c55.svg | 175 +++++++++++++++++++++++ Documentation/docs.rst | 128 ++++++++++++++++- Documentation/documentation-contents.rst | 1 - Documentation/guides/introduction.rst | 78 ---------- Documentation/index.rst | 1 - 5 files changed, 296 insertions(+), 87 deletions(-) create mode 100644 Documentation/c55.svg delete mode 100644 Documentation/guides/introduction.rst diff --git a/Documentation/c55.svg b/Documentation/c55.svg new file mode 100644 index 00000000..9dbd52bb --- /dev/null +++ b/Documentation/c55.svg @@ -0,0 +1,175 @@ + + + + + + +board + + + +n00000001 + + + +mali-c55 tpg +/dev/v4l-subdev0 + +0 + + + +n00000003 + +0 + +4 + +mali-c55 isp +/dev/v4l-subdev1 + +1 + +2 + +3 + + + +n00000001:port0->n00000003:port0 + + + + + +n00000009 + +0 + +2 + +mali-c55 resizer fr +/dev/v4l-subdev2 + +1 + + + +n00000003:port1->n00000009:port0 + + + + + +n00000003:port2->n00000009:port2 + + + + + +n0000000d + +0 + +mali-c55 resizer ds +/dev/v4l-subdev3 + +1 + + + +n00000003:port1->n0000000d:port0 + + + + + +n0000001c + +mali-c55 3a stats +/dev/video3 + + + +n00000003:port3->n0000001c + + + + + +n00000010 + +mali-c55 fr +/dev/video0 + + + +n00000009:port1->n00000010 + + + + + +n00000014 + +mali-c55 ds +/dev/video1 + + + +n0000000d:port1->n00000014 + + + + + +n00000018 + +mali-c55 3a params +/dev/video2 + + + +n00000018->n00000003:port4 + + + + + +n00000030 + +0 + +lte-csi2-rx +/dev/v4l-subdev4 + +1 + + + +n00000030:port1->n00000003:port0 + + + + + +n00000035 + + + +imx415 1-001a +/dev/v4l-subdev5 + +0 + + + +n00000035:port0->n00000030:port0 + + + + + diff --git a/Documentation/docs.rst b/Documentation/docs.rst index d65b2b4f..c495fa61 100644 --- a/Documentation/docs.rst +++ b/Documentation/docs.rst @@ -14,12 +14,87 @@ Documentation API -API -=== +What is libcamera exactly? +========================== + +libcamera is an open source complex camera support library for Linux. The +library interfaces with Linux kernel uAPIs implemented by device drivers and +provides an intuitive API to developers in order to simplify the complexity +involved in capturing images from complex cameras on Linux systems. + +What's a "complex camera"? +========================== + +A modern "camera" tends to infact be several different pieces of hardware which +must all be controlled together in order to capture images. For example the +pipeline might consist of a camera sensor which actually records the data, a +receiver which accepts those data transmitted from the camera sensor and an +image signal processor which processes those data into a useful image in an +accepted format. The Linux kernel handles these multimedia devices through the +'Linux media' subsystem and provides a set of APIs (application programming +interfaces) known collectively as V4L2 (`Video for Linux 2`_) and the +`Media Controller`_ API which provide an interface to interact and control media +devices. + +.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html +.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html + +Included in this subsystem are drivers for camera sensors, CSI2 (Camera +Serial Interface) receivers, and ISPs (Image Signal Processors) + +The usage of these drivers to provide a functioning camera stack is a +responsibility that lies in userspace which is commonly implemented separately +by vendors without a common architecture or API for application developers. This +adds a lot of complexity to the task, particularly when considering that the +differences in hardware pipelines and their representation in the kernel's APIs +often necessitates bespoke handling. + +What is libcamera for? +====================== -The libcamera API is extensively documented using Doxygen. The :ref:`API -nightly build ` contains the most up-to-date API documentation, built from -the latest master branch. +libcamera provides a complete camera stack for Linux based systems to abstract +the configuration of hardware and image control algorithms required to obtain +desirable results from the camera through the kernel's APIs, reducing those +operations to a simple and consistent method for developers. In short instead of +having to deal with this: + +.. figure:: c55.svg + +You can instead simply deal with this:: + + >>> import libcamera as lc + >>> camera_manager = lc.CameraManager.singleton() + [0:15:59.582029920] [504] INFO Camera camera_manager.cpp:313 libcamera v0.3.0+182-01e57380 + >>> for camera in camera_manager.cameras: + ... print(f' - {camera.id}') + ... + - mali-c55 tpg + - imx415 1-001a + +And the library handles the rest for you. These documentary pages give more +information on the internal workings of libcamera (and the kernel camera stack +that lies behind it) as well as guidance on using libcamera in an application or +extending the library with support for your hardware (through the pipeline +handler and IPA module writer's guides). + +How should I use it? +==================== + +There are a few ways you might want to use libcamera, depending on your +application. It's always possible to use the library directly of course, and you +can find detailed information on how to do so in the +:doc:`application writer's guide `. It may be more +appropriate to use one of the frameworks with libcamera support. For example an +application powering an embedded media device incorporating capture, encoding +and streaming of both video and audio might benefit from using `gstreamer`_ (for +which libcamera provides a plugin). Similarly an application for user-facing +devices like a laptop would likely benefit accessing cameras through the XDG +camera portal and `pipewire`_, which brings the advantages of resource sharing +(multiple applications accessing the stream at the same time) and access +control. + +.. _gstreamer: https://gstreamer.freedesktop.org/ +.. _pipewire: https://pipewire.org/ libcamera Architecture ====================== @@ -177,7 +252,7 @@ Helpers and Support Classes V4L2 Compatibility Layer ------------------------- +======================== V4L2 compatibility is achieved through a shared library that traps all accesses to camera devices and routes them to libcamera to emulate high-level @@ -190,7 +265,7 @@ designed for video conferencing. Android Camera HAL ------------------- +================== Camera support for Android is achieved through a generic Android camera HAL implementation on top of libcamera. The HAL will implement internally @@ -200,3 +275,42 @@ support. The Android camera HAL implementation will initially target the LIMITED hardware level, with support for the FULL level then being gradually implemented. + +Platform Support +================ + +The library currently supports the following hardware platforms specifically +with dedicated pipeline handlers: + + - Arm Mali-C55 (mali-c55) + - Intel IPU3 (ipu3) + - Rockchip RK3399 (rkisp1) + - RaspberryPi 3 and 4 (rpi/vc4) + +Furthermore, generic platform support is provided for the following: + + - USB video device class cameras (uvcvideo) + - iMX7, Allwinner Sun6i (simple) + - Virtual media controller driver for test use cases (vimc) + +Licensing +========= + +The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline +Handlers are a part of the libcamera code base and need to be contributed +upstream by device vendors. IPA modules included in libcamera are covered by a +free software license, however third-parties may develop IPA modules outside of +libcamera and distribute them under a closed-source license, provided they do +not include source code from the libcamera project. + +The libcamera project itself contains multiple libraries, applications and +utilities. Licenses are expressed through SPDX tags in text-based files that +support comments, and through the .reuse/dep5 file otherwise. A copy of all +licenses are stored in the LICENSES directory, and a full summary of the +licensing used throughout the project can be found in the COPYING.rst document. + +Applications which link dynamically against libcamera and use only the public +API are an independent work of the authors and have no license restrictions +imposed upon them from libcamera. + +.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst index dedf390c..114c11ac 100644 --- a/Documentation/documentation-contents.rst +++ b/Documentation/documentation-contents.rst @@ -10,7 +10,6 @@ * :doc:`/environment_variables` * :doc:`/feature_requirements` * :doc:`/guides/application-developer` - * :doc:`/guides/introduction` * :doc:`/guides/ipa` * :doc:`/guides/pipeline-handler` * :doc:`/guides/tracing` diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst deleted file mode 100644 index e419eb9d..00000000 --- a/Documentation/guides/introduction.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. include:: ../documentation-contents.rst - -Developers guide to libcamera -============================= - -The Linux kernel handles multimedia devices through the 'Linux media' subsystem -and provides a set of APIs (application programming interfaces) known -collectively as V4L2 (`Video for Linux 2`_) and the `Media Controller`_ API -which provide an interface to interact and control media devices. - -Included in this subsystem are drivers for camera sensors, CSI2 (Camera -Serial Interface) receivers, and ISPs (Image Signal Processors) - -The usage of these drivers to provide a functioning camera stack is a -responsibility that lies in userspace which is commonly implemented separately -by vendors without a common architecture or API for application developers. - -libcamera provides a complete camera stack for Linux based systems to abstract -functionality desired by camera application developers and process the -configuration of hardware and image control algorithms required to obtain -desirable results from the camera. - -.. _Video for Linux 2: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html -.. _Media Controller: https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/mediactl/media-controller.html - - -In this developers guide the current `Platform Support`_ is detailed, as well as -an overview of the `Licensing`_ requirements of the project. - -This introduction is followed by a walkthrough tutorial to newcomers wishing to -support a new platform with the `Pipeline Handler Writers Guide`_ and for those -looking to make use of the libcamera native API an `Application Writers Guide`_ -provides a tutorial of the key APIs exposed by libcamera. - -.. _Pipeline Handler Writers Guide: pipeline-handler.html -.. _Application Writers Guide: application-developer.html - -.. TODO: Correctly link to the other articles of the guide - -Platform Support ----------------- - -The library currently supports the following hardware platforms specifically -with dedicated pipeline handlers: - - - Intel IPU3 (ipu3) - - Rockchip RK3399 (rkisp1) - - RaspberryPi 3 and 4 (rpi/vc4) - -Furthermore, generic platform support is provided for the following: - - - USB video device class cameras (uvcvideo) - - iMX7, Allwinner Sun6i (simple) - - Virtual media controller driver for test use cases (vimc) - -Licensing ---------- - -The libcamera core, is covered by the `LGPL-2.1-or-later`_ license. Pipeline -Handlers are a part of the libcamera code base and need to be contributed -upstream by device vendors. IPA modules included in libcamera are covered by a -free software license, however third-parties may develop IPA modules outside of -libcamera and distribute them under a closed-source license, provided they do -not include source code from the libcamera project. - -The libcamera project itself contains multiple libraries, applications and -utilities. Licenses are expressed through SPDX tags in text-based files that -support comments, and through the .reuse/dep5 file otherwise. A copy of all -licenses are stored in the LICENSES directory, and a full summary of the -licensing used throughout the project can be found in the COPYING.rst document. - -Applications which link dynamically against libcamera and use only the public -API are an independent work of the authors and have no license restrictions -imposed upon them from libcamera. - -.. _LGPL-2.1-or-later: https://spdx.org/licenses/LGPL-2.1-or-later.html diff --git a/Documentation/index.rst b/Documentation/index.rst index 59416906..6d7d2ca3 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -17,7 +17,6 @@ Application Writer's Guide Camera Sensor Model Camera Stack - Developer Guide Environment variables Feature Requirements IPA Writer's guide