MuPDF JavaScript 绑定中的 StrokeState 详解:控制线宽、线帽、线接与虚线描边

原创2026-10-13 13:07:301,832 阅读
文章标签:文档图像处理跨平台桌面应用移动开发WebAssembly

MuPDF JavaScript 绑定中的 StrokeState 详解:控制线宽、线帽、线接与虚线描边

StrokeState 是 MuPDF JavaScript 绑定中用于统一定义"描边(stroking)"操作外观的配置对象。它除了控制线条宽度,还负责线帽样式(line cap style)、线接样式(line join style)、斜接极限(miter limit)以及虚线图案与相位。本文以官方 API 文档 StrokeState.rst 为骨架,结合仓库中的 C 内核结构体、JS FFI 实现与 Device 绘图接口,完整讲解它的构造方式、六个取值方法、底层默认值,以及如何把它接入 strokePath、strokeText 等真实绘图流程。

StrokeState 是什么:一次描边操作的外观控制中枢

在 MuPDF 的绘图模型中,一个矢量路径(Path)或文本(Text)既可以被填充(fill),也可以被描边(stroke)。描边是指沿着路径的轮廓"画一笔",而这一笔的粗细、端点形状、拐角接合方式、虚线节奏,全部由 StrokeState 集中管理。

从 C 内核看,StrokeState 直接对应结构体 fz_stroke_state(定义于 include/mupdf/fitz/path.h#L57-L67):

typedef struct fz_stroke_state
{
	int refs;
	fz_linecap start_cap, dash_cap, end_cap;
	fz_linejoin linejoin;
	float linewidth;
	float miterlimit;
	float dash_phase;
	int dash_len;
	float dash_list[FZ_FLEXIBLE_ARRAY];
} fz_stroke_state;

其中 fz_linecap 与 fz_linejoin 是枚举类型(include/mupdf/fitz/path.h#L41-L55):

typedef enum fz_linecap
{
	FZ_LINECAP_BUTT = 0,
	FZ_LINECAP_ROUND = 1,
	FZ_LINECAP_SQUARE = 2,
	FZ_LINECAP_TRIANGLE = 3
} fz_linecap;

typedef enum fz_linejoin
{
	FZ_LINEJOIN_MITER = 0,
	FZ_LINEJOIN_ROUND = 1,
	FZ_LINEJOIN_BEVEL = 2,
	FZ_LINEJOIN_MITER_XPS = 3
} fz_linejoin;

JavaScript 层的 StrokeState 正是对这一 C 结构体的封装:JS 对象通过 FFI 转换为 fz_stroke_state,供 MuPDF 的绘图设备(Device)使用。因此,理解 StrokeState 的 JS API,本质上是理解 MuPDF 描边参数体系的入口。

构造函数:new mupdf.StrokeState(template)

StrokeState 只有一个构造函数,接收一个 JavaScript 普通对象作为模板:

new mupdf.StrokeState(template)

其中 template 是可选的,用于一次性设置下述六个属性(文档原文示例):

var strokeState = new mupdf.StrokeState({
	lineCap: "Square",
	lineJoin: "Bevel",
	lineWidth: 2.0,
	miterLimit: 1.414,
	dashPhase: 11,
	dashPattern: [ 2, 3 ]
})

六个可配置属性

属性 类型 含义 取值说明
lineCap string 线帽样式,即开放子路径端点处的形状 "Butt"、"Round"、"Square"(底层还支持 "Triangle")
lineJoin string 线接样式,即两条线段拐角处的接合形状 "Miter"、"Round"、"Bevel"
lineWidth number 描边线宽 数值型,无单位,受当前变换矩阵(ctm)缩放影响
miterLimit number 斜接极限,限制尖角"尖出"的长度 数值型,默认 10
dashPhase number 虚线相位,描边从虚线图案的哪个位置开始 数值型,默认 0
dashPattern Array of number 虚线图案,交替指定"实线段长度 / 空隙长度"的序列 数字数组;不设置时描边为实线

所有属性均可省略:例如只想改线宽,可以只传 { lineWidth: 5 }。省略的属性会被替换为内核默认值(见下文"底层默认值")。

构造函数在底层做了什么

JS 构造函数的完整 FFI 实现位于 source/tools/murun.c#L3102-L3177 的 ffi_new_StrokeState 中,处理顺序如下:

  1. 先检测模板对象是否带 dashPattern:若有,先读取数组长度 n,调用 fz_new_stroke_state_with_dash_len(ctx, n) 分配可容纳 n 个虚线长度的内存,再逐项把数组元素写入 stroke->dash_list[i];若无,则调用 fz_new_stroke_state(ctx) 创建空状态(不分配虚线数组);
  2. 若带 lineCap,通过 fz_linecap_from_string 把字符串解析为枚举,并同时赋值给 start_cap、dash_cap、end_cap 三个字段(见 source/tools/murun.c#L3142-L3147);
  3. 依次解析 lineJoin、lineWidth、miterLimit、dashPhase,分别写入 stroke->linejoin、linewidth、miterlimit、dash_phase;
  4. 最后把填充好的 fz_stroke_state 包装为 JS userdata 对象返回。

也就是说,JS 层的 new mupdf.StrokeState({...}) 与 C 层的 fz_new_stroke_state_with_dash_len + 字段赋值是逐字段对应的,字符串形式的 lineCap/lineJoin 会在边界上被解析为枚举值。

底层默认值:不传参时的行为

如果你使用 new mupdf.StrokeState()(不传任何属性),或省略部分属性,得到的将是 MuPDF 的默认描边参数。内核默认值定义在 source/fitz/path.c#L1543-L1549 的 fz_default_stroke_state 与 source/fitz/path.c#L1600-L1626 的 fz_new_stroke_state_with_dash_len:

  • 线帽:Butt(FZ_LINECAP_BUTT,0)
  • 线接:Miter(FZ_LINEJOIN_MITER,0)
  • 线宽:1.0
  • 斜接极限:10
  • 虚线相位:0
  • 虚线长度:0(即无虚线,实线描边)

值得留意的是 fz_linecap 枚举中还存在 FZ_LINECAP_TRIANGLE(3)这一值,字符串转换函数 fz_string_from_linecap 也支持 "Triangle"(见 source/fitz/path.c#L1628-L1650),但 JS 文档公开的取值仅为 "Butt" | "Round" | "Square" 三种,使用 "Triangle" 属于底层扩展能力,不在公开 API 承诺范围内。

字符串与枚举的转换规则同样定义在 source/fitz/path.c#L1628-L1674:fz_linecap_from_string 对 "Round"、"Square"、"Triangle" 精确匹配,其余一律回退为 FZ_LINECAP_BUTT;fz_linejoin_from_string 对 "Round"、"Bevel"、"MiterXPS" 匹配,其余回退为 FZ_LINEJOIN_MITER。这也是为什么传入非法字符串时不会报错、而是静默得到默认样式——在写业务代码时应自行校验取值。

三个核心术语:线帽、线接与斜接极限

StrokeState 中 lineCap、lineJoin、miterLimit 三个参数背后的图形学概念,MuPDF 文档在术语表 glossary.rst 中有专门条目,理解它们才能选对取值。

线帽样式(Line Cap Style)

PDF 规范定义了开放子路径(未闭合路径)端点的三种形状:

  • Butt(平头):线条在端点处垂直截断,不向外延伸;
  • Round(圆头):端点处补上半圆形,半径为线宽的一半;
  • Square(方头):端点处向外延伸半个线宽后垂直截断,形状比 Butt 略长。

MuPDF 三种线帽样式(Butt、Round、Square)的视觉对比

线接样式(Line Join Style)

两条线段在拐角处相接时,PDF 定义三种接合形状:

  • Miter(尖角/斜接):两条线段的描边外缘延长相交,形成尖角;
  • Round(圆角):拐角处以半径为线宽一半的圆弧过渡;
  • Bevel(斜切):拐角处用一条直线把两条描边外缘连接,切掉尖角。

MuPDF 三种线接样式(Miter、Round、Bevel)的视觉对比

斜接极限(Miter Limit)

当使用 Miter 线接且夹角越来越小时,尖角会向外"越伸越长",可能超出预期范围。PDF 因此定义 miter limit:当斜接长度与线宽之比超过该阈值时,尖角会自动退化为 Bevel 接合,避免过长的尖刺。这是 miterLimit 参数的用途——它只对 "Miter" 线接生效。

斜接极限示意图:尖角过长时退化为 Bevel

六个实例方法:读取 StrokeState 的当前值

StrokeState 构造完成后,可通过六个 getter 读取当前参数。它们在 JS 层的实现集中在 source/tools/murun.c#L3179-L3216,全部直接读取 fz_stroke_state 字段并转换为 JS 值。

getLineCap()

获取当前线帽样式,返回值为字符串 "Butt" | "Round" | "Square":

var lineCap = strokeState.getLineCap()

底层由 fz_string_from_linecap(stroke->start_cap) 将枚举转为字符串(source/tools/murun.c#L3179-L3183)。由于构造时 start_cap、dash_cap、end_cap 三字段被统一赋值,因此读取到的就是整条路径统一使用的线帽。

getLineJoin()

获取当前线接样式,返回值为字符串 "Miter" | "Round" | "Bevel":

var lineJoin = strokeState.getLineJoin()

getLineWidth()

获取当前线宽,返回 number:

var width = strokeState.getLineWidth()

注意:读取到的是 StrokeState 中保存的原始线宽值,实际渲染时该值还会随绘图变换矩阵 ctm 一起缩放。

getMiterLimit()

获取当前斜接极限,返回 number:

var limit = strokeState.getMiterLimit()

getDashPhase()

获取当前虚线相位——即描边从虚线图案的哪个位置开始,返回 number:

var limit = strokeState.getDashPhase()

getDashPattern()

获取当前虚线图案,返回"实线段长度与空隙长度交替排列"的数字数组;若未设置虚线则返回 null:

var dashPattern = strokeState.getDashPattern()

底层逻辑(source/tools/murun.c#L3209-L3216)为:仅当 stroke->dash_len > 0 时把 dash_list 逐项推入 JS 数组,否则直接 js_pushnull。这正是文档返回值标注为 Array of number | null 的原因——"空数组"与"未设置虚线"被刻意区分,未设置时返回 null 而非 []。

把 StrokeState 接入真实绘图流程

StrokeState 本身不直接渲染任何东西,它必须作为参数传给 Device(绘图设备)或用于计算边界。以下用法均取自仓库文档并有源码佐证。

描边路径:Device.prototype.strokePath

strokePath(path, stroke, ctm, colorspace, color, alpha) 用给定 StrokeState 沿路径描边,文档示例(Device.rst):

device.strokePath(path,
	{dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
	mupdf.Matrix.identity,
	mupdf.ColorSpace.DeviceRGB,
	[0, 1, 0],
	0.5
)

参数含义依次为:要描边的 Path 对象、描边状态、变换矩阵(ctm)、颜色空间、颜色值(数组)、不透明度(alpha)。这条调用链对应的 C 内核入口是 fz_stroke_path(声明于 include/mupdf/fitz/device.h#L342),每个具体设备(如渲染设备、trace 设备)通过 fz_device 虚函数表中的 stroke_path 回调接收 const fz_stroke_state *stroke 完成实际描边(include/mupdf/fitz/device.h#L291)。

描边文本轮廓:Device.prototype.strokeText

文字同样可以被描边(例如制作空心字效果):strokeText(text, stroke, ctm, colorspace, color, alpha),文档示例(Device.rst):

device.strokeText(text,
	{ dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
	mupdf.Matrix.identity,
	mupdf.ColorSpace.DeviceRGB,
	[1, 0, 0],
	1
)

对应 C 内核入口为 fz_stroke_text(include/mupdf/fitz/device.h#L346)。

描边裁剪:clipStrokePath 与 clipStrokeText

StrokeState 还参与"描边并裁剪"操作:clipStrokePath(path, stroke, ctm) 与 clipStrokeText(text, stroke, ctm) 先用描边轮廓划定裁剪区域,文档示例(Device.rst):

device.clipStrokeText(text,
	{ dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
	mupdf.Matrix.identity
)

对应 C 内核的 fz_clip_stroke_path 与 fz_clip_stroke_text(include/mupdf/fitz/device.h#L344-L348)。

计算描边后的边界:Path.getBounds 与 Text.getBounds

StrokeState 不仅影响绘制,还影响几何边界计算:

  • Path.prototype.getBounds(stroke, transform) 接受 StrokeState | null,传入时按描边后的轮廓计算路径边界,传 null 则按填充轮廓计算(Path.rst);
  • Text.prototype.getBounds(strokeState, transform) 同理(Text.rst)。

这在排版、碰撞检测、绘制包围盒等场景非常实用:描边会让可见区域向外膨胀,用 StrokeState 参与计算才能得到准确的命中区域。

跨语言的一致性:C、Java 与 JavaScript

StrokeState 并非 JavaScript 专属,它在 MuPDF 的 C 内核之上被各语言绑定共享。例如 Java 绑定提供了对应的 com.artifex.mupdf.fitz.StrokeState 类,其 JNI 实现 platform/java/jni/strokestate.c 中的 StrokeState_newNativeStrokeState 与 JS 的 ffi_new_StrokeState 走的是同一套内核函数 fz_new_stroke_state_with_dash_len,六个 getter 也逐字段对应(platform/java/jni/strokestate.c#L35-L120)。这意味着:无论你用 C API、Java API 还是 JavaScript API,描边参数模型与默认值完全一致,概念可以无缝迁移。

延伸阅读

登录后查看全文
mupdf