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();

参考资料