libcamera v0.4.0+51-ca36c77f
Supporting cameras in Linux since 2019
v4l2_videodevice.h
Go to the documentation of this file.
1/* SPDX-License-Identifier: LGPL-2.1-or-later */
2/*
3 * Copyright (C) 2019, Google Inc.
4 *
5 * V4L2 Video Device
6 */
7
8#pragma once
9
10#include <array>
11#include <atomic>
12#include <memory>
13#include <optional>
14#include <ostream>
15#include <queue>
16#include <stdint.h>
17#include <string>
18#include <unordered_set>
19#include <vector>
20
21#include <linux/videodev2.h>
22
24#include <libcamera/base/log.h>
29
32#include <libcamera/geometry.h>
34
38
39namespace libcamera {
40
41class EventNotifier;
42class MediaDevice;
43class MediaEntity;
44
45struct V4L2Capability final : v4l2_capability {
46 const char *driver() const
47 {
48 return reinterpret_cast<const char *>(v4l2_capability::driver);
49 }
50 const char *card() const
51 {
52 return reinterpret_cast<const char *>(v4l2_capability::card);
53 }
54 const char *bus_info() const
55 {
56 return reinterpret_cast<const char *>(v4l2_capability::bus_info);
57 }
58 unsigned int device_caps() const
59 {
60 return capabilities & V4L2_CAP_DEVICE_CAPS
61 ? v4l2_capability::device_caps
62 : v4l2_capability::capabilities;
63 }
64 bool isMultiplanar() const
65 {
66 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE_MPLANE |
67 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
68 V4L2_CAP_VIDEO_M2M_MPLANE);
69 }
70 bool isCapture() const
71 {
72 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
73 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
74 V4L2_CAP_META_CAPTURE);
75 }
76 bool isOutput() const
77 {
78 return device_caps() & (V4L2_CAP_VIDEO_OUTPUT |
79 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
80 V4L2_CAP_META_OUTPUT);
81 }
82 bool isVideo() const
83 {
84 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
85 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
86 V4L2_CAP_VIDEO_OUTPUT |
87 V4L2_CAP_VIDEO_OUTPUT_MPLANE);
88 }
89 bool isM2M() const
90 {
91 return device_caps() & (V4L2_CAP_VIDEO_M2M |
92 V4L2_CAP_VIDEO_M2M_MPLANE);
93 }
94 bool isMeta() const
95 {
96 return device_caps() & (V4L2_CAP_META_CAPTURE |
97 V4L2_CAP_META_OUTPUT);
98 }
99 bool isVideoCapture() const
100 {
101 return isVideo() && isCapture();
102 }
103 bool isVideoOutput() const
104 {
105 return isVideo() && isOutput();
106 }
107 bool isMetaCapture() const
108 {
109 return isMeta() && isCapture();
110 }
111 bool isMetaOutput() const
112 {
113 return isMeta() && isOutput();
114 }
115 bool hasStreaming() const
116 {
117 return device_caps() & V4L2_CAP_STREAMING;
118 }
120 {
121 return device_caps() & V4L2_CAP_IO_MC;
122 }
123};
124
126{
127public:
128 V4L2BufferCache(unsigned int numEntries);
129 V4L2BufferCache(const std::vector<std::unique_ptr<FrameBuffer>> &buffers);
131
132 bool isEmpty() const;
133 int get(const FrameBuffer &buffer);
134 void put(unsigned int index);
135
136private:
137 class Entry
138 {
139 public:
140 Entry();
141 Entry(bool free, uint64_t lastUsed, const FrameBuffer &buffer);
142
143 bool operator==(const FrameBuffer &buffer) const;
144
145 bool free_;
146 uint64_t lastUsed_;
147
148 private:
149 struct Plane {
150 Plane(const FrameBuffer::Plane &plane)
151 : fd(plane.fd.get()), length(plane.length)
152 {
153 }
154
155 int fd;
156 unsigned int length;
157 };
158
159 std::vector<Plane> planes_;
160 };
161
162 std::atomic<uint64_t> lastUsedCounter_;
163 std::vector<Entry> cache_;
164 /* \todo Expose the miss counter through an instrumentation API. */
165 unsigned int missCounter_;
166};
167
169{
170public:
171 struct Plane {
172 uint32_t size = 0;
173 uint32_t bpl = 0;
174 };
175
178 std::optional<ColorSpace> colorSpace;
179
180 std::array<Plane, 3> planes;
181 unsigned int planesCount = 0;
182
183 const std::string toString() const;
184};
185
186std::ostream &operator<<(std::ostream &out, const V4L2DeviceFormat &f);
187
189{
190public:
191 using Formats = std::map<V4L2PixelFormat, std::vector<SizeRange>>;
192
193 explicit V4L2VideoDevice(const std::string &deviceNode);
194 explicit V4L2VideoDevice(const MediaEntity *entity);
196
197 int open();
198 int open(SharedFD handle, enum v4l2_buf_type type);
199 void close();
200
201 const char *driverName() const { return caps_.driver(); }
202 const char *deviceName() const { return caps_.card(); }
203 const char *busName() const { return caps_.bus_info(); }
204
205 const V4L2Capability &caps() const { return caps_; }
206
207 int getFormat(V4L2DeviceFormat *format);
208 int tryFormat(V4L2DeviceFormat *format);
209 int setFormat(V4L2DeviceFormat *format);
210 Formats formats(uint32_t code = 0);
211
212 int getSelection(unsigned int target, Rectangle *rect);
213 int setSelection(unsigned int target, Rectangle *rect);
214
215 int allocateBuffers(unsigned int count,
216 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
217 int exportBuffers(unsigned int count,
218 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
219 int importBuffers(unsigned int count);
220 int releaseBuffers();
221
222 int queueBuffer(FrameBuffer *buffer);
224
225 int streamOn();
226 int streamOff();
227
230
231 static std::unique_ptr<V4L2VideoDevice>
232 fromEntityName(const MediaDevice *media, const std::string &entity);
233
234 V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const;
235
236protected:
237 std::string logPrefix() const override;
238
239private:
241
242 enum class State {
243 Streaming,
244 Stopping,
245 Stopped,
246 };
247
248 int initFormats();
249
250 int getFormatMeta(V4L2DeviceFormat *format);
251 int trySetFormatMeta(V4L2DeviceFormat *format, bool set);
252
253 int getFormatMultiplane(V4L2DeviceFormat *format);
254 int trySetFormatMultiplane(V4L2DeviceFormat *format, bool set);
255
256 int getFormatSingleplane(V4L2DeviceFormat *format);
257 int trySetFormatSingleplane(V4L2DeviceFormat *format, bool set);
258
259 std::vector<V4L2PixelFormat> enumPixelformats(uint32_t code);
260 std::vector<SizeRange> enumSizes(V4L2PixelFormat pixelFormat);
261
262 int requestBuffers(unsigned int count, enum v4l2_memory memoryType);
263 int createBuffers(unsigned int count,
264 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
265 std::unique_ptr<FrameBuffer> createBuffer(unsigned int index);
266 UniqueFD exportDmabufFd(unsigned int index, unsigned int plane);
267
268 void bufferAvailable();
269 FrameBuffer *dequeueBuffer();
270
271 int queueToDevice(FrameBuffer *buffer);
272
273 void watchdogExpired();
274
275 template<typename T>
276 static std::optional<ColorSpace> toColorSpace(const T &v4l2Format);
277
278 V4L2Capability caps_;
279 V4L2DeviceFormat format_;
280 const PixelFormatInfo *formatInfo_;
281 std::unordered_set<V4L2PixelFormat> pixelFormats_;
282
283 enum v4l2_buf_type bufferType_;
284 enum v4l2_memory memoryType_;
285
286 V4L2BufferCache *cache_;
287 std::map<unsigned int, FrameBuffer *> queuedBuffers_;
288 std::queue<FrameBuffer *> pendingBuffersToQueue_;
289
290 EventNotifier *fdBufferNotifier_;
291
292 State state_;
293 std::optional<unsigned int> firstFrame_;
294
295 Timer watchdog_;
296 utils::Duration watchdogDuration_;
297};
298
300{
301public:
302 V4L2M2MDevice(const std::string &deviceNode);
304
305 int open();
306 void close();
307
308 V4L2VideoDevice *output() { return output_; }
309 V4L2VideoDevice *capture() { return capture_; }
310
311private:
312 std::string deviceNode_;
313
314 V4L2VideoDevice *output_;
315 V4L2VideoDevice *capture_;
316};
317
318} /* namespace libcamera */
Utilities to help constructing class interfaces.
#define LIBCAMERA_DISABLE_COPY(klass)
Disable copy construction and assignment of the klass.
Notify of activity on a file descriptor.
Definition: event_notifier.h:20
Frame buffer data and its associated dynamic metadata.
Definition: framebuffer.h:49
The MediaDevice represents a Media Controller device with its full graph of connected objects.
Definition: media_device.h:25
The MediaEntity represents an entity in the media graph.
Definition: media_object.h:97
Information about pixel formats.
Definition: formats.h:21
libcamera image pixel format
Definition: pixel_format.h:17
Describe a rectangle's position and dimensions.
Definition: geometry.h:243
RAII-style wrapper for file descriptors.
Definition: shared_fd.h:17
int get() const
Retrieve the numerical file descriptor.
Definition: shared_fd.h:30
Generic signal and slot communication mechanism.
Definition: signal.h:39
Describe a two-dimensional size.
Definition: geometry.h:53
Single-shot timer interface.
Definition: timer.h:22
unique_ptr-like wrapper for a file descriptor
Definition: unique_fd.h:18
Hot cache of associations between V4L2 buffer indexes and FrameBuffer.
Definition: v4l2_videodevice.h:126
V4L2BufferCache(unsigned int numEntries)
Create an empty cache with numEntries entries.
Definition: v4l2_videodevice.cpp:174
int get(const FrameBuffer &buffer)
Find the best V4L2 buffer for a FrameBuffer.
Definition: v4l2_videodevice.cpp:229
bool isEmpty() const
Check if all the entries in the cache are unused.
Definition: v4l2_videodevice.cpp:206
void put(unsigned int index)
Mark buffer index as free in the cache.
Definition: v4l2_videodevice.cpp:271
The V4L2 video device image format and sizes.
Definition: v4l2_videodevice.h:169
V4L2PixelFormat fourcc
The fourcc code describing the pixel encoding scheme.
Definition: v4l2_videodevice.h:176
const std::string toString() const
Assemble and return a string describing the format.
Definition: v4l2_videodevice.cpp:432
std::array< Plane, 3 > planes
The per-plane memory size information.
Definition: v4l2_videodevice.h:180
Size size
The image size in pixels.
Definition: v4l2_videodevice.h:177
std::optional< ColorSpace > colorSpace
The color space of the pixels.
Definition: v4l2_videodevice.h:178
unsigned int planesCount
The number of valid data planes.
Definition: v4l2_videodevice.h:181
Base class for V4L2VideoDevice and V4L2Subdevice.
Definition: v4l2_device.h:32
const std::string & deviceNode() const
Retrieve the device node path.
Definition: v4l2_device.h:44
Memory-to-Memory video device.
Definition: v4l2_videodevice.h:300
V4L2VideoDevice * capture()
Retrieve the capture V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:309
void close()
Close the memory-to-memory device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:2307
int open()
Open a V4L2 Memory to Memory device.
Definition: v4l2_videodevice.cpp:2270
V4L2VideoDevice * output()
Retrieve the output V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:308
V4L2M2MDevice(const std::string &deviceNode)
Create a new V4L2M2MDevice from the deviceNode.
Definition: v4l2_videodevice.cpp:2249
V4L2 pixel format FourCC wrapper.
Definition: v4l2_pixelformat.h:24
V4L2VideoDevice object and API.
Definition: v4l2_videodevice.h:189
std::map< V4L2PixelFormat, std::vector< SizeRange > > Formats
A map of supported V4L2 pixel formats to frame sizes.
Definition: v4l2_videodevice.h:191
Signal dequeueTimeout
A Signal emitted when the dequeue watchdog timer expires.
Definition: v4l2_videodevice.h:229
const char * driverName() const
Retrieve the name of the V4L2 device driver.
Definition: v4l2_videodevice.h:201
int importBuffers(unsigned int count)
Prepare the device to import count buffers.
Definition: v4l2_videodevice.cpp:1586
int releaseBuffers()
Release resources allocated by allocateBuffers() or importBuffers()
Definition: v4l2_videodevice.cpp:1614
int tryFormat(V4L2DeviceFormat *format)
Try an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:830
const char * deviceName() const
Retrieve the name of the V4L2 video device.
Definition: v4l2_videodevice.h:202
int allocateBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Allocate and export buffers from the video device.
Definition: v4l2_videodevice.cpp:1367
std::string logPrefix() const override
Retrieve a string to be prefixed to the log message.
Definition: v4l2_videodevice.cpp:792
void setDequeueTimeout(utils::Duration timeout)
Set the dequeue timeout value.
Definition: v4l2_videodevice.cpp:2128
int open()
Open the V4L2 video device node and query its capabilities.
Definition: v4l2_videodevice.cpp:569
int streamOn()
Start the video stream.
Definition: v4l2_videodevice.cpp:2041
int queueBuffer(FrameBuffer *buffer)
Queue a buffer to the video device if possible.
Definition: v4l2_videodevice.cpp:1648
V4L2VideoDevice(const std::string &deviceNode)
Construct a V4L2VideoDevice.
Definition: v4l2_videodevice.cpp:534
int streamOff()
Stop the video stream.
Definition: v4l2_videodevice.cpp:2074
int getFormat(V4L2DeviceFormat *format)
Retrieve the image format set on the V4L2 video device.
Definition: v4l2_videodevice.cpp:803
int getSelection(unsigned int target, Rectangle *rect)
Get the selection rectangle for target.
Definition: v4l2_videodevice.cpp:1249
int exportBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Export buffers from the video device.
Definition: v4l2_videodevice.cpp:1416
void close()
Close the video device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:755
const char * busName() const
Retrieve the location of the device in the system.
Definition: v4l2_videodevice.h:203
static std::unique_ptr< V4L2VideoDevice > fromEntityName(const MediaDevice *media, const std::string &entity)
Create a new video device instance from entity in media device media.
Definition: v4l2_videodevice.cpp:2165
int setSelection(unsigned int target, Rectangle *rect)
Set a selection rectangle rect for target.
Definition: v4l2_videodevice.cpp:1281
const V4L2Capability & caps() const
Retrieve the device V4L2 capabilities.
Definition: v4l2_videodevice.h:205
Signal< FrameBuffer * > bufferReady
A Signal emitted when a framebuffer completes.
Definition: v4l2_videodevice.h:223
V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const
Convert PixelFormat to a V4L2PixelFormat supported by the device.
Definition: v4l2_videodevice.cpp:2196
int setFormat(V4L2DeviceFormat *format)
Configure an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:856
Formats formats(uint32_t code=0)
Enumerate all pixel formats and frame sizes.
Definition: v4l2_videodevice.cpp:1126
Helper class from std::chrono::duration that represents a time duration in nanoseconds with double pr...
Definition: utils.h:370
Class and enums to represent color spaces.
Frame buffer handling.
Data structures related to geometric objects.
Types and helper functions to handle libcamera image formats.
Logging infrastructure.
Top-level libcamera namespace.
Definition: backtrace.h:17
std::ostream & operator<<(std::ostream &out, const Point &p)
Insert a text representation of a Point into an output stream.
Definition: geometry.cpp:91
bool operator==(const ColorSpace &lhs, const ColorSpace &rhs)
Compare color spaces for equality.
Definition: color_space.cpp:506
libcamera pixel format
Signal & slot implementation.
A memory region to store a single plane of a frame.
Definition: framebuffer.h:53
unsigned int length
The plane length in bytes.
Definition: framebuffer.h:57
SharedFD fd
The dmabuf file descriptor.
Definition: framebuffer.h:55
struct v4l2_capability object wrapper and helpers
Definition: v4l2_videodevice.h:45
bool hasStreaming() const
Determine if the video device can perform Streaming I/O.
Definition: v4l2_videodevice.h:115
unsigned int device_caps() const
Retrieve the capabilities of the video device.
Definition: v4l2_videodevice.h:58
bool isVideoOutput() const
Identify if the video device outputs images.
Definition: v4l2_videodevice.h:103
bool isM2M() const
Identify if the device is a Memory-to-Memory device.
Definition: v4l2_videodevice.h:89
bool isMetaCapture() const
Identify if the video device captures image meta-data.
Definition: v4l2_videodevice.h:107
bool hasMediaController() const
Determine if the video device uses Media Controller to configure I/O.
Definition: v4l2_videodevice.h:119
bool isOutput() const
Identify if the video device outputs data.
Definition: v4l2_videodevice.h:76
bool isVideoCapture() const
Identify if the video device captures images.
Definition: v4l2_videodevice.h:99
bool isMultiplanar() const
Identify if the video device implements the V4L2 multiplanar APIs.
Definition: v4l2_videodevice.h:64
bool isMeta() const
Identify if the video device captures or outputs image meta-data.
Definition: v4l2_videodevice.h:94
bool isCapture() const
Identify if the video device captures data.
Definition: v4l2_videodevice.h:70
bool isMetaOutput() const
Identify if the video device outputs image meta-data.
Definition: v4l2_videodevice.h:111
const char * bus_info() const
Retrieve the location of the video device in the system.
Definition: v4l2_videodevice.h:54
const char * card() const
Retrieve the video device card name.
Definition: v4l2_videodevice.h:50
bool isVideo() const
Identify if the video device captures or outputs images.
Definition: v4l2_videodevice.h:82
const char * driver() const
Retrieve the driver module name.
Definition: v4l2_videodevice.h:46
Per-plane memory size information.
Definition: v4l2_videodevice.h:171
uint32_t size
The plane total memory size (in bytes)
Definition: v4l2_videodevice.h:172
uint32_t bpl
The plane line stride (in bytes)
Definition: v4l2_videodevice.h:173
Generic timer.
File descriptor wrapper that owns a file descriptor.
Miscellaneous utility functions.
Common base for V4L2 devices and subdevices.
V4L2 Pixel Format.