[{"id":18313,"web_url":"https://patchwork.libcamera.org/comment/18313/","msgid":"","date":"2021-07-24T07:35:13","subject":"Re: [libcamera-devel] [RFC PATCH 17/17] Documentation: guides:\n\tpipeline-handler: Migrate to Camera::Private","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/people/5/","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"content":"Hi Laurent,\n\nThanks for your work.\n\nOn 2021-07-23 07:00:36 +0300, Laurent Pinchart wrote:\n> Update the pipeline handler guide following the migration from the\n> CameraData class to the Camera::Private class.\n> \n> Signed-off-by: Laurent Pinchart \n\nReviewed-by: Niklas Söderlund \n\n> ---\n> Documentation/guides/pipeline-handler.rst | 67 ++++++++++++-----------\n> 1 file changed, 34 insertions(+), 33 deletions(-)\n> \n> diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst\n> index 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> -- \n> Regards,\n> \n> Laurent Pinchart\n>","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 6A38BC322C\n\tfor ;\n\tSat, 24 Jul 2021 07:35:17 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id CF55E687A9;\n\tSat, 24 Jul 2021 09:35:16 +0200 (CEST)","from mail-lf1-x133.google.com (mail-lf1-x133.google.com\n\t[IPv6:2a00:1450:4864:20::133])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id AC8E368540\n\tfor ;\n\tSat, 24 Jul 2021 09:35:15 +0200 (CEST)","by mail-lf1-x133.google.com with SMTP id h14so5865119lfv.7\n\tfor ;\n\tSat, 24 Jul 2021 00:35:15 -0700 (PDT)","from localhost (h-46-59-88-219.A463.priv.bahnhof.se.\n\t[46.59.88.219]) by smtp.gmail.com with ESMTPSA id\n\ts3sm2255232lfb.15.2021.07.24.00.35.14\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tSat, 24 Jul 2021 00:35:14 -0700 (PDT)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key;\n\tunprotected) header.d=ragnatech-se.20150623.gappssmtp.com\n\theader.i=@ragnatech-se.20150623.gappssmtp.com\n\theader.b=\"qRtFRIdg\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=ragnatech-se.20150623.gappssmtp.com; s=20150623;\n\th=date:from:to:cc:subject:message-id:references:mime-version\n\t:content-disposition:content-transfer-encoding:in-reply-to;\n\tbh=QBZlifLmqTUdb0poXF5Iwsf5ncwP36aLFVaJxtEQIR8=;\n\tb=qRtFRIdg+MkKRK0wadb1CAd98NjllHRqckszqPIHr998YqKthBNpGXYtaqKqAG6TuN\n\tWimyOFtiUo588Qamiv7q6B19D5R2fUTakUekFC4bHCUxpmZm7N1wUay9S9DYzstSqDvt\n\ttes9Sb1QyLSuuIIlm62Bha6j6G9E4AEoSZRh+dIgtrqFNoe58MaNKdJ+A0tSmlzMfxmL\n\ti1oVZaaRZ5bwz2hEktbeM3L2J/cWZLW8EhRRxvazvhECV8/1Aenue8MtbuXx4VMMpqoL\n\tXQ/06E12ljD2epM+As/IpbctW8SFoAMbbqeJ2BsBDmskogo4QW4K45SOMPkmG1HskOhM\n\tA+UQ==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:date:from:to:cc:subject:message-id:references\n\t:mime-version:content-disposition:content-transfer-encoding\n\t:in-reply-to;\n\tbh=QBZlifLmqTUdb0poXF5Iwsf5ncwP36aLFVaJxtEQIR8=;\n\tb=cln1saHmN2E9L5449du8mcaVIM2xhGqNxCq5dSYwOgYPuGiq4P/8RwYY2QJp8uJ/16\n\tuTGjzskHNJ9KCPV45SLjmuuxb7y6wnyd9F2uk4cq6e4MvfIKB/HgKqSRcgV94iuLJLj2\n\tq5ZK+ukMwviOTLTUWhwkupZLJMdHzvT62N9eDYHISWo/ER3Ajzv9SnxXDmj5x6/T2gch\n\tGH83UBNWZbtwjSGLEu0rixvBqYQKyZqJqo+uDPOm62SP+yl5WjDxdbA1Zvzm/XAXMzL6\n\tk6EUhgv3VKEDVShOtlOlAJ4XPOA58wuQtpyc8+SRRuK+6eGfniFX0JUYgS27ZP8goiIb\n\t0B9g==","X-Gm-Message-State":"AOAM531H/bcmVOCE1e7Jehjv4/8NicCd1O9g8MuDgrwVyi/yBA6HHiFy\n\ths6vuilia4vZSRfOlOhQEXyOnw==","X-Google-Smtp-Source":"ABdhPJwQQZI6KAlayHFn5ULo1O/zSOY4nSnAKGcX9NFqVzGoZFlT6Y8DegR5xHM9rE4cmya7pKkAkw==","X-Received":"by 2002:a05:6512:c26:: with SMTP id\n\tz38mr5612697lfu.578.1627112114929; \n\tSat, 24 Jul 2021 00:35:14 -0700 (PDT)","Date":"Sat, 24 Jul 2021 09:35:13 +0200","From":"Niklas =?iso-8859-1?q?S=F6derlund?= ","To":"Laurent Pinchart ","Message-ID":"","References":"<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>\n\t<20210723040036.32346-18-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=iso-8859-1","Content-Disposition":"inline","Content-Transfer-Encoding":"8bit","In-Reply-To":"<20210723040036.32346-18-laurent.pinchart@ideasonboard.com>","Subject":"Re: [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","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]