Material Canvas

在Open 3D Engine (O3DE) 中创建材质类型和着色器通常是一个耗时的过程，需要熟悉引擎、渲染器、着色器、数据类型、文件格式以及所有内容的组合方式。它涉及手动编辑和管理多个文件、编写**Amazon Shading Language (AZSL)**着色器代码、在 JSON 中编辑、启动资产处理器编译它们、处理任何报告的错误，然后使用 O3DE 编辑器或材质编辑器预览和自定义资产。

Material Canvas 通过提供一个可视化脚本编辑器，以及熟悉的工具、工作流程、状态报告和实时预览，大大简化、加快并自动创建自定义着色器和材质类型。

通过拖放、连接和配置节点来构建材质图形，这些图形会自动转换为着色器、材质类型和材质的标准源文件。资产处理器会自动识别并处理生成的源文件，因此其他 O3DE 系统和组件也能使用这些材质。默认情况下，只要打开、编辑和保存图形，Material Canvas 就会重新生成并覆盖文件。视口会在更改和处理完成后迅速更新以显示结果。

Material Canvas 建立在与 Script Canvas 和 Material Editor 等其他 O3DE 工具相同的基础之上。它以数据为驱动、可定制、可扩展，并可通过设置注册表、Python 和 C++ 编写脚本。当前所有的材质图节点都定义在包含 AZSL 片段的 JSON 文件中。您可以在 Material Canvas 中编辑和创建新的材质图形节点。

有关 Atom 工具常用功能、菜单、可停靠面板和处理文档的更多信息，请参阅 Atom 工具常用功能。

快速启动

启动 Material Canvas

启动 “材质画布 ”有多种方法。

从O3DE编辑器，选择 主菜单 > Tools > Material Canvas
从Material Component上下文菜单，选择Open Material Canvas…
从Asset Browser，双击一个材质图表或其它与Material Canvas兼容的文件类型。
从Asset Browser，右击一个材质图表或其它与Material Canvas兼容的文件类型。然后选择 Open in Material Canvas…
Material Canvas 也是一个独立的可执行文件，可以直接从文件浏览器或命令控制台启动。
- 启动可执行程序 <build>\bin\profile\MaterialCanvas.exe。指定--project-path，跟上你的项目的路径，就像是命令行参数一样。例如：
```
 .\<build>\bin\profile\MaterialCanvas.exe --project-path MyProject
```

创建材质图形

您有多个选项可以开始编辑材质图形。

默认情况下，“材质画布 ”以一个无标题的空白材质图文档开始，您可以使用该文档创建新的材质图。
注意:
在保存图形之前，生成的文件会暂时输出到项目中的Assets/Materials/Generated 文件夹。保存图形后，生成的文件将输出到与图形相同的文件夹。
根据模板创建新的材质图形。
- 选择 Main Menu > File > New > New Material Graph Document…。这将打开 Create Material Graph Document 对话框。
- 选择一个模板作为新材质图形的基础。
  - 模板是以特殊的.materialgraphtemplate扩展名保存的材质图形，指定它们作为新图形的起点。
- 为新材质图形选择路径和文件名。
打开现有材质图形
- 选择 Main Menu > File > Open > Open Material Graph Document….
从 “资产浏览器 ”打开或创建材质图形。

创建节点

您可以通过将节点从节点调板拖动到图形视图或使用图形视图上下文菜单来创建节点。

将一个输出节点（如基础 PBR）从节点调板拖动到图形视图。您可以从任何节点开始，但如果没有输出节点驱动，则不会进行任何处理。
1. 注意状态栏显示正在生成和处理文件。
注意视口更新以在模型上显示生成的材质。

配置节点

您可以直接在图形视图或检查器中的节点上更改节点属性。如果选择基础 PBR 或标准 PBR 作为输出节点，材质最初是白色的。

例如，更改材质的颜色：

将base color更改为红色 (1,0,0,1)。
注意状态栏显示文件正在再生和重新处理。
注意视口更新后，材质和模型不再是红色。

连接节点

连接是一个节点的输出值与另一个节点的输入值之间的链接。

下面的指令演示了连接节点的常见情况：

