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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
|
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
* Copyright (C) 2018, Google Inc.
*
* camera.cpp - Camera device
*/
#include <libcamera/camera.h>
#include <libcamera/request.h>
#include <libcamera/stream.h>
#include "log.h"
#include "pipeline_handler.h"
#include "utils.h"
/**
* \file camera.h
* \brief Camera device handling
*
* At the core of libcamera is the camera device, combining one image source
* with processing hardware able to provide one or multiple image streams. The
* Camera class represents a camera device.
*
* A camera device contains a single image source, and separate camera device
* instances relate to different image sources. For instance, a phone containing
* front and back image sensors will be modelled with two camera devices, one
* for each sensor. When multiple streams can be produced from the same image
* source, all those streams are guaranteed to be part of the same camera
* device.
*
* While not sharing image sources, separate camera devices can share other
* system resources, such as an ISP. For this reason camera device instances may
* not be fully independent, in which case usage restrictions may apply. For
* instance, a phone with a front and a back camera device may not allow usage
* of the two devices simultaneously.
*/
namespace libcamera {
LOG_DECLARE_CATEGORY(Camera)
/**
* \class Camera
* \brief Camera device
*
* \todo Add documentation for camera start timings. What exactly does the
* camera expect the pipeline handler to do when start() is called?
*
* The Camera class models a camera capable of producing one or more image
* streams from a single image source. It provides the main interface to
* configuring and controlling the device, and capturing image streams. It is
* the central object exposed by libcamera.
*
* To support the central nature of Camera objects, libcamera manages the
* lifetime of camera instances with std::shared_ptr<>. Instances shall be
* created with the create() function which returns a shared pointer. The
* Camera constructors and destructor are private, to prevent instances from
* being constructed and destroyed manually.
*
* \section camera_operation Operating the Camera
*
* An application needs to perform a sequence of operations on a camera before
* it is ready to process requests. The camera needs to be acquired, configured
* and resources allocated or imported to prepare the camera for capture. Once
* started the camera can process requests until it is stopped. When an
* application is done with a camera all resources allocated need to be freed
* and the camera released.
*
* An application may start and stop a camera multiple times as long as it is
* not released. The camera may also be reconfigured provided that all
* resources allocated are freed prior to the reconfiguration.
*
* \subsection Camera States
*
* To help manage the sequence of operations needed to control the camera a set
* of states are defined. Each state describes which operations may be performed
* on the camera. Operations not listed in the state diagram are allowed in all
* states.
*
* \dot
* digraph camera_state_machine {
* node [shape = doublecircle ]; Available;
* node [shape = circle ]; Acquired;
* node [shape = circle ]; Configured;
* node [shape = circle ]; Prepared;
* node [shape = circle ]; Running;
*
* Available -> Available [label = "release()"];
* Available -> Acquired [label = "acquire()"];
*
* Acquired -> Available [label = "release()"];
* Acquired -> Configured [label = "configureStreams()"];
*
* Configured -> Available [label = "release()"];
* Configured -> Configured [label = "configureStreams()"];
* Configured -> Prepared [label = "allocateBuffers()"];
*
* Prepared -> Configured [label = "freeBuffers()"];
* Prepared -> Prepared [label = "createRequest()"];
* Prepared -> Running [label = "start()"];
*
* Running -> Prepared [label = "stop()"];
* Running -> Running [label = "createRequest(), queueRequest()"];
* }
* \enddot
*
* \subsubsection Available
* The base state of a camera, an application can inspect the properties of the
* camera to determine if it wishes to use it. If an application wishes to use
* a camera it should acquire() it to proceed to the Acquired state.
*
* \subsubsection Acquired
* In the acquired state an application has exclusive access to the camera and
* may modify the camera's parameters to configure it and proceed to the
* Configured state.
*
* \subsubsection Configured
* The camera is configured and ready for the application to prepare it with
* resources. The camera may be reconfigured multiple times until resources
* are provided and the state progresses to Prepared.
*
* \subsubsection Prepared
* The camera has been configured and provided with resources and is ready to be
* started. The application may free the camera's resources to get back to the
* Configured state or start() it to progress to the Running state.
*
* \subsubsection Running
* The camera is running and ready to process requests queued by the
* application. The camera remains in this state until it is stopped and moved
* to the Prepared state.
*/
/**
* \brief Create a camera instance
* \param[in] name The name of the camera device
* \param[in] pipe The pipeline handler responsible for the camera device
* \param[in] streams Array of streams the camera provides
*
* The caller is responsible for guaranteeing unicity of the camera name.
*
* \return A shared pointer to the newly created camera object
*/
std::shared_ptr<Camera> Camera::create(PipelineHandler *pipe,
const std::string &name,
const std::set<Stream *> &streams)
{
struct Allocator : std::allocator<Camera> {
void construct(void *p, PipelineHandler *pipe,
const std::string &name)
{
::new(p) Camera(pipe, name);
}
void destroy(Camera *p)
{
p->~Camera();
}
};
std::shared_ptr<Camera> camera =
std::allocate_shared<Camera>(Allocator(), pipe, name);
camera->streams_ = streams;
return camera;
}
/**
* \brief Retrieve the name of the camera
*
* \return Name of the camera device
*/
const std::string &Camera::name() const
{
return name_;
}
/**
* \var Camera::bufferCompleted
* \brief Signal emitted when a buffer for a request queued to the camera has
* completed
*/
/**
* \var Camera::requestCompleted
* \brief Signal emitted when a request queued to the camera has completed
*/
/**
* \var Camera::disconnected
* \brief Signal emitted when the camera is disconnected from the system
*
* This signal is emitted when libcamera detects that the camera has been
* removed from the system. For hot-pluggable devices this is usually caused by
* physical device disconnection. The media device is passed as a parameter.
*
* As soon as this signal is emitted the camera instance will refuse all new
* application API calls by returning errors immediately.
*/
Camera::Camera(PipelineHandler *pipe, const std::string &name)
: pipe_(pipe->shared_from_this()), name_(name), disconnected_(false),
state_(CameraAvailable)
{
}
Camera::~Camera()
{
if (!stateIs(CameraAvailable))
LOG(Camera, Error) << "Removing camera while still in use";
}
static const char *const camera_state_names[] = {
"Available",
"Acquired",
"Configured",
"Prepared",
"Running",
};
bool Camera::stateBetween(State low, State high) const
{
if (state_ >= low && state_ <= high)
return true;
ASSERT(static_cast<unsigned int>(low) < ARRAY_SIZE(camera_state_names) &&
static_cast<unsigned int>(high) < ARRAY_SIZE(camera_state_names));
LOG(Camera, Debug) << "Camera in " << camera_state_names[state_]
<< " state trying operation requiring state between "
<< camera_state_names[low] << " and "
<< camera_state_names[high];
return false;
}
bool Camera::stateIs(State state) const
{
if (state_ == state)
return true;
ASSERT(static_cast<unsigned int>(state) < ARRAY_SIZE(camera_state_names));
LOG(Camera, Debug) << "Camera in " << camera_state_names[state_]
<< " state trying operation requiring state "
<< camera_state_names[state];
return false;
}
/**
* \brief Notify camera disconnection
*
* This method is used to notify the camera instance that the underlying
* hardware has been unplugged. In response to the disconnection the camera
* instance notifies the application by emitting the #disconnected signal, and
* ensures that all new calls to the application-facing Camera API return an
* error immediately.
*
* \todo Deal with pending requests if the camera is disconnected in a
* running state.
* \todo Update comment about Running state when importing buffers as well as
* allocating them are supported.
*/
void Camera::disconnect()
{
LOG(Camera, Debug) << "Disconnecting camera " << name_;
/*
* If the camera was running when the hardware was removed force the
* state to Prepared to allow applications to call freeBuffers() and
* release() before deleting the camera.
*/
if (state_ == CameraRunning)
state_ = CameraPrepared;
disconnected_ = true;
disconnected.emit(this);
}
/**
* \brief Acquire the camera device for exclusive access
*
* After opening the device with open(), exclusive access must be obtained
* before performing operations that change the device state. This function is
* not blocking, if the device has already been acquired (by the same or another
* process) the -EBUSY error code is returned.
*
* Once exclusive access isn't needed anymore, the device should be released
* with a call to the release() function.
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \todo Implement exclusive access across processes.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EBUSY The camera is not free and can't be acquired by the caller
*/
int Camera::acquire()
{
if (disconnected_)
return -ENODEV;
if (!stateIs(CameraAvailable))
return -EBUSY;
state_ = CameraAcquired;
return 0;
}
/**
* \brief Release exclusive access to the camera device
*
* Releasing the camera device allows other users to acquire exclusive access
* with the acquire() function.
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -EBUSY The camera is running and can't be released
*/
int Camera::release()
{
if (!stateBetween(CameraAvailable, CameraConfigured))
return -EBUSY;
state_ = CameraAvailable;
return 0;
}
/**
* \brief Retrieve all the camera's stream information
*
* Retrieve all of the camera's static stream information. The static
* information describes among other things how many streams the camera
* supports and the capabilities of each stream.
*
* \return An array of all the camera's streams.
*/
const std::set<Stream *> &Camera::streams() const
{
return streams_;
}
/**
* \brief Retrieve a group of stream configurations
* \param[in] streams A map of stream IDs and configurations to setup
*
* Retrieve the camera's configuration for a specified group of streams. The
* caller can specifies which of the camera's streams to retrieve configuration
* from by populating \a streams.
*
* The easiest way to populate the array of streams to fetch configuration from
* is to first retrieve the camera's full array of stream with streams() and
* then potentially trim it down to only contain the streams the caller
* are interested in.
*
* \return A map of successfully retrieved stream IDs and configurations or an
* empty list on error.
*/
std::map<Stream *, StreamConfiguration>
Camera::streamConfiguration(std::set<Stream *> &streams)
{
if (disconnected_ || !streams.size())
return std::map<Stream *, StreamConfiguration>{};
return pipe_->streamConfiguration(this, streams);
}
/**
* \brief Configure the camera's streams prior to capture
* \param[in] config A map of stream IDs and configurations to setup
*
* Prior to starting capture, the camera must be configured to select a
* group of streams to be involved in the capture and their configuration.
* The caller specifies which streams are to be involved and their configuration
* by populating \a config.
*
* The easiest way to populate the array of config is to fetch an initial
* configuration from the camera with streamConfiguration() and then change the
* parameters to fit the caller's need and once all the streams parameters are
* configured hand that over to configureStreams() to actually setup the camera.
*
* Exclusive access to the camera shall be ensured by a call to acquire() prior
* to calling this function, otherwise an -EACCES error will be returned.
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EACCES The camera is not in a state where it can be configured
* \retval -EINVAL The configuration is not valid
*/
int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
{
int ret;
if (disconnected_)
return -ENODEV;
if (!stateBetween(CameraAvailable, CameraConfigured))
return -EACCES;
if (!config.size()) {
LOG(Camera, Error)
<< "Can't configure streams without a configuration";
return -EINVAL;
}
ret = pipe_->configureStreams(this, config);
if (ret)
return ret;
activeStreams_.clear();
for (auto const &iter : config) {
Stream *stream = iter.first;
const StreamConfiguration &cfg = iter.second;
stream->configuration_ = cfg;
activeStreams_.insert(stream);
/*
* Allocate buffer objects in the pool.
* Memory will be allocated and assigned later.
*/
stream->bufferPool().createBuffers(cfg.bufferCount);
}
state_ = CameraConfigured;
return 0;
}
/**
* \brief Allocate buffers for all configured streams
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EACCES The camera is not in a state where buffers can be allocated
* \retval -EINVAL The configuration is not valid
*/
int Camera::allocateBuffers()
{
if (disconnected_)
return -ENODEV;
if (!stateIs(CameraConfigured))
return -EACCES;
if (activeStreams_.empty()) {
LOG(Camera, Error)
<< "Can't allocate buffers without streams";
return -EINVAL;
}
for (Stream *stream : activeStreams_) {
int ret = pipe_->allocateBuffers(this, stream);
if (ret) {
LOG(Camera, Error) << "Failed to allocate buffers";
freeBuffers();
return ret;
}
}
state_ = CameraPrepared;
return 0;
}
/**
* \brief Release all buffers from allocated pools in each stream
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -EACCES The camera is not in a state where buffers can be freed
*/
int Camera::freeBuffers()
{
if (!stateIs(CameraPrepared))
return -EACCES;
for (Stream *stream : activeStreams_) {
if (!stream->bufferPool().count())
continue;
/*
* All mappings must be destroyed before buffers can be freed
* by the V4L2 device that has allocated them.
*/
stream->bufferPool().destroyBuffers();
pipe_->freeBuffers(this, stream);
}
state_ = CameraConfigured;
return 0;
}
/**
* \brief Create a request object for the camera
*
* This method creates an empty request for the application to fill with
* buffers and paramaters, and queue for capture.
*
* The ownership of the returned request is passed to the caller, which is
* responsible for either queueing the request or deleting it.
*
* This function shall only be called when the camera is in the Prepared
* or Running state, see \ref camera_operation.
*
* \return A pointer to the newly created request, or nullptr on error
*/
Request *Camera::createRequest()
{
if (disconnected_ || !stateBetween(CameraPrepared, CameraRunning))
return nullptr;
return new Request(this);
}
/**
* \brief Queue a request to the camera
* \param[in] request The request to queue to the camera
*
* This method queues a \a request allocated with createRequest() to the camera
* for capture. Once the request has been queued, the camera will notify its
* completion through the \ref requestCompleted signal.
*
* Ownership of the request is transferred to the camera. It will be deleted
* automatically after it completes.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EACCES The camera is not running so requests can't be queued
*/
int Camera::queueRequest(Request *request)
{
if (disconnected_)
return -ENODEV;
if (!stateIs(CameraRunning))
return -EACCES;
int ret = request->prepare();
if (ret) {
LOG(Camera, Error) << "Failed to prepare request";
return ret;
}
return pipe_->queueRequest(this, request);
}
/**
* \brief Start capture from camera
*
* Start the camera capture session. Once the camera is started the application
* can queue requests to the camera to process and return to the application
* until the capture session is terminated with \a stop().
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EACCES The camera is not in a state where it can be started
*/
int Camera::start()
{
if (disconnected_)
return -ENODEV;
if (!stateIs(CameraPrepared))
return -EACCES;
LOG(Camera, Debug) << "Starting capture";
int ret = pipe_->start(this);
if (ret)
return ret;
state_ = CameraRunning;
return 0;
}
/**
* \brief Stop capture from camera
*
* This method stops capturing and processing requests immediately. All pending
* requests are cancelled and complete synchronously in an error state.
*
* This function affects the state of the camera, see \ref camera_operation.
*
* \return 0 on success or a negative error code otherwise
* \retval -ENODEV The camera has been disconnected from the system
* \retval -EACCES The camera is not running so can't be stopped
*/
int Camera::stop()
{
if (disconnected_)
return -ENODEV;
if (!stateIs(CameraRunning))
return -EACCES;
LOG(Camera, Debug) << "Stopping capture";
state_ = CameraPrepared;
pipe_->stop(this);
return 0;
}
/**
* \brief Handle request completion and notify application
* \param[in] request The request that has completed
*
* This function is called by the pipeline handler to notify the camera that
* the request has completed. It emits the requestCompleted signal and deletes
* the request.
*/
void Camera::requestComplete(Request *request)
{
std::map<Stream *, Buffer *> buffers(std::move(request->bufferMap_));
requestCompleted.emit(request, buffers);
delete request;
}
} /* namespace libcamera */
|