libcamera v0.7.2 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::PipelineHandler Class Referenceabstract

Create and manage cameras based on a set of media devices. More...

Inheritance diagram for libcamera::PipelineHandler:
[legend]
Collaboration diagram for libcamera::PipelineHandler:
[legend]

## Public Member Functions
| PipelineHandler (CameraManager *manager, unsigned int maxQueuedRequestsDevice=32)
| Construct a PipelineHandler instance.
virtual bool | match (DeviceEnumerator *enumerator)=0
| Match media devices and create camera instances.
std::shared_ptr< MediaDevice > | acquireMediaDevice (DeviceEnumerator *enumerator, const DeviceMatch &dm)
| Search and acquire a MediaDevice matching a device pattern.
bool | acquire (Camera *camera)
| Acquire exclusive access to the pipeline handler for the process.
void | release (Camera *camera)
| Release exclusive access to the pipeline handler.
virtual std::unique_ptr< CameraConfiguration > | generateConfiguration (Camera *camera, Span< const StreamRole > roles)=0
| Generate a camera configuration for a specified camera.
virtual int | configure (Camera *camera, CameraConfiguration *config)=0
| Configure a group of streams for capture.
virtual int | exportFrameBuffers (Camera *camera, Stream *stream, std::vector< std::unique_ptr< FrameBuffer > > *buffers)=0
| Allocate and export buffers for stream.
virtual int | start (Camera *camera, const ControlList *controls)=0
| Start capturing from a group of streams.
void | stop (Camera *camera)
| Stop capturing from all running streams and cancel pending requests.
bool | hasPendingRequests (const Camera *camera) const
| Determine if the camera has any requests pending.
void | registerRequest (Request *request)
| Register a request for use by the pipeline handler.
void | queueRequest (Request *request)
| Queue a request.
bool | completeBuffer (Request *request, FrameBuffer *buffer)
| Complete a buffer for a request.
void | completeRequest (Request *request)
| Signal request completion.
void | cancelRequest (Request *request)
| Cancel request and signal its completion.
std::string | configurationFile (const std::string &subdir, const std::string &name, bool silent=false) const
| Retrieve the absolute path to a platform configuration file.
const char * | name () const
| Retrieve the pipeline handler name.
CameraManager * | cameraManager () const
| Retrieve the CameraManager that this pipeline handler belongs to.
template<typename T>
std::unique_ptr< T > | createIPA (uint32_t minVersion, uint32_t maxVersion)
| Create an IPA proxy that matches this pipeline handler.
Public Member Functions inherited from libcamera::Object
| Object (Object *parent=nullptr)
| Construct an Object instance.
virtual | ~Object ()
| Destroy an Object instance.
void | deleteLater ()
| Schedule deletion of the instance in the thread it belongs to.
void | postMessage (std::unique_ptr< Message > msg)
| Post a message to the object's thread.
template<typename T, typename R, typename... FuncArgs, typename... Args, std::enable_if_t< std::is_base_of< Object, T >::value > * = nullptr>
R | invokeMethod (R(T::*func)(FuncArgs...), ConnectionType type, Args &&... args)
| Invoke a method asynchronously on an Object instance.
Thread * | thread () const
| Retrieve the thread the object is bound to.
void | moveToThread (Thread *thread)
| Move the object and all its children to a different thread.
Object * | parent () const
| Retrieve the object's parent.

## Protected Member Functions
void | registerCamera (std::shared_ptr< Camera > camera)
| Register a camera to the camera manager and pipeline handler.
void | hotplugMediaDevice (std::shared_ptr< MediaDevice > media)
| Enable hotplug handling for a media device.
unsigned int | useCount () const
| Retrieve the pipeline handler's used camera count.
virtual int | queueRequestDevice (Camera *camera, Request *request)=0
| Queue a request to the device.
virtual void | stopDevice (Camera *camera)=0
| Stop capturing from all running streams.
virtual bool | acquireDevice (Camera *camera)
| Acquire resources associated with this camera.
virtual void | releaseDevice (Camera *camera)
| Release resources associated with this camera.
Protected Member Functions inherited from libcamera::Object
virtual void | message (Message *msg)
| Message handler for the object.
bool | assertThreadBound (const char *message)
| Check if the caller complies with thread-bound constraints.

