[libcamera-devel] [PATCH v2 10/11] Documentation: guides: pipeline-handler: Migrate to Camera::Private

[Laurent Pinchart]

Update the pipeline handler guide following the migration from the
CameraData class to the Camera::Private class.

Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
---
 Documentation/guides/pipeline-handler.rst | 67 ++++++++++++-----------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst
index 152776935a33..7e9ff824dd50 100644
--- a/Documentation/guides/pipeline-handler.rst
+++ b/Documentation/guides/pipeline-handler.rst
@@ -106,7 +106,7 @@ functionalities descibed above. Below is a brief overview of each of those:
    Abstracts camera sensor handling by hiding the details of the V4L2 subdevice
    kernel API and caching sensor information.
 
--  `CameraData <http://libcamera.org/api-html/classlibcamera_1_1CameraData.html>`_:
+-  `Camera::Private <http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html>`_:
    Represents device-specific data a pipeline handler associates to each Camera
    instance.
 
@@ -416,26 +416,26 @@ receivers port output.
 The Pipeline Handler is responsible for defining the set of Streams associated
 with the Camera.
 
-Each Camera has instance-specific data represented using the `CameraData`_
+Each Camera has instance-specific data represented using the `Camera::Private`_
 class, which can be extended for the specific needs of the pipeline handler.
 
-.. _CameraData: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html
+.. _Camera::Private: http://libcamera.org/api-html/classlibcamera_1_1Camera_1_1Private.html
 
 
-To support the Camera we will later register, we need to create a CameraData
+To support the Camera we will later register, we need to create a Camera::Private
 class that we can implement for our specific Pipeline Handler.
 
-Define a new ``VividCameraData()`` class derived from ``CameraData`` by adding
-the following code before the PipelineHandlerVivid class definition where it
-will be used:
+Define a new ``VividCameraPrivate()`` class derived from ``Camera::Private`` by
+adding the following code before the PipelineHandlerVivid class definition where
+it will be used:
 
 .. code-block:: cpp
 
-   class VividCameraData : public CameraData
+   class VividCameraData : public Camera::Private
    {
    public:
           VividCameraData(PipelineHandler *pipe, MediaDevice *media)
-                : CameraData(pipe), media_(media), video_(nullptr)
+                : Camera::Private(pipe), media_(media), video_(nullptr)
           {
           }
 
@@ -457,17 +457,17 @@ single stream, represented by the ``VividCameraData`` class members. More
 complex pipeline handlers might register cameras composed of several video
 devices and sub-devices, or multiple streams per camera that represent the
 several components of the image capture pipeline. You should represent all these
-components in the ``CameraData`` derived class when developing a custom
+components in the ``Camera::Private`` derived class when developing a custom
 PipelineHandler.
 
 In our example VividCameraData we implement an ``init()`` function to prepare
-the object from our PipelineHandler, however the CameraData class does not
+the object from our PipelineHandler, however the Camera::Private class does not
 specify the interface for initialisation and PipelineHandlers can manage this
-based on their own needs. Derived CameraData classes are used only by their
+based on their own needs. Derived Camera::Private classes are used only by their
 respective pipeline handlers.
 
-The CameraData class stores the context required for each camera instance and
-is usually responsible for opening all Devices used in the capture pipeline.
+The Camera::Private class stores the context required for each camera instance
+and is usually responsible for opening all Devices used in the capture pipeline.
 
 We can now implement the ``init`` method for our example Pipeline Handler to
 create a new V4L2 video device from the media entity, which we can specify using
@@ -488,11 +488,11 @@ capture device named 'vivid-000-vid-cap' by the device.
           return 0;
    }
 
-The CameraData should be created and initialised before we move on to register a
-new Camera device so we need to construct and initialise our
+The VividCameraData should be created and initialised before we move on to
+register a new Camera device so we need to construct and initialise our
 VividCameraData after we have identified our device within
 PipelineHandlerVivid::match(). The VividCameraData is wrapped by a
-std::unique_ptr to help manage the lifetime of our CameraData instance.
+std::unique_ptr to help manage the lifetime of the instance.
 
 If the camera data initialization fails, return ``false`` to indicate the
 failure to the ``match()`` method and prevent retrying of the pipeline handler.
@@ -508,9 +508,9 @@ failure to the ``match()`` method and prevent retrying of the pipeline handler.
 Once the camera data has been initialized, the Camera device instances and the
 associated streams have to be registered. Create a set of streams for the
 camera, which for this device is only one. You create a camera using the static
-`Camera::create`_ method, passing the pipeline handler, the id of the camera,
-and the streams available. Then register the camera and its data with the
-pipeline handler and camera manager using `registerCamera`_.
+`Camera::create`_ method, passing the Camera::Private instance, the id of the
+camera, and the streams available. Then register the camera with the pipeline
+handler and camera manager using `registerCamera`_.
 
 Finally with a successful construction, we return 'true' indicating that the
 PipelineHandler successfully matched and constructed a device.
@@ -548,23 +548,24 @@ Our match function should now look like the following:
 
    	/* Create and register the camera. */
    	std::set<Stream *> streams{ &data->stream_ };
-   	std::shared_ptr<Camera> camera = Camera::create(this, data->video_->deviceName(), streams);
-   	registerCamera(std::move(camera), std::move(data));
+        const std::string &id = data->video_->deviceName();
+   	std::shared_ptr<Camera> camera = Camera::create(data.release(), id, streams);
+   	registerCamera(std::move(camera));
 
    	return true;
    }
 
-We will need to use our custom CameraData class frequently throughout the
+We will need to use our custom VividCameraData class frequently throughout the
 pipeline handler, so we add a private convenience helper to our Pipeline handler
-to obtain and cast the custom CameraData instance from a Camera instance.
+to obtain and cast the custom VividCameraData instance from a Camera::Private
+instance.
 
 .. code-block:: cpp
 
    private:
-       VividCameraData *cameraData(const Camera *camera)
+       VividCameraData *cameraData(Camera *camera)
        {
-               return static_cast<VividCameraData *>(
-                        PipelineHandler::cameraData(camera));
+               return static_cast<VividCameraData *>(camera->_d());
        }
 
 At this point, you need to add the following new includes to provide the Camera
@@ -594,12 +595,12 @@ are defined by src/libcamera/`properties_ids.yaml`_.
 
 Pipeline handlers can optionally register the list of controls an application
 can set as well as a list of immutable camera properties. Being both
-Camera-specific values, they are represented in the ``CameraData`` base class,
-which provides two members for this purpose: the `CameraData::controlInfo_`_ and
-the `CameraData::properties_`_ fields.
+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.
 
-.. _CameraData::controlInfo_: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html#ab9fecd05c655df6084a2233872144a52
-.. _CameraData::properties_: http://libcamera.org/api-html/classlibcamera_1_1CameraData.html#a84002c29f45bd35566c172bb65e7ec0b
+.. _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
 
 The ``controlInfo_`` field represents a map of ``ControlId`` instances
 associated with the limits of valid values supported for the control. More
@@ -617,7 +618,7 @@ Complete the initialization of the ``VividCameraData`` class by adding the
 following code to the ``VividCameraData::init()`` method to initialise the
 controls. For more complex control configurations, this could of course be
 broken out to a separate function, but for now we just initialise the small set
-inline in our CameraData init:
+inline in our VividCameraData init:
 
 .. code-block:: cpp
 
-- 
Regards,

Laurent Pinchart