MGFX

简体中文

English

简体中文

English

Appearance

形状与线条 ​

Rounded、Chamfer、常用凸多边形、Poly、Line、Circle、Capsule 以及通用 shape style 能力。

适用边界 ​

  • 简单热路径优先用短签名，复杂视觉用 NameEx(..., style)。
  • 高级效果放在 style 里：fill、stroke、innerGlow、outerGlow、backdrop、pattern、transform。
  • RegularPoly、Diamond、Caret 覆盖常见凸多边形，不需要调用方手写点表。
  • Poly / PolyEx 的 public contract 是 3..8 个点的凸多边形，复杂路径应先拆成凸片段。

本页 API ​

  • RoundedBox - 高频路径圆角矩形 helper。
  • RoundedBoxBackdrop - backdrop-only 的 positional 热路径，不创建临时 style 表。
  • RoundedBoxEx - 表格式样式的高级圆角矩形。
  • ChamferBox - 高频路径切角矩形 helper。
  • ChamferBoxEx - 使用 style.cuts 的高级切角矩形。
  • RegularPoly - 正 3..8 边形 helper，适合徽章、六边形和等边三角形。
  • RegularPolyEx - 带 style 表的正多边形。
  • Diamond - 盒子内菱形 helper。
  • DiamondEx - 带 style 表的菱形。
  • Caret - 明确方向的三角箭头 helper。
  • CaretEx - 带 style 表和 direction 字段的三角箭头。
  • Poly - 根据调用方传入的点绘制凸多边形。
  • PolyEx - 带命名 style 字段的高级凸多边形。
  • Line - 用简单 positional 签名绘制线段。
  • LineNoCaps - 不把端点向外延伸半个线宽的 positional 线段。
  • LineEx - 带命名 width 与绘制字段的高级线条绘制。
  • Circle - 基于圆角盒覆盖的简单圆形 helper。
  • CircleEx - 使用圆角矩形样式模型的高级圆形。
  • Capsule - 简单胶囊矩形 helper。
  • CapsuleEx - 使用圆角矩形样式模型的高级胶囊。
  • style.stroke - 居中实线、点线、虚线和点划线描边。
  • style.backdrop - 由形状或图像遮罩裁剪的 framebuffer 模糊/染色效果。
  • style.transform - 用于形状、图像和组件 Ex 调用的绘制阶段视觉变换。
  • Radial vignette fill - 暗角现在用普通透明径向渐变 fill 表达。

style.stroke ​

shape 描边统一以轮廓为中心：一半宽度在形状内部，另一半在外部。旧写法 stroke = Color(...) 配合 strokeWidth 保持兼容；需要点线、虚线或点划线时， 把 stroke 写成 record：

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 12,
    fill = Color(18, 24, 32),
    stroke = {
        color = Color(90, 190, 255),
        width = 3,
        kind = "dot-dash",
        length = 12,
        gap = 6,
        offset = 0,
    },
})
字段说明
color必填描边 Color；也接受别名 tint。
width像素宽度。兼容字段 style.strokeWidth 单独给出时优先。
kind"solid"、"dot"、"dash" 或 "dot-dash"；默认 "solid"。
lengthdash 可见长度，单位像素。
gapdot 或 dash 之间的间距，单位像素。
offset图案相位，单位像素；每帧改变可得到流动效果。

非 solid 描边走独立 stroke pass，不改变 fill、渐变、阴影、发光和 backdrop 的原有路径。支持 RoundedBox、ChamferBox、Circle、Capsule、3..8 点凸多边形、 ProgressBar、SegmentBar、Ring、Arc 和 Sector。未知 kind 会直接报错，不会静默 退化为实线。

编译与无分配热路径 ​

每帧重复使用同一效果时，可在初始化阶段编译并复用：

lua
local backdrop = MGFX.CompileBackdrop({blur = 8, tint = Color(8, 16, 24, 90)})
local style = MGFX.CompileStyle({
    radius = 10,
    fill = Color(18, 24, 32),
    backdrop = backdrop,
}, MGFX.TARGET.ROUNDED_BOX)

MGFX.RoundedBoxEx(x, y, w, h, style)
MGFX.RoundedBoxBackdrop(x, y, w, h, 10, backdrop)
MGFX.LineNoCaps(x1, y1, x2, y2, 2, color)

CompileStyle 只做一次浅拷贝，并预规范化 backdrop 与 pattern 字段；调用方应把 返回值视为只读并跨帧复用。RoundedBoxBackdrop 与 LineNoCaps 用于已有标量参数的 高频路径，避免为一次绘制构造 style 表。

常用形状配方 ​

这些配方覆盖大多数 HUD/VGUI 需求。先从这里复制，再按完整函数参考微调。

