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_context * | 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 standard plain C interface.

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

struct ipa_context *ipaCreate();
ipaCreate
struct ipa_context * ipaCreate()
Entry point to the IPA modules.
ipa_context
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