@builtin
标记着色器入口的系统输入或输出：输入值由 GPU/管线自动提供，输出值交给固定功能阶段；名称、阶段、方向与类型必须匹配规范。可用名称由 WGSL 枚举，不能自定义。
@builtin 在完整技术链路中承担什么职责？
先确认它处理的对象、输入与输出，再顺着课程和相邻概念检查边界。
@builtin 完整取值表20 个名称均由 WGSL 规范预定义，不能自定义；展开后可按阶段、方向和类型核对。
| 可用值 | 阶段 · 方向 | 类型 | 含义 | 要求 |
|---|---|---|---|---|
| vertex_index | 顶点 · 输入 | u32 | 当前顶点编号；非索引绘制从 firstVertex 开始，索引绘制还会计入 baseVertex。 | 核心 |
| instance_index | 顶点 · 输入 | u32 | 当前实例编号，从绘制命令的 firstInstance 开始。 | 核心 |
| clip_distances | 顶点 · 输出 | array<f32, N> | 到用户裁剪平面的有符号距离；N 最大为 8。 | clip_distances |
| position | 顶点输出 / 片元输入 | vec4<f32> | 顶点输出时是齐次裁剪空间位置；片元输入时是当前 framebuffer 位置。 | 核心 |
| front_facing | 片元 · 输入 | bool | 当前片元是否来自正面图元。 | 核心 |
| frag_depth | 片元 · 输出 | f32 | 由片元着色器显式写出的深度值。 | 核心 |
| primitive_index | 片元 · 输入 | u32 | 当前实例内已处理图元的编号；同一图元的所有片元取值一致。 | primitive_index |
| sample_index | 片元 · 输入 | u32 | 当前 MSAA 样本编号，范围为 0 到 sampleCount - 1。 | 核心 |
| sample_mask | 片元 · 输入/输出 | u32 | 输入时表示图元覆盖的样本；输出时可进一步关闭样本。 | 核心 |
| local_invocation_id | 计算 · 输入 | vec3<u32> | 当前 invocation 在所属工作组内的三维坐标。 | 核心 |
| local_invocation_index | 计算 · 输入 | u32 | 工作组内按 x 最快、再 y、最后 z 展开的线性编号。 | 核心 |
| global_invocation_id | 计算 · 输入 | vec3<u32> | 当前 invocation 在整个 dispatch 网格中的三维坐标。 | 核心 |
| global_invocation_index | 计算 · 输入 | u32 | 整个 dispatch 网格按 x、y、z 展开的线性编号。 | linear_indexing |
| workgroup_id | 计算 · 输入 | vec3<u32> | 当前工作组在 dispatch 网格中的三维坐标。 | 核心 |
| workgroup_index | 计算 · 输入 | u32 | 当前工作组在 dispatch 网格中的线性编号。 | linear_indexing |
| num_workgroups | 计算 · 输入 | vec3<u32> | 本次 dispatch 在 x、y、z 三个维度启动的工作组数量。 | 核心 |
| subgroup_invocation_id | 计算 / 片元 · 输入 | u32 | 当前 invocation 在线程子组中的编号。 | subgroups |
| subgroup_size | 计算 / 片元 · 输入 | u32 | 当前线程子组中的 invocation 数量。 | subgroups |
| subgroup_id | 计算 · 输入 | u32 | 当前工作组内的子组编号。 | subgroups + subgroup_id |
| num_subgroups | 计算 · 输入 | u32 | 当前工作组包含的子组数量。 | subgroups + subgroup_id |