在图形的任意位置创建 Float4 或 Color 输入节点。这些节点可以互换，但在用户界面中代表不同控件的值。
将连接线从输出插槽拖放到输出节点上的基色插槽。连接完成后，节点上的可编辑值将消失，并在 “检查器 ”中显示为灰色。
请注意，视口模型的颜色已从之前的颜色变为输入节点的颜色。更改输入节点的属性值，注意视口中颜色的更新。

对于输入节点，您也可以在 “材质编辑器 ”中打开生成的材质或材质类型，并在其中配置属性。

通过在功能、纹理采样、时间、变换和其他节点之间添加和嵌套连接，您可以创建更有趣、更高级的图形。在 Gems/Atom/Tools/MaterialCanvas/Assets/MaterialCanvas 文件夹中可找到多个示例。

Navigating Material Canvas

When you launch Material Canvas, you will see the following main window.

Material Canvas

有关 Atom 工具常用功能、菜单、可停靠面板和处理文档的更多信息，请参阅 Atom 工具常用功能。

文档类型和视图

Material Canvas 支持创建、打开和编辑多种类型的文档。

材质图文档

材质图文档（.materialgraph）是 Material Canvas 中的主要文档类型。每个打开的材质图形都有一个相应的二维网格图形视图，大部分编辑工作都在该视图中进行。所有与节点、连接、槽值、定位、选择相关的数据以及与图形相关的任何其他元数据都存储在材质图形文件中。

材质图节点文档

Material Graph Node 文档（.materialgraphnode）是 JSON 文件，用于定义可在 Material Canvas 中创建的每种类型的节点。它们包含节点及其插槽的唯一 ID、唯一名称、显示名称、描述、数据类型和默认值的设置。此外，它们还声明了 AZSL 着色器代码片段和其他元数据，Material Canvas 会使用这些代码和元数据来组装完整的着色器。当前所有的 Material Canvas 节点都是通过材质图节点配置文件指定的。也可以使用 C++ 或 Python 以编程方式创建和注册节点。

着色器源数据配置文档

着色器源数据配置文档（.shader）用于编辑着色器配置文件。它反映了所有支持的数据类型，因此你可以在检查器中或使用 Python 编辑着色器源数据文件。在检查器中，会列出所有选项。这对于编辑着色器源数据文件和为材质图形输出节点创建新模板非常有用。

主菜单

主菜单包含所有 Atom 工具通用的子菜单和操作，以及 Material Canvas 的特定操作。

有关 Atom 工具常用功能、菜单、可停靠面板和处理文档的更多信息，请参阅 Atom 工具常用功能。

Edit 菜单

除了 Atom 工具常用的选项外，当材质图形文档打开并处于活动状态时，还有管理图形及其元素的选项。

与脚本画布和横向画布类似，您可以选择、对齐、删除、复制、剪切、拷贝和粘贴节点。

View 菜单

除了 Atom 工具常用的选项外，还有导航和管理图表视图的选项，以及打开编辑器配置注释节点和节点组预设的选项。

Tools 菜单

通过 “工具 ”菜单，可以切换 “材质画布 ”特有的可停靠窗口。

停靠窗口

Material Canvas 提供了几个与图形相关的附加窗口。与 Material Editor 不同，视口也是可停靠的。

Node palette

节点调色板包含一棵树，树上有所有可用的材质图形节点和其他实用节点，您可以将它们添加到图形中。这些节点按类别排列，并以颜色标示。

您可以执行以下操作：

将鼠标悬停在树状图中的每个节点上，以阅读该节点的详细信息。
将调色板中的节点拖到活动图形视图中，在图形上的下拉位置创建该节点的实例。

Bookmarks

使用书签面板管理活动图表上的所有书签。您可以配置书签说明和颜色书签面板和检查器。

您可以执行以下操作：

在图表上放置书签，就像在地图上放置图钉一样，作为重要位置的参考点。
在书签上双击，将图表视图置于该位置的中心。

Mini Map

小地图窗口显示节点和图表的放大概览。点击并拖动小地图，可快速浏览图表的不同部分。

视口

