libcamera::IPAInterface Class Referenceabstract

C++ Interface for IPA implementation. More...

Inheritance diagram for libcamera::IPAInterface:

## Public Member Functions

virtual int | init (const IPASettings &settings)=0
| Initialise the IPAInterface. More...
virtual int | start ()=0
| Start the IPA. More...
virtual void | stop ()=0
| Stop the IPA. More...
virtual void | configure (const CameraSensorInfo &sensorInfo, const std::map< unsigned int, IPAStream > &streamConfig, const std::map< unsigned int, const ControlInfoMap & > &entityControls)=0
| Configure the IPA stream and sensor settings. More...
virtual void | mapBuffers (const std::vector< IPABuffer > &buffers)=0
| Map buffers shared between the pipeline handler and the IPA. More...
virtual void | unmapBuffers (const std::vector< unsigned int > &ids)=0
| Unmap buffers shared by the pipeline to the IPA. More...
virtual void | processEvent (const IPAOperationData &data)=0
| Process an event from the pipeline handler. More...

## Public Attributes

Signal< unsigned int, const IPAOperationData & > | queueFrameAction
| Queue an action associated with a frame to the pipeline handler. More...

## Detailed Description

C++ Interface for IPA implementation.

This pure virtual class defines a C++ API corresponding to the ipa_context, ipa_context_ops and ipa_callback_ops API. It is used by pipeline handlers to interact with IPA modules, and may be used internally in IPA modules if desired to benefit from the data and helper classes provided by libcamera.

Functions defined in the ipa_context_ops structure are mapped to IPAInterface methods, while functions defined in the ipa_callback_ops are mapped to IPAInterface signals. As with the C API, the IPA C++ interface uses serializable data types only. It reuses structures defined by the C API, or defines corresponding classes using C++ containers when required.

Due to process isolation all arguments to the IPAInterface methods and signals may need to be transferred over IPC. The class thus uses serializable data types only. The IPA C++ interface defines custom data structures that mirror core libcamera structures when the latter are not suitable, such as IPAStream to carry StreamConfiguration data.

As for the functions defined in struct ipa_context_ops, the methods defined by this class shall not return data from the IPA.

The pipeline handler shall use the IPAManager to locate a compatible IPAInterface. The interface may then be used to interact with the IPA module.

## Member Function Documentation

## configure()

libcamera::IPAInterface::configure | ( | const CameraSensorInfo & | sensorInfo,
|  | const std::map< unsigned int, IPAStream > & | streamConfig,
|  | const std::map< unsigned int, const ControlInfoMap & > & | entityControls
| ) |  |

pure virtual

Configure the IPA stream and sensor settings.

Parameters

  [in] | sensorInfo | Camera sensor information
  [in] | streamConfig | Configuration of all active streams
  [in] | entityControls | Controls provided by the pipeline entities

This method shall be called when the camera is started to inform the IPA of the camera's streams and the sensor settings. The meaning of the numerical keys in the streamConfig and entityControls maps is defined by the IPA protocol.

The sensorInfo conveys information about the camera sensor settings that the pipeline handler has selected for the configuration. The IPA may use that information to tune its algorithms.

Implemented in libcamera::IPAContextWrapper.

## init()

libcamera::IPAInterface::init | ( | const IPASettings & | settings | ) |

pure virtual

Initialise the IPAInterface.

Parameters

  [in] | settings | The IPA initialization settings

This function initializes the IPA interface. It shall be called before any other function of the IPAInterface. The settings carry initialization parameters that are valid for the whole life time of the IPA interface.

Implemented in libcamera::IPAContextWrapper.

## mapBuffers()

libcamera::IPAInterface::mapBuffers | ( | const std::vector< IPABuffer > & | buffers | ) |

pure virtual

Map buffers shared between the pipeline handler and the IPA.

Parameters

  [in] | buffers | List of buffers to map

This method informs the IPA module of memory buffers set up by the pipeline handler that the IPA needs to access. It provides dmabuf file handles for each buffer, and associates the buffers with unique numerical IDs.

IPAs shall map the dmabuf file handles to their address space and keep a cache of the mappings, indexed by the buffer numerical IDs. The IDs are used in all other IPA interface methods to refer to buffers, including the unmapBuffers() method.

All buffers that the pipeline handler wishes to share with an IPA shall be mapped with this method. Buffers may be mapped all at once with a single call, or mapped and unmapped dynamically at runtime, depending on the IPA protocol. Regardless of the protocol, all buffers mapped at a given time shall have unique numerical IDs.

The numerical IDs have no meaning defined by the IPA interface, and IPA protocols shall not give them any specific meaning either. They should be treated as opaque handles by IPAs, with the only exception that ID zero is invalid.

See also
  unmapBuffers()

Todo:
  Provide a generic implementation of mapBuffers and unmapBuffers for IPAs

Implemented in libcamera::IPAContextWrapper.

## processEvent()

libcamera::IPAInterface::processEvent | ( | const IPAOperationData & | data | ) |

pure virtual

Process an event from the pipeline handler.

Parameters

  [in] | data | IPA operation data

This operation is used by pipeline handlers to inform the IPA module of events that occurred during the on-going capture operation.

The event notified by the pipeline handler with this method is handled by the IPA, which interprets the operation parameters according to the separately documented IPA protocol.

Implemented in libcamera::IPAContextWrapper.

## start()

libcamera::IPAInterface::start | ( |  | ) |

pure virtual

Start the IPA.

This method informs the IPA module that the camera is about to be started. The IPA module shall prepare any resources it needs to operate.

Returns
  0 on success or a negative error code otherwise

Implemented in libcamera::IPAContextWrapper.

## stop()

libcamera::IPAInterface::stop | ( |  | ) |

pure virtual

Stop the IPA.

This method informs the IPA module that the camera is stopped. The IPA module shall release resources prepared in start().

Implemented in libcamera::IPAContextWrapper.

## unmapBuffers()

libcamera::IPAInterface::unmapBuffers | ( | const std::vector< unsigned int > & | ids | ) |

pure virtual

Unmap buffers shared by the pipeline to the IPA.

Parameters

  [in] | ids | List of buffer IDs to unmap

This method removes mappings set up with mapBuffers(). Buffers may be unmapped all at once with a single call, or selectively at runtime, depending on the IPA protocol. Numerical IDs of unmapped buffers may be reused when mapping new buffers.

See also
  mapBuffers()

Implemented in libcamera::IPAContextWrapper.

## Member Data Documentation

## queueFrameAction

libcamera::IPAInterface::queueFrameAction

Queue an action associated with a frame to the pipeline handler.

Parameters

  [in] | frame | The frame number for the action
  [in] | data | IPA operation data

This signal is emitted when the IPA wishes to queue a FrameAction on the pipeline. The pipeline is still responsible for the scheduling of the action on its timeline.

This signal is emitted by the IPA to queue an action to be executed by the pipeline handler on a frame. The type of action is identified by the data.operation field, as defined by the IPA protocol, and the rest of the data is interpreted accordingly. The pipeline handler shall queue the action and execute it as appropriate.

The signal is only emitted when the IPA is running, that is after start() and before stop() have been called.

The documentation for this class was generated from the following files:

- include/libcamera/ipa/ipa_interface.h
- src/libcamera/ipa_interface.cpp