带真实投影的卡片 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 10,
    fill = Color(20, 24, 32, 232),
    stroke = Color(255, 255, 255, 26),
    strokeWidth = "hairline",
    shadow = {
        {x = 0, y = 1, blur = 2, color = Color(0, 0, 0, 86)},
        {x = 0, y = 6, blur = 14, spread = 1, color = Color(0, 0, 0, 118), softness = 0.66},
    },
})
lux
import * as mgfx from "@lux/mgfx"

mgfx.api.roundedBoxEx(x, y, w, h, {
  radius = 10,
  fill = Color(20, 24, 32, 232),
  stroke = Color(255, 255, 255, 26),
  strokeWidth = "hairline",
  shadow = {
    {x = 0, y = 1, blur = 2, color = Color(0, 0, 0, 86)},
    {x = 0, y = 6, blur = 14, spread = 1, color = Color(0, 0, 0, 118), softness = 0.66},
  },
});

小控件把 shadow.y 降到 1..3、blur 降到 4..8。大面板可以用 y = 8..12、blur = 18..28。

RoundedBoxEx.shadow 支持数组形式，适合 CSS box-shadow 那样的多层阴影。这样比叠多个 RoundedBoxEx 更便宜：内部只循环 shadow-only path，不会重复 fill、stroke、backdrop、pattern 或 innerGlow。

只做毛玻璃，不做投影 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 12,
    fill = Color(0, 0, 0, 0),
    backdrop = {blur = 5, tint = Color(8, 14, 24, 112), opacity = 1},
    stroke = Color(255, 255, 255, 22),
    strokeWidth = 1,
})

backdrop 只影响形状内部覆盖范围。需要下坠阴影时加 shadow，不要用 backdrop 模拟 shadow。

切角状态块 ​

lua
MGFX.ChamferBoxEx(x, y, w, h, {
    cuts = {tl = 10, tr = 3, br = 10, bl = 3},
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(32, 42, 48, 230), Color(18, 24, 30, 230)),
    outerGlow = {width = 10, color = Color(80, 220, 255, 42), softness = 0.60},
})

cuts = 6..14 适合 HUD 卡片；高度很小的条形控件不要让切角超过 h * 0.45。

正多边形徽章、菱形、方向箭头 ​

lua
MGFX.RegularPolyEx(cx, cy, 18, 6, {
    rotation = 30,
    fill = Color(80, 170, 255, 220),
    shadow = {x = 0, y = 3, blur = 8, color = Color(0, 0, 0, 110), softness = 0.68},
})

MGFX.DiamondEx(x, y, 24, 24, {
    fill = Color(255, 190, 66, 220),
    stroke = Color(255, 255, 255, 48),
    strokeWidth = 1,
})

MGFX.CaretEx(x, y, 18, 18, {
    direction = "right",
    fill = Color(255, 112, 92, 220),
})

RegularPoly 是正 3..8 边形。等边三角形写 RegularPoly(..., 3, ...)；方向箭头写 Caret，不要用含糊的 Triangle 名称。

任意凸多边形 ​

lua
local points = {
    {x = x + 8, y = y},
    {x = x + w, y = y + 10},
    {x = x + w - 6, y = y + h},
    {x = x, y = y + h - 8},
}

MGFX.PolyEx(points, {
    fill = Color(28, 36, 44, 230),
    stroke = Color(255, 255, 255, 36),
    strokeWidth = 1,
    shadow = {x = 0, y = 4, blur = 10, spread = 1, color = Color(0, 0, 0, 120), softness = 0.68},
})

PolyEx 的 contract 是 3..8 点凸多边形。凹多边形、星形、复杂路径需要先拆成多个凸片段。

Rounded 和 Chamfer 的兼容 shadow + outerGlow 会走合成 shader pass。shadow 仍然是投影偏移，outerGlow 仍然是外部发光；合并只影响性能，不改变 API 语义。

效果参数速查 ​

字段推荐范围怎么调
radius小按钮 4..8，面板 8..16，胶囊 h * 0.5半径会被规范化，不会让相邻角相互穿透。
cuts小块 4..8，卡片 8..14切角过大会吃掉内容区；先限制在 h * 0.45 内。
shadow.x/y小控件 y = 1..3，卡片 4..8，大面板 8..12正 x 向右，正 y 向下；这是投影偏移。
shadow.blur小控件 4..8，卡片 10..18，大面板 18..28软边宽度，不是位置偏移。
shadow.spread0..3 常用先扩张形状再做软边；按钮通常 0..1，大面板 1..3。
outerGlow.width/size6..18 常用发光范围；需要不对称 glow 时可加 x/y 偏移。
innerGlow.width/size4..14 常用始终裁剪在形状内部，不支持偏移。
softness0..1，常用 0.55..0.75越大越柔；锐利 HUD 光可用 0.35..0.55。
backdrop.blur3..10 常用只模糊形状内部背景，和 shadow 是不同 pass。