视口可在可配置的照明条件下渲染包含模型的场景，并应用当前材质。视口窗口有一个工具栏，用于设置与网格、阴影捕捉器和色调映射模式相关的不同选项。此外，还有用于选择视口模型、照明预设和渲染管道的下拉菜单。照明预设包含天空盒、基于图像的照明、方向灯的所有设置，以及视口中使用的其他设置。自从引入材质管道系统后，渲染管道也可以在运行时更改。

有关视口以及如何与之交互的更多信息，请参阅 Atom Tools Viewport。

Viewport Settings

使用视口设置面板编辑活动照明预设。更改会反映在视口中。从该面板选择、创建和保存灯光预设。您还可以管理模型预设，它是用于识别视口中可用模型的辅助文件。视口设置面板目前不支持撤消和重做。

有关视口设置的更多信息，请参阅 Atom 工具视口。

编辑材质图

创建和放置节点

节点是每个材质图形的组成部分。每个节点都有其作用，提供数据或独特的功能，你可以将其添加到图形中。

要创建和放置节点，请执行以下操作之一：

将节点从节点调板拖到材质图形视图上。
右键单击图形视图，从嵌入的节点调板中选择一个节点。创建节点时，节点会出现在拖放或单击的位置。节点被选中后，其属性会显示在 “检查器 ”中供编辑。

根据系统限制，您可以重复此过程为图形添加更多节点。根据图形上节点的数量或所选节点的数量，某些操作的执行时间可能会更长。

添加节点后，可以通过拖动到新位置来移动和重组节点。访问工具栏和编辑菜单中的操作可更改所选节点的位置和对齐方式。

节点插槽和连接

每个 Material Canvas 节点都有一定数量的插槽。插槽定义了节点的属性、输入和输出。

属性插槽没有输入或输出连接。它们通常用作常量或描述节点的其他细节。

输入插槽具有默认值，这些值被节点内部使用的变量消耗并分配给这些变量。输入槽只能有一个输入连接。

输出插槽代表节点执行某些操作后的返回值。输出槽可以连接到其他节点上的多个输入槽。当一个输出槽连接到另一个节点上的输入槽时，输出槽的值将取代输入槽的值。

输入槽和输出槽之间的连接是通过拖动连接线来实现的。Material Canvas 可防止节点之间出现无效、递归或循环连接。

节点类型

Material Canvas 具有不同的节点类型，这些类型根据节点的功能分为不同的逻辑组和颜色编码。

输出节点（主节点）

材质图中最重要的节点类型是主输出节点。这些节点提供所有模板和元数据，指示 Material Canvas 生成什么数据。材质图中添加了具有正确配置的模板数据的输出节点后，Material Canvas 即开始生成数据。

目前，“材质画布 ”有两个输出节点。基础 PBR 节点和标准 PBR 节点包含输入插槽、选项和模板，可用于创建自定义着色器和材质，其光照模型和功能与核心材质类型类似。标准 PBR 节点并未包含所有功能。

请将其中一个节点拖到材质图形上进行试验。如果启用了自动图形编译设置（默认情况下是这样），则会在包含材质图形文件的文件夹中生成多个着色器文件、材质类型和默认材质。

Constant 节点

常量节点代表着色器代码中定义的常量变量。有多个常量节点与 AZSL 支持的不同数据类型相对应。这些节点应用于设置任何不需要暴露在着色器外部或可通过材质进行配置的变量。

Input 节点

输入节点表示命名变量，这些变量将被添加到材质 SRG 结构中，并在材质类型中显示属性和连接。这些属性将在 “材质编辑器 ”和材质组件中显示和配置。您还可以通过脚本控制它们。输入节点有额外的属性插槽，用于指定其名称、描述和其他数据，使其易于识别。与常量节点一样，AZSL 和材质系统支持的数据类型也有几种不同的节点。

Vertex 节点

顶点节点类别包含与不同顶点属性（如位置、法线、纹理坐标等）相对应的节点。同一属性在本地空间和世界空间都有节点。

Function 节点

函数节点类别包含几个数学相关和实用的函数节点，用于处理属性和输入值并返回结果。目前，大部分函数节点都是 AZSL 固有函数的封装器。

Texturing 节点

此类别包含与纹理采样相关的节点。请注意，某些纹理采样节点默认从恒定向量采样。您可能需要 UV 节点或其他不同顶点属性节点的输入，才能使用覆盖曲面或模型的纹理坐标进行采样。