## Protected Attributes
CameraManager * | manager_
| The Camera manager associated with the pipeline handler.
const unsigned int | maxQueuedRequestsDevice_
| The maximum number of requests the pipeline handler shall queue to the device.

## Friends
class | PipelineHandlerFactoryBase

## Detailed Description

Create and manage cameras based on a set of media devices.

The PipelineHandler matches the media devices provided by a DeviceEnumerator with the pipelines it supports and creates corresponding Camera devices.

Pipeline handler instances are reference-counted through std::shared_ptr<>. They implement std::enable_shared_from_this<> in order to create new std::shared_ptr<> in code paths originating from member functions of the PipelineHandler class where only the 'this' pointer is available.

## Constructor & Destructor Documentation

## ◆ PipelineHandler()

libcamera::PipelineHandler::PipelineHandler | ( | CameraManager * | manager,
|  | unsigned int | maxQueuedRequestsDevice = 32 )

Construct a PipelineHandler instance.

Parameters

  [in] | manager | The camera manager
  [in] | maxQueuedRequestsDevice | The maximum number of requests queued to the device

In order to honour the std::enable_shared_from_this<> contract, PipelineHandler instances shall never be constructed manually, but always through the PipelineHandlerFactoryBase::create() function.

## Member Function Documentation

## ◆ acquire()

bool libcamera::PipelineHandler::acquire | ( | Camera * | camera | ) |

Acquire exclusive access to the pipeline handler for the process.

This function locks all the media devices used by the pipeline to ensure that no other process can access them concurrently.

Access to a pipeline handler may be acquired recursively from within the same process. Every successful acquire() call shall be matched with a release() call. This allows concurrent access to the same pipeline handler from different cameras within the same process.

Pipeline handlers shall not call this function directly as the Camera class handles access internally.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  True if the pipeline handler was acquired, false if another process has already acquired it

See also
  release()

## ◆ acquireDevice()

bool libcamera::PipelineHandler::acquireDevice | ( | Camera * | camera | ) |
| protected virtual

Acquire resources associated with this camera.

Parameters

  [in] | camera | The camera for which to acquire resources

Pipeline handlers may override this in order to get resources such as opening devices and allocating buffers when a camera is acquired.

This is used by the uvcvideo pipeline handler to delay opening /dev/video# until the camera is acquired to avoid excess power consumption. The delayed opening of /dev/video# is a special case because the kernel uvcvideo driver powers on the USB device as soon as /dev/video# is opened. This behavior should not be copied by other pipeline handlers.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  True on success, false on failure

See also
  releaseDevice()

## ◆ acquireMediaDevice()

std::shared_ptr< MediaDevice > libcamera::PipelineHandler::acquireMediaDevice | ( | DeviceEnumerator * | enumerator,
|  | const DeviceMatch & | dm )

Search and acquire a MediaDevice matching a device pattern.

Parameters

  [in] | enumerator | Enumerator containing all media devices in the system
  [in] | dm | Device match pattern

Search the device enumerator for an available media device matching the device match pattern dm. Matching media device that have previously been acquired by MediaDevice::acquire() are not considered. If a match is found, the media device is acquired and returned. The caller shall not release the device explicitly, it will be automatically released when the pipeline handler is destroyed.

Thread Safety
  This function shall be called from the CameraManager thread.

Returns
  A shared pointer to the matching MediaDevice, or nullptr if no match is found

## ◆ cameraManager()

CameraManager * libcamera::PipelineHandler::cameraManager | ( |  | ) | const
| inline

Retrieve the CameraManager that this pipeline handler belongs to.

Thread Safety
  This function is thread-safe.

Returns
  The CameraManager for this pipeline handler

## ◆ cancelRequest()

void libcamera::PipelineHandler::cancelRequest | ( | Request * | request | ) |

Cancel request and signal its completion.

Parameters

  [in] | request | The request to cancel

This function cancels and completes the request. The same rules as for completeRequest() apply.

## ◆ completeBuffer()

bool libcamera::PipelineHandler::completeBuffer | ( | Request * | request,
|  | FrameBuffer * | buffer )

Complete a buffer for a request.

Parameters

  [in] | request | The request the buffer belongs to
  [in] | buffer | The buffer that has completed