函数参考 ​

RoundedBox ​

lua
MGFX.RoundedBox(x, y, w, h, radius, fill, stroke, strokeWidth)

高频路径圆角矩形 helper。

参数 ​

参数说明
x, y, w, h当前帧本地像素中的矩形。
radius像素圆角半径。单角半径请使用 RoundedBoxEx。
fillColor 或 MGFX 渐变记录。
stroke, strokeWidth可选描边颜色与宽度。

用法说明 ​

  • 适合简单面板、胶囊按钮和单元格。
  • 需要阴影、发光、图案或单角圆角时使用 RoundedBoxEx。

示例 ​

lua
MGFX.RoundedBox(16, 16, 220, 48, 8, Color(28, 34, 46, 230), Color(255, 255, 255, 28), 1)

RoundedBoxEx ​

lua
MGFX.RoundedBoxEx(x, y, w, h, style, children)

表格式样式的高级圆角矩形。

参数 ​

参数说明
style.radius数字或 {tl, tr, br, bl} 角表。
style.fillColor 或渐变填充。
style.stroke / strokeWidth可选描边。
style.shadow, innerGlow, outerGlow受支持路径上的可选特效。
style.patternStripePattern、SmokePattern 或 WornPattern 叠加。
children可选 callback；使用当前 rounded boundary 裁剪其内容。

用法说明 ​

  • 精细面板建议默认用它，因为高级字段都有名字。
  • radius 会被规范化，避免相对角超过矩形尺寸。
  • 提供 children 时，绘制层级为背景/效果 → 裁剪内容 → 前景描边；完整约束见 Coverage Mask、Clip 与 Shape 自遮罩。

半径与单角写法 ​

字段 / 可接受值默认值作用
number
像素半径。		0每个角使用相同半径。
{tl, tr, br, bl}
命名单角表，也接受数组顺序 {tl, tr, br, bl}。		0用于表格式形状 API 的单角半径。

style 字段 ​

字段 / 可接受值默认值作用
radius
数字或 {tl, tr, br, bl}。		0圆角半径。
fill
Color 或 MGFX 绘制记录。		color_white主体填充。
stroke / strokeWidth
Color 加数字、true、"hairline"、"thin" 或 "none" 宽度。		nil / 0可选描边。
shadow
true、数字，或 {x/y、offsetX/offsetY、dx/dy、offset、blur/radius/size/width、spread/grow、color/tint、opacity/strength、softness/falloff}。		nil外部软阴影；convex poly 使用多边形距离 shader。
innerGlow
true、Color，或 {color/tint, width/size, opacity/strength, softness/falloff}。		nil内边缘发光。
outerGlow
true、Color，或 {x/y、offsetX/offsetY、color/tint、width/size/spread、opacity/strength、softness/falloff}。		nil外发光；x/y 是方向偏置，不会像 shadow 那样移动发光源形状。
backdrop
true、数字、Color 或 {blur, tint, opacity}。		nil按圆角形状裁剪的 framebuffer 模糊/染色层。
pattern
MGFX.StripePattern、MGFX.SmokePattern、MGFX.WornPattern、true，或图案 spec 表。		nil在支持的形状路径上叠加图案。

支持目标与边界 ​

字段 / 可接受值默认值作用
Shape Ex calls
RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx。		supported调用内部的所有绘制/特效层共享同一个 transform。
Image Ex calls
ImageEx 和 IconEx。		supportedshader 图像、遮罩、backdrop、发光、背景和描边路径共享 transform。
Widget Ex calls
ProgressBarEx、SegmentBarEx、RingEx、ArcEx、SectorEx。		supported复合回退层会继承同一个 pushed transform。
Text
TextEx 和 TextBoxEx。		not promised文本使用独立的延迟 glyph/atlas 合成器。
Layout/input
帧坐标和命中测试。		unchangedtransform 只影响视觉。TransformPoint/UntransformPoint 只用于显式视觉辅助。

示例 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = {tl = 10, tr = 10, br = 4, bl = 4},
    fill = MGFX.LinearGradient(0, 0, 0, 1, Color(28, 34, 46), Color(16, 20, 28)),
    stroke = Color(255, 255, 255, 28),
    strokeWidth = 1,
    outerGlow = {color = Color(80, 170, 255, 46), width = 14},
})

ChamferBox ​

lua
MGFX.ChamferBox(x, y, w, h, cuts, fill, stroke, strokeWidth)