Scene 节点

该类别旨在包含场景 SRG 元素的节点。目前，唯一公开的节点是时间。

Utility 节点

实用节点类别包含所有 O3DE 图形编辑工具使用的标准注释和分组节点。注释节点可以放置在整个图形中，以便对图形的特定部分进行注释和描述。您可以使用组节点作为图形上其他节点的容器。对于包含其他节点的组，您可以展开、折叠并将它们视为一个节点。

创建新的材质图节点

材质图节点（实用工具节点除外）完全由 JSON 配置文件定义。如前所述，这些文件描述了节点的 UUID、名称、描述、类别以及节点上每个插槽的布局和细节。节点配置可能会有额外的设置或元数据，以驱动代码和数据生成过程。

通过材质图节点文档检查器，可以创建唯一的节点 UUID、添加和删除插槽、选择数据类型、配置默认值以及管理节点和插槽的自定义设置。检查器还具有用于进行选择和编辑 AZSL 的自定义控件。

使用 Material Canvas 提供的工具可以从头开始创建节点。不过，有些节点非常简单，复制现有的材质图节点文件、更新 UUID 并使用工具或直接在 JSON 中进行更改可能会更方便。

材质图节点配置示例

下面是一个浮点常量节点的材质图节点配置，该节点有一个属性和一个输出槽。

{
    "Type": "JsonSerialization",
    "Version": 1,
    "ClassName": "DynamicNodeConfig",
    "ClassData": {
        "id": "{5E2A378E-D27D-43C0-B708-3586FA2293F3}",
        "category": "Constants",
        "title": "Float Constant",
        "titlePaletteName": "ConstantNodeTitlePalette",
        "description": "Create a shader constant with the type and value defined by this node.",
        "slotDataTypeGroups": [
            "inValue|outValue"
        ],
        "propertySlots": [
            {
                "name": "inValue",
                "displayName": "Value",
                "description": "Value",
                "supportedDataTypeRegex": "float", 
                "defaultDataType": "float",
                "settings": {
                    "instructions": [
                        "SLOTTYPE SLOTNAME = SLOTVALUE;"
                    ]
                }
            }
        ],
        "outputSlots": [
            {
                "name": "outValue",
                "displayName": "Value",
                "description": "Value",
                "supportedDataTypeRegex": "float",
                "defaultDataType": "float",
                "settings": {
                    "instructions": [
                        "SLOTTYPE SLOTNAME = inValue;"
                    ]
                }
            }
        ]
    }
}

材质图节点配置属性

每个节点配置都必须有一个唯一的 ID。这可以确保它们具有唯一的可识别性，而不受磁盘位置、项目、名称碰撞或其他因素的影响。

节点类别决定了节点在节点调色板树中的分组方式。

节点标题是节点调色板和图形视图中节点顶部显示的名称。它还用于在着色器代码中创建唯一的符号名称和变量名称。

节点标题调色板名称是一个可选字段，用于指定节点标题栏使用的样式表调色板。样式表可配置样式、着色、字体和其他属性，以控制节点调色板和图形视图中元素的显示方式。样式表是在一个单独的应用程序文件中定义的。

节点描述是一个可选字段，当你将鼠标悬停在调板中的节点上时，它会以工具提示的形式显示出来。

槽数据类型组包含一个槽名称分隔列表。Material Canvas 图形遍历和代码生成过程会强制将此字段中列出的所有插槽名称提升为相同的数据类型（如果它们是兼容的）。目前，如果列出的所有插槽都引用了标量或矢量值，那么所有插槽值都将提升为最大的数据类型。例如，如果节点上的所有插槽都是标量值，但输入的连接是三维向量，那么所有其他插槽都将向上转换为三维向量。除了其他形式的转换外，这样做也是必要的，这样从不同输入类型生成的变量才能与节点中定义的代码和函数调用兼容。

材质图节点槽配置属性

相对于节点而言，每个插槽配置都必须有一个唯一的名称。插槽名称用于标识和寻址插槽、建立插槽之间的连接，以及在生成的着色器代码和其他文件中创建唯一的变量名。如果没有指定显示名称，该名称还将用作用户界面中的显示名称。请避免更改名称，因为这会破坏连接并丢失与插槽相关的任何数据。

