/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2021, Google Inc.
 *
 * camera_sensor_helper.cpp - Helper class that performs sensor-specific
 * parameter computations
 */
#include "camera_sensor_helper.h"

#include <libcamera/base/log.h>

/**
 * \file camera_sensor_helper.h
 * \brief Helper class that performs sensor-specific parameter computations
 *
 * Computation of sensor configuration parameters is a sensor specific
 * operation. Each CameraHelper derived class computes the value of
 * configuration parameters, for example the analogue gain value, using
 * sensor-specific functions and constants.
 *
 * Every subclass of CameraSensorHelper shall be registered with libipa using
 * the REGISTER_CAMERA_SENSOR_HELPER() macro.
 */

namespace libcamera {

LOG_DEFINE_CATEGORY(CameraSensorHelper)

namespace ipa {

/**
 * \class CameraSensorHelper
 * \brief Base class for computing sensor tuning parameters using
 * sensor-specific constants
 *
 * Instances derived from CameraSensorHelper class are sensor-specific.
 * Each supported sensor will have an associated base class defined.
 */

/**
 * \brief Construct a CameraSensorHelper instance
 *
 * CameraSensorHelper derived class instances shall never be constructed
 * manually but always through the CameraSensorHelperFactory::create() function.
 */

/**
 * \brief Compute gain code from the analogue gain absolute value
 * \param[in] gain The real gain to pass
 *
 * This function aims to abstract the calculation of the gain letting the IPA
 * use the real gain for its estimations.
 *
 * The parameters come from the MIPI Alliance Camera Specification for
 * Camera Command Set (CCS).
 *
 * \return The gain code to pass to V4L2
 */
uint32_t CameraSensorHelper::gainCode(double gain) const
{
	ASSERT(analogueGainConstants_.m0 == 0 || analogueGainConstants_.m1 == 0);
	ASSERT(analogueGainConstants_.type == AnalogueGainLinear);

	return (analogueGainConstants_.c0 - analogueGainConstants_.c1 * gain) /
	       (analogueGainConstants_.m1 * gain - analogueGainConstants_.m0);
}

/**
 * \brief Compute the real gain from the V4L2 subdev control gain code
 * \param[in] gainCode The V4L2 subdev control gain
 *
 * This function aims to abstract the calculation of the gain letting the IPA
 * use the real gain for its estimations. It is the counterpart of the function
 * CameraSensorHelper::gainCode.
 *
 * The parameters come from the MIPI Alliance Camera Specification for
 * Camera Command Set (CCS).
 *
 * \return The real gain
 */
double CameraSensorHelper::gain(uint32_t gainCode) const
{
	ASSERT(analogueGainConstants_.m0 == 0 || analogueGainConstants_.m1 == 0);
	ASSERT(analogueGainConstants_.type == AnalogueGainLinear);

	return (analogueGainConstants_.m0 * static_cast<double>(gainCode) + analogueGainConstants_.c0) /
	       (analogueGainConstants_.m1 * static_cast<double>(gainCode) + analogueGainConstants_.c1);
}

/**
 * \enum CameraSensorHelper::AnalogueGainType
 * \brief The gain calculation modes as defined by the MIPI CCS
 *
 * Describes the image sensor analogue gain capabilities.
 * Two modes are possible, depending on the sensor: Linear and Exponential.
 */

/**
 * \var CameraSensorHelper::AnalogueGainLinear
 * \brief Gain is computed using linear gain estimation
 *
 * The relationship between the integer gain parameter and the resulting gain
 * multiplier is given by the following equation:
 *
 * \f$gain=\frac{m0x+c0}{m1x+c1}\f$
 *
 * Where 'x' is the gain control parameter, and m0, m1, c0 and c1 are
 * image-sensor-specific constants of the sensor.
 * These constants are static parameters, and for any given image sensor either
 * m0 or m1 shall be zero.
 *
 * The full Gain equation therefore reduces to either:
 *
 * \f$gain=\frac{c0}{m1x+c1}\f$ or \f$\frac{m0x+c0}{c1}\f$
 */

/**
 * \var CameraSensorHelper::AnalogueGainExponential
 * \brief Gain is computed using exponential gain estimation
 * (introduced in CCS v1.1)
 *
 * Starting with CCS v1.1, Alternate Global Analogue Gain is also available.
 * If the image sensor supports it, then the global analogue gain can be
 * controlled by linear and exponential gain formula:
 *
 * \f$gain = analogLinearGainGlobal * 2^{analogExponentialGainGlobal}\f$
 * \todo not implemented in libipa
 */

/**
 * \struct CameraSensorHelper::AnalogueGainConstants
 * \brief Analogue gain constants used for gain calculation
 */

/**
 * \var CameraSensorHelper::AnalogueGainConstants::type
 * \brief Analogue gain calculation mode
 */

/**
 * \var CameraSensorHelper::AnalogueGainConstants::m0
 * \brief Constant used in the analogue Gain coding/decoding
 *
 * \note Either m0 or m1 shall be zero.
 */

/**
 * \var CameraSensorHelper::AnalogueGainConstants::c0
 * \brief Constant used in the analogue gain coding/decoding
 */

/**
 * \var CameraSensorHelper::AnalogueGainConstants::m1
 * \brief Constant used in the analogue gain coding/decoding
 *
 * \note Either m0 or m1 shall be zero.
 */

/**
 * \var CameraSensorHelper::AnalogueGainConstants::c1
 * \brief Constant used in the analogue gain coding/decoding
 */

/**
 * \var CameraSensorHelper::analogueGainConstants_
 * \brief The analogue gain parameters used for calculation
 *
 * The analogue gain is calculated through a formula, and its parameters are