libcamera: include/libcamera/ipa/ipa_interface.h File Reference

libcamera v0.7.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
ipa_interface.h File Reference

Image Processing Algorithm interface. More...

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
namespace | libcamera
| Top-level libcamera namespace.

## Functions
libcamera::IPAInterface * | libcamera::ipaCreate ()
| Create an instance of the IPA interface.

## 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.