图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载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-L67typedef 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-L55typedef 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 ] })六个可配置属性属性类型含义取值说明lineCapstring线帽样式即开放子路径端点处的形状Butt、Round、Square底层还支持TrianglelineJoinstring线接样式即两条线段拐角处的接合形状Miter、Round、BevellineWidthnumber描边线宽数值型无单位受当前变换矩阵ctm缩放影响miterLimitnumber斜接极限限制尖角尖出的长度数值型默认 10dashPhasenumber虚线相位描边从虚线图案的哪个位置开始数值型默认 0dashPatternArray of number虚线图案交替指定实线段长度 / 空隙长度的序列数字数组不设置时描边为实线所有属性均可省略例如只想改线宽可以只传{ lineWidth: 5 }。省略的属性会被替换为内核默认值见下文底层默认值。构造函数在底层做了什么JS 构造函数的完整 FFI 实现位于 source/tools/murun.c#L3102-L3177 的ffi_new_StrokeState中处理顺序如下先检测模板对象是否带dashPattern若有先读取数组长度n调用fz_new_stroke_state_with_dash_len(ctx, n)分配可容纳n个虚线长度的内存再逐项把数组元素写入stroke-dash_list[i]若无则调用fz_new_stroke_state(ctx)创建空状态不分配虚线数组若带lineCap通过fz_linecap_from_string把字符串解析为枚举并同时赋值给start_cap、dash_cap、end_cap三个字段见 source/tools/murun.c#L3142-L3147依次解析lineJoin、lineWidth、miterLimit、dashPhase分别写入stroke-linejoin、linewidth、miterlimit、dash_phase最后把填充好的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线帽ButtFZ_LINECAP_BUTT0线接MiterFZ_LINEJOIN_MITER0线宽1.0斜接极限10虚线相位0虚线长度0即无虚线实线描边值得留意的是fz_linecap枚举中还存在FZ_LINECAP_TRIANGLE3这一值字符串转换函数fz_string_from_linecap也支持Triangle见 source/fitz/path.c#L1628-L1650但 JS 文档公开的取值仅为Butt | Round | Square三种使用Triangle属于底层扩展能力不在公开 API 承诺范围内。字符串与枚举的转换规则同样定义在 source/fitz/path.c#L1628-L1674fz_linecap_from_string对Round、Square、Triangle精确匹配其余一律回退为FZ_LINECAP_BUTTfz_linejoin_from_string对Round、Bevel、MiterXPS匹配其余回退为FZ_LINEJOIN_MITER。这也是为什么传入非法字符串时不会报错、而是静默得到默认样式——在写业务代码时应自行校验取值。三个核心术语线帽、线接与斜接极限StrokeState 中lineCap、lineJoin、miterLimit三个参数背后的图形学概念MuPDF 文档在术语表 glossary.rst 中有专门条目理解它们才能选对取值。线帽样式Line Cap StylePDF 规范定义了开放子路径未闭合路径端点的三种形状Butt平头线条在端点处垂直截断不向外延伸Round圆头端点处补上半圆形半径为线宽的一半Square方头端点处向外延伸半个线宽后垂直截断形状比 Butt 略长。线接样式Line Join Style两条线段在拐角处相接时PDF 定义三种接合形状Miter尖角/斜接两条线段的描边外缘延长相交形成尖角Round圆角拐角处以半径为线宽一半的圆弧过渡Bevel斜切拐角处用一条直线把两条描边外缘连接切掉尖角。斜接极限Miter Limit当使用 Miter 线接且夹角越来越小时尖角会向外越伸越长可能超出预期范围。PDF 因此定义 miter limit当斜接长度与线宽之比超过该阈值时尖角会自动退化为 Bevel 接合避免过长的尖刺。这是miterLimit参数的用途——它只对Miter线接生效。六个实例方法读取 StrokeState 的当前值StrokeState 构造完成后可通过六个 getter 读取当前参数。它们在 JS 层的实现集中在 source/tools/murun.c#L3179-L3216全部直接读取fz_stroke_state字段并转换为 JS 值。getLineCap()获取当前线帽样式返回值为字符串Butt | Round | Squarevar 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 | Bevelvar lineJoin strokeState.getLineJoin()getLineWidth()获取当前线宽返回 numbervar width strokeState.getLineWidth()注意读取到的是 StrokeState 中保存的原始线宽值实际渲染时该值还会随绘图变换矩阵ctm一起缩放。getMiterLimit()获取当前斜接极限返回 numbervar limit strokeState.getMiterLimit()getDashPhase()获取当前虚线相位——即描边从虚线图案的哪个位置开始返回 numbervar limit strokeState.getDashPhase()getDashPattern()获取当前虚线图案返回实线段长度与空隙长度交替排列的数字数组若未设置虚线则返回nullvar 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.strokePathstrokePath(path, stroke, ctm, colorspace, color, alpha)用给定 StrokeState 沿路径描边文档示例Device.rstdevice.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.rstdevice.strokeText(text, { dashes: [5, 10], lineWidth: 3, lineCap: Round }, mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, [1, 0, 0], 1 )对应 C 内核入口为fz_stroke_textinclude/mupdf/fitz/device.h#L346。描边裁剪clipStrokePath 与 clipStrokeTextStrokeState 还参与描边并裁剪操作clipStrokePath(path, stroke, ctm)与clipStrokeText(text, stroke, ctm)先用描边轮廓划定裁剪区域文档示例Device.rstdevice.clipStrokeText(text, { dashes: [5, 10], lineWidth: 3, lineCap: Round }, mupdf.Matrix.identity )对应 C 内核的fz_clip_stroke_path与fz_clip_stroke_textinclude/mupdf/fitz/device.h#L344-L348。计算描边后的边界Path.getBounds 与 Text.getBoundsStrokeState 不仅影响绘制还影响几何边界计算Path.prototype.getBounds(stroke, transform)接受StrokeState | null传入时按描边后的轮廓计算路径边界传null则按填充轮廓计算Path.rstText.prototype.getBounds(strokeState, transform)同理Text.rst。这在排版、碰撞检测、绘制包围盒等场景非常实用描边会让可见区域向外膨胀用 StrokeState 参与计算才能得到准确的命中区域。跨语言的一致性C、Java 与 JavaScriptStrokeState 并非 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描边参数模型与默认值完全一致概念可以无缝迁移。延伸阅读StrokeState 官方 API 文档本文主题的权威出处Device.rststrokePath、strokeText、clipStrokePath、clipStrokeText的完整参数说明与示例Path.rst路径构造与getBounds用法Text.rst文本对象与getBounds用法glossary.rst线帽、线接、斜接极限等术语的规范解释include/mupdf/fitz/path.hfz_stroke_state结构体与枚举定义source/fitz/path.c默认值、内存分配与字符串/枚举转换实现source/tools/murun.cJavaScript 绑定的 FFI 实现platform/java/jni/strokestate.cJava 绑定的 JNI 实现可对照阅读。赞分享图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载相关推荐urxvt-perls键盘快捷键大全vi模式编辑与高效文本选择技巧urxvt perls键盘快捷键大全vi模式编辑与高效文本选择技巧 想要在终端中实现像vim编辑器一样的文本选择体验吗urxvt perls为rxvt unFlet Map StrokePattern 类型详解为地图折线与多边形定制实线、虚线与点线描边Flet Map StrokePattern 类型详解为地图折线与多边形定制实线、虚线与点线描边 导读 flet_map.StrokePattern 是 Fl前端跨平台桌面应用移动开发flet.BorderSide 详解掌握 Flet 边框线的宽度、颜色、描边对齐与样式flet.BorderSide 详解掌握 Flet 边框线的宽度、颜色、描边对齐与样式 导读 在 Flet 中几乎任何需要画一条边框的场景—— Cont前端跨平台桌面应用移动开发上一篇突破配置限制EnvoyPatchPolicy实战指南——从API定义到生产级JSONPatch应用下一篇从零构建企业级Node.js Koa博客系统文章接口架构设计到性能优化全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考