libcamera
v0.0.0
Supporting cameras in Linux since 2019
|
Create and manage cameras based on a set of media devices. More...
Public Member Functions | |
PipelineHandler (CameraManager *manager) | |
Construct a PipelineHandler instance. More... | |
virtual bool | match (DeviceEnumerator *enumerator)=0 |
Match media devices and create camera instances. More... | |
MediaDevice * | acquireMediaDevice (DeviceEnumerator *enumerator, const DeviceMatch &dm) |
Search and acquire a MediaDevice matching a device pattern. More... | |
bool | lock () |
Lock all media devices acquired by the pipeline. More... | |
void | unlock () |
Unlock all media devices acquired by the pipeline. More... | |
const ControlInfoMap & | controls (Camera *camera) |
Retrieve the list of controls for a camera. More... | |
const ControlList & | properties (Camera *camera) |
Retrieve the list of properties for a camera. More... | |
virtual CameraConfiguration * | generateConfiguration (Camera *camera, const StreamRoles &roles)=0 |
Generate a camera configuration for a specified camera. More... | |
virtual int | configure (Camera *camera, CameraConfiguration *config)=0 |
Configure a group of streams for capture. More... | |
virtual int | exportFrameBuffers (Camera *camera, Stream *stream, std::vector< std::unique_ptr< FrameBuffer >> *buffers)=0 |
Allocate and export buffers for stream. More... | |
virtual int | start (Camera *camera)=0 |
Start capturing from a group of streams. More... | |
virtual void | stop (Camera *camera)=0 |
Stop capturing from all running streams. More... | |
int | queueRequest (Camera *camera, Request *request) |
Queue a request to the camera. More... | |
bool | completeBuffer (Camera *camera, Request *request, FrameBuffer *buffer) |
Complete a buffer for a request. More... | |
void | completeRequest (Camera *camera, Request *request) |
Signal request completion. More... | |
const char * | name () const |
Retrieve the pipeline handler name. More... | |
![]() | |
Object (Object *parent=nullptr) | |
Construct an Object instance. More... | |
virtual | ~Object () |
Destroy an Object instance. More... | |
void | postMessage (std::unique_ptr< Message > msg) |
Post a message to the object's thread. More... | |
template<typename T , typename R , typename... FuncArgs, typename... Args, typename 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. More... | |
Thread * | thread () const |
Retrieve the thread the object is bound to. More... | |
void | moveToThread (Thread *thread) |
Move the object and all its children to a different thread. More... | |
Object * | parent () const |
Retrieve the object's parent. More... | |
Protected Member Functions | |
void | registerCamera (std::shared_ptr< Camera > camera, std::unique_ptr< CameraData > data) |
Register a camera to the camera manager and pipeline handler. More... | |
void | hotplugMediaDevice (MediaDevice *media) |
Enable hotplug handling for a media device. More... | |
virtual int | queueRequestDevice (Camera *camera, Request *request)=0 |
Queue a request to the device. More... | |
CameraData * | cameraData (const Camera *camera) |
Retrieve the pipeline-specific data associated with a Camera. More... | |
![]() | |
virtual void | message (Message *msg) |
Message handler for the object. More... | |
Protected Attributes | |
CameraManager * | manager_ |
The Camera manager associated with the pipeline handler. More... | |
Friends | |
class | PipelineHandlerFactory |
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.
libcamera::PipelineHandler::PipelineHandler | ( | CameraManager * | manager | ) |
Construct a PipelineHandler instance.
[in] | manager | The camera manager |
In order to honour the std::enable_shared_from_this<> contract, PipelineHandler instances shall never be constructed manually, but always through the PipelineHandlerFactory::create() method implemented by the respective factories.
MediaDevice * libcamera::PipelineHandler::acquireMediaDevice | ( | DeviceEnumerator * | enumerator, |
const DeviceMatch & | dm | ||
) |
Search and acquire a MediaDevice matching a device pattern.
[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.
|
protected |
Retrieve the pipeline-specific data associated with a Camera.
[in] | camera | The camera whose data to retrieve |
bool libcamera::PipelineHandler::completeBuffer | ( | Camera * | camera, |
Request * | request, | ||
FrameBuffer * | buffer | ||
) |
Complete a buffer for a request.
[in] | camera | The camera the request belongs to |
[in] | request | The request the buffer belongs to |
[in] | buffer | The buffer that has completed |
This method 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().
Signal request completion.
[in] | camera | The camera that the request belongs to |
[in] | request | The request that has completed |
The pipeline handler shall call this method to notify the camera that the request has completed. The request is deleted and shall not be accessed once this method returns.
This method 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.
|
pure virtual |
Configure a group of streams for capture.
[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::valid(). 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() method.
const ControlInfoMap & libcamera::PipelineHandler::controls | ( | Camera * | camera | ) |
Retrieve the list of controls for a camera.
[in] | camera | The camera |
|
pure virtual |
Allocate and export buffers for stream.
[in] | camera | The camera |
[in] | stream | The stream to allocate buffers for |
[out] | buffers | Array of buffers successfully allocated |
This method 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 method 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().
|
pure virtual |
Generate a camera configuration for a specified camera.
[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.
|
protected |
Enable hotplug handling for a media device.
[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.
bool libcamera::PipelineHandler::lock | ( | ) |
Lock all media devices acquired by the pipeline.
This method shall not be called from pipeline handler implementation, as the Camera class handles locking directly.
|
pure virtual |
Match media devices and create camera instances.
[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.
|
inline |
Retrieve the pipeline handler name.
const ControlList & libcamera::PipelineHandler::properties | ( | Camera * | camera | ) |
Retrieve the list of properties for a camera.
[in] | camera | The camera |
Queue a request to the camera.
[in] | camera | The camera to queue the request to |
[in] | request | The request to queue |
This method queues a capture request to the pipeline handler for processing. The request is first added to the internal list of queued requests, and then passed to the pipeline handler with a call to queueRequestDevice().
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() method.
|
protectedpure virtual |
Queue a request to the device.
[in] | camera | The camera to queue the request to |
[in] | request | The request to queue |
This method 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.
|
protected |
Register a camera to the camera manager and pipeline handler.
[in] | camera | The camera to be added |
[in] | data | Pipeline-specific data for the camera |
This method is called by pipeline handlers to register the cameras they handle with the camera manager. It associates the pipeline-specific data with the camera, for later retrieval with cameraData(). Ownership of data is transferred to the PipelineHandler.
|
pure virtual |
Start capturing from a group of streams.
[in] | camera | The camera to start |
Start the group of streams that have been configured for capture by configure(). The intended caller of this method 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.
|
pure virtual |
Stop capturing from all running streams.
[in] | camera | The camera to stop |
This method stops capturing and processing requests immediately. All pending requests are cancelled and complete immediately in an error state.
void libcamera::PipelineHandler::unlock | ( | ) |
Unlock all media devices acquired by the pipeline.
This method shall not be called from pipeline handler implementation, as the Camera class handles locking directly.
|
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.