预览

DreamShader » 工具 » 预览

编辑器端的渲染器，用于编译材质源并将其材质渲染为 PNG，可执行一次，也可作为帧流连续渲染。

渲染在游戏线程的 ticker 上运行。流式传输路径的存在正是为了不阻塞该线程。

[!NOTE] 自 1.7.0 起，流式传输路径默认使用原始 RGBA8 帧（encoding: "raw"）：编辑器读回渲染目标并将像素按原样发送，不进行 PNG 编码，客户端将它们直接绘制到画布上。这正是能够流畅实现 30–60 FPS 流式传输的原因。旧的 JSON 元数据加 PNG 路径仍可作为 encoding: "png" 供旧版客户端使用。会话还会对相同帧进行去重，并在画面静止后退避到较低的闲置速率，因此静止的预览几乎不消耗资源。有关线路格式，请参阅桥接 » 分帧。

断点（探针预览）

自 1.7.0 起。 在材质代码的某一行上设置的断点——.dsm 中的 Graph 行、.dss 中材质主体的语句 (自 2.0.0 起)——（在 DreamShaderLang VS Code 扩展中按 F9）会在网格体上预览该行绑定的值，而不是成品材质——这是材质编辑器右键开始预览节点的文本对应功能。

该机制复用了引擎自身的预览材质机制：一个临时的 UPreviewMaterial，它共享所生成材质的表达式集合，并将被探测的节点接入其中，通过 FMaterialUpdateContext 重新编译。UPreviewMaterial 受限的 ShouldCache 将该重新编译限制在少量着色器内。协议侧为 setProbe / clearProbe / probeState ——请参阅桥接 » 消息类型。

两条路径

[!NOTE] 流式传输路径不等待着色器编译。刚编辑过的材质的早期帧可能会显示先前或默认的着色器，直到编译完成；之后的帧会予以纠正。一次性路径会等待着色器就绪。文件/PNG 请求可能会短暂阻塞编辑器；原始请求会异步交付其单帧，包括在 frameRate <= 0 时。

帧会保留渲染开始时使用的摄像机、探针、编码和尺寸。在 GPU 读回期间更改的控件会应用于下一帧。启动另一个预览请求会丢弃前一个请求的任何待处理帧，因此它无法在新的请求 ID 下被发送。

材质内容浏览器的检查器也通过此渲染器进行渲染：一个 224×224 的预览，异步执行，每次编译时重新渲染。1.x 的 Dream Shader Gen 页面及其静态资产缩略图已被移除。

请求字段

尺寸限制会分别在三个点上独立应用——读取请求文件时、解析 WebSocket 消息时，以及渲染上下文内部——因此没有任何路径能够绕过它。

轨道默认值与 Unreal 自身的场景缩略图默认值相匹配，因此省略两个角度的请求会从与内容浏览器图块相同的视点进行渲染。

网格体

网格体名称的比较不区分大小写。任何无法识别的名称，包括空字符串，都会回退到球体。

[!WARNING] 未知的网格体名称会被静默接受并渲染一个球体。没有诊断信息。请检查 preview.json 或 previewResult 回复中回显的 mesh 字段，以查看实际使用的内容。

形状和两个轨道角度会在每次渲染前写入材质资产自身的场景缩略图信息——正是原生材质编辑器的预览形状按钮和拖拽轨道视口所写入的那些字段。如果材质没有该信息，则会延迟创建一个。

[!NOTE] 由于设置位于资产上，预览渲染会更改该材质的内容浏览器图块和材质编辑器预览视口所使用的形状和摄像机。

摄像机

渲染设置

GPU 就绪状态在该帧的复制命令之后于渲染线程上轮询，因此复用回读缓冲区不会把上一帧已完成的栅栏误认为当前帧的完成信号。游戏线程只检查异步结果。在捕获期间断开连接会安全地释放挂起的结果，而无效的渲染目标纹理会报告错误，而不是让捕获一直挂起。

[!WARNING] 请使用正方形 width/height。 预览通过 FThumbnailPreviewScene 进行渲染，其 投影矩阵构建为 FReversedZPerspectiveMatrix(halfFov, 1, 1, near) — 宽高比 是硬编码的，不会取自视图矩形。因此，非正方形的渲染目标并不会显示更多场景； 它会把球体拉伸成椭圆。这没有任何诊断提示。请请求正方形帧，如果其填充的表面 不是正方形，则在客户端一侧进行加黑边处理。

场景的材质接口在提交一帧后有意不清除；清除它会与仍在执行中的渲染命令产生竞态。