对于显示名称，请指定一个更方便用户使用的名称，以便在用户界面中显示。如果没有提供显示名称，则根据槽名推断名称。

描述提供了有关槽的作用或表示的更多细节。当您将鼠标悬停在图形视图中的节点和槽上时，这些信息会以工具提示的形式显示出来。

支持数据类型的正则表达式字段用于获取与插槽兼容的数据类型。使用正则表达式，可以查询与特定模式匹配的多个数据类型，也可以单独列出数据类型。

默认值字段用于为槽设置特定的默认值。这是可选项，因为系统会在注册所有数据类型时指定一个标准默认值。如果节点配置中没有指定明确的默认值，则将使用已注册的默认值。

材质图节点设置

材质图节点和插槽为任意设置提供了一个字段。材质图节点使用的设置数据包括 AZSL 指令块、模板文件列表、包含文件列表以及其他用于材质输入和着色器选项的条目。

在前面的示例中，设置用于添加 AZSL 指令块和代码片段，以便从属性槽创建变量，并在输出槽中返回变量值。

AZSL 指令的材质图节点设置

材质图节点和插槽配置都可以包含 AZSL 指令块的设置。这些指令设置是简单的 AZSL 代码行，用于创建变量、赋值、调用函数以及其他任何可以在 AZSL 中完成的操作。

在上述示例中，每个输入和输出插槽都添加了独特的指令集。输入槽指令用于创建带有槽类型和指定值的变量。输出槽指令创建另一个变量来保存乘法运算的结果。

在代码生成过程中，会按深度顺序遍历整个图形，并将每个节点的指令拼接在一起，以填充着色器程序。对于每个节点，指令按以下顺序添加：属性槽指令、输入槽指令、节点指令、输出槽指令。这样就形成了从输入到输出的确定数据流。在最终的着色器代码中，每个变量名的前缀都是该节点的唯一标识符。

使用以下宏在指令设置中插入节点或槽的详细信息。

SLOTTYPE 将被替换为当前插槽的 AZSL 数据类型。
SLOTTYPE(name) 将被指定名称的插槽的 AZSL 数据类型所替代。
SLOTNAME 会被替换为当前槽的唯一、经过修饰的变量名。
SLOTNAME(name) 会被指定名称的槽的唯一、经过修饰的变量名所替代。
SLOTVALUE 将被替换为当前时段的值，除非该时段有输入连接。如果有输入连接，则用该连接的唯一变量名代替。
SLOTVALUE(name) 将被指定名称的插槽值取代，除非该插槽有输入连接。如果有输入连接，则用该连接的唯一变量名代替。

故障排除

编辑图形后，“材质画布 ”视口不会立即更新

如果资产处理器尚未运行，Material Canvas 会自动启动该处理器。在主窗口打开之前，必须先处理一些与图形相关的资产。请等待资产处理器处理完所有资产。

着色器编译过程既昂贵又复杂，目前由着色器资产生成器管理。材质画布依靠 “资产处理器 ”和 “着色器资产生成器 ”来处理、验证和预览由材质图形生成的内容。在创建着色器和材质资产时，资产处理器会报告状态、错误信息和其他通知。视口更新着色器和材质预览的速度与处理这些资产的速度一样快。

在 Windows 上构建着色器资产要比在 Linux 或其他平台上花费更多时间。部分原因是 Windows 默认为空渲染器、DX12 和 Vulkan 构建着色器。可以对注册表设置进行配置，禁用未使用的目标，大幅缩短着色器编译和预览时间。使用 “材质画布 ”设置对话框可覆盖这些设置。

Material Canvas 启动失败

Material Canvas 会初始化游戏项目启用的所有 O3DE Gems，以访问相同的渲染功能和资产。为了减少启动时间和系统资源利用率，Material Canvas 和其他 Atom 工具包含注册表设置文件，可强制禁用工具内不需要的多个标准 O3DE Gems。

如果 Material Canvas 无法启动，则可能是因为活动项目中 Gems 的依赖性问题。检查 MaterialCanvas.log 是否有任何系统实体或模块初始化错误。如有必要，更改或删除 Material Canvas 项目注册表文件夹中的自定义注册表设置。