1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
* Copyright (C) 2019, Google Inc.
*
* v4l2_controls.cpp - V4L2 Controls Support
*/
#include "v4l2_controls.h"
#include <string.h>
/**
* \file v4l2_controls.h
* \brief Support for V4L2 Controls using the V4L2 Extended Controls APIs
*
* The V4L2 Control API allows application to inspect and modify sets of
* configurable parameters on a video device or subdevice. The nature of the
* parameters an application can modify using the control framework depends on
* what the driver implements support for, and on the characteristics of the
* underlying hardware platform. Generally controls are used to modify user
* visible settings, such as the image brightness and exposure time, or
* non-standard parameters which cannot be controlled through the V4L2 format
* negotiation API.
*
* Controls are identified by a numerical ID, defined by the V4L2 kernel headers
* and have an associated type. Each control has a value, which is the data that
* can be modified with V4L2Device::setControls() or retrieved with
* V4L2Device::getControls().
*
* The control's type along with the control's flags define the type of the
* control's value content. Controls can transport a single data value stored in
* variable inside the control, or they might as well deal with more complex
* data types, such as arrays of matrices, stored in a contiguous memory
* locations associated with the control and called 'the payload'. Such controls
* are called 'compound controls' and are currently not supported by the
* libcamera V4L2 control framework.
*
* libcamera implements support for controls using the V4L2 Extended Control
* API, which allows future handling of controls with payloads of arbitrary
* sizes.
*
* The libcamera V4L2 Controls framework operates on lists of controls, wrapped
* by the ControlList class, to match the V4L2 extended controls API. The
* interface to set and get control is implemented by the V4L2Device class, and
* this file only provides the data type definitions.
*
* \todo Add support for compound controls
*/
namespace libcamera {
namespace {
std::string v4l2_ctrl_name(const struct v4l2_query_ext_ctrl &ctrl)
{
size_t len = strnlen(ctrl.name, sizeof(ctrl.name));
return std::string(static_cast<const char *>(ctrl.name), len);
}
ControlType v4l2_ctrl_type(const struct v4l2_query_ext_ctrl &ctrl)
{
switch (ctrl.type) {
case V4L2_CTRL_TYPE_BOOLEAN:
return ControlTypeBool;
case V4L2_CTRL_TYPE_INTEGER:
return ControlTypeInteger32;
case V4L2_CTRL_TYPE_INTEGER64:
return ControlTypeInteger64;
case V4L2_CTRL_TYPE_MENU:
case V4L2_CTRL_TYPE_BUTTON:
case V4L2_CTRL_TYPE_BITMASK:
case V4L2_CTRL_TYPE_INTEGER_MENU:
/*
* More precise types may be needed, for now use a 32-bit
* integer type.
*/
return ControlTypeInteger32;
default:
return ControlTypeNone;
}
}
} /* namespace */
/**
* \class V4L2ControlId
* \brief V4L2 control static metadata
*
* The V4L2ControlId class is a specialisation of the ControlId for V4L2
* controls.
*/
/**
* \brief Construct a V4L2ControlId from a struct v4l2_query_ext_ctrl
* \param[in] ctrl The struct v4l2_query_ext_ctrl as returned by the kernel
*/
V4L2ControlId::V4L2ControlId(const struct v4l2_query_ext_ctrl &ctrl)
: ControlId(ctrl.id, v4l2_ctrl_name(ctrl), v4l2_ctrl_type(ctrl))
{
}
/**
* \class V4L2ControlInfo
* \brief Information on a V4L2 control
*
* The V4L2ControlInfo class represents all the information related to a V4L2
* control, such as its ID, its type, its user-readable name and the expected
* size of its value data.
*
* V4L2ControlInfo instances are created by inspecting the fieldS of a struct
* v4l2_query_ext_ctrl structure, after it has been filled by the device driver
* as a consequence of a VIDIOC_QUERY_EXT_CTRL ioctl call.
*
* This class does not contain the control value, but only static information on
* the control, which shall be cached by the caller at initialisation time or
* the first time the control information is accessed.
*/
/**
* \brief Construct a V4L2ControlInfo from a struct v4l2_query_ext_ctrl
* \param[in] ctrl The struct v4l2_query_ext_ctrl as returned by the kernel
*/
V4L2ControlInfo::V4L2ControlInfo(const struct v4l2_query_ext_ctrl &ctrl)
: id_(ctrl)
{
size_ = ctrl.elem_size * ctrl.elems;
if (ctrl.type == V4L2_CTRL_TYPE_INTEGER64)
range_ = ControlRange(static_cast<int64_t>(ctrl.minimum),
static_cast<int64_t>(ctrl.maximum));
else
range_ = ControlRange(static_cast<int32_t>(ctrl.minimum),
static_cast<int32_t>(ctrl.maximum));
}
/**
* \fn V4L2ControlInfo::id()
* \brief Retrieve the control ID
* \return The V4L2 control ID
*/
/**
* \fn V4L2ControlInfo::size()
* \brief Retrieve the control value data size (in bytes)
* \return The V4L2 control value data size
*/
/**
* \fn V4L2ControlInfo::range()
* \brief Retrieve the control value range
* \return The V4L2 control value range
*/
/**
* \class V4L2ControlInfoMap
* \brief A map of control ID to V4L2ControlInfo
*/
/**
* \brief Move assignment operator from plain map
* \param[in] info The control info map
*
* Populate the map by replacing its contents with those of \a info using move
* semantics. Upon return the \a info map will be empty.
*
* This is the only supported way to populate a V4L2ControlInfoMap.
*
* \return The populated V4L2ControlInfoMap
*/
V4L2ControlInfoMap &V4L2ControlInfoMap::operator=(std::map<unsigned int, V4L2ControlInfo> &&info)
{
std::map<unsigned int, V4L2ControlInfo>::operator=(std::move(info));
idmap_.clear();
for (const auto &ctrl : *this)
idmap_[ctrl.first] = &ctrl.second.id();
return *this;
}
/**
* \fn const ControlIdMap &V4L2ControlInfoMap::idmap() const
* \brief Retrieve the ControlId map
*
* Constructing ControlList instances for V4L2 controls requires a ControlIdMap
* for the V4L2 device that the control list targets. This helper method
* returns a suitable idmap for that purpose.
*
* \return The ControlId map
*/
/**
* \class V4L2ControlList
* \brief A list of controls for a V4L2 device
*
* This class specialises the ControList class for use with V4L2 devices. It
* offers a convenience API to create a ControlList from a V4L2ControlInfoMap.
*
* V4L2ControlList allows easy construction of a ControlList containing V4L2
* controls for a device. It can be used to construct the list of controls
* passed to the V4L2Device::getControls() and V4L2Device::setControls()
* methods. The class should however not be used in place of ControlList in
* APIs.
*/
/**
* \fn V4L2ControlList::V4L2ControlList(const V4L2ControlInfoMap &info)
* \brief Construct a V4L2ControlList associated with a V4L2 device
* \param[in] info The V4L2 device control info map
*/
} /* namespace libcamera */
|
