ljx-null

libcamera 简介

libcamera 是一个开源的多媒体库,用于在 Linux 操作系统上支持多种摄像头硬件的访问,libcamera 是一个用户空间库,可用于开发基于摄像头的应用程序,如相机应用程序或视频通信应用程序。

基础概念

CameraManager

CameraManager 负责列举系统中的所有摄像头

  • 调用 CameraManager::cameras() 返回一组应用程序可用的摄像头
  • 调用 CameraManager::get() 通过摄像头 ID 来获取对应的摄像头
std::unique_ptr<CameraManager> cm = std::make_unique<CameraManager>();

cm->start();

for (auto const &camera : cm->cameras())
	std::cout << " - " << camera.id() << std::endl;

进程空间中只能存在单一的 CameraManager

Camera

Camera 代表系统中可用的一个图像源,比如图像传感器

系统中存在多个摄像头且可以彼此独立操作的时候,libcamera 将它们暴露为多个 Camera 设备,硬件限制(比如内存带宽、CPU 占用率等)允许的情况下,支持多个摄像头的并行操作

Camera 设备在某个时刻只能被单一进程所使用

  • 应用程序使用 Camera 时要先调用 Camera::acquire() 对它上锁
  • 使用结束后要调用 Camera::release() 释放它

调用 Camera::id() 获得摄像头的 ID,它是字符串类型,保证唯一且稳定

  • 只要同一个摄像头以同样的方式(比如插到同一个 USB 接口上)连接到系统上,不管是插拔还是系统重启,ID 都是不变的
std::cout << camera->id() << std::endl;

这里我们打印摄像头的 ID,得到 /base/soc/i2c0mux/i2c@1/imx219@10

调用 Camera::properties() 获得相机的属性列表

  • properties 是描述相机功能的静态信息,在 Camera 对象的整个生命周期内保持不变
  • 比如摄像头的 Location(前置摄像头、后置摄像头或可*移动的摄像头),Model(传感器的名字)
const ControlList &props = camera->properties();
const auto &model = props.get(properties::Model);
if (model)
	name = " '" + *model + "'";

这里我们打印传感器的 Model,输出的结果是 'imx219'

Stream

libcamera 支持并发多路视频流

  • 例如,使用中等分辨率的视频流来做预览,同时使用最大分辨率的视频流来拍照
 +-------------------------------------------------------+
| Camera                                                |
|                +-----------+                          |
| +--------+     |           |------> [  Main output  ] |
| | Image  |     |           |                          |
| |        |---->|    ISP    |------> [   Viewfinder  ] |
| | Source |     |           |                          |
| +--------+     |           |------> [ Still Capture ] |
|                +-----------+                          |
+-------------------------------------------------------+

摄像头流的数量和能力是平台相关的属性,pipeline handler 的实现有责任正确的汇报它

CameraConfiguration

Camera 会根据应用场景来创建一组默认配置模板,然后应用程序可以修改默认参数,并验证确保摄像头能支持新配的参数(某些参数组合可能是系统不支持的)

  • Camera::generateConfiguration() 根据 StreamRole 产生摄像头默认配置
    • StreamRole 就是这个流是被拿来干嘛的,包括
      • Raw
        • 从传感器获得原始帧(raw frames)
      • StillCapture
        • 高分辨率、高质量、低帧率的静态图像
        • 可以用闪光灯曝光
      • VideoRecording
        • 用来录像(recording)或在线播放(streaming)
        • 可能是高帧率,可以做视频稳定(video stabilization)
      • Viewfinder
        • 用于捕获视频,以便在本地屏幕上显示
        • 质量和系统资源使用之间的权衡是可以接受的
    • 每个 StreamRole 都对应一个默认的 StreamConfiguration
  • 应用程序可以修改配置参数
  • CameraConfiguration::validate() 验证并调整配置到最接近的合法配置
  • Camera::configure() 用来修改 Camera 配置,只接受完全有效的配置,对于非法的配置会报错
  • CameraConfiguration 是实现了迭代器,可以用它来遍历所有的 StreamConfiguration,也可以通过用下标调用 CameraConfiguration::at() 获取某个 StreamConfiguration
