ipa_interface.h File Reference

Image Processing Algorithm interface. More...

#include <stddef.h>
#include <stdint.h>
#include <map>
#include <vector>
#include <libcamera/base/flags.h>
#include <libcamera/base/signal.h>
#include <libcamera/controls.h>
#include <libcamera/framebuffer.h>
#include <libcamera/geometry.h>

Include dependency graph for ipa_interface.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	libcamera::IPAInterface
	C++ Interface for IPA implementation. More...

Namespaces
	libcamera
	Top-level libcamera namespace.

Functions
libcamera::IPAInterface *	ipaCreate ()
	Entry point to the IPA modules. More...

Detailed Description

Image Processing Algorithm interface.

Every pipeline handler in libcamera may attach some or all of its cameras to an Image Processing Algorithm (IPA) module. An IPA module is developed for a specific pipeline handler and each pipeline handler may be compatible with multiple IPA implementations, both open and closed source. To support this, libcamera communicates with IPA modules through a per-pipeline C++ interface.

IPA modules shall provide an ipaCreate() function exported as a public C symbol with the following prototype:

IPAInterface *ipaCreate();

The ipaCreate() function creates an instance of an IPA interface, which models a context of execution for the IPA. IPA modules shall support creating one context per camera, as required by their associated pipeline handler.

The IPA module interface operations are defined in the mojom file corresponding to the pipeline handler, in include/libcamera/ipa/{pipeline_name}.mojom.

The IPA interface is specific to each pipeline handler. The pipeline handlers define a set of operations used to communicate with their IPA modules. The operations, along with the data structures they use, are collectively referred to as the IPA protocol.

The IPA protocol is defined using the Mojo interface definition language, in a Mojo module file stored in include/libcamera/ipa/{pipeline_name}.mojom. The Mojo module contains two Mojo interfaces: IPAInterface defines the operations exposed by the IPA and called by the pipeline handler, and IPAEventInterface defines the events generated by the IPA and received by the pipeline handler.

Todo:

Add reference to how pipelines shall document their protocol.

IPAs can be isolated in a separate process. This implies that arguments to the IPA interface functions may need to be transferred over IPC. An IPA proxy is auto-generated based on the mojom file, which abstracts away the (de)serialization from the pipeline handler and the IPA implementation. Thus any C++ structure that is defined in the mojom file, or the C++ libcamera objects that are listed in core.mojom, can be used directly.

Due to IPC, synchronous communication between pipeline handlers and IPAs can be costly. For that reason, functions that cannot afford the high cost should be marked as [async] in the mojom file, and they will operate asynchronously. This implies that these functions don't return a status, and that all functions may copy their arguments. Synchronous functions are still allowed, but should be used with caution.

Function Documentation

ipaCreate()

ipaCreate

(

)

Entry point to the IPA modules.

This function is the entry point to the IPA modules. It is implemented by every IPA module, and called by libcamera to create a new IPA interface instance.

Returns

A newly created IPA interface instance

Entry point to the IPA modules.

This function is the entry point of the IPA module. It is called by the IPA manager to create an instance of the IPA interface for each camera. When matched against with a pipeline handler, the IPAManager will construct an IPA instance for each associated Camera.