From patchwork Mon Sep 14 14:02:47 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Klug X-Patchwork-Id: 28278 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 02825C3354 for ; Mon, 14 Sep 2026 14:05:00 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id A493A6870C; Mon, 14 Sep 2026 16:05:00 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="FsJUET+a"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4F6EF6870A for ; Mon, 14 Sep 2026 16:04:56 +0200 (CEST) Received: from ideasonboard.com (unknown [IPv6:2a00:6020:448c:6c00:a279:75fa:1f6c:7f40]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 534999A4; Mon, 14 Sep 2026 16:03:16 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1789394596; bh=Q9pFjEBzqrZG6vMEJRlIZErNKzUJ8ocd3965jLakZ34=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FsJUET+a+xjqF+LQWH6Q0Icl0xw2YeZUkEMocY+vJ0x9MvC6Q8/wYnt5HXkMghM2A pTQBT3jnti4f2nMty6pZuh1hD+9Uk9DYT0Np3G0zLfXNkZkrIxVz1yx8QsrvPh2rq5 RXFLS2a9Fcy90iy5GAsdEKeOkN1VEGnxbOuAJ7uo= From: Stefan Klug To: libcamera-devel@lists.libcamera.org Cc: Stefan Klug Subject: [PATCH v3 34/41] libipa: algorithm: Update documentation Date: Mon, 14 Sep 2026 16:02:47 +0200 Message-ID: <20260914140309.3354666-35-stefan.klug@ideasonboard.com> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260914140309.3354666-1-stefan.klug@ideasonboard.com> References: <20260914140309.3354666-1-stefan.klug@ideasonboard.com> MIME-Version: 1.0 X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Update the algorithm documentation to reflect the changed timing model. Signed-off-by: Stefan Klug --- 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(-) diff --git a/src/ipa/libipa/algorithm.cpp b/src/ipa/libipa/algorithm.cpp index 757ce3519652..e1869dc1fe78 100644 --- a/src/ipa/libipa/algorithm.cpp +++ b/src/ipa/libipa/algorithm.cpp @@ -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. */ /**