使用二进制着色器¶

使用二进制着色器可以减少 Kanzi 应用程序的加载时间。默认情况下，Kanzi 使用在线着色器，Kanzi Studio 将其作为源代码导出到 kzb 文件中。当您在目标设备上启动 Kanzi 应用程序时，应用程序使用 GL 驱动程序加载并编译着色器。此编译会增加应用程序的加载时间。使用二进制着色器时，Kanzi Studio 在您导出 kzb 文件时编译着色器，并以您设置的二进制格式导出着色器。您的目标设备可以立即使用二进制着色器。

您只能在支持二进制着色器驱动程序的GPU上使用二进制着色器。如果GPU不支持二进制着色器，Kanzi Engine 将从源代码编译着色器。即使设备的制造商声称支持特定的二进制着色器格式，这也并不总是意味着该设备支持所有二进制着色器。

您可以：

为您的目标设备创建二进制着色器格式。请参阅使用通用的二进制着色器格式。

如果您的平台不提供离线着色器编译工具，您可以使用包含应用程序所需着色器集的着色器二进制缓存。请参阅缓存着色器二进制文件。
使用二进制着色器覆盖 Kanzi 默认材质类型的着色器。请参阅使用二进制着色器覆盖 Kanzi 着色器。。
在 kzb 文件中，包含只采用特定目标硬件设备所需格式的二进制着色器。请参阅为工程中的多个目标设备设置二进制着色器。

使用通用的二进制着色器格式¶

要使用通用的二进制着色器格式：

确定您的目标设备所使用的 GPU 的 GPU 厂商、GPU 内核版本和 GPU 驱动程序版本，并从 GPU 厂商那里获得正确的二进制着色器编译器。
在 Library 中的 Kanzi Studio，按 Alt 并右键单击 Materials and Textures > Shader Formats 并选择 Binary Shader Format。

以您的目标设备所使用的 GPU 名称命名二进制着色器格式：

GPU 供应商	Name
Imagination Technologies	SGX_BINARY_IMG，或 IMG
ARM Mali	MALI_SHADER_BINARY_ARM
Vivante	SHADER_BINARY_VIV
Digital Media Professionals	SHADER_BINARY_DMP
Fujitsu Semiconductor	GCCSO_SHADER_BINARY_FJ
NVidia	NVIDIA_PLATFORM_BINARY_NV，或 Tegra
各种各样的	SPIR-V

如果您的目标设备使用任何其他 GPU，并且您具备该 GPU 的离线着色器编译器，则使用该着色器格式 GL 常量值的十进制值命名。

在 Properties 中，设置：

Enabled 属性用于使用二进制着色器格式。

当您启用 Enabled 属性时，Kanzi Studio 会编译您 Kanzi Studio 项目中的着色器。Kanzi Studio 会在 Log 窗口中显示您使用的编译器是否成功编译了着色器。
（可选） Theme 到为需要此二进制着色器格式的目标设备创建的烘焙主题。

当您将应用程序部署到 GPU 支持不同二进制着色器的不同设备上时，请使用主题在 kzb 文件中，包含只采用特定目标硬件设备所需的二进制着色器格式。请参阅为工程中的多个目标设备设置二进制着色器。

Shader Compile 到着色器编译器可执行文件和目标设备 GPU 的命令行。

Kanzi 将此添加到各个着色器阶段的前面。您可以使用此方法为所有着色器阶段设置通用选项。

使用 Kanzi Studio 宏来告诉编译器存储着色器二进制文件的位置。例如，BinaryShaderCompilerExecutable <vertexshadercode> <vertexshaderbinary>。

着色器代码和着色器二进制文件是文件系统上的临时文件。着色器编译器从 <shadercode> 读取并写入 <outputfile>。如果您的编译器输出带有后缀的二进制文件，请使用包装脚本仅输出没有后缀的二进制文件。

<shadertype> 宏扩展为当前编译的着色器类型：

着色器类型	Expands to
顶点着色器 (Vertex Shader)	`vertex`
片段着色器 (Fragment Shader)	`fragment`
几何着色器	`geometry`
细分控制着色器	`tesscontrol`
细分评估着色器	`tesseval`

这些值直接映射到 glslc -fshader-stage 选项所期望的着色器阶段类型。

例如：

glslc --target-env=opengl -fshader-stage=<shadertype> -o <outputfile> <shadercode>

这些属性用于设置特定着色器类型在目标设备 GPU 上的编译器可执行文件的特定选项：
- Vertex Shader Compile 到特定于顶点着色器编译器可执行文件的选项。
- Fragment Shader Compile 到特定于片段着色器编译器可执行文件的选项。
- Geometry Shader Compile 到特定于几何着色器编译器可执行文件的选项。
- Tessellation Control Shader Compile 到特定于细分控制着色器编译器可执行文件的选项。
- Tessellation Evaluation Shader Compile 到特定于细分评估着色器编译器可执行文件的选项。
对于每种着色器类型，使用 Kanzi Studio 宏告诉编译器将着色器二进制文件存储在哪里。例如，BinaryShaderCompilerExecutable <shadercode> <outputfile>。