std::unique_ptr<CameraConfiguration> config =
	camera->generateConfiguration( { StreamRole::Viewfinder } );

StreamConfiguration &viewFinderStreamConfig = config->at(0);

std::cout << "Default viewfinder configuration is: "
		<< viewFinderStreamConfig.toString() << std::endl;

这里我们打印 Viewfinder、StillCapture、Raw、VideoRecording 的默认配置

Default viewfinder configuration is: 800x600-NV12
Default stillcapture configuration is: 3280x2464-NV12
Default raw configuration is: 3280x2464-SBGGR10_CSI2P
Default videorecording configuration is: 1920x1080-YUV420

Buffer 分配

捕获到的图像要存储到 framebuffer 中

  • framebuffer 可以是应用程序提供给库
    • 应用程序可以把 buffer 分配到任何地方,比如可以直接 display driver 分配的内存中,就会被 display driver 用来渲染
    • 通过构建 FrameBuffer 实例
  • 也可以是 Camera 内部分配并暴露给应用程序
    • 使用 FrameBufferAllocator 实例来分配 buffer
    • 根据 Camera 配置来决定 buffer 的大小和类型
FrameBufferAllocator *allocator = new FrameBufferAllocator(camera);

for (StreamConfiguration &cfg : *config) {
	int ret = allocator->allocate(cfg.stream());
	if (ret < 0) {
		std::cerr << "Can't allocate buffers" << std::endl;
		return EXIT_FAILURE;
	}

	auto &buffers = allocator->buffers(cfg.stream());
	size_t allocated = buffers.size();
	std::cout << "Allocated " << allocated << " buffers for stream" << std::endl;

	for (auto &buffer: buffers) {
		for (auto &plane : buffer->planes()) {
			std::cout << "~ " << plane.length << std::endl;
		}
		std::cout << std::endl;
	}
}

这里我们通过 FrameBufferAllocator 分配了缓冲区,采用的像素格式是 NV12,所以缓冲区有两个 planes

Allocated 4 buffers for stream
~ 480000
~ 240000

~ 480000
~ 240000

~ 480000
~ 240000

~ 480000
~ 240000

捕获帧

libcamera 的视频捕获基于 Request 的概念

  • 每一帧的请求必须在摄像头中排队等待处理
  • 请求至少要和一个 Stream 关联起来
  • Buffer 要被添加到请求中
    • 请求完成后,图像数据会被写到 Buffer 里,等待应用程序消费
    • 可以给每个流都配置一个 Buffer,这样就可以同时处理 viewfinder 和 still image,或通过获取原始图像和 ISP 处理后的图像
  • 请求会有一系列 Controls,它们是可调节的参数,可以以帧为单位做调整
  • 请求完成后,可以查看元数据以确定应用于图像的捕获参数
std::unique_ptr<Request> request = camera->createRequest();
if (!request)
{
	std::cerr << "Can't create request" << std::endl;
	return EXIT_FAILURE;
}

int ret = request->addBuffer(stream, buffer.get());
if (ret < 0)
{
	std::cerr << "Can't set buffer for request"
		  << std::endl;
	return EXIT_FAILURE;
}

ControlList &controls = request->controls();
controls.set(controls::Brightness, 0.5);

Signal&Slots

libcamera 采用了类似于 QT 的信号槽机制

  • Signals 代表类实例产生的事件,Slots 是关联到某个 Signal 上的回调函数
  • Camera 暴露出的信号
    • requestCompleted
      • 在摄像头中排队的请求完成了
    • bufferCompleted
      • 请求中的某个 Buffer 完成了
    • disconnected
      • 设备从系统上断开了
  • 应用程序必须在摄像头开始运行前,将回调函数注册到这些信号上,才能处理对应的事件
