libcamera/vivid.git - libcamera pipeline handler for VIVID

diff options

author	Jacopo Mondi <jacopo@jmondi.org>	2022-07-15 13:47:01 +0200
committer	Jacopo Mondi <jacopo@jmondi.org>	2022-08-03 15:07:20 +0200
commit	d1abe2bdc88393da7bee3f80451636754d572567 (patch)
tree	f19886e2edadb09f4615afa7a1cb261cd463f6cc /src/ipa/raspberrypi/controller/alsc_status.h
parent	29c09e3ab6c18c649d8510a1faee6c5a2b52c04a (diff)

libcamera: v4l2_videodevice: Match formats supported by the device

Now that V4L2PixelFormat::fromPixelFormat() returns a list of formats to chose from, select the one supported by the video device by matching against the list of supported pixel formats. The first format found to match one of the device supported ones is returned. As the list of pixel formats supported by the video device does not change at run-time, cache it at device open() time. Maximize the lookup efficiency by storing the list of supported V4L2PixelFormat in an std::unordered_set<>. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Tested-by: Paul Elder <paul.elder@ideasonboard.com>

Diffstat (limited to 'src/ipa/raspberrypi/controller/alsc_status.h')

0 files changed, 0 insertions, 0 deletions

.. SPDX-License-Identifier: CC-BY-SA-4.0 Using libcamera in a C++ application ==================================== This tutorial shows how to create a C++ application that uses libcamera to interface with a camera on a system, capture frames from it for 3 seconds, and write metadata about the frames to standard out. .. TODO: Check how much of the example code runs before camera start etc? Application skeleton -------------------- Most of the code in this tutorial runs in the ``int main()`` function with a separate global function to handle events. The two functions need to share data, which are stored in global variables for simplicity. A production-ready application would organize the various objects created in classes, and the event handler would be a class member function to provide context data without requiring global variables. Use the following code snippets as the initial application skeleton. It already lists all the necessary includes directives and instructs the compiler to use the libcamera namespace, which gives access to the libcamera defined names and types without the need of prefixing them. .. code:: cpp #include <iomanip> #include <iostream> #include <memory> #include <libcamera/libcamera.h> using namespace libcamera; int main() { // Code to follow return 0; } Camera Manager -------------- Every libcamera-based application needs an instance of a `CameraManager`_ that runs for the life of the application. When the Camera Manager starts, it enumerates all the cameras detected in the system. Behind the scenes, libcamera abstracts and manages the complex pipelines that kernel drivers expose through the `Linux Media Controller`_ and `Video for Linux`_ (V4L2) APIs, meaning that an application doesn’t need to handle device or driver specific details. .. _CameraManager: http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html .. _Linux Media Controller: https://www.kernel.org/doc/html/latest/media/uapi/mediactl/media-controller-intro.html .. _Video for Linux: https://www.linuxtv.org/docs.php Before the ``int main()`` function, create a global shared pointer variable for the camera to support the event call back later: .. code:: cpp std::shared_ptr<Camera> camera; Create a Camera Manager instance at the beginning of the main function, and then start it. An application should only create a single Camera Manager instance. .. code:: cpp CameraManager *cm = new CameraManager(); cm->start(); During the application initialization, the Camera Manager is started to enumerate all the supported devices and create cameras that the application can interact with. Once the camera manager is started, we can use it to iterate the available cameras in the system: .. code:: cpp for (auto const &camera : cm->cameras()) std::cout << camera->id() << std::endl; Printing the camera id lists the machine-readable unique identifiers, so for example, the output on a Linux machine with a connected USB webcam is ``\_SB_.PCI0.XHC_.RHUB.HS08-8:1.0-5986:2115``. What libcamera considers a camera ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The libcamera library considers any unique source of video frames, which usually correspond to a camera sensor, as a single camera device. Camera devices expose streams, which are obtained by processing data from the single image source and all share some basic properties such as the frame duration and the image exposure time, as they only depend by the image source configuration. Applications select one or multiple Camera devices they wish to operate on, and require frames from at least one of their Streams. Create and acquire a camera --------------------------- This example application uses a single camera (the first enumerated one) that the Camera Manager reports as available to applications. Camera devices are stored by the CameraManager in a list accessible by index, or can be retrieved by name through the ``CameraManager::get()`` function. The code below retrieves the name of the first available camera and gets the camera by name from the Camera Manager. .. code:: cpp std::string cameraId = cm->cameras()[0]->id(); camera = cm->get(cameraId); /* * Note that is equivalent to: * camera = cm->cameras()[0]; */ Once a camera has been selected an application needs to acquire an exclusive lock to it so no other application can use it. .. code:: cpp camera->acquire(); Configure the camera -------------------- Before the application can do anything with the camera, it needs to configure the image format and sizes of the streams it wants to capture frames from. Stream configurations are represented by instances of the ``StreamConfiguration`` class, which are grouped together in a ``CameraConfiguration`` object. Before an application can start setting its desired configuration, a ``CameraConfiguration`` instance needs to be generated from the ``Camera`` device using the ``Camera::generateConfiguration()`` function. The libcamera library uses the ``StreamRole`` enumeration to define predefined ways an application intends to use a camera. The ``Camera::generateConfiguration()`` function accepts a list of desired roles and generates a ``CameraConfiguration`` with the best stream parameters configuration for each of the requested roles. If the camera can handle the requested roles, it returns an initialized ``CameraConfiguration`` and a null pointer if it can't. It is possible for applications to generate an empty ``CameraConfiguration`` instance by not providing any role. The desired configuration will have to be filled-in manually and manually validated. In the example application, create a new configuration variable and use the ``Camera::generateConfiguration`` function to produce a ``CameraConfiguration`` for the single ``StreamRole::Viewfinder`` role. .. code:: cpp std::unique_ptr<CameraConfiguration> config = camera->generateConfiguration( { StreamRole::Viewfinder } ); The generated ``CameraConfiguration`` has a ``StreamConfiguration`` instance for each ``StreamRole`` the application requested. Each of these has a default size and format that the camera assigned, and a list of supported pixel formats and sizes. The code below accesses the first and only ``StreamConfiguration`` item in the ``CameraConfiguration`` and outputs its parameters to standard output. .. code:: cpp StreamConfiguration &streamConfig = config->at(0); std::cout << "Default viewfinder configuration is: " << streamConfig.toString() << std::endl; This is expected to output something like: ``Default viewfinder configuration is: 1280x720-MJPEG`` Change and validate the configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With an initialized ``CameraConfiguration``, an application can make changes to the parameters it contains, for example, to change the width and height, use the following code: .. code:: cpp streamConfig.size.width = 640; streamConfig.size.height = 480; If an application changes any parameters, it must validate the configuration before applying it to the camera using the ``CameraConfiguration::validate()`` 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 see if the Pipeline Handler adjusted the configuration. .. _Status: http://libcamera.org/api-html/classlibcamera_1_1CameraConfiguration.html#a64163f21db2fe1ce0a6af5a6f6847744 For example, the code above set the width and height to 640x480, but if the camera cannot produce an image that large, it might adjust the configuration to the supported size of 320x240 and return ``Adjusted`` as validation status result. If the configuration to validate cannot be adjusted to a set of supported values, the validation procedure fails and returns the ``Invalid`` status. For this example application, the code below prints the adjusted values to standard out. .. code:: cpp config->validate(); std::cout << "Validated viewfinder configuration is: " << streamConfig.toString() << std::endl; For example, the output might be something like ``Validated viewfinder configuration is: 320x240-MJPEG`` A validated ``CameraConfiguration`` can bet given to the ``Camera`` device to be applied to the system. .. code:: cpp camera->configure(config.get()); If an application doesn’t first validate the configuration before calling ``Camera::configure()``, there’s a chance that calling the function can fail, if the given configuration would have to be adjusted. Allocate FrameBuffers --------------------- An application needs to reserve the memory that libcamera can write incoming frames and data to, and that the application can then read. The libcamera library uses ``FrameBuffer`` instances to represent memory buffers allocated in memory. An application should reserve enough memory for the frame size the streams need based on the configured image sizes and formats. The libcamera library consumes buffers provided by applications as ``FrameBuffer`` instances, which makes libcamera a consumer of buffers exported by other devices (such as displays or video encoders), or allocated from an external allocator (such as ION on Android). In some situations, applications do not have any means to allocate or get hold of suitable buffers, for instance, when no other device is involved, or on Linux platforms that lack a centralized allocator. The ``FrameBufferAllocator`` class provides a buffer allocator an application can use in these situations. An application doesn’t have to use the default ``FrameBufferAllocator`` that libcamera provides. It can instead allocate memory manually and pass the buffers in ``Request``\s (read more about ``Request`` in `the frame capture section <#frame-capture>`_ of this guide). The example in this guide covers using the ``FrameBufferAllocator`` that libcamera provides. Using the libcamera ``FrameBufferAllocator`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Applications create a ``FrameBufferAllocator`` for a Camera and use it to allocate buffers for streams of a ``CameraConfiguration`` with the ``allocate()`` function. The list of allocated buffers can be retrieved using the ``Stream`` instance as the parameter of the ``FrameBufferAllocator::buffers()`` function. .. code:: cpp FrameBufferAllocator *allocator = new FrameBufferAllocator(camera); for (StreamConfiguration &cfg : *config) { int ret = allocator->allocate(cfg.stream()); if (ret < 0) { std::cerr << "Can't allocate buffers" << std::endl; return -ENOMEM; } unsigned int allocated = allocator->buffers(cfg.stream()).size(); std::cout << "Allocated " << allocated << " buffers for stream" << std::endl; } Frame Capture ~~~~~~~~~~~~~ The libcamera library implements a streaming model based on per-frame requests. For each frame an application wants to capture it must queue a request for it to the camera. With libcamera, a ``Request`` is at least one ``Stream`` associated with a ``FrameBuffer`` representing the memory location where frames have to be stored. First, by using the ``Stream`` instance associated to each ``StreamConfiguration``, retrieve the list of ``FrameBuffer``\s created for it using the frame allocator. Then create a vector of requests to be submitted to the camera. .. code:: cpp Stream *stream = streamConfig.stream(); const std::vector<std::unique_ptr<FrameBuffer>> &buffers = allocator->buffers(stream); std::vector<Request *> requests; Proceed to fill the request vector by creating ``Request`` instances from the camera device, and associate a buffer for each of them for the ``Stream``. .. code:: cpp for (unsigned int i = 0; i < buffers.size(); ++i) { Request *request = camera->createRequest(); if (!request) { std::cerr << "Can't create request" << std::endl; return -ENOMEM; } const std::unique_ptr<FrameBuffer> &buffer = buffers[i]; int ret = request->addBuffer(stream, buffer.get()); if (ret < 0) { std::cerr << "Can't set buffer for request" << std::endl; return ret; } requests.push_back(request); } .. TODO: Controls .. TODO: A request can also have controls or parameters that you can apply to the image. Event handling and callbacks ---------------------------- The libcamera library uses the concept of `signals and slots` (similar to `Qt Signals and Slots`_) to connect events with callbacks to handle them. .. _signals and slots: http://libcamera.org/api-html/classlibcamera_1_1Signal.html#details .. _Qt Signals and Slots: https://doc.qt.io/qt-5/signalsandslots.html The ``Camera`` device emits two signals that applications can connect to in order to execute callbacks on frame completion events. The ``Camera::bufferCompleted`` signal notifies applications that a buffer with image data is available. Receiving notifications about the single buffer completion event allows applications to implement partial request completion support, and to inspect the buffer content before the request it is part of has fully completed. The ``Camera::requestCompleted`` signal notifies applications that a request has completed, which means all the buffers the request contains have now completed. Request completion notifications are always emitted in the same order as the requests have been queued to the camera. To receive the signals emission notifications, connect a slot function to the signal to handle it in the application code. .. code:: cpp camera->requestCompleted.connect(requestComplete); For this example application, only the ``Camera::requestCompleted`` signal gets handled and the matching ``requestComplete`` slot method outputs information


context:
space:
mode: