ipa: rkisp1: Document the active state and frame context

Now that data used by algorithms has been partitioned between the active
state and frame context, we have a better view of the role of each of
those structures. Document them appropriately.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>

src/ipa/rkisp1/ipa_context.cpp

@@ -88,16 +88,28 @@ namespace libcamera::ipa::rkisp1 {
  * \struct IPAActiveState
  * \brief Active state for algorithms
  *
- * The active state stores algorithm-specific data that needs to be shared
+ * The active state contains all algorithm-specific data that needs to be
- * between multiple algorithms and the IPA module. It is accessible through the
+ * maintained by algorithms across frames. Unlike the session configuration,
- * IPAContext structure.
+ * the active state is mutable and constantly updated by algorithms. The active
+ * state is accessible through the IPAContext structure.
  *
- * \todo Split the data contained in this structure between the active state
+ * The active state stores two distinct categories of information:
- * and the frame contexts.
  *
- * Each of the fields in the active state belongs to either a specific
+ *  - The consolidated value of all algorithm controls. Requests passed to
- * algorithm, or to the top-level IPA module. A field may be read by any
+ *    the queueRequest() function store values for controls that the
- * algorithm, but should only be written by its owner.
+ *    application wants to modify for that particular frame, and the
+ *    queueRequest() function updates the active state with those values.
+ *    The active state thus contains a consolidated view of the value of all
+ *    controls handled by the algorithm.
+ *
+ *  - The value of parameters computed by the algorithm when running in auto
+ *    mode. Algorithms running in auto mode compute new parameters every
+ *    time statistics buffers are received (either synchronously, or
+ *    possibly in a background thread). The latest computed value of those
+ *    parameters is stored in the active state in the process() function.
+ *
+ * Each of the members in the active state belongs to a specific algorithm. A
+ * member may be read by any algorithm, but shall only be written by its owner.
  */
 
 /**
@@ -185,7 +197,32 @@ namespace libcamera::ipa::rkisp1 {
  * \struct IPAFrameContext
  * \brief Per-frame context for algorithms
  *
- * \todo Populate the frame context for all algorithms
+ * The frame context stores two distinct categories of information:
+ *
+ * - The value of the controls to be applied to the frame. These values are
+ *   typically set in the queueRequest() function, from the consolidated
+ *   control values stored in the active state. The frame context thus stores
+ *   values for all controls related to the algorithm, not limited to the
+ *   controls specified in the corresponding request, but consolidated from all
+ *   requests that have been queued so far.
+ *
+ *   For controls that can be set manually or computed by an algorithm
+ *   (depending on the algorithm operation mode), such as for instance the
+ *   colour gains for the AWB algorithm, the control value will be stored in
+ *   the frame context in the queueRequest() function only when operating in
+ *   manual mode. When operating in auto mode, the values are computed by the
+ *   algorithm in process(), stored in the active state, and copied to the
+ *   frame context in prepare(), just before being stored in the ISP parameters
+ *   buffer.
+ *
+ *   The queueRequest() function can also store ancillary data in the frame
+ *   context, such as flags to indicate if (and what) control values have
+ *   changed compared to the previous request.
+ *
+ * - Status information computed by the algorithm for a frame. For instance,
+ *   the colour temperature estimated by the AWB algorithm from ISP statistics
+ *   calculated on a frame is stored in the frame context for that frame in
+ *   the process() function.
  */
 
 /**