libcamera: libcamera::ipa::FCQueue< FrameContext > Class Template Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ipa::FCQueue< FrameContext > Class Template Reference

A support class for managing FrameContext instances in IPA modules. More...

## Public Member Functions
| FCQueue (unsigned int size)
| Construct a frame contexts queue of a specified size.
void | clear ()
| Clear the contexts queue.
FrameContext & | alloc (const uint32_t frame)
| Allocate and return a FrameContext for the frame.
FrameContext & | get (uint32_t frame)
| Obtain the FrameContext for the frame.

## Detailed Description

template<typename FrameContext>
class libcamera::ipa::FCQueue< FrameContext >

A support class for managing FrameContext instances in IPA modules.

Template Parameters

  FrameContext | The IPA module-specific FrameContext derived class type

Along with the Module and Algorithm classes, the frame context queue is a core component of the libipa infrastructure. It stores per-frame contexts used by the Algorithm operations. By centralizing the lifetime management of the contexts and implementing safeguards against underflows and overflows, it simplifies IPA modules and improves their reliability.

The queue references frame contexts by a monotonically increasing sequence number. The FCQueue design assumes that this number matches both the sequence number of the corresponding frame, as generated by the camera sensor, and the sequence number of the request. This allows IPA modules to obtain the frame context from any location where a request or a frame is available.

A frame context normally begins its lifetime when the corresponding request is queued, way before the frame is captured by the camera sensor. IPA modules allocate the context from the queue at that point, calling alloc() using the request number. The queue initializes the context, and the IPA module then populates it with data from the request. The context can be later retrieved with a call to get(), typically when the IPA module is requested to provide sensor or ISP parameters or receives statistics for a frame. The frame number is used at that point to identify the context.

If an application fails to queue requests to the camera fast enough, frames may be produced by the camera sensor and processed by the IPA module without a corresponding request having been queued to the IPA module. This creates an underrun condition, where the IPA module will try to get a frame context that hasn't been allocated. In this case, the get() function will allocate and initialize a context for the frame, and log a message. Algorithms will not apply the controls associated with the late request, but should otherwise behave correctly.

Todo
  Mark the frame context with a per-frame control error flag in case of underrun, and research how algorithms should handle this.

At its core, the queue uses a circular buffer to avoid dynamic memory allocation at runtime. The buffer is pre-allocated with a maximum number of entries when the FCQueue instance is constructed. Entries are initialized on first use by alloc() or, in underrun conditions, get(). The queue is not allowed to overflow, which must be ensured by pipeline handlers never queuing more in-flight requests to the IPA module than the queue size. If an overflow condition is detected, the queue will log a fatal error.

IPA module-specific frame context implementations shall inherit from the FrameContext base class to support the minimum required features for a FrameContext.

## Constructor & Destructor Documentation

## ◆ FCQueue()

template<typename FrameContext>

libcamera::ipa::FCQueue< FrameContext >::FCQueue | ( | unsigned int | size | ) |
| inline

Construct a frame contexts queue of a specified size.

Parameters

  [in] | size | The number of contexts in the queue

## Member Function Documentation

## ◆ alloc()

template<typename FrameContext>

FrameContext & libcamera::ipa::FCQueue< FrameContext >::alloc | ( | const uint32_t | frame | ) |
| inline

Allocate and return a FrameContext for the frame.

Parameters

  [in] | frame | The frame context sequence number

The first call to obtain a FrameContext from the FCQueue should be handled through this function. The FrameContext will be initialised, if not initialised already, and returned to the caller.

If the FrameContext was already initialized for this frame, a warning will be reported and the previously initialized FrameContext is returned.

Frame contexts are expected to be initialised when a Request is first passed to the IPA module in IPAModule::queueRequest().

Returns
  A reference to the FrameContext for sequence frame

## ◆ clear()

template<typename FrameContext>

void libcamera::ipa::FCQueue< FrameContext >::clear | ( |  | ) |
| inline

Clear the contexts queue.

IPA modules must clear the frame context queue at the beginning of a new streaming session, in IPAModule::start().

Todo
  Fix any issue this may cause with requests queued before the camera is started.

## ◆ get()

template<typename FrameContext>

FrameContext & libcamera::ipa::FCQueue< FrameContext >::get | ( | uint32_t | frame | ) |
| inline

Obtain the FrameContext for the frame.

Parameters

  [in] | frame | The frame context sequence number

If the FrameContext is not correctly initialised for the frame, it will be initialised.

Returns
  A reference to the FrameContext for sequence frame

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

- src/ipa/libipa/fc_queue.h
- src/ipa/libipa/fc_queue.cpp