高频路径切角矩形 helper。

参数 ​

参数说明
cuts所有角共用的数字，或 {tl, tr, br, bl}。
fillColor 或渐变填充。
stroke, strokeWidth可选描边颜色与宽度。

用法说明 ​

  • cuts 会限制到较短边的一半。
  • 需要发光、图案和命名字段时使用 ChamferBoxEx。

切角写法 ​

字段 / 可接受值默认值作用
number
应用到每个角的像素切角。		0统一切角。
{tl, tr, br, bl}
命名表，也接受数组顺序 {tl, tr, br, bl}。		0单角切角。数值会限制到较短边的一半。

示例 ​

lua
MGFX.ChamferBox(16, 80, 220, 44, {tl = 10, tr = 0, br = 10, bl = 0}, Color(28, 34, 46, 230))

ChamferBoxEx ​

lua
MGFX.ChamferBoxEx(x, y, w, h, style, children)

使用 style.cuts 的高级切角矩形。

参数 ​

参数说明
style.cuts数字或 {tl, tr, br, bl}。
style.fillColor 或渐变填充。
style.pattern可选 StripePattern、SmokePattern 或 WornPattern。
style.innerGlow / outerGlow可选的切角感知发光效果。
children可选 callback；使用当前 chamfer boundary 裁剪其内容。

用法说明 ​

  • 适合棱角 HUD 面板、警告标记和科幻风 scoreboard 行。
  • 省略 style.cuts 时，形状基本等同矩形。
  • children 收到 x, y, w, h，描边会在 children 之后作为前景层绘制。

切角写法 ​

字段 / 可接受值默认值作用
number
应用到每个角的像素切角。		0统一切角。
{tl, tr, br, bl}
命名表，也接受数组顺序 {tl, tr, br, bl}。		0单角切角。数值会限制到较短边的一半。

style 字段 ​

字段 / 可接受值默认值作用
cuts
数字或 {tl, tr, br, bl}。		0切角尺寸。
fill
Color 或 MGFX 绘制记录。		color_white主体填充。
stroke / strokeWidth
Color 加描边宽度。		nil / 0切角感知描边。
shadow
true、数字，或 {x/y、offsetX/offsetY、dx/dy、offset、blur/radius/size/width、spread/grow、color/tint、opacity/strength、softness/falloff}。		nil外部软阴影。
innerGlow
true、Color，或 {color/tint, width/size, opacity/strength, softness/falloff}。		nil内边缘发光。
outerGlow
true、Color，或 {x/y、offsetX/offsetY、color/tint、width/size/spread、opacity/strength、softness/falloff}。		nil外发光；x/y 是方向偏置，不会像 shadow 那样移动发光源形状。
backdrop
true、数字、Color 或 {blur, tint, opacity}。		nil按切角形状裁剪的 framebuffer 模糊/染色层。
pattern
StripePattern、SmokePattern 或 WornPattern。		nil裁剪到切角多边形内的图案。

支持目标与边界 ​

字段 / 可接受值默认值作用
Shape Ex calls
RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx。		supported调用内部的所有绘制/特效层共享同一个 transform。
Image Ex calls
ImageEx 和 IconEx。		supportedshader 图像、遮罩、backdrop、发光、背景和描边路径共享 transform。
Widget Ex calls
ProgressBarEx、SegmentBarEx、RingEx、ArcEx、SectorEx。		supported复合回退层会继承同一个 pushed transform。
Text
TextEx 和 TextBoxEx。		not promised文本使用独立的延迟 glyph/atlas 合成器。
Layout/input
帧坐标和命中测试。		unchangedtransform 只影响视觉。TransformPoint/UntransformPoint 只用于显式视觉辅助。

示例 ​

lua
MGFX.ChamferBoxEx(x, y, w, h, {
    cuts = {tl = 12, tr = 3, br = 12, bl = 3},
    fill = Color(20, 26, 34, 235),
    pattern = MGFX.StripePattern({color = Color(255, 255, 255, 24), spacing = 9, width = 1}),
})

RegularPoly ​

lua
MGFX.RegularPoly(cx, cy, radius, sides, rotation, fill, stroke, strokeWidth)

正 3..8 边形 helper。等边三角形请用 sides = 3；MGFX 不提供含糊的 Triangle 名称。

参数 ​

参数说明
cx, cy中心点。
radius外接圆半径。
sides边数，限制为 3..8。
rotation第一顶点角度，单位度；默认方向用 -90 时顶点朝上。
fill, stroke, strokeWidth填充与可选描边。

示例 ​

lua
MGFX.RegularPoly(cx, cy, 14, 6, 30, Color(80, 170, 255, 220))

RegularPolyEx ​