This function shall be called by pipeline handlers to signal completion of the buffer part of the request. It notifies applications of buffer completion and updates the request's internal buffer tracking. The request is not completed automatically when the last buffer completes to give pipeline handlers a chance to perform any operation that may still be needed. They shall complete requests explicitly with completeRequest().

Thread Safety
  This function shall be called from the CameraManager thread.

Returns
  True if all buffers contained in the request have completed, false otherwise

## ◆ completeRequest()

void libcamera::PipelineHandler::completeRequest | ( | Request * | request | ) |

Signal request completion.

Parameters

  [in] | request | The request that has completed

The pipeline handler shall call this function to notify the camera that the request has completed. The request is no longer managed by the pipeline handler and shall not be accessed once this function returns.

This function ensures that requests will be returned to the application in submission order, the pipeline handler may call it on any complete request without any ordering constraint.

Thread Safety
  This function shall be called from the CameraManager thread.

## ◆ configurationFile()

std::string libcamera::PipelineHandler::configurationFile | ( | const std::string & | subdir,
|  | const std::string & | name,
|  | bool | silent = false ) const

Retrieve the absolute path to a platform configuration file.

Parameters

  [in] | subdir | The pipeline handler specific subdirectory name
  [in] | name | The configuration file name
  [in] | silent | Disable error messages

This function locates a named platform configuration file and returns its absolute path to the pipeline handler. It searches the following directories, in order:

- If libcamera is not installed, the src/libcamera/pipeline/<subdir>/data/ directory within the source tree ; otherwise
- The system data (share/libcamera/pipeline/<subdir>) directory.

The system directories are not searched if libcamera is not installed.

Returns
  The full path to the pipeline handler configuration file, or an empty string if no configuration file can be found

## ◆ configure()

virtual int libcamera::PipelineHandler::configure | ( | Camera * | camera,
|  | CameraConfiguration * | config )
| pure virtual

Configure a group of streams for capture.

Parameters

  [in] | camera | The camera to configure
  [in] | config | The camera configurations to setup

Configure the specified group of streams for camera according to the configuration specified in config. The intended caller of this interface is the Camera class which will receive configuration to apply from the application.

The configuration is guaranteed to have been validated with CameraConfiguration::validate(). The pipeline handler implementation shall not perform further validation and may rely on any custom field stored in its custom CameraConfiguration derived class.

When configuring the camera the pipeline handler shall associate a Stream instance to each StreamConfiguration entry in the CameraConfiguration using the StreamConfiguration::setStream() function.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  0 on success or a negative error code otherwise

## ◆ createIPA()

template<typename T>

std::unique_ptr< T > libcamera::PipelineHandler::createIPA | ( | uint32_t | minVersion,
|  | uint32_t | maxVersion )
| inline

Create an IPA proxy that matches this pipeline handler.

Parameters

  [in] | minVersion | Minimum acceptable version of IPA module
  [in] | maxVersion | Maximum acceptable version of IPA module

Returns
  A newly created IPA proxy, or nullptr if no matching IPA module is found or if the IPA proxy fails to initialize

## ◆ exportFrameBuffers()

virtual int libcamera::PipelineHandler::exportFrameBuffers | ( | Camera * | camera,
|  | Stream * | stream,
|  | std::vector< std::unique_ptr< FrameBuffer > > * | buffers )
| pure virtual

Allocate and export buffers for stream.

Parameters

  [in] | camera | The camera
  [in] | stream | The stream to allocate buffers for
  [out] | buffers | Array of buffers successfully allocated

This function allocates buffers for the stream from the devices associated with the stream in the corresponding pipeline handler. Those buffers shall be suitable to be added to a Request for the stream, and shall be mappable to the CPU through their associated dmabufs with mmap().

The function may only be called after the Camera has been configured and before it gets started, or after it gets stopped. It shall be called only for streams that are part of the active camera configuration.

The only intended caller is Camera::exportFrameBuffers().

Thread Safety
  This function is called from the CameraManager thread.

Returns
  The number of allocated buffers on success or a negative error code otherwise

## ◆ generateConfiguration()

virtual std::unique_ptr< CameraConfiguration > libcamera::PipelineHandler::generateConfiguration | ( | Camera * | camera,
|  | Span< const StreamRole > | roles )
| pure virtual

