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
21#include <libcamera/base/class.h>
22#include <libcamera/base/log.h>
23#include <libcamera/base/signal.h>
24#include <libcamera/base/timer.h>
25#include <libcamera/base/unique_fd.h>
26#include <libcamera/base/utils.h>
27
28#include <libcamera/color_space.h>
29#include <libcamera/framebuffer.h>
30#include <libcamera/geometry.h>
31#include <libcamera/pixel_format.h>
32
33#include "libcamera/internal/formats.h"
34#include "libcamera/internal/v4l2_device.h"
35#include "libcamera/internal/v4l2_pixelformat.h"
36
37 namespace libcamera {
38
39 class EventNotifier;
40 class MediaDevice;
41 class MediaEntity;
42
43 struct 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 }
117 bool hasMediaController() const
118 {
119 return device_caps() & V4L2_CAP_IO_MC;
120 }
121};
122
123 class V4L2BufferCache
124{
125 public:
126 V4L2BufferCache(unsigned int numEntries);
127 V4L2BufferCache(const std::vector<std::unique_ptr<FrameBuffer>> &buffers);
128 ~V4L2BufferCache();
129
130 bool isEmpty() const;
131 int get(const FrameBuffer &buffer);
132 void put(unsigned int index);
133
134 private:
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
166 class V4L2DeviceFormat
167{
168 public:
169 struct Plane {
170 uint32_t size = 0;
171 uint32_t bpl = 0;
172 };
173
174 V4L2PixelFormat fourcc;
175 Size size;
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
186 class V4L2VideoDevice : public V4L2Device
187{
188 public:
189 using Formats = std::map<V4L2PixelFormat, std::vector<SizeRange>>;
190
191 explicit V4L2VideoDevice(const std::string &deviceNode);
192 explicit V4L2VideoDevice(const MediaEntity *entity);
193 ~V4L2VideoDevice();
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);
221 Signal<FrameBuffer *> bufferReady;
222
223 int streamOn();
224 int streamOff();
225
226 void setDequeueTimeout(utils::Duration timeout);
227 Signal<> dequeueTimeout;
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
234 protected:
235 std::string logPrefix() const override;
236
237 private:
238 LIBCAMERA_DISABLE_COPY(V4L2VideoDevice)
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
294 class V4L2M2MDevice
295{
296 public:
297 V4L2M2MDevice(const std::string &deviceNode);
298 ~V4L2M2MDevice();
299
300 int open();
301 void close();
302
303 V4L2VideoDevice *output() { return output_; }
304 V4L2VideoDevice *capture() { return capture_; }
305
306 private:
307 std::string deviceNode_;
308
309 V4L2VideoDevice *output_;
310 V4L2VideoDevice *capture_;
311};
312
313} /* namespace libcamera */
class.h
Utilities to help constructing class interfaces.
LIBCAMERA_DISABLE_COPY
#define LIBCAMERA_DISABLE_COPY(klass)
Disable copy construction and assignment of the klass.
Definition class.h:27
libcamera::EventNotifier
Notify of activity on a file descriptor.
Definition event_notifier.h:20
libcamera::FrameBuffer
Frame buffer data and its associated dynamic metadata.
Definition framebuffer.h:49
libcamera::MediaDevice
The MediaDevice represents a Media Controller device with its full graph of connected objects.
Definition media_device.h:25
libcamera::MediaEntity
The MediaEntity represents an entity in the media graph.
Definition media_object.h:97
libcamera::PixelFormatInfo
Information about pixel formats.
Definition formats.h:21
libcamera::PixelFormat
libcamera image pixel format
Definition pixel_format.h:17
libcamera::Rectangle
Describe a rectangle's position and dimensions.
Definition geometry.h:241
libcamera::SharedFD
RAII-style wrapper for file descriptors.
Definition shared_fd.h:17
libcamera::SharedFD::get
int get() const
Retrieve the numerical file descriptor.
Definition shared_fd.h:30
libcamera::Signal
Generic signal and slot communication mechanism.
Definition signal.h:39
libcamera::Size
Describe a two-dimensional size.
Definition geometry.h:51
libcamera::Timer
Single-shot timer interface.
Definition timer.h:22
libcamera::UniqueFD
unique_ptr-like wrapper for a file descriptor
Definition unique_fd.h:17
libcamera::V4L2BufferCache
Hot cache of associations between V4L2 buffer indexes and FrameBuffer.
Definition v4l2_videodevice.h:124
libcamera::V4L2BufferCache::V4L2BufferCache
V4L2BufferCache(unsigned int numEntries)
Create an empty cache with numEntries entries.
Definition v4l2_videodevice.cpp:174
libcamera::V4L2BufferCache::get
int get(const FrameBuffer &buffer)
Find the best V4L2 buffer for a FrameBuffer.
Definition v4l2_videodevice.cpp:229
libcamera::V4L2BufferCache::isEmpty
bool isEmpty() const
Check if all the entries in the cache are unused.
Definition v4l2_videodevice.cpp:206
libcamera::V4L2BufferCache::put
void put(unsigned int index)
Mark buffer index as free in the cache.
Definition v4l2_videodevice.cpp:271
libcamera::V4L2DeviceFormat
The V4L2 video device image format and sizes.
Definition v4l2_videodevice.h:167
libcamera::V4L2DeviceFormat::fourcc
V4L2PixelFormat fourcc
The fourcc code describing the pixel encoding scheme.
Definition v4l2_videodevice.h:174
libcamera::V4L2DeviceFormat::toString
const std::string toString() const
Assemble and return a string describing the format.
Definition v4l2_videodevice.cpp:432
libcamera::V4L2DeviceFormat::planesCount
unsigned int planesCount
The number of valid data planes.
Definition v4l2_videodevice.h:179
libcamera::V4L2DeviceFormat::colorSpace
std::optional< ColorSpace > colorSpace
The color space of the pixels.
Definition v4l2_videodevice.h:176
libcamera::V4L2DeviceFormat::planes
std::array< Plane, 3 > planes
The per-plane memory size information.
Definition v4l2_videodevice.h:178
libcamera::V4L2DeviceFormat::size
Size size
The image size in pixels.
Definition v4l2_videodevice.h:175
libcamera::V4L2Device::deviceNode
const std::string & deviceNode() const
Retrieve the device node path.
Definition v4l2_device.h:45
libcamera::V4L2Device::V4L2Device
V4L2Device(const std::string &deviceNode)
Construct a V4L2Device.
Definition v4l2_device.cpp:59
libcamera::V4L2M2MDevice::close
void close()
Close the memory-to-memory device, releasing any resources acquired by open()
Definition v4l2_videodevice.cpp:2245
libcamera::V4L2M2MDevice::output
V4L2VideoDevice * output()
Retrieve the output V4L2VideoDevice instance.
Definition v4l2_videodevice.h:303
libcamera::V4L2M2MDevice::capture
V4L2VideoDevice * capture()
Retrieve the capture V4L2VideoDevice instance.
Definition v4l2_videodevice.h:304
libcamera::V4L2M2MDevice::open
int open()
Open a V4L2 Memory to Memory device.
Definition v4l2_videodevice.cpp:2208
libcamera::V4L2M2MDevice::V4L2M2MDevice
V4L2M2MDevice(const std::string &deviceNode)
Create a new V4L2M2MDevice from the deviceNode.
Definition v4l2_videodevice.cpp:2187
libcamera::V4L2PixelFormat
V4L2 pixel format FourCC wrapper.
Definition v4l2_pixelformat.h:24
libcamera::V4L2VideoDevice
V4L2VideoDevice object and API.
Definition v4l2_videodevice.h:187
libcamera::V4L2VideoDevice::importBuffers
int importBuffers(unsigned int count)
Prepare the device to import count buffers.
Definition v4l2_videodevice.cpp:1587
libcamera::V4L2VideoDevice::releaseBuffers
int releaseBuffers()
Release resources allocated by allocateBuffers() or importBuffers()
Definition v4l2_videodevice.cpp:1615
libcamera::V4L2VideoDevice::tryFormat
int tryFormat(V4L2DeviceFormat *format)
Try an image format on the V4L2 video device.
Definition v4l2_videodevice.cpp:830
libcamera::V4L2VideoDevice::allocateBuffers
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
libcamera::V4L2VideoDevice::logPrefix
std::string logPrefix() const override
Retrieve a string to be prefixed to the log message.
Definition v4l2_videodevice.cpp:792
libcamera::V4L2VideoDevice::Formats
std::map< V4L2PixelFormat, std::vector< SizeRange > > Formats
A map of supported V4L2 pixel formats to frame sizes.
Definition v4l2_videodevice.h:189
libcamera::V4L2VideoDevice::setDequeueTimeout
void setDequeueTimeout(utils::Duration timeout)
Set the dequeue timeout value.
Definition v4l2_videodevice.cpp:2066
libcamera::V4L2VideoDevice::open
int open()
Open the V4L2 video device node and query its capabilities.
Definition v4l2_videodevice.cpp:569
libcamera::V4L2VideoDevice::bufferReady
Signal< FrameBuffer * > bufferReady
A Signal emitted when a framebuffer completes.
Definition v4l2_videodevice.h:221
libcamera::V4L2VideoDevice::busName
const char * busName() const
Retrieve the location of the device in the system.
Definition v4l2_videodevice.h:201
libcamera::V4L2VideoDevice::streamOn
int streamOn()
Start the video stream.
Definition v4l2_videodevice.cpp:1979
libcamera::V4L2VideoDevice::queueBuffer
int queueBuffer(FrameBuffer *buffer)
Queue a buffer to the video device.
Definition v4l2_videodevice.cpp:1645
libcamera::V4L2VideoDevice::V4L2VideoDevice
V4L2VideoDevice(const std::string &deviceNode)
Construct a V4L2VideoDevice.
Definition v4l2_videodevice.cpp:534
libcamera::V4L2VideoDevice::streamOff
int streamOff()
Stop the video stream.
Definition v4l2_videodevice.cpp:2012
libcamera::V4L2VideoDevice::getFormat
int getFormat(V4L2DeviceFormat *format)
Retrieve the image format set on the V4L2 video device.
Definition v4l2_videodevice.cpp:803
libcamera::V4L2VideoDevice::getSelection
int getSelection(unsigned int target, Rectangle *rect)
Get the selection rectangle for target.
Definition v4l2_videodevice.cpp:1249
libcamera::V4L2VideoDevice::exportBuffers
int exportBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer > > *buffers)
Export buffers from the video device.
Definition v4l2_videodevice.cpp:1417
libcamera::V4L2VideoDevice::dequeueTimeout
Signal dequeueTimeout
A Signal emitted when the dequeue watchdog timer expires.
Definition v4l2_videodevice.h:227
libcamera::V4L2VideoDevice::driverName
const char * driverName() const
Retrieve the name of the V4L2 device driver.
Definition v4l2_videodevice.h:199
libcamera::V4L2VideoDevice::close
void close()
Close the video device, releasing any resources acquired by open()
Definition v4l2_videodevice.cpp:755
libcamera::V4L2VideoDevice::caps
const V4L2Capability & caps() const
Retrieve the device V4L2 capabilities.
Definition v4l2_videodevice.h:203
libcamera::V4L2VideoDevice::fromEntityName
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
libcamera::V4L2VideoDevice::setSelection
int setSelection(unsigned int target, Rectangle *rect)
Set a selection rectangle rect for target.
Definition v4l2_videodevice.cpp:1281
libcamera::V4L2VideoDevice::toV4L2PixelFormat
V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const
Convert PixelFormat to a V4L2PixelFormat supported by the device.
Definition v4l2_videodevice.cpp:2134
libcamera::V4L2VideoDevice::setFormat
int setFormat(V4L2DeviceFormat *format)
Configure an image format on the V4L2 video device.
Definition v4l2_videodevice.cpp:856
libcamera::V4L2VideoDevice::deviceName
const char * deviceName() const
Retrieve the name of the V4L2 video device.
Definition v4l2_videodevice.h:200
libcamera::utils::Duration
Helper class from std::chrono::duration that represents a time duration in nanoseconds with double pr...
Definition utils.h:371
color_space.h
Class and enums to represent color spaces.
framebuffer.h
Frame buffer handling.
geometry.h
Data structures related to geometric objects.
formats.h
Types and helper functions to handle libcamera image formats.
log.h
Logging infrastructure.
libcamera
Top-level libcamera namespace.
Definition backtrace.h:17
libcamera::operator<<
std::ostream & operator<<(std::ostream &out, const Point &p)
Insert a text representation of a Point into an output stream.
Definition geometry.cpp:91
pixel_format.h
libcamera pixel format
signal.h
Signal & slot implementation.
libcamera::FrameBuffer::Plane
A memory region to store a single plane of a frame.
Definition framebuffer.h:53
libcamera::FrameBuffer::Plane::fd
SharedFD fd
The dmabuf file descriptor.
Definition framebuffer.h:55
libcamera::FrameBuffer::Plane::length
unsigned int length
The plane length in bytes.
Definition framebuffer.h:57
libcamera::V4L2Capability
struct v4l2_capability object wrapper and helpers
Definition v4l2_videodevice.h:43
libcamera::V4L2Capability::hasStreaming
bool hasStreaming() const
Determine if the video device can perform Streaming I/O.
Definition v4l2_videodevice.h:113
libcamera::V4L2Capability::bus_info
const char * bus_info() const
Retrieve the location of the video device in the system.
Definition v4l2_videodevice.h:52
libcamera::V4L2Capability::isVideoCapture
bool isVideoCapture() const
Identify if the video device captures images.
Definition v4l2_videodevice.h:97
libcamera::V4L2Capability::isMultiplanar
bool isMultiplanar() const
Identify if the video device implements the V4L2 multiplanar APIs.
Definition v4l2_videodevice.h:62
libcamera::V4L2Capability::isOutput
bool isOutput() const
Identify if the video device outputs data.
Definition v4l2_videodevice.h:74
libcamera::V4L2Capability::isMetaOutput
bool isMetaOutput() const
Identify if the video device outputs image meta-data.
Definition v4l2_videodevice.h:109
libcamera::V4L2Capability::isMeta
bool isMeta() const
Identify if the video device captures or outputs image meta-data.
Definition v4l2_videodevice.h:92
libcamera::V4L2Capability::isMetaCapture
bool isMetaCapture() const
Identify if the video device captures image meta-data.
Definition v4l2_videodevice.h:105
libcamera::V4L2Capability::hasMediaController
bool hasMediaController() const
Determine if the video device uses Media Controller to configure I/O.
Definition v4l2_videodevice.h:117
libcamera::V4L2Capability::driver
const char * driver() const
Retrieve the driver module name.
Definition v4l2_videodevice.h:44
libcamera::V4L2Capability::isM2M
bool isM2M() const
Identify if the device is a Memory-to-Memory device.
Definition v4l2_videodevice.h:87
libcamera::V4L2Capability::isVideoOutput
bool isVideoOutput() const
Identify if the video device outputs images.
Definition v4l2_videodevice.h:101
libcamera::V4L2Capability::isVideo
bool isVideo() const
Identify if the video device captures or outputs images.
Definition v4l2_videodevice.h:80
libcamera::V4L2Capability::isCapture
bool isCapture() const
Identify if the video device captures data.
Definition v4l2_videodevice.h:68
libcamera::V4L2Capability::device_caps
unsigned int device_caps() const
Retrieve the capabilities of the video device.
Definition v4l2_videodevice.h:56
libcamera::V4L2Capability::card
const char * card() const
Retrieve the video device card name.
Definition v4l2_videodevice.h:48
libcamera::V4L2DeviceFormat::Plane
Per-plane memory size information.
Definition v4l2_videodevice.h:169
libcamera::V4L2DeviceFormat::Plane::size
uint32_t size
The plane total memory size (in bytes)
Definition v4l2_videodevice.h:170
libcamera::V4L2DeviceFormat::Plane::bpl
uint32_t bpl
The plane line stride (in bytes)
Definition v4l2_videodevice.h:171
timer.h
Generic timer.
unique_fd.h
File descriptor wrapper that owns a file descriptor.
utils.h
Miscellaneous utility functions.
v4l2_device.h
Common base for V4L2 devices and subdevices.
v4l2_pixelformat.h
V4L2 Pixel Format.