lua
MGFX.RegularPolyEx(cx, cy, radius, sides, style)

带 style 表的正多边形。内部走 PolyEx，所以 fill、stroke、shadow、outerGlow、backdrop、pattern 和 transform 语义一致。

style 字段 ​

字段 / 可接受值默认值作用
rotation / angle
角度，单位度。		-90第一顶点方向；屏幕坐标中 -90 朝上，0 朝右。
fill
Color 或 MGFX 绘制记录。		color_white主体填充。
stroke / strokeWidth
Color 加宽度。		nil / 0边缘描边。
shadow / outerGlow / backdrop / pattern / transformnil与 PolyEx 相同。

示例 ​

lua
MGFX.RegularPolyEx(cx, cy, 18, 5, {
    rotation = -90,
    fill = MGFX.LinearGradient(0, 0, 1, 1, Color(80, 170, 255), Color(90, 220, 180)),
    shadow = {x = 0, y = 3, blur = 8, color = Color(0, 0, 0, 110), softness = 0.68},
})

Diamond ​

lua
MGFX.Diamond(x, y, w, h, fill, stroke, strokeWidth)

在矩形盒子内绘制上、右、下、左四点菱形。

参数 ​

参数说明
x, y, w, h菱形外接矩形。
fill, stroke, strokeWidth填充与可选描边。

示例 ​

lua
MGFX.Diamond(x, y, 24, 24, Color(255, 190, 66, 220))

DiamondEx ​

lua
MGFX.DiamondEx(x, y, w, h, style)

带 style 表的菱形。内部走 PolyEx，适合按钮焦点、选择标记和 HUD 装饰。

示例 ​

lua
MGFX.DiamondEx(x, y, 28, 28, {
    fill = MGFX.LinearGradient(0, 0, 1, 1, Color(80, 220, 255), Color(255, 190, 66)),
    outerGlow = {color = Color(80, 220, 255, 64), size = 10, softness = 0.62},
})

Caret ​

lua
MGFX.Caret(x, y, w, h, direction, fill, stroke, strokeWidth)

明确方向的三角箭头。它是三角形的一种具体语义，不替代所有 triangle 形态。

参数 ​

参数说明
x, y, w, h三角箭头外接矩形。
direction"right"、"left"、"up" 或 "down"。
fill, stroke, strokeWidth填充与可选描边。

示例 ​

lua
MGFX.Caret(x, y, 18, 18, "right", Color(255, 112, 92, 220))

CaretEx ​

lua
MGFX.CaretEx(x, y, w, h, style)

带 style 表的三角箭头。direction 可以写在 style.direction 或 style.dir，默认 "right"。

示例 ​

lua
MGFX.CaretEx(x, y, 18, 18, {
    direction = "down",
    fill = Color(255, 112, 92, 220),
    stroke = Color(255, 255, 255, 42),
    strokeWidth = 1,
})

Poly ​

lua
MGFX.Poly(points, fill, stroke, strokeWidth)

根据调用方传入的点绘制凸多边形。

参数 ​

参数说明
points{x, y} 或 {number, number} 点数组。
fillColor 或渐变填充。
stroke, strokeWidth可选描边。

用法说明 ​

  • 公共契约是凸多边形。凹多边形输入可能渲染错误。
  • 调用时会复制 points，之后调用方修改不会影响命令。

点格式 ​

字段 / 可接受值默认值作用
points[i]
{x = number, y = number}。		required命名点格式。
points[i]
{number, number}。		required数组点格式。
vertex count
3 到 8 个凸多边形顶点。		required凹多边形输入会被拒绝或渲染错误。

示例 ​

lua
MGFX.Poly({
    {x = x + 18, y = y},
    {x = x + w, y = y},
    {x = x + w - 18, y = y + h},
    {x = x, y = y + h},
}, Color(80, 170, 255, 160))

PolyEx ​

lua
MGFX.PolyEx(points, style)

带命名 style 字段的高级凸多边形。

参数 ​

参数说明
points凸多边形点数组。
style.fillColor 或渐变填充。
style.stroke / strokeWidth可选描边。
style.shadow / outerGlow基于凸多边形距离场的外部软阴影和外发光。
style.pattern受支持 shader 路径上的可选图案。

用法说明 ​

  • 适合菱形、斜角标签、方向标记和自定义凸 UI 板。
  • 一般复杂路径请先拆成凸形再传给 MGFX。

点格式 ​

字段 / 可接受值默认值作用
points[i]
{x = number, y = number}。		required命名点格式。
points[i]
{number, number}。		required数组点格式。
vertex count
3 到 8 个凸多边形顶点。		required凹多边形输入会被拒绝或渲染错误。

