1 files changed, 181 insertions, 0 deletions
diff --git a/src/ipa/libipa/algorithm.cpp b/src/ipa/libipa/algorithm.cpp
new file mode 100644
index 00000000..201efdfd
--- /dev/null
+++ b/src/ipa/libipa/algorithm.cpp
@@ -0,0 +1,181 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2021, Ideas On Board
+ *
+ * IPA control algorithm interface
+ */
+
+#include "algorithm.h"
+
+/**
+ * \file algorithm.h
+ * \brief Algorithm common interface
+ */
+
+namespace libcamera {
+
+namespace ipa {
+
+/**
+ * \class Algorithm
+ * \brief The base class for all IPA algorithms
+ * \tparam Module The IPA module type for this class of algorithms
+ *
+ * The Algorithm class defines a standard interface for IPA algorithms
+ * compatible with the \a Module. By abstracting algorithms, it makes possible
+ * the implementation of generic code to manage algorithms regardless of their
+ * specific type.
+ *
+ * To specialize the Algorithm class template, an IPA module shall specialize
+ * the Module class template with module-specific context and configuration
+ * types, and pass the specialized Module class as the \a Module template
+ * argument.
+ */
+
+/**
+ * \typedef Algorithm::Module
+ * \brief The IPA module type for this class of algorithms
+ */
+
+/**
+ * \fn Algorithm::init()
+ * \brief Initialize the Algorithm with tuning data
+ * \param[in] context The shared IPA context
+ * \param[in] tuningData The tuning data for the algorithm
+ *
+ * This function is called once, when the IPA module is initialized, to
+ * initialize the algorithm. The \a tuningData YamlObject contains the tuning
+ * data for algorithm.
+ *
+ * \return 0 if successful, an error code otherwise
+ */
+
+/**
+ * \fn Algorithm::configure()
+ * \brief Configure the Algorithm given an IPAConfigInfo
+ * \param[in] context The shared IPA context
+ * \param[in] configInfo The IPA configuration data, received from the pipeline
+ * handler
+ *
+ * Algorithms may implement a configure operation to pre-calculate
+ * parameters prior to commencing streaming.
+ *
+ * Configuration state may be stored in the IPASessionConfiguration structure of
+ * the IPAContext.
+ *
+ * \return 0 if successful, an error code otherwise
+ */
+
+/**
+ * \fn Algorithm::queueRequest()
+ * \brief Provide control values to the algorithm
+ * \param[in] context The shared IPA context
+ * \param[in] frame The frame number to apply the control values
+ * \param[in] frameContext The current frame's context
+ * \param[in] controls The list of user controls
+ *
+ * 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
+ * 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.
+ */
+
+/**
+ * \fn Algorithm::prepare()
+ * \brief Fill the \a params buffer with ISP processing parameters for a frame
+ * \param[in] context The shared IPA context
+ * \param[in] frame The frame context sequence number
+ * \param[in] frameContext The FrameContext for this frame
+ * \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.
+ *
+ * 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.
+ */
+
+/**
+ * \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] stats The IPA statistics and ISP results
+ * \param[out] metadata Metadata for the frame, to be filled by the algorithm
+ *
+ * This function is called while camera is running for every frame processed by
+ * the ISP, to process statistics generated from that frame by the ISP.
+ * Algorithms shall use this data to run calculations, update their state
+ * accordingly, and fill the frame metadata.
+ *
+ * Processing shall not take an undue amount of time, and any extended or
+ * 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 shall be taken to ensure the ordering of access to the information
+ * such that the algorithms use up to date state as required.
+ */
+
+/**
+ * \class AlgorithmFactory
+ * \brief Registration of Algorithm classes and creation of instances
+ * \tparam _Algorithm The algorithm class type for this factory
+ *
+ * To facilitate instantiation of Algorithm classes, the AlgorithmFactory class
+ * implements auto-registration of algorithms with the IPA Module class. Each
+ * Algorithm subclass shall register itself using the REGISTER_IPA_ALGORITHM()
+ * macro, which will create a corresponding instance of an AlgorithmFactory and
+ * register it with the IPA Module.
+ */
+
+/**
+ * \fn AlgorithmFactory::AlgorithmFactory()
+ * \brief Construct an algorithm factory
+ * \param[in] name Name of the algorithm class
+ *
+ * Creating an instance of the factory automatically registers is with the IPA
+ * Module class, enabling creation of algorithm instances through
+ * Module::createAlgorithm().
+ *
+ * The factory \a name identifies the algorithm and shall be unique.
+ */
+
+/**
+ * \fn AlgorithmFactory::create()
+ * \brief Create an instance of the Algorithm corresponding to the factory
+ * \return A pointer to a newly constructed instance of the Algorithm subclass
+ * corresponding to the factory
+ */
+
+/**
+ * \def REGISTER_IPA_ALGORITHM
+ * \brief Register an algorithm with the IPA module
+ * \param[in] algorithm Class name of Algorithm derived class to register
+ * \param[in] name Name of the algorithm
+ *
+ * Register an Algorithm subclass with the IPA module to make it available for
+ * instantiation through Module::createAlgorithm(). The \a name identifies the
+ * algorithm and must be unique across all algorithms registered for the IPA
+ * module.
+ */
+
+} /* namespace ipa */
+
+} /* namespace libcamera */