a8c40942b9
Rework the control-related classes to improve the API towards applications. The goal is to enable writing code similar to Request *req = ...; ControlList &controls = req->controls(); controls->set(controls::AwbEnable, false); controls->set(controls::ManualExposure, 1000); ... int32_t exposure = controls->get(controls::ManualExposure); with the get and set operations ensuring type safety for the control values. This is achieved by creating the following classes: - Control defines controls and is the main way to reference a control. It is a template class to allow methods using it to refer to the control type. - ControlId is the base class of Control. It stores the control ID, name and type, and can be used in contexts where a control needs to be referenced regardless of its type (for instance in lists of controls). This class replaces ControlIdentifier. - ControlValue is kept as-is. The ControlList class now exposes two template get() and set() methods that replace the operator[]. They ensure type safety by infering the value type from the Control reference that they receive. The main way to refer to a control is now through the Control class, and optionally through its base ControlId class. The ControlId enumeration is removed, replaced by a list of global Control instances. Numerical control IDs are turned into macros, and are still exposed as they are required to communicate with IPAs (especially to deserialise control lists). They should however not be used by applications. Auto-generation of header and source files is removed for now to keep the change simple. It will be added back in the future in a more elaborate form. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
544 lines
14 KiB
C++
544 lines
14 KiB
C++
/* 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 */
|