style 字段 ​

字段 / 可接受值默认值作用
fill
Color 或 MGFX 绘制记录。		color_white多边形填充。
stroke / strokeWidth
Color 加宽度。		nil / 0边缘描边。四点以内使用 shader 描边；回退路径绘制边线。
shadow
true、数字、Color，或 {x/y、offsetX/offsetY、dx/dy、offset、blur/radius/size/width、spread/grow、color/tint、opacity/strength、softness/falloff}。		nil基于凸多边形距离场的外部软阴影；x/y 控制偏移，spread/grow 控制实体扩张，blur 控制软边宽度。
outerGlow
true、Color，或 {x/y、offsetX/offsetY、color/tint、width/size/spread、opacity/strength、softness/falloff}。		nil基于凸多边形距离场的外发光；x/y 会把 glow 偏向一侧，但不会平移多边形轮廓。
backdrop
true、数字、Color 或 {blur, tint, opacity}。		nil按多边形裁剪的 framebuffer 模糊/染色层。
pattern
StripePattern、SmokePattern 或 WornPattern。		nil裁剪到多边形内的图案。

支持目标与边界 ​

字段 / 可接受值默认值作用
Shape Ex calls
RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx。		supported调用内部的所有绘制/特效层共享同一个 transform。
Image Ex calls
ImageEx 和 IconEx。		supportedshader 图像、遮罩、backdrop、发光、背景和描边路径共享 transform。
Widget Ex calls
ProgressBarEx、SegmentBarEx、RingEx、ArcEx、SectorEx。		supported复合回退层会继承同一个 pushed transform。
Text
TextEx 和 TextBoxEx。		not promised文本使用独立的延迟 glyph/atlas 合成器。
Layout/input
帧坐标和命中测试。		unchangedtransform 只影响视觉。TransformPoint/UntransformPoint 只用于显式视觉辅助。

示例 ​

lua
MGFX.PolyEx(points, {
    fill = MGFX.LinearGradient(0, 0, 1, 1, Color(80, 170, 255), Color(90, 220, 180)),
    stroke = Color(255, 255, 255, 36),
    strokeWidth = 1,
    outerGlow = {color = Color(80, 170, 255, 58), width = 12},
})

Line ​

lua
MGFX.Line(x1, y1, x2, y2, width, fill)

用简单 positional 签名绘制线段。

参数 ​

参数说明
x1, y1, x2, y2当前帧本地像素中的线段端点。
width线宽，单位像素。
fillColor 或线性渐变。

用法说明 ​

  • 需要端点、radius 或发光时使用 LineEx。
  • 水平和垂直线在可行时会使用优化矩形路径。

示例 ​

lua
MGFX.Line(24, 64, 220, 64, 2, Color(80, 170, 255, 220))

LineEx ​

lua
MGFX.LineEx(x1, y1, x2, y2, style)

带命名 width 与绘制字段的高级线条绘制。

参数 ​

参数说明
style.width线条厚度，单位像素。
style.fillColor 或渐变。
style.noCaps设为 true 可避免斜线 quad 的延伸端点。
style.radius / outerGlow可选圆角矩形路径或线段四边形发光路径。

用法说明 ​

  • 当线条样式需要在调用点保持可读时使用 LineEx。
  • 渐变使用图元本地归一化绘制模型。

style 字段 ​

字段 / 可接受值默认值作用
width
数字。		1线宽，单位像素。
fill / color
Color 或 MGFX 绘制记录。		color_white线段绘制。渐变会沿线段采样。
noCaps
布尔 true。		false在四边形路径上移除圆头端帽。
caps
布尔兼容字段。		true设为 false 等同于 noCaps = true。
radius
数字。		nil轴对齐线段矩形可走圆角矩形渲染。
outerGlow
发光 spec 表。		nil轴对齐线段使用矩形路径，斜线使用线段四边形覆盖绘制发光。
backdrop
true、数字、Color 或表。		nil按线段覆盖区域裁剪的 framebuffer 模糊/染色。

支持目标与边界 ​

字段 / 可接受值默认值作用
Shape Ex calls
RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx。		supported调用内部的所有绘制/特效层共享同一个 transform。
Image Ex calls
ImageEx 和 IconEx。		supportedshader 图像、遮罩、backdrop、发光、背景和描边路径共享 transform。
Widget Ex calls
ProgressBarEx、SegmentBarEx、RingEx、ArcEx、SectorEx。		supported复合回退层会继承同一个 pushed transform。
Text
TextEx 和 TextBoxEx。		not promised文本使用独立的延迟 glyph/atlas 合成器。
Layout/input
帧坐标和命中测试。		unchangedtransform 只影响视觉。TransformPoint/UntransformPoint 只用于显式视觉辅助。