源文件的编译方式为交互式编译：即一个 ThinCustom 产物 Ephemeral，因此 预览永远不会将其写入磁盘；一个 Graph 后端材质和一个 .dsi 实例则是普通资产， 会像任何编译保存它们一样被保存 (自 2.0.0 起)。未更改的源文件会被构建键跳过， 除非请求强制进行。结果有意地类型化为材质接口，因为 默认的 ThinCustom 后端产生的是一层薄薄的材质实例而非 UMaterial，而 .dsi 则会生成一个材质实例。

输出

PNG 文件名为 <sanitized source stem>-<crc32 of the project-relative path>.png，其中 CRC 打印为八位小写十六进制数字。如果源文件的主干部分清洗后为空，则生成 DreamShaderPreview-<crc32>.png。

preview.json 字段：

流式预览

每条消息都以原始 WebSocket 二进制帧发出，因此操作码无法区分 JSON 与图像字节 — 这就是需要显式类型标签的原因。完整帧格式、标签 3 的原始帧头部以及帧标志位均记录于 Bridge » Framing。

previewControl 读取 requestId、stream、frameRate、orbitYaw、orbitPitch、width、 height、mesh 和 ackFrameIndex；除 requestId/ackFrameIndex 之外的每个字段在省略时都保持其 当前值。与活动会话不匹配的 requestId 会被忽略。

帧节奏

流式传输既受确认门控，也受速率限制。只有在两个条件同时满足时才会开始新的一帧：客户端已确认上一帧，且帧间隔已过去。 间隔为 1 / frameRate 秒，frameRate 被限制在 [0.25, 60.0]。

流式传输期间的任何错误都会关闭流式传输并发送错误 previewResult。

[!NOTE] 60 FPS 的上限之所以能够达到，仅仅是因为预览运行在它自己的每帧计时器上。 如果共用桥接的 0.1 秒请求计时器，则无论 frameRate 要求多少， 每个会话都会被限制在 10 FPS。

诊断

运行时替换显示为 {Placeholder}。

解析材质

按此顺序检查；第一个失败即为所报告的消息。

源文件由编译自身的前半部分解析 — 预处理器、前端、绑定器、import 头文件单独解析 — 因此预览与编译对于某个文件会构建哪个资产不可能产生分歧。1.x 预览会剥离 import 行并运行 1.x 解析器 (2.0.0 之前)。

渲染

Server

无法解析的入站消息会得到 previewResult 响应，其状态为 error， 消息为 Invalid DreamShader preview request JSON.

限制

• 仅支持材质来源 — .dss、.dsi、.dsm。.dsf、.dsh 或 .dsp 完全无法预览； 也没有函数预览。
• 尺寸在两个维度上都被限制为 [64, 2048]。
• 运动模糊、抗锯齿和动态屏幕百分比均已关闭，因此预览不会与视口捕获 逐像素匹配。
• 插件侧没有俯仰角限制。
• Alpha 通道会被丢弃 — 半透明材质会针对固定的清除颜色进行预览。
• 一次性路径会阻塞，直到所有着色器都编译完成；在冷着色器缓存上这可能会耗费 很长时间。
• 只能有一个异步回读处于未完成状态；启动第二个会返回 A preview readback is already in flight.
• 请求文件传输会完全忽略 orbitYaw 和 orbitPitch。

示例

由 bridge 请求文件驱动的一次性渲染。将其放入 <Project>/Saved/DreamShader/Bridge/Requests/，可使用任意 .json 名称；轮询器会处理它， 然后将其删除。

{
  "action": "previewMaterial",
  "sourceFile": "I:/Project/DShader/Materials/M_Emissive.dsm",
  "mesh": "shaderball",
  "width": 512,
  "height": 512,
  "requestId": "preview-1"
}

生成的 <Project>/Saved/DreamShader/Bridge/preview.json：

{
  "version": 1,
  "requestId": "preview-1",
  "status": "ready",
  "sourceFile": "I:/Project/DShader/Materials/M_Emissive.dsm",
  "assetPath": "/Game/Materials/M_Emissive.M_Emissive",
  "imagePath": "I:/Project/Saved/DreamShader/Bridge/Preview/M_Emissive-1a2b3c4d.png",
  "mesh": "shaderball",
  "message": "Rendered preview for /Game/Materials/M_Emissive.M_Emissive.",
  "updatedAtUtc": "2026-08-02T09:14:07Z"
}

另请参阅

• Bridge — 请求文件协议和完整的 WebSocket 消息架构
• Material Content Browser — 检查器的实时预览，由此渲染器绘制
• 编辑器集成 — -NoDreamShaderEditorBridge，它会禁用服务器
• 临时材质 — 为什么预览编译不会写入 ThinCustom 材质
• 后端 — 为什么预览的对象可能是实例而不是 UMaterial
• 源文件 — 哪些源会构建材质
• 工作区 — 驱动流式客户端的编辑器扩展
• 诊断索引 — 按阶段列出的每条消息