Shader Platform Macro Generator

通过 Excel 配置每个平台、每个画质等级下的 Feature 开关，自动生成 HLSL 预处理宏头文件，减少 Shader 变体数量。 易于自定义，适用于 Unity / Unreal 等多种 Shader 语言和游戏引擎。

Configure feature switches per platform and quality tier via Excel, then auto-generate an HLSL preprocessor macro header to reduce shader variant count. Easy to customize, works with Unity / Unreal and any shader language using C-style preprocessor.

Usage

方式一：直接运行 EXE / Option 1: Run EXE directly

双击 ShaderPlatformMacroGenerator.exe，自动读取同目录下的 Config.xlsx，弹窗显示生成结果，点击按钮复制到剪贴板。

Double-click ShaderPlatformMacroGenerator.exe. It reads Config.xlsx from the same directory, shows the generated result in a popup, and provides a button to copy to clipboard.

方式二：通过 bat 指定配置文件 / Option 2: Specify config via bat

双击 _run_py.bat（或自定义 bat），通过命令行参数指定 Excel 路径：

Double-click _run_py.bat (or a custom bat) to specify the Excel path via command-line argument:

@echo off
python "%~dp0main.py" "Config.xlsx"
pause

也可指定其他路径 / You can also specify a different path:

ShaderPlatformMacroGenerator.exe "path/to/MyConfig.xlsx"

Excel 配置格式 / Excel Configuration Format

配置文件为 .xlsx 格式，包含以下 4 个 Sheet：

The config file is in .xlsx format with 4 sheets:

Platform Macros

定义平台及其预处理条件。A 列为平台名，B 列为宏条件（支持多行拼接）。

Defines platforms and their preprocessor conditions. Column A = platform name, Column B = macro condition (supports multi-line concatenation).

A (Platform)	B (Condition)
PC	defined(SHADER_API_D3D11)
	|| defined(SHADER_API_D3D12)
IOS	defined(SHADER_API_METAL)

Quality Macros

定义画质等级及其预处理条件。格式与 Platform Macros 一致，支持多行。

Defines quality tiers and their preprocessor conditions. Same format as Platform Macros, supports multi-line.

A (Quality)	B (Condition)
High	HYG_GRAPHIC_QUALITY_HIGH
Medium	HYG_GRAPHIC_QUALITY_MEDIUM
Low	HYG_GRAPHIC_QUALITY_LOW

Feature Switch

二维矩阵：行 = Feature，列 = Platform × Quality。

2D matrix: rows = Features, columns = Platform × Quality.

• Row 1：平台名（合并单元格跨越对应画质列） / Platform names (merged cells spanning quality columns)
• Row 2：画质名 / Quality names
• Row 3+：数据行 / Data rows
  • A 列有值、B 列为空 → 分组标题（输出为注释） / A has value, B empty → group header (output as comment)
  • A + B 列都有值 → Feature（B = Keyword，后续列 = 各组合的值） / A + B both have values → Feature (B = Keyword, following columns = values per combination)
  • 空行 → 忽略 / Empty row → skip

值可以是数字、字符串或函数调用，原样输出到 #define 后。

Values can be numbers, strings, or function calls — output as-is after #define.

Other Settings

通用的 Key-Value 配置。A 列为 key 名，B 列为值（支持多行）。

Generic key-value settings. Column A = key name, Column B = value (supports multi-line).

A (Key)	B (Value)
Prefix	// Tool Path: ...
	// 第二行注释
File Include Macro	MY_INCLUDE_GUARD_NAME

Sample Output

// Tool Path: //XXX/ShaderPlatformMacroGenerator

// Generated by Shader Platform Macro Generator (https://github.com/JasonMa0012/ShaderPlatformMacroGenerator)
// Unity Builtin Macros: https://docs.unity3d.com/2022.3/Documentation/Manual/SL-BuiltinMacros.html
// Unreal Builtin Macros: https://github.com/EpicGames/UnrealEngine/blob/5.5/Engine/Shaders/Public/Platform.ush

#ifndef COMMON_PLATFORM_FEATURE_CODEGEN_INCLUDE
    #define COMMON_PLATFORM_FEATURE_CODEGEN_INCLUDE

    // PC
    #if defined(SHADER_API_D3D11) || defined(SHADER_API_D3D12)
        #if HYG_GRAPHIC_QUALITY_HIGH
            // Reflection Probe
            #define _REFLECTION_PROBE_BLENDING 1
            #define _REFLECTION_PROBE_BOX_PROJECTION 1
            // Scene
            #define _POM_SAMPLE_COUNT 10
        #elif HYG_GRAPHIC_QUALITY_MEDIUM
            // Reflection Probe
            #define _REFLECTION_PROBE_BLENDING 1
            #define _REFLECTION_PROBE_BOX_PROJECTION 1
            // Scene
            #define _POM_SAMPLE_COUNT 8
        #endif
    // IOS
    #elif defined(SHADER_API_METAL)
        #if HYG_GRAPHIC_QUALITY_HIGH
            ...
        #endif
    #endif

#endif // COMMON_PLATFORM_FEATURE_CODEGEN_INCLUDE

Build

1. 安装依赖：运行 _install_deps.bat / Install dependencies: run _install_deps.bat

   • Python >= 3.10
   • openpyxl
   • pyinstaller

2. 打包 EXE：运行 _build.bat / Build EXE: run _build.bat

Project Structure

├── main.py              # 入口：参数解析 + 生成 + 弹窗 / Entry: arg parsing + generation + popup
├── excel_reader.py      # Excel 解析（动态发现，不硬编码索引） / Excel parser (dynamic discovery, no hardcoded indices)
├── hlsl_generator.py    # HLSL 代码生成 / HLSL code generation
├── Config.xlsx          # 配置文件 / Configuration file
├── _run_py.bat          # Python 运行入口 / Python run entry
├── _build.bat           # PyInstaller 打包脚本 / PyInstaller build script
├── _install_deps.bat    # 依赖安装脚本 / Dependency install script
└── requirements.txt     # Python 依赖 / Python dependencies