示例 ​

lua
MGFX.LineEx(x, y, x + w, y, {
    width = 3,
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(80, 170, 255), Color(90, 220, 180)),
    outerGlow = {color = Color(80, 170, 255, 60), width = 12},
})

Circle ​

lua
MGFX.Circle(cx, cy, radius, fill, stroke, strokeWidth)

基于圆角盒覆盖的简单圆形 helper。

参数 ​

参数说明
cx, cy圆心。
radius圆半径，单位像素。
fill, stroke, strokeWidth填充与可选描边。

用法说明 ​

  • 适合点、状态灯和圆形徽章。
  • 需要特效字段时使用 CircleEx。

示例 ​

lua
MGFX.Circle(x + 12, y + 12, 6, Color(90, 220, 180), Color(255, 255, 255, 40), 1)

CircleEx ​

lua
MGFX.CircleEx(cx, cy, radius, style, children)

使用圆角矩形样式模型的高级圆形。

参数 ​

参数说明
style.fillColor 或渐变填充。
style.stroke / strokeWidth可选描边。
style.shadow, innerGlow, outerGlow, pattern可选形状特效。
children可选 callback；收到圆形外接方框 x, y, size, size。

用法说明 ​

  • MGFX 会根据圆心和半径计算盒子，再应用圆形半径。
  • 圆形图片请使用 ImageEx(..., {mask = {kind = "circle"}})；MGFX.Mask(painter) 属于多次绘制共享 coverage 的 Clip API。
  • children 形式直接以圆自身为抗锯齿 Clip，不需要再创建 MGFX.Masks.Circle。

示例 ​

lua
MGFX.CircleEx(cx, cy, 18, {
    fill = Color(80, 170, 255, 220),
    outerGlow = {color = Color(80, 170, 255, 75), width = 16},
})

Capsule ​

lua
MGFX.Capsule(x, y, w, h, fill, stroke, strokeWidth)

简单胶囊矩形 helper。

参数 ​

参数说明
x, y, w, h胶囊边界。
fill, stroke, strokeWidth填充与可选描边。

用法说明 ​

  • 半径自动为较短边的一半。
  • 适合标签、紧凑条和胶囊按钮。

示例 ​

lua
MGFX.Capsule(x, y, 96, 24, Color(80, 170, 255, 180), Color(255, 255, 255, 36), 1)

CapsuleEx ​

lua
MGFX.CapsuleEx(x, y, w, h, style, children)

使用圆角矩形样式模型的高级胶囊。

参数 ​

参数说明
style.fillColor 或渐变填充。
style.stroke / strokeWidth可选描边。
style.shadow, innerGlow, outerGlow, pattern可选特效。
children可选 callback；收到 x, y, w, h 并由胶囊边界裁剪。

用法说明 ​

  • CapsuleEx 会根据当前渲染尺寸设置半径；胶囊形状本身不需要传 style.radius。
  • 当胶囊表示一个 clamp 后的数值时使用 ProgressBarEx。
  • children 形式的 transform 与 bounds 限制见 自遮罩 API。

示例 ​

lua
MGFX.CapsuleEx(x, y, w, 28, {
    fill = MGFX.LinearGradient(0, 0, 1, 0, Color(80, 170, 255), Color(90, 220, 180)),
    outerGlow = {color = Color(80, 170, 255, 45), width = 10},
})

style.backdrop ​

lua
style.backdrop = true | number | Color | {blur, tint, opacity, level, recapture}

由形状或图像遮罩裁剪的 framebuffer 模糊/染色效果。Backdrop 只影响形状内部覆盖范围，不是投影；需要 drop shadow 时使用 style.shadow。

参数 ​

参数说明
true使用默认 blur = 4。
number数字值会作为 blur 强度。
Color只绘制按形状裁剪的 tint。
table支持 blur、tint/color、opacity/strength、padding/spread、整数 level 和显式 recapture。

用法说明 ​

  • Backdrop 是 style 字段，不再是独立 primitive。
  • RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、RingEx、ArcEx、SectorEx、CircleEx、CapsuleEx 和 ImageEx 都会按自身覆盖区域裁剪它。
  • 每个引擎渲染帧按整数 level 分层捕获 framebuffer，并用横向、纵向两个全屏 pass 建立该层共享模糊源；同层同强度的后续 shape 只做一次带遮罩采样。
  • 提高 level 会在当前绘制位置捕获，使高层包含已经画出的低层 UI；同层切换强度只重跑模糊 pass。只有同层内也必须更新 framebuffer 源时才设置 recapture = true。

style 字段 ​

