libcamera v0.0.0
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_videodevice.h - V4L2 Video Device
6 */
7
8#pragma once
9
10#include <array>
11#include <atomic>
12#include <memory>
13#include <optional>
14#include <stdint.h>
15#include <string>
16#include <vector>
17
18#include <linux/videodev2.h>
19
21#include <libcamera/base/log.h>
24
27#include <libcamera/geometry.h>
29
33
34namespace libcamera {
35
36class EventNotifier;
37class MediaDevice;
38class MediaEntity;
39
40struct V4L2Capability final : v4l2_capability {
41 const char *driver() const
42 {
43 return reinterpret_cast<const char *>(v4l2_capability::driver);
44 }
45 const char *card() const
46 {
47 return reinterpret_cast<const char *>(v4l2_capability::card);
48 }
49 const char *bus_info() const
50 {
51 return reinterpret_cast<const char *>(v4l2_capability::bus_info);
52 }
53 unsigned int device_caps() const
54 {
55 return capabilities & V4L2_CAP_DEVICE_CAPS
56 ? v4l2_capability::device_caps
57 : v4l2_capability::capabilities;
58 }
59 bool isMultiplanar() const
60 {
61 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE_MPLANE |
62 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
63 V4L2_CAP_VIDEO_M2M_MPLANE);
64 }
65 bool isCapture() const
66 {
67 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
68 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
69 V4L2_CAP_META_CAPTURE);
70 }
71 bool isOutput() const
72 {
73 return device_caps() & (V4L2_CAP_VIDEO_OUTPUT |
74 V4L2_CAP_VIDEO_OUTPUT_MPLANE |
75 V4L2_CAP_META_OUTPUT);
76 }
77 bool isVideo() const
78 {
79 return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
80 V4L2_CAP_VIDEO_CAPTURE_MPLANE |
81 V4L2_CAP_VIDEO_OUTPUT |
82 V4L2_CAP_VIDEO_OUTPUT_MPLANE);
83 }
84 bool isM2M() const
85 {
86 return device_caps() & (V4L2_CAP_VIDEO_M2M |
87 V4L2_CAP_VIDEO_M2M_MPLANE);
88 }
89 bool isMeta() const
90 {
91 return device_caps() & (V4L2_CAP_META_CAPTURE |
92 V4L2_CAP_META_OUTPUT);
93 }
94 bool isVideoCapture() const
95 {
96 return isVideo() && isCapture();
97 }
98 bool isVideoOutput() const
99 {
100 return isVideo() && isOutput();
101 }
102 bool isMetaCapture() const
103 {
104 return isMeta() && isCapture();
105 }
106 bool isMetaOutput() const
107 {
108 return isMeta() && isOutput();
109 }
110 bool hasStreaming() const
111 {
112 return device_caps() & V4L2_CAP_STREAMING;
113 }
115 {
116 return device_caps() & V4L2_CAP_IO_MC;
117 }
118};
119
121{
122public:
123 V4L2BufferCache(unsigned int numEntries);
124 V4L2BufferCache(const std::vector<std::unique_ptr<FrameBuffer>> &buffers);
126
127 int get(const FrameBuffer &buffer);
128 void put(unsigned int index);
129
130private:
131 class Entry
132 {
133 public:
134 Entry();
135 Entry(bool free, uint64_t lastUsed, const FrameBuffer &buffer);
136
137 bool operator==(const FrameBuffer &buffer) const;
138
139 bool free_;
140 uint64_t lastUsed_;
141
142 private:
143 struct Plane {
144 Plane(const FrameBuffer::Plane &plane)
145 : fd(plane.fd.get()), length(plane.length)
146 {
147 }
148
149 int fd;
150 unsigned int length;
151 };
152
153 std::vector<Plane> planes_;
154 };
155
156 std::atomic<uint64_t> lastUsedCounter_;
157 std::vector<Entry> cache_;
158 /* \todo Expose the miss counter through an instrumentation API. */
159 unsigned int missCounter_;
160};
161
163{
164public:
165 struct Plane {
166 uint32_t size = 0;
167 uint32_t bpl = 0;
168 };
169
172 std::optional<ColorSpace> colorSpace;
173
174 std::array<Plane, 3> planes;
175 unsigned int planesCount = 0;
176
177 const std::string toString() const;
178};
179
181{
182public:
183 using Formats = std::map<V4L2PixelFormat, std::vector<SizeRange>>;
184
185 explicit V4L2VideoDevice(const std::string &deviceNode);
186 explicit V4L2VideoDevice(const MediaEntity *entity);
188
189 int open();
190 int open(SharedFD handle, enum v4l2_buf_type type);
191 void close();
192
193 const char *driverName() const { return caps_.driver(); }
194 const char *deviceName() const { return caps_.card(); }
195 const char *busName() const { return caps_.bus_info(); }
196
197 const V4L2Capability &caps() const { return caps_; }
198
199 int getFormat(V4L2DeviceFormat *format);
200 int tryFormat(V4L2DeviceFormat *format);
201 int setFormat(V4L2DeviceFormat *format);
202 Formats formats(uint32_t code = 0);
203
204 int setSelection(unsigned int target, Rectangle *rect);
205
206 int allocateBuffers(unsigned int count,
207 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
208 int exportBuffers(unsigned int count,
209 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
210 int importBuffers(unsigned int count);
211 int releaseBuffers();
212
213 int queueBuffer(FrameBuffer *buffer);
215
216 int streamOn();
217 int streamOff();
218
219 static std::unique_ptr<V4L2VideoDevice>
220 fromEntityName(const MediaDevice *media, const std::string &entity);
221
222protected:
223 std::string logPrefix() const override;
224
225private:
227
228 int getFormatMeta(V4L2DeviceFormat *format);
229 int trySetFormatMeta(V4L2DeviceFormat *format, bool set);
230
231 int getFormatMultiplane(V4L2DeviceFormat *format);
232 int trySetFormatMultiplane(V4L2DeviceFormat *format, bool set);
233
234 int getFormatSingleplane(V4L2DeviceFormat *format);
235 int trySetFormatSingleplane(V4L2DeviceFormat *format, bool set);
236
237 std::vector<V4L2PixelFormat> enumPixelformats(uint32_t code);
238 std::vector<SizeRange> enumSizes(V4L2PixelFormat pixelFormat);
239
240 int requestBuffers(unsigned int count, enum v4l2_memory memoryType);
241 int createBuffers(unsigned int count,
242 std::vector<std::unique_ptr<FrameBuffer>> *buffers);
243 std::unique_ptr<FrameBuffer> createBuffer(unsigned int index);
244 UniqueFD exportDmabufFd(unsigned int index, unsigned int plane);
245
246 void bufferAvailable();
247 FrameBuffer *dequeueBuffer();
248
249 V4L2Capability caps_;
250 V4L2DeviceFormat format_;
251 const PixelFormatInfo *formatInfo_;
252
253 enum v4l2_buf_type bufferType_;
254 enum v4l2_memory memoryType_;
255
256 V4L2BufferCache *cache_;
257 std::map<unsigned int, FrameBuffer *> queuedBuffers_;
258
259 EventNotifier *fdBufferNotifier_;
260
261 bool streaming_;
262};
263
265{
266public:
267 V4L2M2MDevice(const std::string &deviceNode);
269
270 int open();
271 void close();
272
273 V4L2VideoDevice *output() { return output_; }
274 V4L2VideoDevice *capture() { return capture_; }
275
276private:
277 std::string deviceNode_;
278
279 V4L2VideoDevice *output_;
280 V4L2VideoDevice *capture_;
281};
282
283} /* 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:50
The MediaDevice represents a Media Controller device with its full graph of connected objects.
Definition: media_device.h:26
The MediaEntity represents an entity in the media graph.
Definition: media_object.h:89
Information about pixel formats.
Definition: formats.h:22
Describe a rectangle's position and dimensions.
Definition: geometry.h:236
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:50
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:121
V4L2BufferCache(unsigned int numEntries)
Create an empty cache with numEntries entries.
Definition: v4l2_videodevice.cpp:175
int get(const FrameBuffer &buffer)
Find the best V4L2 buffer for a FrameBuffer.
Definition: v4l2_videodevice.cpp:217
void put(unsigned int index)
Mark buffer index as free in the cache.
Definition: v4l2_videodevice.cpp:259
The V4L2 video device image format and sizes.
Definition: v4l2_videodevice.h:163
V4L2PixelFormat fourcc
The fourcc code describing the pixel encoding scheme.
Definition: v4l2_videodevice.h:170
const std::string toString() const
Assemble and return a string describing the format.
Definition: v4l2_videodevice.cpp:420
std::array< Plane, 3 > planes
The per-plane memory size information.
Definition: v4l2_videodevice.h:174
Size size
The image size in pixels.
Definition: v4l2_videodevice.h:171
std::optional< ColorSpace > colorSpace
The color space of the pixels.
Definition: v4l2_videodevice.h:172
unsigned int planesCount
The number of valid data planes.
Definition: v4l2_videodevice.h:175
Base class for V4L2VideoDevice and V4L2Subdevice.
Definition: v4l2_device.h:30
const std::string & deviceNode() const
Retrieve the device node path.
Definition: v4l2_device.h:42
Memory-to-Memory video device.
Definition: v4l2_videodevice.h:265
V4L2VideoDevice * capture()
Retrieve the capture V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:274
void close()
Close the memory-to-memory device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:1954
int open()
Open a V4L2 Memory to Memory device.
Definition: v4l2_videodevice.cpp:1917
V4L2VideoDevice * output()
Retrieve the output V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:273
V4L2M2MDevice(const std::string &deviceNode)
Create a new V4L2M2MDevice from the deviceNode.
Definition: v4l2_videodevice.cpp:1896
V4L2 pixel format FourCC wrapper.
Definition: v4l2_pixelformat.h:21
V4L2VideoDevice object and API.
Definition: v4l2_videodevice.h:181
std::map< V4L2PixelFormat, std::vector< SizeRange > > Formats
A map of supported V4L2 pixel formats to frame sizes.
Definition: v4l2_videodevice.h:183
const char * driverName() const
Retrieve the name of the V4L2 device driver.
Definition: v4l2_videodevice.h:193
int importBuffers(unsigned int count)
Prepare the device to import count buffers.
Definition: v4l2_videodevice.cpp:1444
int releaseBuffers()
Release resources allocated by allocateBuffers() or importBuffers()
Definition: v4l2_videodevice.cpp:1472
int tryFormat(V4L2DeviceFormat *format)
Try an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:779
const char * deviceName() const
Retrieve the name of the V4L2 video device.
Definition: v4l2_videodevice.h:194
int allocateBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Allocate and export buffers from the video device.
Definition: v4l2_videodevice.cpp:1225
std::string logPrefix() const override
Retrieve a string to be prefixed to the log message.
Definition: v4l2_videodevice.cpp:748
int open()
Open the V4L2 video device node and query its capabilities.
Definition: v4l2_videodevice.cpp:541
int streamOn()
Start the video stream.
Definition: v4l2_videodevice.cpp:1788
int queueBuffer(FrameBuffer *buffer)
Queue a buffer to the video device.
Definition: v4l2_videodevice.cpp:1496
V4L2VideoDevice(const std::string &deviceNode)
Construct a V4L2VideoDevice.
Definition: v4l2_videodevice.cpp:508
int streamOff()
Stop the video stream.
Definition: v4l2_videodevice.cpp:1817
int getFormat(V4L2DeviceFormat *format)
Retrieve the image format set on the V4L2 video device.
Definition: v4l2_videodevice.cpp:759
int exportBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Export buffers from the video device.
Definition: v4l2_videodevice.cpp:1274
void close()
Close the video device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:711
const char * busName() const
Retrieve the location of the device in the system.
Definition: v4l2_videodevice.h:195
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:1855
int setSelection(unsigned int target, Rectangle *rect)
Set a selection rectangle rect for target.
Definition: v4l2_videodevice.cpp:1139
const V4L2Capability & caps() const
Retrieve the device V4L2 capabilities.
Definition: v4l2_videodevice.h:197
Signal< FrameBuffer * > bufferReady
A Signal emitted when a framebuffer completes.
Definition: v4l2_videodevice.h:214
int setFormat(V4L2DeviceFormat *format)
Configure an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:798
Formats formats(uint32_t code=0)
Enumerate all pixel formats and frame sizes.
Definition: v4l2_videodevice.cpp:1016
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
bool operator==(const ColorSpace &lhs, const ColorSpace &rhs)
Compare color spaces for equality.
Definition: color_space.cpp:303
libcamera pixel format
Signal & slot implementation.
A memory region to store a single plane of a frame.
Definition: framebuffer.h:54
unsigned int length
The plane length in bytes.
Definition: framebuffer.h:58
SharedFD fd
The dmabuf file descriptor.
Definition: framebuffer.h:56
struct v4l2_capability object wrapper and helpers
Definition: v4l2_videodevice.h:40
bool hasStreaming() const
Determine if the video device can perform Streaming I/O.
Definition: v4l2_videodevice.h:110
unsigned int device_caps() const
Retrieve the capabilities of the video device.
Definition: v4l2_videodevice.h:53
bool isVideoOutput() const
Identify if the video device outputs images.
Definition: v4l2_videodevice.h:98
bool isM2M() const
Identify if the device is a Memory-to-Memory device.
Definition: v4l2_videodevice.h:84
bool isMetaCapture() const
Identify if the video device captures image meta-data.
Definition: v4l2_videodevice.h:102
bool hasMediaController() const
Determine if the video device uses Media Controller to configure I/O.
Definition: v4l2_videodevice.h:114
bool isOutput() const
Identify if the video device outputs data.
Definition: v4l2_videodevice.h:71
bool isVideoCapture() const
Identify if the video device captures images.
Definition: v4l2_videodevice.h:94
bool isMultiplanar() const
Identify if the video device implements the V4L2 multiplanar APIs.
Definition: v4l2_videodevice.h:59
bool isMeta() const
Identify if the video device captures or outputs image meta-data.
Definition: v4l2_videodevice.h:89
bool isCapture() const
Identify if the video device captures data.
Definition: v4l2_videodevice.h:65
bool isMetaOutput() const
Identify if the video device outputs image meta-data.
Definition: v4l2_videodevice.h:106
const char * bus_info() const
Retrieve the location of the video device in the system.
Definition: v4l2_videodevice.h:49
const char * card() const
Retrieve the video device card name.
Definition: v4l2_videodevice.h:45
bool isVideo() const
Identify if the video device captures or outputs images.
Definition: v4l2_videodevice.h:77
const char * driver() const
Retrieve the driver module name.
Definition: v4l2_videodevice.h:41
Per-plane memory size information.
Definition: v4l2_videodevice.h:165
uint32_t size
The plane total memory size (in bytes)
Definition: v4l2_videodevice.h:166
uint32_t bpl
The plane line stride (in bytes)
Definition: v4l2_videodevice.h:167
File descriptor wrapper that owns a file descriptor.
Common base for V4L2 devices and subdevices.
V4L2 Pixel Format.