From patchwork Tue May 3 16:30:36 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Quentin Schulz X-Patchwork-Id: 15763 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 ECA44C0F2A for ; Tue, 3 May 2022 16:30:52 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5D8D46564A; Tue, 3 May 2022 18:30:52 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1651595452; bh=yxT/rwKPnoOX7zqgQ49cmyZxJg6aeT1CJHkM6WIOh4Q=; h=To:Date:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=XduIUpMTTPAQJfi7cceWesm27YUITnTqSQmEo5LlpihPIU5xG+ZpIic3uvFQ7SSyK vxo/tr453IRGw9QUYZ+FFefbo+6Uy/qlZv2lwvEviDl8rhTuab1YSpOn0Tn6oTjuy3 SQTIcpQJcKN8qk4NgSZuGrIE8jn30NhrjP7oTrnc8zuf0Hq4iJqRkjcVS9p/H/hP/T V8mownJjIBGsj1pK2+VMQXGyLzQweyzmzPIXDWycc12aT6hDPBUkwKVoJ4bzR8oyl9 Xn2P8J1uK9MnKAJxN0KUaHduD10Sl09VEgVVzoNQqirm5luq+4uCRtk7/YVdNzVTLf VePOhs5TjdRwA== Received: from relay2-d.mail.gandi.net (relay2-d.mail.gandi.net [217.70.183.194]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 6D5B365645 for ; Tue, 3 May 2022 18:30:50 +0200 (CEST) Received: (Authenticated sender: foss@0leil.net) by mail.gandi.net (Postfix) with ESMTPSA id BFD6540006; Tue, 3 May 2022 16:30:49 +0000 (UTC) To: Date: Tue, 3 May 2022 18:30:36 +0200 Message-Id: <20220503163038.1174462-1-foss+libcamera@0leil.net> X-Mailer: git-send-email 2.35.1 MIME-Version: 1.0 Subject: [libcamera-devel] =?utf-8?q?=5BPATCH_1/3=5D_Documentation=3A_repl?= =?utf-8?b?YWNlIOKAmSBieSAn?= 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: , X-Patchwork-Original-From: Quentin Schulz via libcamera-devel From: Quentin Schulz Reply-To: Quentin Schulz Cc: libcamera-devel@lists.libcamera.org Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Quentin Schulz Replace U+2019 unicode character (’; right single quotation mark) by U+27 unicode character ('; apostrophe) as it is what most people are used to in sentences. While Sphinx seems to be rendering both the same way, it makes it easier for searching in rST files directly. Cc: Quentin Schulz Signed-off-by: Quentin Schulz Reviewed-by: Jacopo Mondi Reviewed-by: Laurent Pinchart --- Documentation/guides/application-developer.rst | 10 +++++----- Documentation/guides/introduction.rst | 2 +- Documentation/guides/pipeline-handler.rst | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst index cafb24b1..07cc7273 100644 --- a/Documentation/guides/application-developer.rst +++ b/Documentation/guides/application-developer.rst @@ -47,7 +47,7 @@ runs for the life of the application. When the Camera Manager starts, it enumerates all the cameras detected in the system. Behind the scenes, libcamera abstracts and manages the complex pipelines that kernel drivers expose through the `Linux Media Controller`_ and `Video for Linux`_ (V4L2) APIs, meaning that -an application doesn’t need to handle device or driver specific details. +an application doesn't need to handle device or driver specific details. .. _CameraManager: http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html .. _Linux Media Controller: https://www.kernel.org/doc/html/latest/media/uapi/mediactl/media-controller-intro.html @@ -236,8 +236,8 @@ applied to the system. camera->configure(config.get()); -If an application doesn’t first validate the configuration before calling -``Camera::configure()``, there’s a chance that calling the function can fail, if +If an application doesn't first validate the configuration before calling +``Camera::configure()``, there's a chance that calling the function can fail, if the given configuration would have to be adjusted. Allocate FrameBuffers @@ -259,7 +259,7 @@ of suitable buffers, for instance, when no other device is involved, or on Linux platforms that lack a centralized allocator. The ``FrameBufferAllocator`` class provides a buffer allocator an application can use in these situations. -An application doesn’t have to use the default ``FrameBufferAllocator`` that +An application doesn't have to use the default ``FrameBufferAllocator`` that libcamera provides. It can instead allocate memory manually and pass the buffers in ``Request``\s (read more about ``Request`` in `the frame capture section <#frame-capture>`_ of this guide). The example in this guide covers using the @@ -392,7 +392,7 @@ Create the ``requestComplete`` function by matching the slot signature: Request completion events can be emitted for requests which have been canceled, for example, by unexpected application shutdown. To avoid an application -processing invalid image data, it’s worth checking that the request has +processing invalid image data, it's worth checking that the request has completed successfully. The list of request completion statuses is available in the `Request::Status`_ class enum documentation. diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst index a4671a07..d080679f 100644 --- a/Documentation/guides/introduction.rst +++ b/Documentation/guides/introduction.rst @@ -150,7 +150,7 @@ Architecture ------------ While offering a unified API towards upper layers, and presenting itself as a -single library, libcamera isn’t monolithic. It exposes multiple components +single library, libcamera isn't monolithic. It exposes multiple components through its public API and is built around a set of separate helpers internally. Hardware abstractions are handled through the use of device-specific components where required and dynamically loadable plugins are used to separate image diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index c0fb7147..a7208f57 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -1036,8 +1036,8 @@ values. Handling of device controls is again performed using the libcamera .. _Controls Framework: http://libcamera.org/api-html/controls_8h.html This section is particularly specific to Vivid as it sets the initial values of -controls to match `Vivid Controls`_ defined by the kernel driver. You won’t need -any of the code below for your pipeline handler, but it’s included as an example +controls to match `Vivid Controls`_ defined by the kernel driver. You won't need +any of the code below for your pipeline handler, but it's included as an example of how to implement functionality your pipeline handler might need. .. _Vivid Controls: https://www.kernel.org/doc/html/latest/admin-guide/media/vivid.html#controls From patchwork Tue May 3 16:30:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Schulz X-Patchwork-Id: 15764 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 4E9D2C0F2A for ; Tue, 3 May 2022 16:30:54 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E402765649; Tue, 3 May 2022 18:30:52 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1651595452; bh=FB53gOuCzI3rtV/38aBP8CDX9Db8oz0d7g1i2UfssnY=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=M0HuqxB8lvpsGpWRjOOBgbQio+7hh5JpANLmnnJDe0i51d8xvbPtVNjij8ft62O4X v+zEte76Y/h/DmqhN5ns8w1T4xY00JRgyTvLeqceuxOq3YDH8PidZlJGZrPzFwAlen fMc/VC2e2Wmlo+aSoueKEdpksL4K7JTea8gSvwWqawRiBdJWwL0fc4Jybt9u21B8us PHwu9a76gd7XRdpzb7f9Zn+UpwQfjHmxhwQ9zKyfYU5IhaVuFEMWTcVWVD7fypfTB8 6pWVDDdV53IIP8gPhBnq7iE0PRDrgz82Tv/uzTxmoIURns2ncM976IJuh3aSuQ9qS8 68SzI+nlfJgsQ== Received: from relay2-d.mail.gandi.net (relay2-d.mail.gandi.net [217.70.183.194]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id EB9F665645 for ; Tue, 3 May 2022 18:30:50 +0200 (CEST) Received: (Authenticated sender: foss@0leil.net) by mail.gandi.net (Postfix) with ESMTPSA id 707DA40004; Tue, 3 May 2022 16:30:50 +0000 (UTC) To: Date: Tue, 3 May 2022 18:30:37 +0200 Message-Id: <20220503163038.1174462-2-foss+libcamera@0leil.net> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220503163038.1174462-1-foss+libcamera@0leil.net> References: <20220503163038.1174462-1-foss+libcamera@0leil.net> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 2/3] Documentation: fix typos 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: , X-Patchwork-Original-From: Quentin Schulz via libcamera-devel From: Quentin Schulz Reply-To: Quentin Schulz Cc: libcamera-devel@lists.libcamera.org Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Quentin Schulz A few typos made it to the docs, so let's fix them. Cc: Quentin Schulz Signed-off-by: Quentin Schulz Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham --- Documentation/guides/introduction.rst | 2 +- Documentation/guides/pipeline-handler.rst | 28 +++++++++++------------ 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst index d080679f..07f66881 100644 --- a/Documentation/guides/introduction.rst +++ b/Documentation/guides/introduction.rst @@ -221,7 +221,7 @@ Camera Device of producing one or more image streams, and provides the API to interact with the underlying device. - If a system has multiple instances of the same hardware attached, each has it's + If a system has multiple instances of the same hardware attached, each has its own instance of the camera class. The API exposes full control of the device to upper layers of libcamera through diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index a7208f57..989b0163 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -75,7 +75,7 @@ Prerequisite knowledge: libcamera architecture ---------------------------------------------- A pipeline handler makes use of the following libcamera classes to realize the -functionalities descibed above. Below is a brief overview of each of those: +functionalities described above. Below is a brief overview of each of those: .. TODO: (All) Convert to sphinx refs .. TODO: (MediaDevice) Reference to the Media Device API (possibly with versioning requirements) @@ -405,7 +405,7 @@ Creating camera devices If the pipeline handler successfully matches with the system it is running on, it can proceed to initialization, by creating all the required instances of the ``V4L2VideoDevice``, ``V4L2Subdevice`` and ``CameraSensor`` hardware abstraction -classes. If the Pipeline handler supports an ISP, it can then also Initialise +classes. If the Pipeline handler supports an ISP, it can then also initialise the IPA module before proceeding to the creation of the Camera devices. An image ``Stream`` represents a sequence of images and data of known size and @@ -687,8 +687,8 @@ and validated to adjust it to a supported configuration. This may involve adjusting the formats or image sizes or alignments for example to match the capabilities of the device. -Applications may choose to repeat validation stages, adjusting paramters until a -set of validated StreamConfigurations are returned that is acceptable for the +Applications may choose to repeat validation stages, adjusting parameters until +a set of validated StreamConfigurations are returned that is acceptable for the applications needs. When the pipeline handler receives a valid camera configuration it can use the image stream configurations to apply settings to the hardware devices. @@ -765,11 +765,11 @@ example (with only one stream), the pipeline handler always returns the same configuration, inferred from the underlying V4L2VideoDevice. How it does this is shown below, but examination of the more full-featured -pipelines for IPU3, RKISP1 and RaspberryPi are recommend to explore more +pipelines for IPU3, RKISP1 and RaspberryPi are recommended to explore more complex examples. To generate a ``StreamConfiguration``, you need a list of pixel formats and -frame sizes which supported outputs of the stream. You can fetch a map of the +frame sizes supported by outputs of the stream. You can fetch a map of the ``V4LPixelFormat`` and ``SizeRange`` supported by the underlying output device, but the pipeline handler needs to convert this to a ``libcamera::PixelFormat`` type to pass to applications. We do this here using ``std::transform`` to @@ -811,9 +811,9 @@ Continue adding the following code to support this: StreamConfiguration cfg(formats); As well as a list of supported StreamFormats, the StreamConfiguration is also -expected to provide an initialsed default configuration. This may be arbitrary, -but depending on use case you may which to select an output that matches the -Sensor output, or prefer a pixelformat which might provide higher performance on +expected to provide an initialised default configuration. This may be arbitrary, +but depending on use case you may wish to select an output that matches the +Sensor output, or prefer a pixelFormat which might provide higher performance on the hardware. The bufferCount represents the number of buffers required to support functional continuous processing on this stream. @@ -826,7 +826,7 @@ support functional continuous processing on this stream. Finally add each ``StreamConfiguration`` generated to the ``CameraConfiguration``, and ensure that it has been validated before returning it to the application. With only a single supported stream, this code adds only -a single StreamConfiguration however a StreamConfiguration should be added for +a single StreamConfiguration. However a StreamConfiguration should be added for each supported role in a device that can handle more streams. Add the following code to complete the implementation of @@ -841,7 +841,7 @@ Add the following code to complete the implementation of return config; To validate a camera configuration, a pipeline handler must implement the -`CameraConfiguration::validate()`_ function in it's derived class to inspect all +`CameraConfiguration::validate()`_ function in its derived class to inspect all the stream configuration associated to it, make any adjustments required to make the configuration valid, and return the validation status. @@ -1372,9 +1372,9 @@ classes documentation. .. _libcamera Signal and Slot: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#details In order to notify applications about the availability of new frames and data, -the ``Camera`` device exposes two ``Signals`` which applications can connect to -be notified of frame completion events. The ``bufferComplete`` signal serves to -report to applications the completion event of a single ``Stream`` part of a +the ``Camera`` device exposes two ``Signals`` to which applications can connect +to be notified of frame completion events. The ``bufferComplete`` signal serves +to report to applications the completion event of a single ``Stream`` part of a ``Request``, while the ``requestComplete`` signal notifies the completion of all the ``Streams`` and data submitted as part of a request. This mechanism allows implementation of partial request completion, which allows an application to From patchwork Tue May 3 16:30:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Quentin Schulz X-Patchwork-Id: 15765 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 9353EC326C for ; Tue, 3 May 2022 16:30:55 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id B820665657; Tue, 3 May 2022 18:30:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1651595453; bh=VJtnbU2zAM/FzPQVExCCjrBnd+OLTNDWBn2vJQwfXiw=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=ah4ovu3dqv3R/KmxQ1LGTWes9I9ipDqICJ5oNqbEgCQuvnufU7SfzVyTh374Ds8yg 5Xu1I0gFpCqwF2WmBgeU05rK56Mjy1f02J9CMS01FK2LcIHDMLVq4P+7GHEfxGKGtd Pz2hyyyvGCRwOCk8xucDdJ03TMidvAlsnpO5EWATDKghHQ9kV5QG+1HFQQARcH36uf DFOxBiL0/8bbzUaN5tQuRUrdhf5VH+2XobiU5evMkIkAhjUbJkNueYqyRO3ZRc5oaC 3bqCQNzmFZShCZ6lEsHSeiZgqOOFOLrO9uk4nHuN0UEwBZ32d3+St7EEyeWUIJyR8t N6MiRy1f4dh7A== Received: from relay2-d.mail.gandi.net (relay2-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::222]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 9D0F465648 for ; Tue, 3 May 2022 18:30:51 +0200 (CEST) Received: (Authenticated sender: foss@0leil.net) by mail.gandi.net (Postfix) with ESMTPSA id 0FF9040007; Tue, 3 May 2022 16:30:50 +0000 (UTC) To: Date: Tue, 3 May 2022 18:30:38 +0200 Message-Id: <20220503163038.1174462-3-foss+libcamera@0leil.net> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220503163038.1174462-1-foss+libcamera@0leil.net> References: <20220503163038.1174462-1-foss+libcamera@0leil.net> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 3/3] Documentation: use https instead of http 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: , X-Patchwork-Original-From: Quentin Schulz via libcamera-devel From: Quentin Schulz Reply-To: Quentin Schulz Cc: libcamera-devel@lists.libcamera.org Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Quentin Schulz Avoid a redirection from http by using https directly. Cc: Quentin Schulz Signed-off-by: Quentin Schulz Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham --- Documentation/contributing.rst | 4 +- Documentation/environment_variables.rst | 2 +- .../guides/application-developer.rst | 8 +- Documentation/guides/introduction.rst | 6 +- Documentation/guides/pipeline-handler.rst | 116 +++++++++--------- 5 files changed, 68 insertions(+), 68 deletions(-) diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst index 57bc9acc..6405c5fb 100644 --- a/Documentation/contributing.rst +++ b/Documentation/contributing.rst @@ -56,8 +56,8 @@ Documentation Project documentation is created using `Sphinx`_. Source level documentation uses `Doxygen`_. Please make sure to document all code during development. -.. _Sphinx: http://www.sphinx-doc.org -.. _Doxygen: http://www.doxygen.nl +.. _Sphinx: https://www.sphinx-doc.org +.. _Doxygen: https://www.doxygen.nl Submitting Patches ------------------ diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst index 1e85befd..fa703a72 100644 --- a/Documentation/environment_variables.rst +++ b/Documentation/environment_variables.rst @@ -54,7 +54,7 @@ The optional `category `__ is a string matching the categories defined by each file in the source base using the logging infrastructure. It can include a wildcard ('*') character at the end to match multiple categories. -For more information refer to the `API documentation `__. +For more information refer to the `API documentation `__. Examples: diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst index 07cc7273..16bea9c4 100644 --- a/Documentation/guides/application-developer.rst +++ b/Documentation/guides/application-developer.rst @@ -49,7 +49,7 @@ abstracts and manages the complex pipelines that kernel drivers expose through the `Linux Media Controller`_ and `Video for Linux`_ (V4L2) APIs, meaning that an application doesn't need to handle device or driver specific details. -.. _CameraManager: http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html +.. _CameraManager: https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html .. _Linux Media Controller: https://www.kernel.org/doc/html/latest/media/uapi/mediactl/media-controller-intro.html .. _Video for Linux: https://www.linuxtv.org/docs.php @@ -207,7 +207,7 @@ supported values. The ``validate`` function returns a `Status`_ which applications shall check to see if the Pipeline Handler adjusted the configuration. -.. _Status: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a64163f21db2fe1ce0a6af5a6f6847744 +.. _Status: https://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a64163f21db2fe1ce0a6af5a6f6847744 For example, the code above set the width and height to 640x480, but if the camera cannot produce an image that large, it might adjust the configuration to @@ -345,7 +345,7 @@ Event handling and callbacks The libcamera library uses the concept of `signals and slots` (similar to `Qt Signals and Slots`_) to connect events with callbacks to handle them. -.. _signals and slots: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#details +.. _signals and slots: https://libcamera.org/api-html/classlibcamera_1_1Signal.html#details .. _Qt Signals and Slots: https://doc.qt.io/qt-5/signalsandslots.html The ``Camera`` device emits two signals that applications can connect to in @@ -418,7 +418,7 @@ in this request, and access the metadata associated to each frame. The metadata buffer contains information such the capture status, a timestamp, and the bytes used, as described in the `FrameMetadata`_ documentation. -.. _FrameMetaData: http://libcamera.org/api-html/structlibcamera_1_1FrameMetadata.html +.. _FrameMetaData: https://libcamera.org/api-html/structlibcamera_1_1FrameMetadata.html .. code:: cpp diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst index 07f66881..2d1760c1 100644 --- a/Documentation/guides/introduction.rst +++ b/Documentation/guides/introduction.rst @@ -214,7 +214,7 @@ Camera Manager Read the `Camera Manager API`_ documentation for more details. -.. _Camera Manager API: http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html +.. _Camera Manager API: https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html Camera Device The Camera class represents a single item of camera hardware that is capable @@ -231,7 +231,7 @@ Camera Device Read the `Camera API`_ documentation for more details. -.. _Camera API: http://libcamera.org/api-html/classlibcamera_1_1Camera.html +.. _Camera API: https://libcamera.org/api-html/classlibcamera_1_1Camera.html Pipeline Handler The Pipeline Handler manages the complex pipelines exposed by the kernel @@ -254,7 +254,7 @@ Pipeline Handler More details can be found in the `PipelineHandler API`_ documentation, and the `Pipeline Handler Writers Guide`_. -.. _PipelineHandler API: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html +.. _PipelineHandler API: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html Image Processing Algorithms An image processing algorithm (IPA) component is a loadable plugin that diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 989b0163..8e3f991d 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -81,49 +81,49 @@ functionalities described above. Below is a brief overview of each of those: .. TODO: (MediaDevice) Reference to the Media Device API (possibly with versioning requirements) .. TODO: (IPAInterface) refer to the IPA guide -- `MediaDevice `_: +- `MediaDevice `_: Instances of this class are associated with a kernel media controller device and its connected objects. -- `DeviceEnumerator `_: +- `DeviceEnumerator `_: Enumerates all media devices attached to the system and the media entities registered with it, by creating instances of the ``MediaDevice`` class and storing them. -- `DeviceMatch `_: +- `DeviceMatch `_: Describes a media device search pattern using entity names, or other properties. -- `V4L2VideoDevice `_: +- `V4L2VideoDevice `_: Models an instance of a V4L2 video device constructed with the path to a V4L2 video device node. -- `V4L2SubDevice `_: +- `V4L2SubDevice `_: Provides an API to the sub-devices that model the hardware components of a V4L2 device. -- `CameraSensor `_: +- `CameraSensor `_: Abstracts camera sensor handling by hiding the details of the V4L2 subdevice kernel API and caching sensor information. -- `Camera::Private `_: +- `Camera::Private `_: Represents device-specific data a pipeline handler associates to each Camera instance. -- `StreamConfiguration `_: +- `StreamConfiguration `_: Models the current configuration of an image stream produced by the camera by reporting its format and sizes. -- `CameraConfiguration `_: +- `CameraConfiguration `_: Represents the current configuration of a camera, which includes a list of stream configurations for each active stream in a capture session. When validated, it is applied to the camera. -- `IPAInterface `_: +- `IPAInterface `_: The interface to the Image Processing Algorithm (IPA) module which performs the computation of the image processing pipeline tuning parameters. -- `ControlList `_: +- `ControlList `_: A list of control items, indexed by Control<> instances or by numerical index which contains values used by application and IPA to change parameters of image streams, used to return to applications and share with IPA the metadata @@ -191,7 +191,7 @@ In *vivid.cpp* add the pipeline handler to the ``libcamera`` namespace, defining a `PipelineHandler`_ derived class named PipelineHandlerVivid, and add stub implementations for the overridden class members. -.. _PipelineHandler: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html +.. _PipelineHandler: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html .. code-block:: cpp @@ -267,7 +267,7 @@ handler factory using the `REGISTER_PIPELINE_HANDLER`_ macro which registers it and creates a global symbol to reference the class and make it available to try and match devices. -.. _REGISTER_PIPELINE_HANDLER: http://libcamera.org/api-html/pipeline__handler_8h.html +.. _REGISTER_PIPELINE_HANDLER: https://libcamera.org/api-html/pipeline__handler_8h.html For debugging and testing a pipeline handler during development, you can define a log message category for the pipeline handler. The ``LOG_DEFINE_CATEGORY`` @@ -275,7 +275,7 @@ macro and ``LIBCAMERA_LOG_LEVELS`` environment variable help you use the inbuilt libcamera `logging infrastructure`_ that allow for the inspection of internal operations in a user-configurable way. -.. _logging infrastructure: http://libcamera.org/api-html/log_8h.html +.. _logging infrastructure: https://libcamera.org/api-html/log_8h.html Add the following before the ``PipelineHandlerVivid`` class declaration: @@ -334,8 +334,8 @@ You can specify the search further by adding specific media entities to the search using the ``.add()`` function on the DeviceMatch. .. _match(): https://www.libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7cd5b652a2414b543ec20ba9dabf61b6 -.. _start(): http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html#a49e322880a2a26013bb0076788b298c5 -.. _DeviceMatch: http://libcamera.org/api-html/classlibcamera_1_1DeviceMatch.html +.. _start(): https://libcamera.org/api-html/classlibcamera_1_1CameraManager.html#a49e322880a2a26013bb0076788b298c5 +.. _DeviceMatch: https://libcamera.org/api-html/classlibcamera_1_1DeviceMatch.html This example uses search patterns that match vivid, but when developing a new pipeline handler, you should change this value to suit your device identifier. @@ -354,7 +354,7 @@ to the matching media controller device with the `acquireMediaDevice`_ function. If the function attempts to acquire a device it has already matched, it returns ``false``. -.. _acquireMediaDevice: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a77e424fe704e7b26094164b9189e0f84 +.. _acquireMediaDevice: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a77e424fe704e7b26094164b9189e0f84 Add the following below ``dm.add("vivid-000-vid-cap");``: @@ -419,7 +419,7 @@ with the Camera. Each Camera has instance-specific data represented using the `Camera::Private`_ class, which can be extended for the specific needs of the pipeline handler. -.. _Camera::Private: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html +.. _Camera::Private: https://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html To support the Camera we will later register, we need to create a Camera::Private @@ -475,7 +475,7 @@ the `MediaDevice::getEntityByName`_ function from the MediaDevice. As our example is based upon the simplistic Vivid test device, we only need to open a single capture device named 'vivid-000-vid-cap' by the device. -.. _MediaDevice::getEntityByName: http://libcamera.org/api-html/classlibcamera_1_1MediaDevice.html#ad5d9279329ef4987ceece2694b33e230 +.. _MediaDevice::getEntityByName: https://libcamera.org/api-html/classlibcamera_1_1MediaDevice.html#ad5d9279329ef4987ceece2694b33e230 .. code-block:: cpp @@ -516,8 +516,8 @@ handler and camera manager using `registerCamera`_. Finally with a successful construction, we return 'true' indicating that the PipelineHandler successfully matched and constructed a device. -.. _Camera::create: http://libcamera.org/api-html/classlibcamera_1_1Camera.html#a453740e0d2a2f495048ae307a85a2574 -.. _registerCamera: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#adf02a7f1bbd87aca73c0e8d8e0e6c98b +.. _Camera::create: https://libcamera.org/api-html/classlibcamera_1_1Camera.html#a453740e0d2a2f495048ae307a85a2574 +.. _registerCamera: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#adf02a7f1bbd87aca73c0e8d8e0e6c98b .. code-block:: cpp @@ -590,9 +590,9 @@ processed to automatically generate documentation and interfaces. Controls are defined by the src/libcamera/`control_ids.yaml`_ file and camera properties are defined by src/libcamera/`properties_ids.yaml`_. -.. _controls framework: http://libcamera.org/api-html/controls_8h.html -.. _control_ids.yaml: http://libcamera.org/api-html/control__ids_8h.html -.. _properties_ids.yaml: http://libcamera.org/api-html/property__ids_8h.html +.. _controls framework: https://libcamera.org/api-html/controls_8h.html +.. _control_ids.yaml: https://libcamera.org/api-html/control__ids_8h.html +.. _properties_ids.yaml: https://libcamera.org/api-html/property__ids_8h.html Pipeline handlers can optionally register the list of controls an application can set as well as a list of immutable camera properties. Being both @@ -600,14 +600,14 @@ Camera-specific values, they are represented in the ``Camera::Private`` base class, which provides two members for this purpose: the `Camera::Private::controlInfo_`_ and the `Camera::Private::properties_`_ fields. -.. _Camera::Private::controlInfo_: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ab4e183eb4dabe929d1b2bbbb519b969f -.. _Camera::Private::properties_: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ad31f12f5ed9c1fbe25750902f4791064 +.. _Camera::Private::controlInfo_: https://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ab4e183eb4dabe929d1b2bbbb519b969f +.. _Camera::Private::properties_: https://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ad31f12f5ed9c1fbe25750902f4791064 The ``controlInfo_`` field represents a map of ``ControlId`` instances associated with the limits of valid values supported for the control. More information can be found in the `ControlInfoMap`_ class documentation. -.. _ControlInfoMap: http://libcamera.org/api-html/classlibcamera_1_1ControlInfoMap.html +.. _ControlInfoMap: https://libcamera.org/api-html/classlibcamera_1_1ControlInfoMap.html Pipeline handlers register controls to expose the tunable device and IPA parameters to applications. Our example pipeline handler only exposes trivial @@ -700,7 +700,7 @@ To support validation in our example pipeline handler, Create a new class called ``VividCameraConfiguration`` derived from the base `CameraConfiguration`_ class which we can implement and use within our ``PipelineHandlerVivid`` class. -.. _CameraConfiguration: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html +.. _CameraConfiguration: https://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html The derived ``CameraConfiguration`` class must override the base class ``validate()`` function, where the stream configuration inspection and @@ -726,8 +726,8 @@ Applications generate a ``CameraConfiguration`` instance by calling the implementation of the overridden `PipelineHandler::generateConfiguration()`_ function. -.. _Camera::generateConfiguration(): http://libcamera.org/api-html/classlibcamera_1_1Camera.html#a25c80eb7fc9b1cf32692ce0c7f09991d -.. _PipelineHandler::generateConfiguration(): http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7932e87735695500ce1f8c7ae449b65b +.. _Camera::generateConfiguration(): https://libcamera.org/api-html/classlibcamera_1_1Camera.html#a25c80eb7fc9b1cf32692ce0c7f09991d +.. _PipelineHandler::generateConfiguration(): https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7932e87735695500ce1f8c7ae449b65b Configurations are generated by receiving a list of ``StreamRoles`` instances, which libcamera uses as predefined ways an application intends to use a camera @@ -735,7 +735,7 @@ which libcamera uses as predefined ways an application intends to use a camera optional hints on how an application intends to use a stream, and a pipeline handler should return an ideal configuration for each role that is requested. -.. _StreamRole API: http://libcamera.org/api-html/stream_8h.html#file_a295d1f5e7828d95c0b0aabc0a8baac03 +.. _StreamRole API: https://libcamera.org/api-html/stream_8h.html#file_a295d1f5e7828d95c0b0aabc0a8baac03 In the pipeline handler ``generateConfiguration`` implementation, remove the ``return nullptr;``, create a new instance of the ``CameraConfiguration`` @@ -796,7 +796,7 @@ The `StreamFormats`_ class holds information about the pixel formats and frame sizes that a stream can support. The class groups size information by the pixel format, which can produce it. -.. _StreamFormats: http://libcamera.org/api-html/classlibcamera_1_1StreamFormats.html +.. _StreamFormats: https://libcamera.org/api-html/classlibcamera_1_1StreamFormats.html The code below uses the ``StreamFormats`` class to represent all of the supported pixel formats, associated with a list of frame sizes. It then @@ -849,7 +849,7 @@ If changes are made, it marks the configuration as ``Adjusted``, however if the requested configuration is not supported and cannot be adjusted it shall be refused and marked as ``Invalid``. -.. _CameraConfiguration::validate(): http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a29f8f263384c6149775b6011c7397093 +.. _CameraConfiguration::validate(): https://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a29f8f263384c6149775b6011c7397093 The validation phase makes sure all the platform-specific constraints are respected by the requested configuration. The most trivial examples being making @@ -949,8 +949,8 @@ The `PipelineHandler::configure()`_ function receives a valid parameters to prepare a device for a streaming session with the desired properties. -.. _PipelineHandler::configure(): http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a930f2a9cdfb51dfb4b9ca3824e84fc29 -.. _CameraConfiguration: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html +.. _PipelineHandler::configure(): https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a930f2a9cdfb51dfb4b9ca3824e84fc29 +.. _CameraConfiguration: https://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html Replace the contents of the stubbed ``PipelineHandlerVivid::configure`` function with the following to obtain the camera data and stream configuration. This @@ -972,8 +972,8 @@ node. The fourcc attribute is a `V4L2PixelFormat`_ and differs from the plane configuration for multiplanar formats, so you must explicitly convert it using the helper ``V4L2PixelFormat::fromPixelFormat()``. -.. _V4L2DeviceFormat: http://libcamera.org/api-html/classlibcamera_1_1V4L2DeviceFormat.html -.. _V4L2PixelFormat: http://libcamera.org/api-html/classlibcamera_1_1V4L2PixelFormat.html +.. _V4L2DeviceFormat: https://libcamera.org/api-html/classlibcamera_1_1V4L2DeviceFormat.html +.. _V4L2PixelFormat: https://libcamera.org/api-html/classlibcamera_1_1V4L2PixelFormat.html Add the following code beneath the code from above: @@ -989,7 +989,7 @@ driver has adjusted the format, as this shows the pipeline handler has failed to handle the validation stages correctly, and the configure operation shall also fail. -.. _V4L2VideoDevice::setFormat(): http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#ad67b47dd9327ce5df43350b80c083cca +.. _V4L2VideoDevice::setFormat(): https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#ad67b47dd9327ce5df43350b80c083cca Continue the implementation with the following code: @@ -1008,7 +1008,7 @@ Associate the configuration with the stream by using the `StreamConfiguration::setStream`_ function, and set the values of individual stream configuration members as required. -.. _StreamConfiguration::setStream: http://libcamera.org/api-html/structlibcamera_1_1StreamConfiguration.html#a74a0eb44dad1b00112c7c0443ae54a12 +.. _StreamConfiguration::setStream: https://libcamera.org/api-html/structlibcamera_1_1StreamConfiguration.html#a74a0eb44dad1b00112c7c0443ae54a12 .. NOTE: the cfg.setStream() call here associates the stream to the StreamConfiguration however that should quite likely be done as part of @@ -1033,7 +1033,7 @@ controls at system configuration time, to make sure they are defaulted to sane values. Handling of device controls is again performed using the libcamera `controls framework`_. -.. _Controls Framework: http://libcamera.org/api-html/controls_8h.html +.. _Controls Framework: https://libcamera.org/api-html/controls_8h.html This section is particularly specific to Vivid as it sets the initial values of controls to match `Vivid Controls`_ defined by the kernel driver. You won't need @@ -1056,8 +1056,8 @@ come directly from the kernel sources: We can now use the V4L2 control IDs to prepare a list of controls with the `ControlList`_ class, and set them using the `ControlList::set()`_ function. -.. _ControlList: http://libcamera.org/api-html/classlibcamera_1_1ControlList.html -.. _ControlList::set(): http://libcamera.org/api-html/classlibcamera_1_1ControlList.html#a74a1a29abff5243e6e37ace8e24eb4ba +.. _ControlList: https://libcamera.org/api-html/classlibcamera_1_1ControlList.html +.. _ControlList::set(): https://libcamera.org/api-html/classlibcamera_1_1ControlList.html#a74a1a29abff5243e6e37ace8e24eb4ba In our pipeline ``configure`` function, add the following code after the format has been set and checked to initialise the ControlList and apply it to the @@ -1111,16 +1111,16 @@ libcamera also provides an API to allocate and export memory to applications realized through the `exportFrameBuffers`_ function and the `FrameBufferAllocator`_ class which will be presented later. -.. _exportFrameBuffers: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a6312a69da7129c2ed41f9d9f790adf7c -.. _FrameBufferAllocator: http://libcamera.org/api-html/classlibcamera_1_1FrameBufferAllocator.html +.. _exportFrameBuffers: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a6312a69da7129c2ed41f9d9f790adf7c +.. _FrameBufferAllocator: https://libcamera.org/api-html/classlibcamera_1_1FrameBufferAllocator.html Please refer to the V4L2VideoDevice API documentation, specifically the `allocateBuffers`_, `importBuffers`_ and `exportBuffers`_ functions for a detailed description of the video device memory management. -.. _allocateBuffers: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a3a1a77e5e6c220ea7878e89485864a1c -.. _importBuffers: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a154f5283d16ebd5e15d63e212745cb64 -.. _exportBuffers: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#ae9c0b0a68f350725b63b73a6da5a2ecd +.. _allocateBuffers: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a3a1a77e5e6c220ea7878e89485864a1c +.. _importBuffers: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a154f5283d16ebd5e15d63e212745cb64 +.. _exportBuffers: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#ae9c0b0a68f350725b63b73a6da5a2ecd Video memory buffers are represented in libcamera by the `FrameBuffer`_ class. A ``FrameBuffer`` instance has to be associated to each ``Stream`` which is part @@ -1129,7 +1129,7 @@ by importing the dma-buf file descriptors it needs to operate on. This operation is performed by using the ``V4L2VideoDevice`` API, which provides an ``importBuffers()`` function that prepares the video device accordingly. -.. _FrameBuffer: http://libcamera.org/api-html/classlibcamera_1_1FrameBuffer.html +.. _FrameBuffer: https://libcamera.org/api-html/classlibcamera_1_1FrameBuffer.html Implement the pipeline handler ``start()`` function by replacing the stub version with the following code: @@ -1160,13 +1160,13 @@ and exports it as dma-buf file descriptors. From this point on, the allocated imported by the pipeline hander in exactly the same fashion as if they were allocated elsewhere. -.. _FrameBufferAllocator: http://libcamera.org/api-html/classlibcamera_1_1FrameBufferAllocator.html +.. _FrameBufferAllocator: https://libcamera.org/api-html/classlibcamera_1_1FrameBufferAllocator.html Pipeline handlers support the ``FrameBufferAllocator`` operations by implementing the `exportFrameBuffers`_ function, which will allocate memory in the video device associated with a stream and export it. -.. _exportFrameBuffers: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a6312a69da7129c2ed41f9d9f790adf7c +.. _exportFrameBuffers: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a6312a69da7129c2ed41f9d9f790adf7c Implement the ``exportFrameBuffers`` stub function with the following code to handle this: @@ -1198,14 +1198,14 @@ caller and the `releaseBuffers`_ function releases any buffers to leave the device in a consistent state. If your pipeline handler uses any image processing algorithms, or other devices you should also stop them. -.. _streamOn: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a588a5dc9d6f4c54c61136ac43ff9a8cc -.. _releaseBuffers: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a191619c152f764e03bc461611f3fcd35 +.. _streamOn: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a588a5dc9d6f4c54c61136ac43ff9a8cc +.. _releaseBuffers: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a191619c152f764e03bc461611f3fcd35 Of course we also need to handle the corresponding actions to stop streaming on a device, Add the following to the ``stop`` function, to stop the stream with the `streamOff`_ function and release all buffers. -.. _streamOff: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a61998710615bdf7aa25a046c8565ed66 +.. _streamOff: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a61998710615bdf7aa25a046c8565ed66 .. code-block:: cpp @@ -1228,8 +1228,8 @@ This example pipeline handler identifies the buffer using the `findBuffer`_ helper from the only supported stream and queues it to the capture device directly with the `queueBuffer`_ function provided by the V4L2VideoDevice. -.. _findBuffer: http://libcamera.org/api-html/classlibcamera_1_1Request.html#ac66050aeb9b92c64218945158559c4d4 -.. _queueBuffer: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a594cd594686a8c1cf9ae8dba0b2a8a75 +.. _findBuffer: https://libcamera.org/api-html/classlibcamera_1_1Request.html#ac66050aeb9b92c64218945158559c4d4 +.. _queueBuffer: https://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a594cd594686a8c1cf9ae8dba0b2a8a75 Replace the stubbed contents of ``queueRequestDevice`` with the following: @@ -1328,7 +1328,7 @@ This example pipeline handler applies controls during the `queueRequestDevice`_ function for each request, and applies them to the capture device through the capture node. -.. _queueRequestDevice: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a106914cca210640c9da9ee1f0419e83c +.. _queueRequestDevice: https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a106914cca210640c9da9ee1f0419e83c In the ``queueRequestDevice`` function, replace the following: @@ -1369,7 +1369,7 @@ of the libcamera implementation is available in the `libcamera Signal and Slot`_ classes documentation. .. _Qt Signals and Slots: https://doc.qt.io/qt-5/signalsandslots.html -.. _libcamera Signal and Slot: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#details +.. _libcamera Signal and Slot: https://libcamera.org/api-html/classlibcamera_1_1Signal.html#details In order to notify applications about the availability of new frames and data, the ``Camera`` device exposes two ``Signals`` to which applications can connect @@ -1396,7 +1396,7 @@ the PipelineHandler base class ``completeRequest`` function. The PipelineHandler class implementation makes sure the request completion notifications are delivered to applications in the same order as they have been submitted. -.. _connecting: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#aa04db72d5b3091ffbb4920565aeed382 +.. _connecting: https://libcamera.org/api-html/classlibcamera_1_1Signal.html#aa04db72d5b3091ffbb4920565aeed382 Returning to the ``int VividCameraData::init()`` function, add the following above the closing ``return 0;`` to connect the pipeline handler ``bufferReady``