字段 / 可接受值默认值作用
true
快捷写法。		{blur = 4}默认按形状裁剪的模糊。
number
快捷写法。		{blur = number}数字作为 blur 强度。
Color
快捷写法。		{tint = Color}只绘制按形状裁剪的 tint。
blur / size
数字。		0帧缓冲模糊强度。
tint / color
Color。		transparent覆盖在模糊区域上的颜色。
opacity / strength
0..1 数字。		1tint alpha 的乘数。
padding / spread
数字。		0为形状 backdrop pass 预留的扩展提示。
level
整数。		0backdrop 捕获层；层变化时在当前绘制位置捕获 framebuffer。
recapture
布尔值。		false在同一 level 内也强制重新捕获 framebuffer；后续同层 backdrop 复用新结果。

示例 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 12,
    fill = Color(0, 0, 0, 0),
    backdrop = {blur = 5, tint = Color(8, 14, 24, 150)},
})

style.transform ​

lua
style.transform = MGFX.Transform(...) | MGFX.PointerTilt(...) | MGFX.ProjectedQuad(...)

用于形状、图像和组件 Ex 调用的绘制阶段视觉变换。

参数 ​

参数说明
origin类似 CSS 的原点，例如 "50% 50%"、"left top" 或 {x, y}。
rotate / rotateX / rotateY角度，单位度。
perspective2.5D 投影的透视距离。
scale / translate / skew2D 变换字段；translate 可包含 z。
steps / subdivisions投影/透视变换的网格细分数。

用法说明 ​

  • transform 只影响视觉绘制，不改变布局、命中测试、文本排版或矩形裁剪。
  • 支持 RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx、ImageEx、IconEx、ProgressBarEx、SegmentBarEx、RingEx、ArcEx 和 SectorEx。
  • TextEx/TextBoxEx 暂不属于这个 transform 契约，因为文本使用独立 glyph atlas 合成器。

transform 字段 ​

字段 / 可接受值默认值作用
origin / transformOrigin
"50% 50%"、"left top"、{x, y} 或数字。		"50% 50%"用于缩放、旋转、透视和指针倾斜的锚点。
rotate / rotateZ
角度，单位度。		0围绕 origin 的 2D 旋转。
rotateX / rotateY
角度，单位度。		02.5D 倾斜。透视/投影路径会被细分，让现有 shader 保持有效 UV。
perspective
数字。		0 / 900 for PointerTilt透视距离。数值越大投影越平。
scale / scaleX / scaleY
数字或 {x, y}。		1围绕 origin 的视觉缩放。
translate / x/y/z
{x, y, z} 或独立字段。		0视觉位移；z 只影响透视。
skew / skewX / skewY
角度，单位度。		0旋转前的 2D 斜切。
steps / subdivisions
0..24 的整数。		auto投影和透视变换的细分数。

支持目标与边界 ​

字段 / 可接受值默认值作用
Shape Ex calls
RoundedBoxEx、ChamferBoxEx、PolyEx、LineEx、CircleEx、CapsuleEx。		supported调用内部的所有绘制/特效层共享同一个 transform。
Image Ex calls
ImageEx 和 IconEx。		supportedshader 图像、遮罩、backdrop、发光、背景和描边路径共享 transform。
Widget Ex calls
ProgressBarEx、SegmentBarEx、RingEx、ArcEx、SectorEx。		supported复合回退层会继承同一个 pushed transform。
Text
TextEx 和 TextBoxEx。		not promised文本使用独立的延迟 glyph/atlas 合成器。
Layout/input
帧坐标和命中测试。		unchangedtransform 只影响视觉。TransformPoint/UntransformPoint 只用于显式视觉辅助。

示例 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 10,
    fill = Color(28, 34, 46, 230),
    transform = MGFX.PointerTilt(mx, my, {
        origin = "50% 50%",
        perspective = 900,
        maxRotateX = 4,
        maxRotateY = 6,
        strength = hover,
        steps = 12,
    }),
})

Radial vignette fill ​

lua
fill = MGFX.RadialGradient(cx, cy, radius, stops)

暗角现在用普通透明径向渐变 fill 表达。

参数 ​

参数说明
stops使用显式透明/不透明 stops。
alpha缺省 alpha 等于 255；需要消失时写 Color(..., 0)。

用法说明 ​

  • 这替代旧的 backdrop 内置 vignette 字段。
  • 需要边缘暗角时，把它作为单独形状层绘制。

示例 ​

lua
MGFX.RoundedBoxEx(x, y, w, h, {
    radius = 12,
    fill = MGFX.RadialGradient(0.5, 0.5, 0.85, {
        {0, Color(0, 0, 0, 0)},
        {1, Color(0, 0, 0, 96)},
    }),
})

返回详细 API 入口