docs: clarify source paint handoff and raster presentation limits

This commit is contained in:
2026-11-12 20:11:57 +08:00
parent b10a5b43d2
commit f743c427f7
2 changed files with 17 additions and 2 deletions
+11
View File
@@ -1,6 +1,9 @@
//! 把 DisplayList 写入 CPU 像素缓冲。裁剪栈限定矩形、文字和 3D 表面的实际写入区域。
//! RenderScope 约束递归深度;累计像素预算限制嵌套 3D 和世界 UI 的中间表面分配。错误向上传递,不把半幅结果当成成功帧呈现。
//!
//! shell::app 的 redraw 在取得 softbuffer 后调用 render,成功后才 present;scene3d::panel 也调用它生成离屏 UI 纹理。
//! 本模块不访问 VM,也不重新运行源 paint,只执行目标像素坐标下的 DrawCommand;文字覆盖回调同样同步写入当前 Canvas。
//! render 原地改 target,不提供失败回滚;调用方必须尊重 Result,在错误时停止呈现或终止纹理生成,不把残留像素当作完整新帧。
use crate::{
display_list::{Color, DisplayList, DrawCommand},
geometry::{Point, Rect},
@@ -100,11 +103,13 @@ impl SoftwareRenderer {
// 先将 3D 矩形与当前裁剪和目标尺寸相交;完全不可见时连中间表面都不生成。
let left = rect.x.max(canvas.clip.x).max(0.).floor() as u32;
let top = rect.y.max(canvas.clip.y).max(0.).floor() as u32;
// 右界同时受命令矩形、当前 clip 和目标缓冲宽度限制,ceil 给出保守的整数扫描末端。
let right = (rect.x + rect.width)
.min(canvas.clip.x + canvas.clip.width)
.min(width as f32)
.ceil()
.max(0.) as u32;
// 底边界采用与右界相同的规则;后面的空交集检查同时防止不可见/退化矩形进入像素循环。
let bottom = (rect.y + rect.height)
.min(canvas.clip.y + canvas.clip.height)
.min(height as f32)
@@ -129,6 +134,7 @@ impl SoftwareRenderer {
let u = (((x as f32 + 0.5 - rect.x) / rect.width) * w as f32)
.clamp(0., (w - 1) as f32)
as u32;
// v 对应源表面的行索引,仍从完整 rect 原点映射,裁剪不会把剩余区域重新拉伸成整张图。
let v = (((y as f32 + 0.5 - rect.y) / rect.height) * h as f32)
.clamp(0., (h - 1) as f32)
as u32;
@@ -235,6 +241,7 @@ impl Canvas<'_> {
// 绕命令 origin 旋转局部角点;rect.x/y 仍是相对该 origin 的偏移。
for (x, y) in corners {
let px = origin.x + cos * x - sin * y;
// 同一旋转矩阵的纵分量,与 px 一起更新包围盒;原图像资源和命令 rect 都保持只读。
let py = origin.y + sin * x + cos * y;
lo.x = lo.x.min(px);
lo.y = lo.y.min(py);
@@ -333,6 +340,7 @@ impl Canvas<'_> {
// 将文字原点对齐整数像素;转换 clip 到字形局部空间,回调再加原点写回目标。
let x = origin.x.round() as i32;
let y = origin.y.round() as i32;
// draw_clipped 接受字形局部坐标的 clip,减去取整后的文字原点,回调再加回同一原点,避免两次转换不一致。
let clip = Rect::new(
self.clip.x - x as f32,
self.clip.y - y as f32,
@@ -355,6 +363,7 @@ impl Canvas<'_> {
// 段落文本临时收窄 clip 到文本框;下方调用完成后恢复 old,后续命令不能继承段落私有裁剪。
let old = self.clip;
let x = old.x.max(rect.x);
// x/y 是祖先裁剪与段落框交集的左上角,不替代原段落的排版原点;下面 left/top 仍从 rect 取值。
let y = old.y.max(rect.y);
self.clip = Rect::new(
x,
@@ -365,6 +374,7 @@ impl Canvas<'_> {
// 段落原点对齐整数像素,随后把交集 clip 换到文字局部空间;排版宽度仍保持原框宽。
let left = rect.x.round() as i32;
let top = rect.y.round() as i32;
// 只把交集移到字形局部空间;换行宽度仍在后面单独传 rect.width,不用裁掉后的 clip.width 重排文字。
let clip = Rect::new(
self.clip.x - left as f32,
self.clip.y - top as f32,
@@ -435,6 +445,7 @@ impl Canvas<'_> {
// 非预乘源颜色按 source*alpha + destination*(1-alpha) 合成,目标不存 alpha,逐通道整除 255。
let alpha = source.alpha as u32;
let inverse = 255 - alpha;
// red/green/blue 各自使用同一 alpha 和余量,计算提升到 u32 后整除,避免 u8 乘法溢出;最终目标仍是不透明 RGB。
let red = (source.red as u32 * alpha + dst_red * inverse) / 255;
let green = (source.green as u32 * alpha + dst_green * inverse) / 255;
let blue = (source.blue as u32 * alpha + dst_blue * inverse) / 255;