着色器代码和着色器二进制文件是文件系统上的临时文件。着色器编译器从 <shadercode> 读取并写入 <outputfile>。如果您的编译器输出带有后缀的二进制文件，请使用包装脚本仅输出没有后缀的二进制文件。

当 GPU 供应商提供的编译器将所有类型的着色器集于一身时，请将 Combined Compile 设置为着色器编译器的位置和选项。

为了优化资源使用，请使用 Vertex Shader Compile 和 Fragment Shader Compile 或 Combined Compile，但不能同时使用。您可以在 Khronos OpenGL 注册表中找到您的扩展的详细信息。

您可以使用 <vertexshadercode> 和 <fragmentshadercode> 宏指向单个源，并使用 <shaderbinary> 宏指向合并的输出文件。

当您设置 Combined Compile 属性时，使用这些名称：

GPU 供应商	Name
Imagination Technologies	SGX_PROGRAM_BINARY_IMG
ARM Mali	MALI_PROGRAM_BINARY_ARM
Vivante	PROGRAM_BINARY_VIV
Digital Media Professionals	SMAPHS30_PROGRAM_BINARY_DMP SMAPHS_PROGRAM_BINARY_DMP DMP_PROGRAM_BINARY_DMP
NVidia	NVIDIA_PROGRAM_BINARY_NV
AMD	Z400_BINARY_AMD

要测试目标设备上的二进制着色器是否正常工作，请执行以下操作：
1. 选择 File > Export > Export KZB。
2. 在目标设备上启动您的 Kanzi 应用程序并检查应用程序日志。如果没有与二进制着色器相关的错误，则二进制着色器正常工作。请参阅部署 Kanzi 应用程序。

使用二进制着色器覆盖 Kanzi 着色器。¶

Kanzi 附带一组默认材质类型，用于执行基本渲染操作，例如渲染文本或混合纹理。Kanzi 将默认材质类型存储在专用的 kzb 文件中，这些文件嵌入在 Kanzi kzcoreui 和 kzui 库中。默认材质类型仅具有源着色器，这就是为什么 Kanzi 在应用程序启动期间或在应用程序运行时获取着色器时需要一些时间来编译着色器。要减少 Kanzi 应用程序的启动时间，您可以用目标设备的二进制着色器覆盖默认材质类型的内置源着色器。

要使用二进制着色器覆盖 Kanzi 着色器：

在 Kanzi Studio 中打开以下任一项：
- <KanziWorkspace>/Assets/RuntimeAssets/Tool_project/RuntimeAssets.kzproj Kanzi Studio 项目。
- 在您的 Kanzi 应用程序的主项目中，在 Library 按 Alt 并右键单击 Project References 中，选择 Existing Project，并选择 <KanziWorkspace>/Assets/RuntimeAssets/Tool_project/RuntimeAssets.kzproj Kanzi Studio 项目。请参阅将 Kanzi Studio 项目合并到 Kanzi 应用程序中。。Kanzi Studio 在新选项卡中加载 RuntimeAssets 项目。
（可选）如果您不想用二进制着色器覆盖所有 Kanzi 默认着色器，请在 RuntimeAssets 项目中删除：
- 您不希望将其着色器覆盖为二进制着色器的材质。
- 以上材质所使用的材质类型和着色器文件。
为您的目标设备创建二进制着色器格式。请参阅使用通用的二进制着色器格式。
在 RuntimeAssets 项目中：
1. 在主菜单中选择 Project > Properties，然后在 Properties 中：
  - 禁用 Export Shader Source Code 属性。
    
    如需缩小 kzb 文件大小，请不要导出着色器源代码。
  - 确保将 Property Namespace 清空。
2. 在 Node Tree 中选择 RuntimeAssetsScreen 节点，并在 Properties 中确保将 Disable KZB Export 属性启用。
选择 File > Export > Export KZB。

Kanzi Studio 在 <KanziWorkspace>/Assets/RuntimeAssets/Tool_project/Binary 目录中创建 RuntimeAssets.kzb 文件。
通过以下方式之一在您的 Kanzi 应用程序的 Resource Manager 中注册 RuntimeAssets.kzb 文件：
- 如果您的 Kanzi 应用程序使用 kzb 配置文件加载启动 kzb 文件，请将 RuntimeAssets.kzb 添加到应用程序主项目的 kzb 配置文件 <project_name>.kzb.cfg 中。
- 如果您将 RuntimeAssets.kzproj 作为项目引用添加到应用程序的主 Kanzi Studio 项目中，当您导出主项目的 kzb 文件时，Kanzi Studio 会自动将 RuntimeAssets.kzb 添加到主项目的 kzb 配置文件中。
- 如果您手动加载启动 kzb 文件，请使用 ResourceManager::addKzbFile 函数将 RuntimeAssets.kzb 文件添加到您的 Kanzi 应用程序的资源管理器中。
```
// At application startup register the RuntimeAssets.kzb file to the resource manager.
void onStartup() override
{
    getResourceManager()->addKzbFile("RuntimeAssets.kzb");
}
```
如果您的应用程序包含3D文本，请使用 <KanziWorkspace>/Assets/kzuiassets/Tool_project/kzuiassets.kzproj Kanzi Studio 项目重复该过程。

