{"id":13103,"url":"https://patchwork.libcamera.org/api/1.1/patches/13103/?format=json","web_url":"https://patchwork.libcamera.org/patch/13103/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","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=json","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=json","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":"","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 ;\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 ;\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 ;\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 ","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":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"Update the pipeline handler guide following the migration from the\nCameraData class to the Camera::Private class.\n\nSigned-off-by: Laurent Pinchart \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 `_:\n+- `Camera::Private `_:\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 streams{ &data->stream_ };\n- \tstd::shared_ptr 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::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(\n- PipelineHandler::cameraData(camera));\n+ return static_cast(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"]}