diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/coding-style.rst | 2 | ||||
| -rw-r--r-- | Documentation/docs.rst | 2 | ||||
| -rw-r--r-- | Documentation/guides/application-developer.rst | 4 | ||||
| -rw-r--r-- | Documentation/guides/ipa.rst | 10 | ||||
| -rw-r--r-- | Documentation/guides/pipeline-handler.rst | 102 |
5 files changed, 61 insertions, 59 deletions
diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst index 30c1778e..5db7f480 100644 --- a/Documentation/coding-style.rst +++ b/Documentation/coding-style.rst @@ -251,7 +251,7 @@ member function of the PipelineHandler class. * \param[in] camera The camera to start * * Start the group of streams that have been configured for capture by - * \a configureStreams(). The intended caller of this method is the Camera + * \a configureStreams(). The intended caller of this function is the Camera * class which will in turn be called from the application to indicate that * it has configured the streams and is ready to capture. * diff --git a/Documentation/docs.rst b/Documentation/docs.rst index f4c6ec5b..a6e8a59a 100644 --- a/Documentation/docs.rst +++ b/Documentation/docs.rst @@ -310,7 +310,7 @@ Camera Device thus the highest level object exposed by libcamera. Camera Device instances are created by the Camera Devices - Manager. An optional method to create new instances could be exposed + Manager. An optional function to create new instances could be exposed through the public API to speed up initialization when the upper layer knows how to directly address camera devices present in the system. diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst index e0bbbad4..fb6a80a5 100644 --- a/Documentation/guides/application-developer.rst +++ b/Documentation/guides/application-developer.rst @@ -194,7 +194,7 @@ function. If the new values are not supported by the ``Camera`` device, the validation process adjusts the parameters to what it considers to be the closest supported values. -The ``validate`` method returns a `Status`_ which applications shall check to +The ``validate`` function returns a `Status`_ which applications shall check to see if the Pipeline Handler adjusted the configuration. .. _Status: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a64163f21db2fe1ce0a6af5a6f6847744 @@ -360,7 +360,7 @@ signal to handle it in the application code. camera->requestCompleted.connect(requestComplete); For this example application, only the ``Camera::requestCompleted`` signal gets -handled and the matching ``requestComplete`` slot method outputs information +handled and the matching ``requestComplete`` slot function outputs information about the FrameBuffer to standard output. This callback is typically where an application accesses the image data from the camera and does something with it. diff --git a/Documentation/guides/ipa.rst b/Documentation/guides/ipa.rst index c612470f..fc031745 100644 --- a/Documentation/guides/ipa.rst +++ b/Documentation/guides/ipa.rst @@ -172,7 +172,7 @@ function of the IPAInterface. stop() informs the IPA module that the camera is stopped. The IPA module shall release resources prepared in start(). -A configure() method is recommended. Any ControlInfoMap instances that will be +A configure() function is recommended. Any ControlInfoMap instances that will be used by the IPA must be sent to the IPA from the pipeline handler, at configure time, for example. @@ -184,11 +184,11 @@ parameter, in which case it will become a regular return value. const is not allowed inside of arrays and maps. mojo arrays will become C++ std::vector<>. -By default, all methods defined in the main interface are synchronous. This +By default, all functions defined in the main interface are synchronous. This means that in the case of IPC (i.e. isolated IPA), the function call will not return until the return value or output parameters are ready. To specify an asynchronous function, the [async] attribute can be used. Asynchronous -methods must not have any return value or output parameters, since in the +functions must not have any return value or output parameters, since in the case of IPC the call needs to return immediately. It is also possible that the IPA will not be run in isolation. In this case, @@ -245,11 +245,11 @@ the camera pipeline from the IPA. The event interface must be named as IPA{pipeline_name}EventInterface. -Methods defined in the event interface are implicitly asynchronous. +Functions defined in the event interface are implicitly asynchronous. Thus they cannot return any value. Specifying the [async] tag is not necessary. -Methods defined in the event interface will become signals in the IPA +Functions defined in the event interface will become signals in the IPA interface. The IPA can emit signals, while the pipeline handler can connect slots to them. diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 15277693..5c5cf5a9 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -189,7 +189,7 @@ to the libcamera build options in the top level ``meson_options.txt``. In *vivid.cpp* add the pipeline handler to the ``libcamera`` namespace, defining a `PipelineHandler`_ derived class named PipelineHandlerVivid, and add stub -methods for the overridden class members. +implementations for the overridden class members. .. _PipelineHandler: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html @@ -322,16 +322,16 @@ have been registered in the system and allows the pipeline handler to be initialized. The main entry point of a pipeline handler is the `match()`_ class member -function. When the ``CameraManager`` is started (using the `start()`_ method), +function. When the ``CameraManager`` is started (using the `start()`_ function), all the registered pipeline handlers are iterated and their ``match`` function called with an enumerator of all devices it found on a system. -The match method should identify if there are suitable devices available in the -``DeviceEnumerator`` which the pipeline supports, returning ``true`` if it +The match function should identify if there are suitable devices available in +the ``DeviceEnumerator`` which the pipeline supports, returning ``true`` if it matches a device, and ``false`` if it does not. To do this, construct a `DeviceMatch`_ class with the name of the ``MediaController`` device to match. You can specify the search further by adding specific media entities to the -search using the ``.add()`` method on the DeviceMatch. +search using the ``.add()`` function on the DeviceMatch. .. _match(): https://www.libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7cd5b652a2414b543ec20ba9dabf61b6 .. _start(): http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html#a49e322880a2a26013bb0076788b298c5 @@ -340,7 +340,7 @@ search using the ``.add()`` method on the DeviceMatch. This example uses search patterns that match vivid, but when developing a new pipeline handler, you should change this value to suit your device identifier. -Replace the contents of the ``PipelineHandlerVivid::match`` method with the +Replace the contents of the ``PipelineHandlerVivid::match`` function with the following: .. code-block:: cpp @@ -350,8 +350,8 @@ following: return false; // Prevent infinite loops for now With the device matching criteria defined, attempt to acquire exclusive access -to the matching media controller device with the `acquireMediaDevice`_ method. -If the method attempts to acquire a device it has already matched, it returns +to the matching media controller device with the `acquireMediaDevice`_ function. +If the function attempts to acquire a device it has already matched, it returns ``false``. .. _acquireMediaDevice: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a77e424fe704e7b26094164b9189e0f84 @@ -382,7 +382,7 @@ As a temporary validation step, add a debug print with LOG(VIVID, Debug) << "Vivid Device Identified"; before the final closing return statement in the ``PipelineHandlerVivid::match`` -method for when when the pipeline handler successfully matches the +function for when when the pipeline handler successfully matches the ``MediaDevice`` and ``MediaEntity`` names. Test that the pipeline handler matches and finds a device by rebuilding, and @@ -469,11 +469,11 @@ 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. -We can now implement the ``init`` method for our example Pipeline Handler to +We can now implement the ``init`` function for our example Pipeline Handler to create a new V4L2 video device from the media entity, which we can specify using -the `MediaDevice::getEntityByName`_ method from the MediaDevice. As our example -is based upon the simplistic Vivid test device, we only need to open a single -capture device named 'vivid-000-vid-cap' by the device. +the `MediaDevice::getEntityByName`_ function from the MediaDevice. As our +example is based upon the simplistic Vivid test device, we only need to open a +single capture device named 'vivid-000-vid-cap' by the device. .. _MediaDevice::getEntityByName: http://libcamera.org/api-html/classlibcamera_1_1MediaDevice.html#ad5d9279329ef4987ceece2694b33e230 @@ -495,7 +495,8 @@ PipelineHandlerVivid::match(). The VividCameraData is wrapped by a std::unique_ptr to help manage the lifetime of our CameraData instance. If the camera data initialization fails, return ``false`` to indicate the -failure to the ``match()`` method and prevent retrying of the pipeline handler. +failure to the ``match()`` function and prevent retrying of the pipeline +handler. .. code-block:: cpp @@ -508,7 +509,7 @@ 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, +`Camera::create`_ function, 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`_. @@ -614,7 +615,7 @@ associated values for each supported V4L2 control but demonstrates the mapping of V4L2 Controls to libcamera ControlIDs. Complete the initialization of the ``VividCameraData`` class by adding the -following code to the ``VividCameraData::init()`` method to initialise the +following code to the ``VividCameraData::init()`` function 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: @@ -722,7 +723,7 @@ adjustment happens. Applications generate a ``CameraConfiguration`` instance by calling the `Camera::generateConfiguration()`_ function, which calls into the pipeline implementation of the overridden `PipelineHandler::generateConfiguration()`_ -method. +function. .. _Camera::generateConfiguration(): http://libcamera.org/api-html/classlibcamera_1_1Camera.html#a25c80eb7fc9b1cf32692ce0c7f09991d .. _PipelineHandler::generateConfiguration(): http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7932e87735695500ce1f8c7ae449b65b @@ -839,7 +840,7 @@ Add the following code to complete the implementation of return config; To validate a camera configuration, a pipeline handler must implement the -`CameraConfiguration::validate()`_ method in it's derived class to inspect all +`CameraConfiguration::validate()`_ function in it's derived class to inspect all the stream configuration associated to it, make any adjustments required to make the configuration valid, and return the validation status. @@ -939,10 +940,10 @@ Configuring a device ~~~~~~~~~~~~~~~~~~~~ With the configuration generated, and optionally modified and re-validated, a -pipeline handler needs a method that allows an application to apply a +pipeline handler needs a function that allows an application to apply a configuration to the hardware devices. -The `PipelineHandler::configure()`_ method receives a valid +The `PipelineHandler::configure()`_ function receives a valid `CameraConfiguration`_ and applies the settings to hardware devices, using its parameters to prepare a device for a streaming session with the desired properties. @@ -950,7 +951,7 @@ properties. .. _PipelineHandler::configure(): http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a930f2a9cdfb51dfb4b9ca3824e84fc29 .. _CameraConfiguration: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html -Replace the contents of the stubbed ``PipelineHandlerVivid::configure`` method +Replace the contents of the stubbed ``PipelineHandlerVivid::configure`` function with the following to obtain the camera data and stream configuration. This pipeline handler supports only a single stream, so it directly obtains the first ``StreamConfiguration`` from the camera configuration. A pipeline handler with @@ -983,7 +984,7 @@ Add the following code beneath the code from above: format.size = cfg.size; Set the video device format defined above using the -`V4L2VideoDevice::setFormat()`_ method. You should check if the kernel +`V4L2VideoDevice::setFormat()`_ function. You should check if the kernel driver has adjusted the format, as this shows the pipeline handler has failed to handle the validation stages correctly, and the configure operation shall also fail. @@ -1004,7 +1005,7 @@ Continue the implementation with the following code: Finally, store and set stream-specific data reflecting the state of the stream. Associate the configuration with the stream by using the -`StreamConfiguration::setStream`_ method, and set the values of individual +`StreamConfiguration::setStream`_ function, and set the values of individual stream configuration members as required. .. _StreamConfiguration::setStream: http://libcamera.org/api-html/structlibcamera_1_1StreamConfiguration.html#a74a0eb44dad1b00112c7c0443ae54a12 @@ -1053,12 +1054,12 @@ come directly from the kernel sources: #define VIVID_CID_HOR_MOVEMENT (VIVID_CID_VIVID_BASE + 2) We can now use the V4L2 control IDs to prepare a list of controls with the -`ControlList`_ class, and set them using the `ControlList::set()`_ method. +`ControlList`_ class, and set them using the `ControlList::set()`_ function. .. _ControlList: http://libcamera.org/api-html/classlibcamera_1_1ControlList.html .. _ControlList::set(): http://libcamera.org/api-html/classlibcamera_1_1ControlList.html#a74a1a29abff5243e6e37ace8e24eb4ba -In our pipeline ``configure`` method, add the following code after the format +In our pipeline ``configure`` function, add the following code after the format has been set and checked to initialise the ControlList and apply it to the device: @@ -1082,7 +1083,7 @@ device: These controls configure VIVID to use a default test pattern, and enable all on-screen display text, while configuring sensible brightness, contrast and -saturation values. Use the ``controls.set`` method to set individual controls. +saturation values. Use the ``controls.set`` function to set individual controls. Buffer handling and stream control ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1097,8 +1098,8 @@ frames as soon as they are requested. Memory should be initialized and made available to the devices which have to be started and ready to produce images. At the end of a capture session the ``Camera`` device needs to be stopped, to gracefully clean up any allocated memory and stop the hardware -devices. Pipeline handlers implement two methods for these purposes, the -``start()`` and ``stop()`` methods. +devices. Pipeline handlers implement two functions for these purposes, the +``start()`` and ``stop()`` functions. The memory initialization phase that happens at ``start()`` time serves to configure video devices to be able to use memory buffers exported as dma-buf @@ -1167,7 +1168,7 @@ the video device associated with a stream and export it. .. _exportFrameBuffers: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a6312a69da7129c2ed41f9d9f790adf7c -Implement the ``exportFrameBuffers`` stub method with the following code to +Implement the ``exportFrameBuffers`` stub function with the following code to handle this: .. code-block:: cpp @@ -1178,7 +1179,7 @@ handle this: return data->video_->exportBuffers(count, buffers); Once memory has been properly setup, the video devices can be started, to -prepare for capture operations. Complete the ``start`` method implementation +prepare for capture operations. Complete the ``start`` function implementation with the following code: .. code-block:: cpp @@ -1191,18 +1192,18 @@ with the following code: return 0; -The method starts the video device associated with the stream with the -`streamOn`_ method. If the call fails, the error value is propagated to the -caller and the `releaseBuffers`_ method releases any buffers to leave the device -in a consistent state. If your pipeline handler uses any image processing +The function starts the video device associated with the stream with the +`streamOn`_ function. If the call fails, the error value is propagated to the +caller and the `releaseBuffers`_ function releases any buffers to leave the +device in a consistent state. If your pipeline handler uses any image processing algorithms, or other devices you should also stop them. .. _streamOn: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a588a5dc9d6f4c54c61136ac43ff9a8cc .. _releaseBuffers: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a191619c152f764e03bc461611f3fcd35 Of course we also need to handle the corresponding actions to stop streaming on -a device, Add the following to the ``stop`` method, to stop the stream with the -`streamOff`_ method and release all buffers. +a device, Add the following to the ``stop`` function, to stop the stream with +the `streamOff`_ function and release all buffers. .. _streamOff: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a61998710615bdf7aa25a046c8565ed66 @@ -1225,7 +1226,7 @@ the enabled streams. This example pipeline handler identifies the buffer using the `findBuffer`_ helper from the only supported stream and queues it to the capture device -directly with the `queueBuffer`_ method provided by the V4L2VideoDevice. +directly with the `queueBuffer`_ function provided by the V4L2VideoDevice. .. _findBuffer: http://libcamera.org/api-html/classlibcamera_1_1Request.html#ac66050aeb9b92c64218945158559c4d4 .. _queueBuffer: http://libcamera.org/api-html/classlibcamera_1_1V4L2VideoDevice.html#a594cd594686a8c1cf9ae8dba0b2a8a75 @@ -1260,10 +1261,11 @@ Applications can set controls registered by the pipeline handler in the initialization phase, as explained in the `Registering controls and properties`_ section. -Implement a ``processControls`` method above the ``queueRequestDevice`` method -to loop through the control list received with each request, and inspect the -control values. Controls may need to be converted between the libcamera control -range definitions and their corresponding values on the device before being set. +Implement a ``processControls`` function above the ``queueRequestDevice`` +function to loop through the control list received with each request, and +inspect the control values. Controls may need to be converted between the +libcamera control range definitions and their corresponding values on the device +before being set. .. code-block:: cpp @@ -1307,7 +1309,7 @@ range definitions and their corresponding values on the device before being set. return ret; } -Declare the function prototype for the ``processControls`` method within the +Declare the function prototype for the ``processControls`` function within the private ``PipelineHandlerVivid`` class members, as it is only used internally as a helper when processing Requests. @@ -1323,12 +1325,12 @@ handler is responsible for understanding the correct procedure for applying controls to the device they support. This example pipeline handler applies controls during the `queueRequestDevice`_ -method for each request, and applies them to the capture device through the +function for each request, and applies them to the capture device through the capture node. .. _queueRequestDevice: http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a106914cca210640c9da9ee1f0419e83c -In the ``queueRequestDevice`` method, replace the following: +In the ``queueRequestDevice`` function, replace the following: .. code-block:: cpp @@ -1396,19 +1398,19 @@ delivered to applications in the same order as they have been submitted. .. _connecting: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#aa04db72d5b3091ffbb4920565aeed382 -Returning to the ``int VividCameraData::init()`` method, add the following above -the closing ``return 0;`` to connect the pipeline handler ``bufferReady`` -method to the V4L2 device buffer signal. +Returning to the ``int VividCameraData::init()`` function, add the following +above the closing ``return 0;`` to connect the pipeline handler ``bufferReady`` +function to the V4L2 device buffer signal. .. code-block:: cpp video_->bufferReady.connect(this, &VividCameraData::bufferReady); -Create the matching ``VividCameraData::bufferReady`` method after your +Create the matching ``VividCameraData::bufferReady`` function after your VividCameradata::init() impelementation. -The ``bufferReady`` method obtains the request from the buffer using the -``request`` method, and notifies the ``Camera`` that the buffer and +The ``bufferReady`` function obtains the request from the buffer using the +``request`` function, and notifies the ``Camera`` that the buffer and request are completed. In this simpler pipeline handler, there is only one stream, so it completes the request immediately. You can find a more complex example of event handling with supporting multiple streams in the libcamera |