Patch Detail
Show a patch.
GET /api/1.1/patches/13320/?format=api
{ "id": 13320, "url": "https://patchwork.libcamera.org/api/1.1/patches/13320/?format=api", "web_url": "https://patchwork.libcamera.org/patch/13320/", "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": "<20210811232625.17280-13-laurent.pinchart@ideasonboard.com>", "date": "2021-08-11T23:26:23", "name": "[libcamera-devel,v3,12/14] Documentation: guides: pipeline-handler: Migrate to Camera::Private", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "8cbcbf59e6423d26981f668c62c94a56d517b6a7", "submitter": { "id": 2, "url": "https://patchwork.libcamera.org/api/1.1/people/2/?format=api", "name": "Laurent Pinchart", "email": "laurent.pinchart@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/13320/mbox/", "series": [ { "id": 2341, "url": "https://patchwork.libcamera.org/api/1.1/series/2341/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=2341", "date": "2021-08-11T23:26:11", "name": "libcamera: Replace CameraData with Camera::Private", "version": 3, "mbox": "https://patchwork.libcamera.org/series/2341/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/13320/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/13320/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 87F52C3247\n\tfor <parsemail@patchwork.libcamera.org>;\n\tWed, 11 Aug 2021 23:26:46 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 218096891B;\n\tThu, 12 Aug 2021 01:26:46 +0200 (CEST)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id E195B68889\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 12 Aug 2021 01:26:36 +0200 (CEST)", "from pendragon.lan (62-78-145-57.bb.dnainternet.fi [62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 88F1A268\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 12 Aug 2021 01:26:36 +0200 (CEST)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"DMK/x6MG\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1628724396;\n\tbh=g9AgRfz9xzgF4vUVob/uEjlfhPVRQGhG8OnTJlzBtUM=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=DMK/x6MGqo9RLGmoSAbx93PPgKZ3lmA0yelhDhecMmQvAAGHPM9tOvrXlBqXD+a4E\n\tyMbZPj5v2Pzq9XmnyOCLMqqnQekq4UFuxiohipgl/bjfhY4OjmkzPy8NRilIGtveNZ\n\t73ibhmv16fFh44BJE/cpUgMhNWzSLnik7pZGiYsM=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Thu, 12 Aug 2021 02:26:23 +0300", "Message-Id": "<20210811232625.17280-13-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.31.1", "In-Reply-To": "<20210811232625.17280-1-laurent.pinchart@ideasonboard.com>", "References": "<20210811232625.17280-1-laurent.pinchart@ideasonboard.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [PATCH v3 12/14] Documentation: guides:\n\tpipeline-handler: Migrate to Camera::Private", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "Update the pipeline handler guide following the migration from the\nCameraData class to the Camera::Private class.\n\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\nReviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>\nReviewed-by: Jacopo Mondi <jacopo@jmondi.org>\n---\nChanges since v2:\n\n- Fix indentiation\n---\n Documentation/guides/pipeline-handler.rst | 67 ++++++++++++-----------\n 1 file changed, 34 insertions(+), 33 deletions(-)", "diff": "diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\nindex 5c5cf5a9cdc3..54c8e7f1f553 100644\n--- a/Documentation/guides/pipeline-handler.rst\n+++ b/Documentation/guides/pipeline-handler.rst\n@@ -106,7 +106,7 @@ functionalities descibed above. Below is a brief overview of each of those:\n Abstracts camera sensor handling by hiding the details of the V4L2 subdevice\n kernel API and caching sensor information.\n \n-- `CameraData <http://libcamera.org/api-html/classlibcamera_1_1CameraData.html>`_:\n+- `Camera::Private <http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html>`_:\n Represents device-specific data a pipeline handler associates to each Camera\n instance.\n \n@@ -416,26 +416,26 @@ receivers port output.\n The Pipeline Handler is responsible for defining the set of Streams associated\n with the Camera.\n \n-Each Camera has instance-specific data represented using the `CameraData`_\n+Each Camera has instance-specific data represented using the `Camera::Private`_\n class, which can be extended for the specific needs of the pipeline handler.\n \n-.. _CameraData: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html\n+.. _Camera::Private: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html\n \n \n-To support the Camera we will later register, we need to create a CameraData\n+To support the Camera we will later register, we need to create a Camera::Private\n class that we can implement for our specific Pipeline Handler.\n \n-Define a new ``VividCameraData()`` class derived from ``CameraData`` by adding\n-the following code before the PipelineHandlerVivid class definition where it\n-will be used:\n+Define a new ``VividCameraPrivate()`` class derived from ``Camera::Private`` by\n+adding the following code before the PipelineHandlerVivid class definition where\n+it will be used:\n \n .. code-block:: cpp\n \n- class VividCameraData : public CameraData\n+ class VividCameraData : public Camera::Private\n {\n public:\n VividCameraData(PipelineHandler *pipe, MediaDevice *media)\n- : CameraData(pipe), media_(media), video_(nullptr)\n+ : Camera::Private(pipe), media_(media), video_(nullptr)\n {\n }\n \n@@ -457,17 +457,17 @@ single stream, represented by the ``VividCameraData`` class members. More\n complex pipeline handlers might register cameras composed of several video\n devices and sub-devices, or multiple streams per camera that represent the\n several components of the image capture pipeline. You should represent all these\n-components in the ``CameraData`` derived class when developing a custom\n+components in the ``Camera::Private`` derived class when developing a custom\n PipelineHandler.\n \n In our example VividCameraData we implement an ``init()`` function to prepare\n-the object from our PipelineHandler, however the CameraData class does not\n+the object from our PipelineHandler, however the Camera::Private class does not\n specify the interface for initialisation and PipelineHandlers can manage this\n-based on their own needs. Derived CameraData classes are used only by their\n+based on their own needs. Derived Camera::Private classes are used only by their\n respective pipeline handlers.\n \n-The CameraData class stores the context required for each camera instance and\n-is usually responsible for opening all Devices used in the capture pipeline.\n+The Camera::Private class stores the context required for each camera instance\n+and is usually responsible for opening all Devices used in the capture pipeline.\n \n We can now implement the ``init`` function for our example Pipeline Handler to\n create a new V4L2 video device from the media entity, which we can specify using\n@@ -488,11 +488,11 @@ single capture device named 'vivid-000-vid-cap' by the device.\n return 0;\n }\n \n-The CameraData should be created and initialised before we move on to register a\n-new Camera device so we need to construct and initialise our\n+The VividCameraData should be created and initialised before we move on to\n+register a new Camera device so we need to construct and initialise our\n VividCameraData after we have identified our device within\n PipelineHandlerVivid::match(). The VividCameraData is wrapped by a\n-std::unique_ptr to help manage the lifetime of our CameraData instance.\n+std::unique_ptr to help manage the lifetime of the instance.\n \n If the camera data initialization fails, return ``false`` to indicate the\n failure to the ``match()`` function and prevent retrying of the pipeline\n@@ -509,9 +509,9 @@ handler.\n Once the camera data has been initialized, the Camera device instances and the\n associated streams have to be registered. Create a set of streams for the\n camera, which for this device is only one. You create a camera using the static\n-`Camera::create`_ function, passing the pipeline handler, the id of the camera,\n-and the streams available. Then register the camera and its data with the\n-pipeline handler and camera manager using `registerCamera`_.\n+`Camera::create`_ function, passing the Camera::Private instance, the id of the\n+camera, and the streams available. Then register the camera with the pipeline\n+handler and camera manager using `registerCamera`_.\n \n Finally with a successful construction, we return 'true' indicating that the\n PipelineHandler successfully matched and constructed a device.\n@@ -549,23 +549,24 @@ Our match function should now look like the following:\n \n \t/* Create and register the camera. */\n \tstd::set<Stream *> streams{ &data->stream_ };\n- \tstd::shared_ptr<Camera> camera = Camera::create(this, data->video_->deviceName(), streams);\n- \tregisterCamera(std::move(camera), std::move(data));\n+ \tconst std::string &id = data->video_->deviceName();\n+ \tstd::shared_ptr<Camera> camera = Camera::create(data.release(), id, streams);\n+ \tregisterCamera(std::move(camera));\n \n \treturn true;\n }\n \n-We will need to use our custom CameraData class frequently throughout the\n+We will need to use our custom VividCameraData class frequently throughout the\n pipeline handler, so we add a private convenience helper to our Pipeline handler\n-to obtain and cast the custom CameraData instance from a Camera instance.\n+to obtain and cast the custom VividCameraData instance from a Camera::Private\n+instance.\n \n .. code-block:: cpp\n \n private:\n- VividCameraData *cameraData(const Camera *camera)\n+ VividCameraData *cameraData(Camera *camera)\n {\n- return static_cast<VividCameraData *>(\n- PipelineHandler::cameraData(camera));\n+ return static_cast<VividCameraData *>(camera->_d());\n }\n \n At this point, you need to add the following new includes to provide the Camera\n@@ -595,12 +596,12 @@ are defined by src/libcamera/`properties_ids.yaml`_.\n \n Pipeline handlers can optionally register the list of controls an application\n can set as well as a list of immutable camera properties. Being both\n-Camera-specific values, they are represented in the ``CameraData`` base class,\n-which provides two members for this purpose: the `CameraData::controlInfo_`_ and\n-the `CameraData::properties_`_ fields.\n+Camera-specific values, they are represented in the ``Camera::Private`` base\n+class, which provides two members for this purpose: the\n+`Camera::Private::controlInfo_`_ and the `Camera::Private::properties_`_ fields.\n \n-.. _CameraData::controlInfo_: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html#ab9fecd05c655df6084a2233872144a52\n-.. _CameraData::properties_: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html#a84002c29f45bd35566c172bb65e7ec0b\n+.. _Camera::Private::controlInfo_: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ab4e183eb4dabe929d1b2bbbb519b969f\n+.. _Camera::Private::properties_: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html#ad31f12f5ed9c1fbe25750902f4791064\n \n The ``controlInfo_`` field represents a map of ``ControlId`` instances\n associated with the limits of valid values supported for the control. More\n@@ -618,7 +619,7 @@ Complete the initialization of the ``VividCameraData`` class by adding the\n following code to the ``VividCameraData::init()`` function to initialise the\n controls. For more complex control configurations, this could of course be\n broken out to a separate function, but for now we just initialise the small set\n-inline in our CameraData init:\n+inline in our VividCameraData init:\n \n .. code-block:: cpp\n \n", "prefixes": [ "libcamera-devel", "v3", "12/14" ] }