diff options
Diffstat (limited to 'Documentation/guides/pipeline-handler.rst')
| -rw-r--r-- | Documentation/guides/pipeline-handler.rst | 83 |
1 files changed, 68 insertions, 15 deletions
diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 2d55666d..728e9676 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -183,7 +183,7 @@ to the libcamera build options in the top level ``meson_options.txt``. option('pipelines', type : 'array', - choices : ['ipu3', 'raspberrypi', 'rkisp1', 'simple', 'uvcvideo', 'vimc', 'vivid'], + choices : ['ipu3', 'rkisp1', 'rpi/vc4', 'simple', 'uvcvideo', 'vimc', 'vivid'], description : 'Select which pipeline handlers to include') @@ -203,7 +203,7 @@ implementations for the overridden class members. PipelineHandlerVivid(CameraManager *manager); CameraConfiguration *generateConfiguration(Camera *camera, - const StreamRoles &roles) override; + Span<const StreamRole> roles) override; int configure(Camera *camera, CameraConfiguration *config) override; int exportFrameBuffers(Camera *camera, Stream *stream, @@ -223,7 +223,7 @@ implementations for the overridden class members. } CameraConfiguration *PipelineHandlerVivid::generateConfiguration(Camera *camera, - const StreamRoles &roles) + Span<const StreamRole> roles) { return nullptr; } @@ -289,7 +289,7 @@ features: .. code-block:: cpp #include <libcamera/base/log.h> - + #include "libcamera/internal/pipeline_handler.h" Run the following commands: @@ -587,12 +587,12 @@ immutable properties of the ``Camera`` device. The libcamera controls and properties are defined in YAML form which is processed to automatically generate documentation and interfaces. Controls are -defined by the src/libcamera/`control_ids.yaml`_ file and camera properties -are defined by src/libcamera/`properties_ids.yaml`_. +defined by the src/libcamera/`control_ids_core.yaml`_ file and camera properties +are defined by src/libcamera/`properties_ids_core.yaml`_. .. _controls framework: https://libcamera.org/api-html/controls_8h.html -.. _control_ids.yaml: https://libcamera.org/api-html/control__ids_8h.html -.. _properties_ids.yaml: https://libcamera.org/api-html/property__ids_8h.html +.. _control_ids_core.yaml: https://libcamera.org/api-html/control__ids_8h.html +.. _properties_ids_core.yaml: https://libcamera.org/api-html/property__ids_8h.html Pipeline handlers can optionally register the list of controls an application can set as well as a list of immutable camera properties. Being both @@ -651,7 +651,7 @@ inline in our VividCameraData init: ctrls.emplace(id, info); } - controlInfo_ = std::move(ctrls); + controlInfo_ = ControlInfoMap(std::move(ctrls), controls::controls); The ``properties_`` field is a list of ``ControlId`` instances associated with immutable values, which represent static characteristics that can @@ -672,6 +672,58 @@ handling controls: #include <libcamera/controls.h> #include <libcamera/control_ids.h> +Vendor-specific controls and properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vendor-specific controls and properties must be defined in a separate YAML file +and included in the build by defining the pipeline handler to file mapping in +include/libcamera/meson.build. These YAML files live in the src/libcamera +directory. + +For example, adding a Raspberry Pi vendor control file for the PiSP pipeline +handler is done with the following mapping: + +.. code-block:: meson + + controls_map = { + 'controls': { + 'draft': 'control_ids_draft.yaml', + 'libcamera': 'control_ids_core.yaml', + 'rpi/pisp': 'control_ids_rpi.yaml', + }, + + 'properties': { + 'draft': 'property_ids_draft.yaml', + 'libcamera': 'property_ids_core.yaml', + } + } + +The pipeline handler named above must match the pipeline handler option string +specified in the meson build configuration. + +Vendor-specific controls and properties must contain a `vendor: <vendor_string>` +tag in the YAML file. Every unique vendor tag must define a unique and +non-overlapping range of reserved control IDs in src/libcamera/control_ranges.yaml. + +For example, the following block defines a vendor-specific control with the +`rpi` vendor tag: + +.. code-block:: yaml + + vendor: rpi + controls: + - PispConfigDumpFile: + type: string + description: | + Triggers the Raspberry Pi PiSP pipeline handler to generate a JSON + formatted dump of the Backend configuration to the filename given by the + value of the control. + +The controls will be generated in the vendor-specific namespace +`libcamera::controls::rpi`. Additionally a `#define +LIBCAMERA_HAS_RPI_VENDOR_CONTROLS` will be available to allow applications to +test for the availability of these controls. + Generating a default configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -729,7 +781,7 @@ function. .. _Camera::generateConfiguration(): https://libcamera.org/api-html/classlibcamera_1_1Camera.html#a25c80eb7fc9b1cf32692ce0c7f09991d .. _PipelineHandler::generateConfiguration(): https://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html#a7932e87735695500ce1f8c7ae449b65b -Configurations are generated by receiving a list of ``StreamRoles`` instances, +Configurations are generated by receiving a list of ``StreamRole`` instances, which libcamera uses as predefined ways an application intends to use a camera (You can read the full list in the `StreamRole API`_ documentation). These are optional hints on how an application intends to use a stream, and a pipeline @@ -971,7 +1023,8 @@ with the fourcc and size attributes to apply directly to the capture device node. The fourcc attribute is a `V4L2PixelFormat`_ and differs from the ``libcamera::PixelFormat``. Converting the format requires knowledge of the plane configuration for multiplanar formats, so you must explicitly convert it -using the helper ``V4L2PixelFormat::fromPixelFormat()``. +using the helper ``V4L2VideoDevice::toV4L2PixelFormat()`` provided by the +V4L2VideoDevice instance that the format will be applied on. .. _V4L2DeviceFormat: https://libcamera.org/api-html/classlibcamera_1_1V4L2DeviceFormat.html .. _V4L2PixelFormat: https://libcamera.org/api-html/classlibcamera_1_1V4L2PixelFormat.html @@ -981,7 +1034,7 @@ Add the following code beneath the code from above: .. code-block:: cpp V4L2DeviceFormat format = {}; - format.fourcc = V4L2PixelFormat::fromPixelFormat(cfg.pixelFormat); + format.fourcc = data->video_->toV4L2PixelFormat(cfg.pixelFormat); format.size = cfg.size; Set the video device format defined above using the @@ -1001,7 +1054,7 @@ Continue the implementation with the following code: return ret; if (format.size != cfg.size || - format.fourcc != V4L2PixelFormat::fromPixelFormat(cfg.pixelFormat)) + format.fourcc != data->video_->toV4L2PixelFormat(cfg.pixelFormat)) return -EINVAL; Finally, store and set stream-specific data reflecting the state of the stream. @@ -1369,7 +1422,7 @@ emitted triggers the execution of the connected slots. A detailed description of the libcamera implementation is available in the `libcamera Signal and Slot`_ classes documentation. -.. _Qt Signals and Slots: https://doc.qt.io/qt-5/signalsandslots.html +.. _Qt Signals and Slots: https://doc.qt.io/qt-6/signalsandslots.html .. _libcamera Signal and Slot: https://libcamera.org/api-html/classlibcamera_1_1Signal.html#details In order to notify applications about the availability of new frames and data, @@ -1408,7 +1461,7 @@ function to the V4L2 device buffer signal. video_->bufferReady.connect(this, &VividCameraData::bufferReady); Create the matching ``VividCameraData::bufferReady`` function after your -VividCameradata::init() impelementation. +VividCameradata::init() implementation. The ``bufferReady`` function obtains the request from the buffer using the ``request`` function, and notifies the ``Camera`` that the buffer and |