path: root/src/libcamera/controls.cpp

/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2019, Google Inc.
 *
 * controls.cpp - Control handling
 */

#include <libcamera/controls.h>

#include <sstream>
#include <string>

#include <libcamera/camera.h>

#include "log.h"
#include "utils.h"

/**
 * \file controls.h
 * \brief Describes control framework and controls supported by a camera
 *
 * A control is a mean to govern or influence the operation of a camera. Every
 * control is defined by a unique numerical ID, a name string and the data type
 * of the value it stores. The libcamera API defines a set of standard controls
 * in the libcamera::controls namespace, as a set of instances of the Control
 * class.
 *
 * The main way for applications to interact with controls is through the
 * ControlList stored in the Request class:
 *
 * \code{.cpp}
 * Request *req = ...;
 * ControlList &controls = req->controls();
 * controls->set(controls::AwbEnable, false);
 * controls->set(controls::ManualExposure, 1000);
 *
 * ...
 *
 * int32_t exposure = controls->get(controls::ManualExposure);
 * \endcode
 *
 * The ControlList::get() and ControlList::set() methods automatically deduce
 * the data type based on the control.
 */

namespace libcamera {

LOG_DEFINE_CATEGORY(Controls)

/**
 * \enum ControlType
 * \brief Define the data type of a Control
 * \var ControlTypeNone
 * Invalid type, for empty values
 * \var ControlTypeBool
 * The control stores a boolean value
 * \var ControlTypeInteger32
 * The control stores a 32-bit integer value
 * \var ControlTypeInteger64
 * The control stores a 64-bit integer value
 */

/**
 * \class ControlValue
 * \brief Abstract type representing the value of a control
 */

/**
 * \brief Construct an empty ControlValue.
 */
ControlValue::ControlValue()
	: type_(ControlTypeNone)
{
}

/**
 * \brief Construct a Boolean ControlValue
 * \param[in] value Boolean value to store
 */
ControlValue::ControlValue(bool value)
	: type_(ControlTypeBool), bool_(value)
{
}

/**
 * \brief Construct an integer ControlValue
 * \param[in] value Integer value to store
 */
ControlValue::ControlValue(int32_t value)
	: type_(ControlTypeInteger32), integer32_(value)
{
}

/**
 * \brief Construct a 64 bit integer ControlValue
 * \param[in] value Integer value to store
 */
ControlValue::ControlValue(int64_t value)
	: type_(ControlTypeInteger64), integer64_(value)
{
}

/**
 * \fn ControlValue::type()
 * \brief Retrieve the data type of the value
 * \return The value data type
 */

/**
 * \fn ControlValue::isNone()
 * \brief Determine if the value is not initialised
 * \return True if the value type is ControlTypeNone, false otherwise
 */

/**
 * \fn template<typename T> const T &ControlValue::get() const
 * \brief Get the control value
 *
 * The control value type shall match the type T, otherwise the behaviour is
 * undefined.
 *
 * \return The control value
 */

/**
 * \fn template<typename T> void ControlValue::set(const T &value)
 * \brief Set the control value to \a value
 * \param[in] value The control value
 */

#ifndef __DOXYGEN__
template<>
const bool &ControlValue::get<bool>() const
{
	ASSERT(type_ == ControlTypeBool);

	return bool_;
}

template<>
const int32_t &ControlValue::get<int32_t>() const
{
	ASSERT(type_ == ControlTypeInteger32 || type_ == ControlTypeInteger64);

	return integer32_;
}

template<>
const int64_t &ControlValue::get<int64_t>() const
{
	ASSERT(type_ == ControlTypeInteger32 || type_ == ControlTypeInteger64);

	return integer64_;
}

template<>
void ControlValue::set<bool>(const bool &value)
{
	type_ = ControlTypeBool;
	bool_ = value;
}

template<>
void ControlValue::set<int32_t>(const int32_t &value)
{
	type_ = ControlTypeInteger32;
	integer32_ = value;
}

template<>
void ControlValue::set<int64_t>(const int64_t &value)
{
	type_ = ControlTypeInteger64;
	integer64_ = value;
}
#endif /* __DOXYGEN__ */

/**
 * \brief Assemble and return a string describing the value
 * \return A string describing the ControlValue
 */
std::string ControlValue::toString() const
{
	switch (type_) {
	case ControlTypeNone:
		return "<None>";
	case ControlTypeBool:
		return bool_ ? "True" : "False";
	case ControlTypeInteger32:
		return std::to_string(integer32_);
	case ControlTypeInteger64:
		return std::to_string(integer64_);
	}

	return "<ValueType Error>";
}

/**
 * \class ControlId
 * \brief Control static metadata
 *
 * The ControlId class stores a control ID, name and data type. It provides
 * unique identification of a control, but without support for compile-time
 * type deduction that the derived template Control class supports. See the
 * Control class for more information.
 */

/**
 * \fn ControlId::ControlId(unsigned int id, const char *name, ControlType type)
 * \brief Construct a ControlId instance
 * \param[in] id The control numerical ID
 * \param[in] name The control name
 * \param[in] type The control data type
 */

/**
 * \fn unsigned int ControlId::id() const
 * \brief Retrieve the control numerical ID
 * \return The control numerical ID
 */

/**
 * \fn const char *ControlId::name() const
 * \brief Retrieve the control name
 * \return The control name
 */

/**
 * \fn ControlType ControlId::type() const
 * \brief Retrieve the control data type
 * \return The control data type
 */

/**
 * \fn bool operator==(const ControlId &lhs, const ControlId &rhs)
 * \brief Compare two ControlId instances for equality
 * \param[in] lhs Left-hand side ControlId
 * \param[in] rhs Right-hand side ControlId
 *
 * ControlId instances are compared based on the numerical ControlId::id()
 * only, as an object may not have two separate controls with the same
 * numerical ID.
 *
 * \return True if \a lhs and \a rhs have equal control IDs, false otherwise
 */

/**
 * \class Control
 * \brief Describe a control and its intrinsic properties
 *
 * The Control class models a control exposed by a camera. Its template type
 * name T refers to the control data type, and allows methods that operate on
 * control values to be defined as template methods using the same type T for
 * the control value. See for instance how the ControlList::get() method
 * returns a value corresponding to the type of the requested control.
 *
 * While this class is the main mean to refer to a control, the control
 * identifying information are stored in the non-template base ControlId class.
 * This allows code that operates on a set of controls of different types to
 * reference those controls through a ControlId instead of a Control. For
 * instance, the list of controls supported by a camera is exposed as ControlId
 * instead of Control.
 *
 * Controls of any type can be defined through template specialisation, but
 * libcamera only supports the bool, int32_t and int64_t types natively (this
 * includes types that are equivalent to the supported types, such as int and
 * long int).
 *
 * Controls IDs shall be unique. While nothing prevents multiple instances of
 * the Control class to be created with the same ID, this may lead to undefined
 * behaviour.
 */

/**
 * \fn Control::Control(unsigned int id, const char *name)
 * \brief Construct a Control instance
 * \param[in] id The control numerical ID
 * \param[in] name The control name
 *
 * The control data type is automatically deduced from the template type T.
 */

/**
 * \typedef Control::type
 * \brief The Control template type T
 */

#ifndef __DOXYGEN__
template<>
Control<void>::Control(unsigned int id, const char *name)
	: ControlId(id, name, ControlTypeNone)
{
}

template<>
Control<bool>::Control(unsigned int id, const char *name)
	: ControlId(id, name, ControlTypeBool)
{
}

template<>
Control<int32_t>::Control(unsigned int id, const char *name)
	: ControlId(id, name, ControlTypeInteger32)
{
}

template<>
Control<int64_t>::Control(unsigned int id, const char *name)
	: ControlId(id, name, ControlTypeInteger64)
{
}
#endif /* __DOXYGEN__ */

/**
 * \class ControlInfo
 * \brief Describe the information and capabilities of a Control
 *
 * The ControlInfo represents control specific meta-data which is constant on a
 * per camera basis. ControlInfo classes are constructed by pipeline handlers
 * to expose the controls they support and the metadata needed to utilise those
 * controls.
 */

/**
 * \brief Construct a ControlInfo with minimum and maximum range parameters
 * \param[in] id The control ID
 * \param[in] min The control minimum value
 * \param[in] max The control maximum value
 */
ControlInfo::ControlInfo(const ControlId &id, const ControlValue &min,
			 const ControlValue &max)
	: id_(id), min_(min), max_(max)
{
}

/**
 * \fn ControlInfo::id()
 * \brief Retrieve the control ID
 * \return The control ID
 */

/**
 * \fn ControlInfo::min()
 * \brief Retrieve the minimum value of the control
 * \return A ControlValue with the minimum value for the control
 */

/**
 * \fn ControlInfo::max()
 * \brief Retrieve the maximum value of the control
 * \return A ControlValue with the maximum value for the control
 */

/**
 * \brief Provide a string representation of the ControlInfo
 */
std::string ControlInfo::toString() const
{
	std::stringstream ss;

	ss << id_.name() << "[" << min_.toString() << ".." << max_.toString() << "]";

	return ss.str();
}

/**
 * \typedef ControlInfoMap
 * \brief A map of ControlId to ControlInfo
 */

/**
 * \class ControlList
 * \brief Associate a list of ControlId with their values for a camera
 *
 * A ControlList wraps a map of ControlId to ControlValue and provide
 * additional validation against the control information exposed by a Camera.
 *
 * A list is only valid for as long as the camera it refers to is valid. After
 * that calling any method of the ControlList class other than its destructor
 * will cause undefined behaviour.
 */

/**
 * \brief Construct a ControlList with a reference to the Camera it applies on
 * \param[in] camera The camera
 */
ControlList::ControlList(Camera *camera)
	: camera_(camera)
{
}

/**
 * \typedef ControlList::iterator
 * \brief Iterator for the controls contained within the list
 */

/**
 * \typedef ControlList::const_iterator
 * \brief Const iterator for the controls contained within the list
 */

/**
 * \fn iterator ControlList::begin()
 * \brief Retrieve an iterator to the first Control in the list
 * \return An iterator to the first Control in the list
 */

/**
 * \fn const_iterator ControlList::begin() const
 * \brief Retrieve a const_iterator to the first Control in the list
 * \return A const_iterator to the first Control in the list
 */

/**
 * \fn iterator ControlList::end()
 * \brief Retrieve an iterator pointing to the past-the-end control in the list
 * \return An iterator to the element following the last control in the list
 */

/**
 * \fn const_iterator ControlList::end() const
 * \brief Retrieve a const iterator pointing to the past-the-end control in the
 * list
 * \return A const iterator to the element following the last control in the
 * list
 */

/**
 * \brief Check if the list contains a control with the specified \a id
 * \param[in] id The control ID
 *
 * The behaviour is undefined if the control \a id is not supported by the
 * camera that the ControlList refers to.
 *
 * \return True if the list contains a matching control, false otherwise
 */
bool ControlList::contains(const ControlId &id) const
{
	return controls_.find(&id) != controls_.end();
}

/**
 * \fn ControlList::empty()
 * \brief Identify if the list is empty
 * \return True if the list does not contain any control, false otherwise
 */

/**
 * \fn ControlList::size()
 * \brief Retrieve the number of controls in the list
 * \return The number of Control entries stored in the list
 */

/**
 * \fn ControlList::clear()
 * \brief Removes all controls from the list
 */

/**
 * \fn template<typename T> const T &ControlList::get() const
 * \brief Get the value of a control
 * \param[in] ctrl The control
 *
 * The behaviour is undefined if the control \a ctrl is not present in the
 * list. Use ControlList::contains() to test for the presence of a control in
 * the list before retrieving its value.
 *
 * The control value type shall match the type T, otherwise the behaviour is
 * undefined.
 *
 * \return The control value
 */

/**
 * \fn template<typename T> void ControlList::set()
 * \brief Set the control value to \a value
 * \param[in] ctrl The control
 * \param[in] value The control value
 *
 * This method sets the value of a control in the control list. If the control
 * is already present in the list, its value is updated, otherwise it is added
 * to the list.
 *
 * The behaviour is undefined if the control \a ctrl is not supported by the
 * camera that the list refers to.
 */

const ControlValue *ControlList::find(const ControlId &id) const
{
	const auto iter = controls_.find(&id);
	if (iter == controls_.end()) {
		LOG(Controls, Error)
			<< "Control " << id.name() << " not found";

		return nullptr;
	}

	return &iter->second;
}

ControlValue *ControlList::find(const ControlId &id)
{
	const ControlInfoMap &controls = camera_->controls();
	const auto iter = controls.find(&id);
	if (iter == controls.end()) {
		LOG(Controls, Error)
			<< "Camera " << camera_->name()
			<< " does not support control " << id.name();
		return nullptr;
	}

	return &controls_[&id];
}

/**
 * \brief Update the list with a union of itself and \a other
 * \param other The other list
 *
 * Update the control list to include all values from the \a other list.
 * Elements in the list whose control IDs are contained in \a other are updated
 * with the value from \a other. Elements in the \a other list that have no
 * corresponding element in the list are added to the list with their value.
 *
 * The behaviour is undefined if the two lists refer to different Camera
 * instances.
 */
void ControlList::update(const ControlList &other)
{
	if (other.camera_ != camera_) {
		LOG(Controls, Error)
			<< "Can't update ControlList from a different camera";
		return;
	}

	for (auto it : other) {
		const ControlId *id = it.first;
		const ControlValue &value = it.second;

		controls_[id] = value;
	}
}

} /* namespace libcamera */