libcamera  v0.0.0
Supporting cameras in Linux since 2019
Classes | Functions
ipa_interface.h File Reference

Image Processing Algorithm interface. More...

#include <stddef.h>
#include <stdint.h>
#include <map>
#include <vector>
#include <libcamera/buffer.h>
#include <libcamera/controls.h>
#include <libcamera/geometry.h>
#include <libcamera/signal.h>

Go to the source code of this file.

Classes

struct  ipa_context
 IPA module context of execution. More...
 
struct  ipa_settings
 IPA initialization settings for the IPA context operations. More...
 
struct  ipa_sensor_info
 Camera sensor information for the IPA context operations. More...
 
struct  ipa_stream
 Stream information for the IPA context operations. More...
 
struct  ipa_control_info_map
 ControlInfoMap description for the IPA context operations. More...
 
struct  ipa_buffer_plane
 A plane for an ipa_buffer. More...
 
struct  ipa_buffer
 Buffer information for the IPA context operations. More...
 
struct  ipa_control_list
 ControlList description for the IPA context operations. More...
 
struct  ipa_operation_data
 IPA operation data for the IPA context operations. More...
 
struct  ipa_callback_ops
 IPA context operations as a set of function pointers. More...
 
struct  ipa_context_ops
 IPA context operations as a set of function pointers. More...
 
struct  libcamera::IPASettings
 IPA interface initialization settings. More...
 
struct  libcamera::IPAStream
 Stream configuration for the IPA interface. More...
 
struct  libcamera::IPABuffer
 Buffer information for the IPA interface. More...
 
struct  libcamera::IPAOperationData
 Parameters for IPA operations. More...
 
class  libcamera::IPAInterface
 C++ Interface for IPA implementation. More...
 

Functions

struct ipa_contextipaCreate ()
 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 standard plain C interface.

IPA modules shall expose a public function named ipaCreate() with the following prototype.

struct ipa_context * ipaCreate()
Entry point to the IPA modules.
IPA module context of execution.
Definition: ipa_interface.h:17

The ipaCreate() function creates an instance of an IPA context, 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 context operations are defined in the struct ipa_context_ops. They model a low-level interface to configure the IPA, notify it of events, and receive IPA actions through callbacks. An IPA module stores a pointer to the operations corresponding to its context in the ipa_context::ops field. That pointer is immutable for the lifetime of the context, and may differ between different contexts created by the same IPA module.

The IPA interface defines base data types and functions to exchange data. On top of this, each pipeline handler is responsible for defining the set of events and actions used to communicate with their IPA. These are collectively referred to as IPA operations and define the pipeline handler-specific IPA protocol. Each operation defines the data that it carries, and how that data is encoded in the ipa_context_ops functions arguments.

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. All arguments use Plain Old Data types and are documented either in the form of C data types, or as a textual description of byte arrays for types that can't be expressed using C data types (such as arrays of mixed data types). IPA modules can thus use the C API without calling into libcamera to access the data passed to the IPA context operations.

Due to IPC, synchronous communication between pipeline handlers and IPAs can be costly. For that reason, the interface operates asynchronously. This implies that methods don't return a status, and that all methods may copy their arguments.

The IPAInterface class is a C++ representation of the ipa_context_ops, using C++ data classes provided by libcamera. This is the API exposed to pipeline handlers to communicate with IPA modules. IPA modules may use the IPAInterface API internally if they want to benefit from the data and helper classes offered by libcamera.

When an IPA module is loaded directly into the libcamera process and uses the IPAInterface API internally, short-circuiting the path to the ipa_context_ops and back to IPAInterface is desirable. To support this, IPA modules may implement the ipa_context_ops::get_interface function to return a pointer to their internal IPAInterface.

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

Returns
A newly created IPA context