f08b18ebe9
A few periods crept in at the end of Doxygen \brief or \param statements in the src/ipa/ directory. Remove them all in one go. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
180 lines
6.4 KiB
C++
180 lines
6.4 KiB
C++
/* SPDX-License-Identifier: LGPL-2.1-or-later */
|
|
/*
|
|
* Copyright (C) 2021, Ideas On Board
|
|
*
|
|
* algorithm.cpp - 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::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::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::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
|
|
*
|
|
* 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 and update their state
|
|
* accordingly.
|
|
*
|
|
* 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 */
|