Generate a camera configuration for a specified camera.

Parameters

  [in] | camera | The camera to generate a default configuration for
  [in] | roles | A list of stream roles

Generate a default configuration for the camera for a specified list of stream roles. The caller shall populate the roles with the use-cases it wishes to fetch the default configuration for. The returned configuration can then be examined by the caller to learn about the selected streams and their default parameters.

The intended companion to this is configure() which can be used to change the group of streams parameters.

Thread Safety
  This function may be called from any thread and shall be thread-safe. It shall not modify the state of the camera in the pipeline handler.

Returns
  A valid CameraConfiguration if the requested roles can be satisfied, or a null pointer otherwise.

## ◆ hasPendingRequests()

bool libcamera::PipelineHandler::hasPendingRequests | ( | const Camera * | camera | ) | const

Determine if the camera has any requests pending.

Parameters

  [in] | camera | The camera to check

This function determines if there are any requests queued to the pipeline awaiting processing.

Returns
  True if there are pending requests, or false otherwise

## ◆ hotplugMediaDevice()

void libcamera::PipelineHandler::hotplugMediaDevice | ( | std::shared_ptr< MediaDevice > | media | ) |
| protected

Enable hotplug handling for a media device.

Parameters

  [in] | media | The media device

This function enables hotplug handling, and especially hot-unplug handling, of the media device. It shall be called by pipeline handlers for all the media devices that can be disconnected.

When a media device passed to this function is later unplugged, the pipeline handler gets notified and automatically disconnects all the cameras it has registered without requiring any manual intervention.

## ◆ match()

virtual bool libcamera::PipelineHandler::match | ( | DeviceEnumerator * | enumerator | ) |
| pure virtual

Match media devices and create camera instances.

Parameters

  [in] | enumerator | The enumerator providing all media devices found in the system

This function is the main entry point of the pipeline handler. It is called by the camera manager with the enumerator passed as an argument. It shall acquire from the enumerator all the media devices it needs for a single pipeline, create one or multiple Camera instances and register them with the camera manager.

If all media devices needed by the pipeline handler are found, they must all be acquired by a call to MediaDevice::acquire(). This function shall then create the corresponding Camera instances, store them internally, and return true. Otherwise it shall not acquire any media device (or shall release all the media devices is has acquired by calling MediaDevice::release()) and return false.

If multiple instances of a pipeline are available in the system, the PipelineHandler class will be instantiated once per instance, and its match() function called for every instance. Each call shall acquire media devices for one pipeline instance, until all compatible media devices are exhausted.

If this function returns true, a new instance of the pipeline handler will be created and its match() function called.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  true if media devices have been acquired and camera instances created, or false otherwise

## ◆ name()

const char * libcamera::PipelineHandler::name | ( |  | ) | const
| inline

Retrieve the pipeline handler name.

Thread Safety
  This function shall be thread-safe.

Returns
  The pipeline handler name

## ◆ queueRequest()

void libcamera::PipelineHandler::queueRequest | ( | Request * | request | ) |

Queue a request.

Parameters

  [in] | request | The request to queue

This function queues a capture request to the pipeline handler for processing. The request is first added to the internal list of waiting requests which have to be prepared to make sure they are ready for being queued to the pipeline handler.

The queue of waiting requests is iterated and up to maxQueuedRequestsDevice_ prepared requests are passed to the pipeline handler in the same order they have been queued by calling this function.

If a Request fails during the preparation phase or if the pipeline handler fails in queuing the request to the hardware the request is cancelled.

Keeping track of queued requests ensures automatic completion of all requests when the pipeline handler is stopped with stop(). Request completion shall be signalled by the pipeline handler using the completeRequest() function.

Thread Safety
  This function is called from the CameraManager thread.

## ◆ queueRequestDevice()

virtual int libcamera::PipelineHandler::queueRequestDevice | ( | Camera * | camera,
|  | Request * | request )
| protected pure virtual

Queue a request to the device.

Parameters

  [in] | camera | The camera to queue the request to
  [in] | request | The request to queue

This function queues a capture request to the device for processing. The request contains a set of buffers associated with streams and a set of parameters. The pipeline handler shall program the device to ensure that the parameters will be applied to the frames captured in the buffers provided in the request.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  0 on success or a negative error code otherwise