kzuiassets 项目包含默认情况下 Kanzi 用于渲染 3D 文本的材质类型。

当您运行您的 Kanzi 应用程序时，它从您的 RuntimeAssets.kzb 和 kzuiassets.kzb 文件加载二进制着色器，而不是使用内置的源着色器。这减少了您的 Kanzi 应用程序的启动时间，因为 Kanzi Engine 不需要编译源着色器。

为工程中的多个目标设备设置二进制着色器¶

在您的 Kanzi 解决方案中，每个包含着色器的 Kanzi Studio 项目对于每种类型的目标设备只需要一种二进制着色器格式。在 Kanzi Studio 中，您可以使用主题在每个 kzb 文件中仅包含特定目标设备所需的二进制着色器。当您的 Kanzi Studio 解决方案包含多个项目时，您可以在专用资源项目中存储着色器、材质类型和材质。这使您能够在单个项目中管理不同目标设备的内容。

要为一个工程中的多个目标设备设置二进制着色器，请执行以下操作：

在 Library > Themes 中创建一个 Theme Group，并在 Properties 中启用 Export Baked Usages 属性。

使用此 Theme Group 在为每个需要不同二进制着色器格式的目标设备创建主题时。

当您启用 Export Baked Usages 属性时，您可以从此主题组中的主题中烘焙资源。

请参阅烘焙的 Themes。
在 Library > Themes 中，双击您在上一步中创建的 Theme Group，并在 Theme Editor 中为每个需要不同二进制着色器格式的目标设备创建一个主题。请参阅使用 Themes。
在 Library > Materials and Textures > Shader Formats 中，选择您要使用的每个 Binary Shader Format，并在 Properties 中将 Theme 属性设置为您在上一步中为需要此二进制着色器格式的目标设备创建的主题。

通过这种方式，您可以将 Kanzi Studio 设置为使用此烘焙主题导出此 Binary Shader Format。
选择 File > Export > Export Baked Theme Binaries，并在 Themes and Locales to Bake on Export 窗口中为您创建的 Theme Group 选择 < All > 以烘焙该 Theme Group 中的所有主题，或选择您想要烘焙的特定主题。请参阅导出烘焙的 Themes。

当您导出烘焙主题时，Kanzi Studio 在每个 kzb 文件中包含的材质类型仅具有您为该烘焙主题设置的二进制着色器类型。

缓存着色器二进制文件¶

在性能受限的平台上，着色器编译可能会显著减慢应用程序启动速度并降低运行时性能。如果您的平台不提供离线着色器编译工具，您可以使用预先准备好应用程序所需的一组着色器的着色器二进制缓存。这样，您的应用程序在运行时就不必从源代码编译着色器。

要缓存着色器二进制文件，在应用程序配置中：

设置要存储着色器二进制缓存的目录。请参阅 ShaderBinaryCacheDirectory。
启用缓存。请参阅 ShaderBinaryCacheEnabled。
（可选）为防止哈希冲突，在开发期间，您可以将应用程序设置为存储着色器源代码并执行完整的字符串比较，以确保着色器是相同的。如果两个着色器产生相同的哈希值，应用程序会记录一个警告。请参阅 ShaderBinaryCacheCollisionCheck。
（可选）当您的应用程序准备好投入生产时，可以将着色器二进制缓存设置为只读。请参阅 ShaderBinaryCacheReadOnly。

例如，要么：

在 application.cfg 配置文件中，添加

# Set the shader binary cache directory to /tmp/shader-cache/.
ShaderBinaryCacheDirectory = "/tmp/shader-cache/"

# Enable the caching of shader binaries.
ShaderBinaryCacheEnabled = true

# Enable checking for hash collisions in cached shaders.
# Use this only during development.
ShaderBinaryCacheCollisionCheck = true

在 C++ 应用程序中的 Application::onConfigure 函数中，添加

// Set the shader binary cache directory to /tmp/shader-cache/.
configuration.shaderBinaryCacheDirectory = "/tmp/shader-cache/";

// Enable the caching of shader binaries.
configuration.shaderBinaryCacheEnabled = true;

// Enable checking for hash collisions in cached shaders.
// Use this only during development.
configuration.shaderBinaryCacheCollisionCheck = true;