Patch Detail
Show a patch.
GET /api/1.1/patches/13103/?format=api
{ "id": 13103, "url": "https://patchwork.libcamera.org/api/1.1/patches/13103/?format=api", "web_url": "https://patchwork.libcamera.org/patch/13103/", "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": "<20210723040036.32346-18-laurent.pinchart@ideasonboard.com>", "date": "2021-07-23T04:00:36", "name": "[libcamera-devel,RFC,17/17] Documentation: guides: pipeline-handler: Migrate to Camera::Private", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "3c5419093070dfeaf852540f2ebccd90559f40a5", "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/13103/mbox/", "series": [ { "id": 2270, "url": "https://patchwork.libcamera.org/api/1.1/series/2270/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=2270", "date": "2021-07-23T04:00:19", "name": "libcamera: Replace CameraData with Camera::Private", "version": 1, "mbox": "https://patchwork.libcamera.org/series/2270/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/13103/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/13103/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 00EB5C3231\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 23 Jul 2021 04:00:59 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 7C4F8687D0;\n\tFri, 23 Jul 2021 06:00:59 +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 9D25E60274\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 23 Jul 2021 06:00:48 +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 413DA3F2\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 23 Jul 2021 06:00:48 +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=\"ZnAKo5Le\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1627012848;\n\tbh=PwB2hskSDdZ+F+/R7J/JPSoLHHc7r8SiwB2V7al17lA=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=ZnAKo5LepfoxnC5ILlo/2hTYEVFLXEoth77m3JiC8KF9rMqRPAhnuV0VhOKIPVjdc\n\tFyoVqz0iOkH25Oj/MQOehTGfSd31Q45154Tyqljr9yHMT+78R66bbdwC9jCNZ7hcYa\n\tVjLJYJLNpGTiP3S2dEGFF9gyWsDMTmF4HHMngNM0=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Fri, 23 Jul 2021 07:00:36 +0300", "Message-Id": "<20210723040036.32346-18-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.31.1", "In-Reply-To": "<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>", "References": "<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [RFC PATCH 17/17] 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>\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 152776935a33..7e9ff824dd50 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`` method 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 @@ 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()`` method and prevent retrying of the pipeline handler.\n@@ -508,9 +508,9 @@ failure to the ``match()`` method and prevent retrying of the pipeline 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`_ method, 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`_ method, 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@@ -548,23 +548,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+ const 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@@ -594,12 +595,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@@ -617,7 +618,7 @@ Complete the initialization of the ``VividCameraData`` class by adding the\n following code to the ``VividCameraData::init()`` method 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", "RFC", "17/17" ] }