## ◆ registerCamera()

void libcamera::PipelineHandler::registerCamera | ( | std::shared_ptr< Camera > | camera | ) |
| protected

Register a camera to the camera manager and pipeline handler.

Parameters

  [in] | camera | The camera to be added

This function is called by pipeline handlers to register the cameras they handle with the camera manager.

Thread Safety
  This function shall be called from the CameraManager thread.

## ◆ registerRequest()

void libcamera::PipelineHandler::registerRequest | ( | Request * | request | ) |

Register a request for use by the pipeline handler.

Parameters

  [in] | request | The request to register

This function is called when the request is created, and allows the pipeline handler to perform any one-time initialization it requries for the request.

## ◆ release()

void libcamera::PipelineHandler::release | ( | Camera * | camera | ) |

Release exclusive access to the pipeline handler.

Parameters

  [in] | camera | The camera for which to release data

This function releases access to the pipeline handler previously acquired by a call to acquire(). Every release() call shall match a previous successful acquire() call. Calling this function on a pipeline handler that hasn't been acquired results in undefined behaviour.

Pipeline handlers shall not call this function directly as the Camera class handles access internally.

Thread Safety
  This function is called from the CameraManager thread.

See also
  acquire()

## ◆ releaseDevice()

void libcamera::PipelineHandler::releaseDevice | ( | Camera * | camera | ) |
| protected virtual

Release resources associated with this camera.

Parameters

  [in] | camera | The camera for which to release resources

Pipeline handlers may override this in order to perform cleanup operations when a camera is released, such as freeing memory.

This is called once for every camera that is released. If there are resources shared by multiple cameras then the pipeline handler must take care to not release them until releaseDevice() has been called for all previously acquired cameras.

Thread Safety
  This function is called from the CameraManager thread.

See also
  acquireDevice()

## ◆ start()

virtual int libcamera::PipelineHandler::start | ( | Camera * | camera,
|  | const ControlList * | controls )
| pure virtual

Start capturing from a group of streams.

Parameters

  [in] | camera | The camera to start
  [in] | controls | Controls to be applied before starting the Camera

Start the group of streams that have been configured for capture by configure(). 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.

Thread Safety
  This function is called from the CameraManager thread.

Returns
  0 on success or a negative error code otherwise

## ◆ stop()

void libcamera::PipelineHandler::stop | ( | Camera * | camera | ) |

Stop capturing from all running streams and cancel pending requests.

Parameters

  [in] | camera | The camera to stop

This function stops capturing and processing requests immediately. All pending requests are cancelled and complete immediately in an error state.

Thread Safety
  This function is called from the CameraManager thread.

## ◆ stopDevice()

virtual void libcamera::PipelineHandler::stopDevice | ( | Camera * | camera | ) |
| protected pure virtual

Stop capturing from all running streams.

Parameters

  [in] | camera | The camera to stop

This function stops capturing and processing requests immediately. All pending requests are cancelled and complete immediately in an error state.

## ◆ useCount()

unsigned int libcamera::PipelineHandler::useCount | ( |  | ) | const
| inline protected

Retrieve the pipeline handler's used camera count.

Returns
  The number of acquired cameras of the pipeline handler

## Member Data Documentation

## ◆ manager_

CameraManager* libcamera::PipelineHandler::manager_
| protected

The Camera manager associated with the pipeline handler.

The camera manager pointer is stored in the pipeline handler for the convenience of pipeline handler implementations. It remains valid and constant for the whole lifetime of the pipeline handler.

## ◆ maxQueuedRequestsDevice_

const unsigned int libcamera::PipelineHandler::maxQueuedRequestsDevice_
| protected

The maximum number of requests the pipeline handler shall queue to the device.

maxQueuedRequestsDevice_ limits the number of request that the pipeline handler shall queue to the underlying hardware, in order to saturate the pipeline with requests. The application may choose to queue as many requests as it desires, however only maxQueuedRequestsDevice_ requests will be queued to the hardware at a given point in time. The remaining requests will be kept waiting in the internal waiting queue, to be queued at a later stage.

The documentation for this class was generated from the following files:

- include/libcamera/internal/pipeline_handler.h
- src/libcamera/pipeline_handler.cpp