dailz/wl-webrtc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add Chinese documentation comments to core modules

Browse Source 
Add comprehensive Chinese documentation comments to cap_portal,
main, and state_portal modules covering architecture, lifecycle,
and data flow for each component.
This commit is contained in:
dailz
2026-05-25 08:56:43 +08:00
parent 25110e8463
commit dcf8d1affb
3 changed files with 428 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
src/state_portal.rs
View File

@@ -1,3 +1,4 @@
// 采集门户状态模块 —— 通过 PipeWire/DMA-BUF 进行屏幕采集并编码
use std::mem;
use std::path::PathBuf;
@@ -11,24 +12,43 @@ use crate::cap_portal::{CapPortal, PwDmaBufFrame, PwEvent};
use crate::fps_limit::FpsLimit;
use crate::transform::Transform;
/// 门户采集的阶段状态
/// - WaitingForFormat: 等待接收到第一帧 DMA-BUF 以确定视频格式参数
/// - Streaming: 已完成初始化，正在持续编码流
enum PortalStage {
WaitingForFormat,
Streaming,
}
/// 门户模式的主状态机
///
/// 负责管理从 PipeWire 采集屏幕帧、通过 VAAPI 硬件编码的完整生命周期。
/// 工作流程：等待第一帧 → 创建编码器 → 持续编码帧数据。
pub struct StatePortal {
/// 当前采集阶段
stage: PortalStage,
/// 硬件编码器状态（第一帧到达后才初始化）
enc: Option<EncState>,
/// 帧率限制器
fps_limit: FpsLimit<()>,
/// PipeWire 屏幕采集端点
cap: CapPortal,
/// 命令行参数
args: Args,
/// 是否遇到错误
errored: bool,
/// 是否为第一帧（首帧跳过帧率限制）
first_frame: bool,
/// DRM 渲染设备路径（如 /dev/dri/renderD128）
drm_device: PathBuf,
/// 第一帧的时间戳（纳秒），用于计算相对 PTS
first_pts_ns: Option<i64>,
}
impl StatePortal {
/// 创建门户状态实例
///
/// 初始化 DRM 设备路径和 PipeWire 采集端点，编码器延迟到第一帧到达时创建。
pub fn new(args: Args) -> Result<Self> {
let drm_device = resolve_drm_device(&args)?;
tracing::info!("Using DRM device: {}", drm_device.display());
@@ -48,6 +68,10 @@ impl StatePortal {
})
}
/// 轮询 PipeWire 事件并编码帧
///
/// 尝试从采集端点接收一帧事件。返回 `Ok(true)` 表示已处理事件，
/// `Ok(false)` 表示暂无数据。内部根据当前阶段（等待格式/流式）分发处理。
pub fn poll_and_encode(&mut self) -> Result<bool> {
let event = match self.cap.frame_receiver().try_recv() {
Ok(event) => event,
@@ -58,6 +82,7 @@ impl StatePortal {
PwEvent::Frame(frame) => {
match self.stage {
PortalStage::WaitingForFormat => {
// 第一帧到达：记录格式信息并用该分辨率创建编码器
tracing::info!(
"First DMA-BUF frame: {}x{} format=0x{:08X} stride={} modifier=0x{:X}",
frame.width,
@@ -83,15 +108,18 @@ impl StatePortal {
drop(frame);
}
PortalStage::Streaming => {
// 流式阶段：处理每一帧 DMA-BUF 数据
self.handle_pw_frame(frame)?;
}
}
}
PwEvent::StreamEnded => {
// PipeWire 流结束（如用户停止了屏幕共享）
tracing::warn!("PipeWire stream ended");
self.errored = true;
}
PwEvent::Error(e) => {
// PipeWire 返回错误
tracing::error!("PipeWire error: {e}");
self.errored = true;
}
@@ -100,8 +128,20 @@ impl StatePortal {
Ok(true)
}
/// 处理单帧 DMA-BUF 数据
///
/// 完整的帧处理流水线：
/// 1. 帧率限制（首帧跳过）
/// 2. 构建 DRM 描述符
/// 3. 分配 DRM_PRIME 源帧
/// 4. 分配 VAAPI 硬件目标帧
/// 5. 通过 DMA-BUF 导入将帧数据导入 VAAPI
/// 6. 计算 PTS 时间戳
/// 7. 回收 DRM 描述符内存
/// 8. 编码输出
fn handle_pw_frame(&mut self, frame: PwDmaBufFrame) -> Result<()> {
// 1. FPS limiting (first frame bypasses)
// 帧率限制（首帧跳过限制，确保立即编码）
if self.first_frame {
self.first_frame = false;
} else {
@@ -112,10 +152,12 @@ impl StatePortal {
}
// 2. Build DRM descriptor for DMA-BUF import
// 根据 DMA-BUF 帧信息构建 FFmpeg DRM 描述符
let desc = build_drm_descriptor(&frame);
let desc_box = Box::new(desc);
// 3. Allocate raw DRM_PRIME source frame using Video wrapper
// 分配 DRM_PRIME 格式的源帧，将描述符指针挂载到 data[0]
let mut raw_frame = ff::frame::Video::empty();
unsafe {
let raw_ptr = raw_frame.as_mut_ptr();
@@ -126,10 +168,12 @@ impl StatePortal {
}
// 4. Get encoder reference
// 获取编码器引用
let enc = match self.enc.as_mut() {
Some(e) => e,
None => {
// Recover the Box to prevent memory leak of the descriptor
// 编码器未初始化时回收描述符以防止内存泄漏
unsafe {
let desc_ptr = (*raw_frame.as_ptr()).data[0] as *mut ffi::AVDRMFrameDescriptor;
if !desc_ptr.is_null() {
@@ -141,12 +185,14 @@ impl StatePortal {
};
// 5. Allocate VAAPI hardware target frame
// 分配 VAAPI 硬件帧缓冲区
let mut hw_frame = ff::frame::Video::empty();
let ret = unsafe {
ffi::av_hwframe_get_buffer(enc.frames_rgb().as_ptr(), hw_frame.as_mut_ptr(), 0)
};
if ret < 0 {
// Recover the Box to prevent memory leak of the descriptor
// 分配失败时回收描述符防止内存泄漏
unsafe {
let desc_ptr = (*raw_frame.as_ptr()).data[0] as *mut ffi::AVDRMFrameDescriptor;
if !desc_ptr.is_null() {
@@ -157,10 +203,12 @@ impl StatePortal {
}
// 6. Import DMA-BUF into VAAPI via transfer_data
// 通过 DMA-BUF 导入将帧数据从 DRM 传输到 VAAPI 硬件表面
let ret = unsafe {
ffi::av_hwframe_transfer_data(hw_frame.as_mut_ptr(), raw_frame.as_ptr(), 0)
};
if ret < 0 {
// 传输失败时回收描述符防止内存泄漏
unsafe {
let desc_ptr = (*raw_frame.as_ptr()).data[0] as *mut ffi::AVDRMFrameDescriptor;
if !desc_ptr.is_null() {
@@ -180,6 +228,10 @@ impl StatePortal {
// PipeWire PTS is CLOCK_MONOTONIC in nanoseconds.
// Encoder time_base = 1/fps, so PTS must be in frame numbers.
// Use elapsed time since first frame to avoid i64 overflow on absolute timestamps.
//
// PTS 计算：将 PipeWire 的纳秒时间戳转换为编码器的帧号单位
// PipeWire 使用 CLOCK_MONOTONIC 纳秒时间戳，编码器 time_base = 1/fps
// 使用相对时间避免绝对时间戳导致的 i64 溢出
let fps_i64 = self.args.fps as i64;
let base_ns = *self.first_pts_ns.get_or_insert(frame.pts.max(0));
let elapsed_ns = (frame.pts.max(0) - base_ns).max(0);
@@ -193,6 +245,10 @@ impl StatePortal {
// VAAPI surface, so FFmpeg no longer references the descriptor struct.
// Doing this before encode_frame ensures the descriptor is reclaimed
// even if encode_frame returns early via `?`.
//
// 在编码前回收描述符内存。
// 此时 DMA-BUF 数据已导入 VAAPI 表面，FFmpeg 不再引用描述符结构体。
// 在 encode_frame 之前回收确保即使编码返回错误也能正确释放内存。
unsafe {
let desc_ptr = (*raw_frame.as_ptr()).data[0] as *mut ffi::AVDRMFrameDescriptor;
if !desc_ptr.is_null() {
@@ -201,12 +257,15 @@ impl StatePortal {
}
// 9. Encode — safe to early-return via `?` now that descriptor is recovered.
// 编码帧数据（此时描述符已回收，可安全通过 `?` 提前返回）
enc.encode_frame(&hw_frame)?;
// raw_frame and hw_frame drop here via Video::drop → av_frame_free
// raw_frame 和 hw_frame 在此处通过 Video::drop → av_frame_free 释放
Ok(())
}
/// 刷新编码器缓冲区，输出所有剩余帧
pub fn flush(&mut self) -> Result<()> {
if let Some(enc) = &mut self.enc {
enc.flush()?;
@@ -214,6 +273,7 @@ impl StatePortal {
Ok(())
}
/// 关闭状态：刷新编码器并清理资源
pub fn shutdown(&mut self) {
if let Err(e) = self.flush() {
tracing::error!("Flush error during shutdown: {e}");
@@ -221,19 +281,26 @@ impl StatePortal {
tracing::info!("StatePortal shutdown complete");
}
/// 返回是否遇到不可恢复的错误
pub fn is_errored(&self) -> bool {
self.errored
}
}
/// 根据 DMA-BUF 帧信息构建 FFmpeg DRM 帧描述符
///
/// 将 PipeWire 提供的 DMA-BUF 参数（fd、偏移量、步长、修饰符等）
/// 转换为 FFmpeg 的 AVDRMFrameDescriptor 结构体，用于零拷贝硬件导入。
fn build_drm_descriptor(frame: &PwDmaBufFrame) -> ffi::AVDRMFrameDescriptor {
let mut desc: ffi::AVDRMFrameDescriptor = unsafe { mem::zeroed() };
// DMA-BUF 对象层：一个 fd 对应一个内存对象
desc.nb_objects = 1;
desc.objects[0].fd = frame.fd.as_raw_fd();
desc.objects[0].size = 0;
desc.objects[0].size = 0; // 大小为 0 表示整个 fd
desc.objects[0].format_modifier = frame.modifier;
// 像素格式层：单层单平面布局（如 XR24 格式）
desc.nb_layers = 1;
desc.layers[0].format = frame.format;
desc.layers[0].nb_planes = 1;
@@ -246,6 +313,10 @@ fn build_drm_descriptor(frame: &PwDmaBufFrame) -> ffi::AVDRMFrameDescriptor {
use std::os::fd::AsRawFd;
/// 解析 DRM 渲染设备路径
///
/// 优先使用命令行指定的设备路径，否则依次尝试
/// `/dev/dri/renderD128` 和 `/dev/dri/renderD129`。
fn resolve_drm_device(args: &Args) -> Result<PathBuf> {
if let Some(ref drm) = args.drm_device {
return Ok(PathBuf::from(drm));
@@ -266,6 +337,7 @@ mod tests {
use super::*;
use std::os::fd::{FromRawFd, OwnedFd};
/// 创建测试用的 DMA-BUF 帧数据（使用 stderr fd 的副本作为占位）
fn make_test_frame() -> PwDmaBufFrame {
// Create a dummy fd from stderr (always valid fd 2)
let fd = unsafe { OwnedFd::from_raw_fd(libc::dup(2)) };
@@ -281,6 +353,7 @@ mod tests {
}
}
/// 测试 DRM 描述符构建（单平面情况）
#[test]
fn build_drm_descriptor_single_plane() {
let frame = make_test_frame();
@@ -296,6 +369,7 @@ mod tests {
assert_eq!(desc.layers[0].planes[0].pitch, 1920 * 4);
}
/// 测试显式指定 DRM 设备时的解析
#[test]
fn resolve_drm_device_explicit() {
let args = Args {