From patchwork Wed Mar 25 15:13:50 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Klug X-Patchwork-Id: 26360 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 20BCCC3302 for ; Wed, 25 Mar 2026 15:15:34 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 9B0C962C3D; Wed, 25 Mar 2026 16:15:33 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="BBL8VjlX"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id A776F6274D for ; Wed, 25 Mar 2026 16:15:31 +0100 (CET) Received: from ideasonboard.com (unknown [IPv6:2a00:6020:448c:6c00:b16a:5ed9:4ada:a95a]) by perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id B0A901943; Wed, 25 Mar 2026 16:14:13 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1774451653; bh=EFewKCAt/7JAXms7yDaFl2tWUeG+Y0w4vVz6NT4aA/A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BBL8VjlX4prXE/fovZXaBsjasQ5dAc3cLXxHFW9twH6NxvdVg9umPPJCY/Rnsn48Y hrpP7CwfXNmSf711na/4v7uZCHDEp5yt9dPfU6c7NQEDTS96G6I6s8uLzmBjJYxS7O 3u/ga9VpvSB/xNhinNIr0LjJcH/y2xu5nLXQXGWM= From: Stefan Klug To: libcamera-devel@lists.libcamera.org Cc: Stefan Klug Subject: [PATCH v2 18/32] libipa: algorithm: Update docs Date: Wed, 25 Mar 2026 16:13:50 +0100 Message-ID: <20260325151416.2114564-19-stefan.klug@ideasonboard.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260325151416.2114564-1-stefan.klug@ideasonboard.com> References: <20260325151416.2114564-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 v2: - Added more documentation --- src/ipa/libipa/algorithm.cpp | 41 ++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/src/ipa/libipa/algorithm.cpp b/src/ipa/libipa/algorithm.cpp index 201efdfdba25..e491cb241442 100644 --- a/src/ipa/libipa/algorithm.cpp +++ b/src/ipa/libipa/algorithm.cpp @@ -76,11 +76,13 @@ 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. + * use during frame processing. All values that are already known (like exposure + * time/gain in manual mode) shall be updated in \a frameContext to support + * cases where prepare() is never called (like in raw mode). */ /** @@ -92,20 +94,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 +129,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. */ /**