libcamera v0.5.1
Supporting cameras in Linux since 2019
Loading...
Searching...
No Matches
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 <memory>
12#include <optional>
13#include <ostream>
14#include <stdint.h>
15#include <string>
16#include <unordered_set>
17#include <vector>
18
19#include <linux/videodev2.h>
20
22#include <libcamera/base/log.h>
27
30#include <libcamera/geometry.h>
32
36
37namespace libcamera {
38
39class EventNotifier;
40class MediaDevice;
41class MediaEntity;
42
43struct V4L2Capability final : v4l2_capability {
44 const char *driver() const
45 {
46 return reinterpret_cast<const char *>(v4l2_capability::driver);
47 }
48 const char *card() const
49 {
50 return reinterpret_cast<const char *>(v4l2_capability::card);
51 }
52 const char *bus_info() const
53 {
54 return reinterpret_cast<const char *>(v4l2_capability::bus_info);
55 }
56 unsigned int device_caps() const
57 {
58 return capabilities & V4L2_CAP_DEVICE_CAPS
59 ? v4l2_capability::device_caps
60 : v4l2_capability::capabilities;
61 }
62 bool isMultiplanar() const
63 {
64 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE_MPLANE |
65 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
66 V4L2_CAP_VIDEO_M2M_MPLANE);
67 }
68 bool isCapture() const
69 {
70 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
71 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
72 V4L2_CAP_META_CAPTURE);
73 }
74 bool isOutput() const
75 {
76 return device_caps() & (V4L2_CAP_VIDEO_OUTPUT |
77 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
78 V4L2_CAP_META_OUTPUT);
79 }
80 bool isVideo() const
81 {
82 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
83 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
84 V4L2_CAP_VIDEO_OUTPUT |
85 V4L2_CAP_VIDEO_OUTPUT_MPLANE);
86 }
87 bool isM2M() const
88 {
89 return device_caps() & (V4L2_CAP_VIDEO_M2M |
90 V4L2_CAP_VIDEO_M2M_MPLANE);
91 }
92 bool isMeta() const
93 {
94 return device_caps() & (V4L2_CAP_META_CAPTURE |
95 V4L2_CAP_META_OUTPUT);
96 }
97 bool isVideoCapture() const
98 {
99 return isVideo() && isCapture();
100 }
101 bool isVideoOutput() const
102 {
103 return isVideo() && isOutput();
104 }
105 bool isMetaCapture() const
106 {
107 return isMeta() && isCapture();
108 }
109 bool isMetaOutput() const
110 {
111 return isMeta() && isOutput();
112 }
113 bool hasStreaming() const
114 {
115 return device_caps() & V4L2_CAP_STREAMING;
116 }
118 {
119 return device_caps() & V4L2_CAP_IO_MC;
120 }
121};
122
124{
125public:
126 V4L2BufferCache(unsigned int numEntries);
127 V4L2BufferCache(const std::vector<std::unique_ptr<FrameBuffer>> &buffers);
129
130 bool isEmpty() const;
131 int get(const FrameBuffer &buffer);
132 void put(unsigned int index);
133
134private:
135 class Entry
136 {
137 public:
138 Entry();
139 Entry(bool free, uint64_t lastUsed, const FrameBuffer &buffer);
140
141 bool operator==(const FrameBuffer &buffer) const;
142
143 bool free_;
144 uint64_t lastUsed_;
145
146 private:
147 struct Plane {
148 Plane(const FrameBuffer::Plane &plane)
149 : fd(plane.fd.get()), length(plane.length)
150 {
151 }
152
153 int fd;
154 unsigned int length;
155 };
156
157 std::vector<Plane> planes_;
158 };
159
160 uint64_t lastUsedCounter_;
161 std::vector<Entry> cache_;
162 /* \todo Expose the miss counter through an instrumentation API. */
163 unsigned int missCounter_;
164};
165
167{
168public:
169 struct Plane {
170 uint32_t size = 0;
171 uint32_t bpl = 0;
172 };
173
176 std::optional<ColorSpace> colorSpace;
177
178 std::array<Plane, 3> planes;
179 unsigned int planesCount = 0;
180
181 const std::string toString() const;
182};
183
184std::ostream &operator<<(std::ostream &out, const V4L2DeviceFormat &f);
185
187{
188public:
189 using Formats = std::map<V4L2PixelFormat, std::vector<SizeRange>>;
190
191 explicit V4L2VideoDevice(const std::string &deviceNode);
192 explicit V4L2VideoDevice(const MediaEntity *entity);
194
195 int open();
196 int open(SharedFD handle, enum v4l2_buf_type type);
197 void close();
198
199 const char *driverName() const { return caps_.driver(); }
200 const char *deviceName() const { return caps_.card(); }
201 const char *busName() const { return caps_.bus_info(); }
202
203 const V4L2Capability &caps() const { return caps_; }
204
205 int getFormat(V4L2DeviceFormat *format);
206 int tryFormat(V4L2DeviceFormat *format);
207 int setFormat(V4L2DeviceFormat *format);
208 Formats formats(uint32_t code = 0);
209
210 int getSelection(unsigned int target, Rectangle *rect);
211 int setSelection(unsigned int target, Rectangle *rect);
212
213 int allocateBuffers(unsigned int count,
214 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
215 int exportBuffers(unsigned int count,
216 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
217 int importBuffers(unsigned int count);
218 int releaseBuffers();
219
220 int queueBuffer(FrameBuffer *buffer);
222
223 int streamOn();
224 int streamOff();
225
228
229 static std::unique_ptr<V4L2VideoDevice>
230 fromEntityName(const MediaDevice *media, const std::string &entity);
231
232 V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const;
233
234protected:
235 std::string logPrefix() const override;
236
237private:
239
240 enum class State {
241 Streaming,
242 Stopping,
243 Stopped,
244 };
245
246 int initFormats();
247
248 int getFormatMeta(V4L2DeviceFormat *format);
249 int trySetFormatMeta(V4L2DeviceFormat *format, bool set);
250
251 int getFormatMultiplane(V4L2DeviceFormat *format);
252 int trySetFormatMultiplane(V4L2DeviceFormat *format, bool set);
253
254 int getFormatSingleplane(V4L2DeviceFormat *format);
255 int trySetFormatSingleplane(V4L2DeviceFormat *format, bool set);
256
257 std::vector<V4L2PixelFormat> enumPixelformats(uint32_t code);
258 std::vector<SizeRange> enumSizes(V4L2PixelFormat pixelFormat);
259
260 int requestBuffers(unsigned int count, enum v4l2_memory memoryType);
261 int createBuffers(unsigned int count,
262 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
263 std::unique_ptr<FrameBuffer> createBuffer(unsigned int index);
264 UniqueFD exportDmabufFd(unsigned int index, unsigned int plane);
265
266 void bufferAvailable();
267 FrameBuffer *dequeueBuffer();
268
269 void watchdogExpired();
270
271 template<typename T>
272 static std::optional<ColorSpace> toColorSpace(const T &v4l2Format);
273
274 V4L2Capability caps_;
275 V4L2DeviceFormat format_;
276 const PixelFormatInfo *formatInfo_;
277 std::unordered_set<V4L2PixelFormat> pixelFormats_;
278
279 enum v4l2_buf_type bufferType_;
280 enum v4l2_memory memoryType_;
281
282 V4L2BufferCache *cache_;
283 std::map<unsigned int, FrameBuffer *> queuedBuffers_;
284
285 EventNotifier *fdBufferNotifier_;
286
287 State state_;
288 std::optional<unsigned int> firstFrame_;
289
290 Timer watchdog_;
291 utils::Duration watchdogDuration_;
292};
293
295{
296public:
297 V4L2M2MDevice(const std::string &deviceNode);
299
300 int open();
301 void close();
302
303 V4L2VideoDevice *output() { return output_; }
304 V4L2VideoDevice *capture() { return capture_; }
305
306private:
307 std::string deviceNode_;
308
309 V4L2VideoDevice *output_;
310 V4L2VideoDevice *capture_;
311};
312
313} /* namespace libcamera */
Utilities to help constructing class interfaces.
#define LIBCAMERA_DISABLE_COPY(klass)
Disable copy construction and assignment of the klass.
Definition class.h:27
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:241
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:51
Single-shot timer interface.
Definition timer.h:22
unique_ptr-like wrapper for a file descriptor
Definition unique_fd.h:17
Hot cache of associations between V4L2 buffer indexes and FrameBuffer.
Definition v4l2_videodevice.h:124
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:167
V4L2PixelFormat fourcc
The fourcc code describing the pixel encoding scheme.
Definition v4l2_videodevice.h:174
const std::string toString() const
Assemble and return a string describing the format.
Definition v4l2_videodevice.cpp:432
unsigned int planesCount
The number of valid data planes.
Definition v4l2_videodevice.h:179
std::optional< ColorSpace > colorSpace
The color space of the pixels.
Definition v4l2_videodevice.h:176
std::array< Plane, 3 > planes
The per-plane memory size information.
Definition v4l2_videodevice.h:178
Size size
The image size in pixels.
Definition v4l2_videodevice.h:175
const std::string & deviceNode() const
Retrieve the device node path.
Definition v4l2_device.h:45
V4L2Device(const std::string &deviceNode)
Construct a V4L2Device.
Definition v4l2_device.cpp:59
void close()
Close the memory-to-memory device, releasing any resources acquired by open()
Definition v4l2_videodevice.cpp:2245
V4L2VideoDevice * output()
Retrieve the output V4L2VideoDevice instance.
Definition v4l2_videodevice.h:303
V4L2VideoDevice * capture()
Retrieve the capture V4L2VideoDevice instance.
Definition v4l2_videodevice.h:304
int open()
Open a V4L2 Memory to Memory device.
Definition v4l2_videodevice.cpp:2208
V4L2M2MDevice(const std::string &deviceNode)
Create a new V4L2M2MDevice from the deviceNode.
Definition v4l2_videodevice.cpp:2187
V4L2 pixel format FourCC wrapper.
Definition v4l2_pixelformat.h:24
V4L2VideoDevice object and API.
Definition v4l2_videodevice.h:187
int importBuffers(unsigned int count)
Prepare the device to import count buffers.
Definition v4l2_videodevice.cpp:1587
int releaseBuffers()
Release resources allocated by allocateBuffers() or importBuffers()
Definition v4l2_videodevice.cpp:1615
int tryFormat(V4L2DeviceFormat *format)
Try an image format on the V4L2 video device.
Definition v4l2_videodevice.cpp:830
int allocateBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Allocate and export buffers from the video device.
Definition v4l2_videodevice.cpp:1368
std::string logPrefix() const override
Retrieve a string to be prefixed to the log message.
Definition v4l2_videodevice.cpp:792
std::map< V4L2PixelFormat, std::vector< SizeRange > > Formats
A map of supported V4L2 pixel formats to frame sizes.
Definition v4l2_videodevice.h:189
void setDequeueTimeout(utils::Duration timeout)
Set the dequeue timeout value.
Definition v4l2_videodevice.cpp:2066
int open()
Open the V4L2 video device node and query its capabilities.
Definition v4l2_videodevice.cpp:569
Signal< FrameBuffer * > bufferReady
A Signal emitted when a framebuffer completes.
Definition v4l2_videodevice.h:221
const char * busName() const
Retrieve the location of the device in the system.
Definition v4l2_videodevice.h:201
int streamOn()
Start the video stream.
Definition v4l2_videodevice.cpp:1979
int queueBuffer(FrameBuffer *buffer)
Queue a buffer to the video device.
Definition v4l2_videodevice.cpp:1645
V4L2VideoDevice(const std::string &deviceNode)
Construct a V4L2VideoDevice.
Definition v4l2_videodevice.cpp:534
int streamOff()
Stop the video stream.
Definition v4l2_videodevice.cpp:2012
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:1417
Signal dequeueTimeout
A Signal emitted when the dequeue watchdog timer expires.
Definition v4l2_videodevice.h:227
const char * driverName() const
Retrieve the name of the V4L2 device driver.
Definition v4l2_videodevice.h:199
void close()
Close the video device, releasing any resources acquired by open()
Definition v4l2_videodevice.cpp:755
const V4L2Capability & caps() const
Retrieve the device V4L2 capabilities.
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:2103
int setSelection(unsigned int target, Rectangle *rect)
Set a selection rectangle rect for target.
Definition v4l2_videodevice.cpp:1281
V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const
Convert PixelFormat to a V4L2PixelFormat supported by the device.
Definition v4l2_videodevice.cpp:2134
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
const char * deviceName() const
Retrieve the name of the V4L2 video device.
Definition v4l2_videodevice.h:200
Helper class from std::chrono::duration that represents a time duration in nanoseconds with double pr...
Definition utils.h:371
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
libcamera pixel format
Signal & slot implementation.
A memory region to store a single plane of a frame.
Definition framebuffer.h:53
SharedFD fd
The dmabuf file descriptor.
Definition framebuffer.h:55
unsigned int length
The plane length in bytes.
Definition framebuffer.h:57
struct v4l2_capability object wrapper and helpers
Definition v4l2_videodevice.h:43
bool hasStreaming() const
Determine if the video device can perform Streaming I/O.
Definition v4l2_videodevice.h:113
const char * bus_info() const
Retrieve the location of the video device in the system.
Definition v4l2_videodevice.h:52
bool isVideoCapture() const
Identify if the video device captures images.
Definition v4l2_videodevice.h:97
bool isMultiplanar() const
Identify if the video device implements the V4L2 multiplanar APIs.
Definition v4l2_videodevice.h:62
bool isOutput() const
Identify if the video device outputs data.
Definition v4l2_videodevice.h:74
bool isMetaOutput() const
Identify if the video device outputs image meta-data.
Definition v4l2_videodevice.h:109
bool isMeta() const
Identify if the video device captures or outputs image meta-data.
Definition v4l2_videodevice.h:92
bool isMetaCapture() const
Identify if the video device captures image meta-data.
Definition v4l2_videodevice.h:105
bool hasMediaController() const
Determine if the video device uses Media Controller to configure I/O.
Definition v4l2_videodevice.h:117
const char * driver() const
Retrieve the driver module name.
Definition v4l2_videodevice.h:44
bool isM2M() const
Identify if the device is a Memory-to-Memory device.
Definition v4l2_videodevice.h:87
bool isVideoOutput() const
Identify if the video device outputs images.
Definition v4l2_videodevice.h:101
bool isVideo() const
Identify if the video device captures or outputs images.
Definition v4l2_videodevice.h:80
bool isCapture() const
Identify if the video device captures data.
Definition v4l2_videodevice.h:68
unsigned int device_caps() const
Retrieve the capabilities of the video device.
Definition v4l2_videodevice.h:56
const char * card() const
Retrieve the video device card name.
Definition v4l2_videodevice.h:48
Per-plane memory size information.
Definition v4l2_videodevice.h:169
uint32_t size
The plane total memory size (in bytes)
Definition v4l2_videodevice.h:170
uint32_t bpl
The plane line stride (in bytes)
Definition v4l2_videodevice.h:171
Generic timer.
File descriptor wrapper that owns a file descriptor.
Miscellaneous utility functions.
Common base for V4L2 devices and subdevices.
V4L2 Pixel Format.