@@ -76,11 +76,20 @@ namespace ipa {
*
* This function is called for each request queued to the camera. It provides
* the controls stored in the request to the algorithm. The \a frame number
- * is the Request sequence number and identifies the desired corresponding
+ * is the sensor sequence number and identifies the desired corresponding
* frame to target for the controls to take effect.
*
* Algorithms shall read the applicable controls and store their value for later
* use during frame processing.
+ *
+ * Care shall be taken to ensure that all values in \a frameContext that get
+ * accessed from within process() are initialized. Examples for this are
+ * exposure and gain. These should be initialized even if they
+ * get updated again in prepare().
+ * There are two reasons for this. In RAW mode prepare() is not called at all.
+ * The other case is when a resynchronization happens. In that case it is not
+ * guaranteed that prepare() is called for every frame but process() should
+ * still be able to update the active state.
*/
/**
@@ -92,20 +101,29 @@ namespace ipa {
* \param[out] params The ISP specific parameters
*
* This function is called for every frame when the camera is running before it
- * is processed by the ISP to prepare the ISP processing parameters for that
- * frame.
+ * is processed by the ISP to prepare the ISP processing parameters and the
+ * sensor parameters for that frame.
*
* Algorithms shall fill in the parameter structure fields appropriately to
* configure the ISP processing blocks that they are responsible for. This
* includes setting fields and flags that enable those processing blocks.
+ *
+ * Additionally \a frameContext shall be updated with the most up to date values
+ * necessary to configure the sensor. After prepare() the \a frameContext for
+ * this frame shall be treated read only.
+ *
+ * \todo: For offline ISPs there might be use cases where it is beneficial to
+ * separate the calculation of sensor parameters from the calculation of ISP
+ * paremeters. This is currently not supported.
*/
/**
* \fn Algorithm::process()
* \brief Process ISP statistics, and run algorithm operations
* \param[in] context The shared IPA context
- * \param[in] frame The frame context sequence number
- * \param[in] frameContext The current frame's context
+ * \param[in] frame The frame sequence number that produces the stats
+ * \param[in] frameContext The frame context for the frame that produced the
+ * stats
* \param[in] stats The IPA statistics and ISP results
* \param[out] metadata Metadata for the frame, to be filled by the algorithm
*
@@ -118,19 +136,17 @@ namespace ipa {
* computationally expensive calculations or operations must be handled
* asynchronously in a separate thread.
*
- * Algorithms can store state in their respective IPAFrameContext structures,
- * and reference state from the IPAFrameContext of other algorithms.
- *
- * \todo Historical data may be required as part of the processing.
- * Either the previous frame, or the IPAFrameContext state of the frame
- * that generated the statistics for this operation may be required for
- * some advanced algorithms to prevent oscillations or support control
- * loops correctly. Only a single IPAFrameContext is available currently,
- * and so any data stored may represent the results of the previously
- * completed operations.
+ * Care must be taken to ensure that the frameContext is only updated in cases
+ * where the frame was not processed yet. This usually differs between offline
+ * and inline ISPs. In an inline ISP the stats are received after processing the
+ * frame. In this case the frame context *must not* be updated. Algorithms
+ * typically update the active state which is then picked up in prepare().
*
* Care shall be taken to ensure the ordering of access to the information
* such that the algorithms use up to date state as required.
+ *
+ * The \a stats parameter can be null in which case only the frame metadata
+ * shall be filled with the data from frameContext.
*/
/**
Update the algorithm documentation to reflect the changed timing model. Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> --- Changes in v3: - Be more specific on the requirements on prepare() Changes in v2: - Added more documentation --- src/ipa/libipa/algorithm.cpp | 46 ++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 15 deletions(-)