camera->requestCompleted.connect(requestComplete);

开始捕获

启动摄像头,并让请求在其中排队,摄像头管线深度被填满后,其他请求必须排队等待,直到摄像头开始交付帧

  • 对于被交付的帧,在 requestCompleted 上绑定的 Slot 会被调用
camera->start();
camera->queueRequest(request.get());

消费帧

我们可以在 Slot 中消费 Buffer 中的数据和请求的元数据

元数据

请求完成后,元数据列表中包含已完成请求的各种属性,包括传感器捕获的时间戳、传感器增益(gain)和曝光值(exposure values),或来自 IPA 的属性,如 3A 算法的状态

const ControlList &requestMetadata = request->metadata();
for (const auto &ctrl : requestMetadata) {
	const ControlId *id = controls::controls.at(ctrl.first);
	const ControlValue &value = ctrl.second;

	std::cout << "\t" << id->name() << " = " << value.toString()
		  << std::endl;
}

这里我们打印所有的元数据

Request completed: Request(35:C:0/1:0)
	ExposureTime = 66653
	AnalogueGain = 8.000000
	ColourCorrectionMatrix = [ 1.684340, -0.523863, -0.160477, -0.489361, 1.884680, -0.395319, -0.084126, -0.957826, 2.041952 ]
	FrameDuration = 66729
	Lux = 4.425883
	AeLocked = true
	ColourGains = [ 1.286008, 1.913542 ]
	DigitalGain = 1.000183
	ColourTemperature = 3446
	SensorBlackLevels = [ 4096, 4096, 4096, 4096 ]
	ScalerCrop = (0, 2)/3280x2460
	SensorTimestamp = 1463504108407000

Buffer 数据

FrameBuffer::metadata() 可以获得帧的动态元数据,比如帧的状态、序号、时间戳

const Request::BufferMap &buffers = request->buffers();
for (auto bufferPair : buffers) {
	// (Unused) Stream *stream = bufferPair.first;
	FrameBuffer *buffer = bufferPair.second;
	const FrameMetadata &metadata = buffer->metadata();
	
	/* Print some information about the buffer which has completed. */
	std::cout << " seq: " << std::setw(6) << std::setfill('0') << metadata.sequence
		  << " timestamp: " << metadata.timestamp
		  << " bytesused: ";
}

FrameBuffer::Plane 是存储帧单一平面的内存区域

  • FrameBuffer 有一个或多个 Plane,取决于它的像素格式
    • planar 像素格式用多个内存区域来存储帧的不同颜色分量
    • 相对应的是 packed 像素格式,所有分量交织存储,只需要一个内存区域即可
  • 用 dmabuf 文件描述符、偏移量和长度来描述这样一块内存区域
    • 多个 plane 可以用同一个 dmabuf fd 来引用,这时候就需要通过偏移量和长度来区分它们
  • 应用程序应该调用 mmap() 来映射 plane 内存以访问它的内容
size_t buffer_size = 0;
for (unsigned i = 0; i < buffer->planes().size(); i++)
{
	const FrameBuffer::Plane &plane = buffer->planes()[i];
	buffer_size += plane.length;
	if (i == buffer->planes().size() - 1 || plane.fd.get() != buffer->planes()[i + 1].fd.get())
	{
		void *memory = mmap(NULL, buffer_size, PROT_READ | PROT_WRITE, MAP_SHARED, plane.fd.get(), 0);
		buffer_size = 0;
	}
}

复用 Request

将 Buffer 设置为可复用,然后重新入队

request->reuse(Request::ReuseBuffers);
camera->queueRequest(request);

释放资源

关掉摄像头、释放资源并停止 CameraManager

camera->stop();
allocator->free(stream);
delete allocator;
camera->release();
camera.reset();
cm->stop();

参考资料

相关文章: