1# .shader资源文件格式要求 2<!--Kit: ArkGraphics 3D--> 3<!--Subsystem: Graphics--> 4<!--Owner: @zzhao0--> 5<!--Designer: @zdustc--> 6<!--Tester: @zhangyue283--> 7<!--Adviser: @ge-yafang--> 8 9ArkGraphics 3D中支持的.shader文件基于JSON格式，书写.shader文件时需符合JSON语法要求。文件包含以下部分： 10 11## compatibility_info 12 - 类型：object 13 - 说明：用于向引擎声明shader版本兼容性信息。统一使用如下字段： 14 ```json 15 "compatibility_info": { "version": "22.00", "type": "shader" } 16 ``` 17 表示这是引擎22.00版本下的shader描述文件。 18 19## vert 20 - 类型：string 21 - 说明：指定使用该shader的DrawCall中使用的vertex shader文件。 22 - 默认值： 23 ```json 24 "vert": "3dshaders://shader/core3d_dm_fw.vert.spv" 25 ``` 26 - 自定义路径： 27 ```json 28 "vert": "appshaders://yourDir/yourShader.vert.spv" 29 ``` 30 其中yourDir/yourShader.vert.spv是用户使用的shader文件在文件沙箱中的路径。 31 32## frag 33 - 类型：string 34 - 说明：指定使用该shader的DrawCall中使用的fragment shader文件。 35 - 默认值： 36 ```json 37 "frag": "3dshaders://shader/core3d_dm_fw.frag.spv" 38 ``` 39 - 自定义路径： 40 ```json 41 "frag": "appshaders://yourDir/yourShader.frag.spv" 42 ``` 43 其中yourDir/yourShader.frag.spv是用户使用的shader文件在文件沙箱中的路径。 44 45## vertexInputDeclaration 46 - 类型：string 47 - 说明：指定输入vertex数据中的attributes排布方式。 48 - 当前限制：渲染引擎暂不支持自定义attributes排布，保持默认值即可。 49 - 默认值： 50 ```json 51 "vertexInputDeclaration": "3dvertexinputdeclarations://core3d_dm_fw.shadervid" 52 ``` 53 54## state 55 - 类型：object 56 - 说明：指定本次渲染管线中的pipeline state，包括rasterizationState、depthStencilState、colorBlendState三部分： 57 58### rasterizationState 59用于表示光栅化过程中的属性配置，具体包括： 60 - enableDepthClamp：用于控制渲染过程中的depth写入时是不是进行clamp，true表示进行clamp，false表示不进行clamp。当前此属性需保持值为false。 61 - enableDepthBias：用于控制渲染过程中的depth写入时是不是进行Bias计算，true表示进行Bias计算，false表示不进行Bias计算。当前此属性需保持值为false。 62 - enableRasterizerDiscard：用于控制本次drawCall的fragment阶段是否跳过，true表示跳过，false表示不跳过。 63 - polygonMode：用于指定光栅化渲染中的三角形填充方式，可取值及含义见下表。 64 | 可取值 | 说明 | 65 | :----: | :----: | 66 | "fill" | 全填充模式，将三角形内部所有像素填充颜色。 | 67 | "line" | 线填充模式，只绘制三角形的边线。 | 68 | "point" | 点填充模式，只绘制三角形的顶点。 | 69 70 - cullModeFlags：用于指定光栅化渲染中的culling方式，可取值及含义见下表。 71 | 可取值 | 说明 | 72 | :----: | :----: | 73 | "back" | 背面剔除，不渲染三角形的背面。 | 74 | "front" | 正面剔除，不渲染三角形的正面。 | 75 | "none" | 不进行剔除，正面和背面都渲染。 | 76 | "front_and_back" | 全部剔除，正面和背面都不渲染。 | 77 78 - frontFace：用于指定三角面的正面如何定义，可取值及含义见下表。 79 | 可取值 | 顶点排序方式 |说明 | 80 | :----: | :----: | :----: | 81 | "counter_clockwise" | 逆时针 | 按逆时针顺序排列的三角形被认为是正面。 | 82 | "clockwise" | 顺时针 | 按顺时针顺序排列的三角形被认为是正面。 | 83 84### depthStencilState 85用于表示深度测试和模板测试的状态属性，具体包括： 86 - enableDepthTest：用于控制是否开启深度测试，true表示开启，false表示关闭。若开启深度测试则非透明物体将按照深度呈现遮挡关系，若关闭深度测试则物体按照绘制顺序排序。 87 - enableDepthWrite：用于物体绘制时深度附件是否写入该物体的深度值，true表示写入，false表示不写入。 88 - enableDepthBoundsTest：在深度测试的基础上再规定了通过深度测试的最小值和最大值范围，在此范围之外的值不通过深度测试，true表示开启，false表示关闭。当前此属性需保持值为false。 89 - enableStencilTest：用于控制是否开启模板测试，true表示开启，false表示关闭。若开启模板测试则通过模板测试的物体会被绘制，没有通过模板测试的物体不被绘制，若关闭则不进行模板测试。 90 - depthCompareOp：用于控制深度测试的比较方式，可取值及含义见下表。 91 | 可取值 | 说明 | 92 | :----: | :----: | 93 | "never" | 永不通过深度测试，像素不会被绘制。 | 94 | "less" | 当前像素深度小于已有深度值时通过测试，像素被绘制。 | 95 | "equal" | 当前像素深度等于已有深度值时通过测试，像素被绘制。 | 96 | "less_or_equal" | 前像素深度小于或等于已有深度值时通过测试，像素被绘制。 | 97 | "greater" | 当前像素深度大于已有深度值时通过测试，像素被绘制。 | 98 | "not_equal" | 当前像素深度不等于已有深度值时通过测试，像素被绘制。 | 99 | "greater_or_equal" | 当前像素深度大于或等于已有深度值时通过测试，像素被绘制。 | 100 | "always" | 总是通过深度测试，像素总是被绘制。 | 101 102### colorBlendState 103用于指定本次渲染中渲染源与渲染目标的混合状态属性。包括colorAttachments，用于指定本次渲染中颜色附件的混合状态属性。colorAttachments具体包括如下几项： 104 - enableBlend：渲染源与渲染目标的混合是否开启，true表示开启混合，false表示关闭混合。若开启则渲染源与渲染目标以指定方式混合，若不开启则不启用混合。 105 - colorWriteMask：指定渲染颜色附件中通道掩码，若指定了通道掩码则该通道将被计算混合，若不指定则不计算混合，可取值有r_bit、g_bit、b_bit、a_bit，各个通道可以用|符号取并集，可取值及含义见下表。 106 | 可取值 | 说明 | 107 | :----: | :----: | 108 | "r_bit" | 红色通道允许写入或参与混合。 | 109 | "g_bit" | 绿色通道允许写入或参与混合。 | 110 | "b_bit" | 蓝色通道允许写入或参与混合。 | 111 | "a_bit" | 透明通道允许写入或参与混合。 | 112 113 - srcColorBlendFactor: 指定渲染源颜色通道的混合因子，可取值及含义见下表。 114 | 可取值 | 因子 | 结果 | 应用场景 | 115 | :----: | :----: | :----: | :----: | 116 | "zero" | 0 | 源颜色×0=0 | 不显示新颜色，只保留背景。 | 117 | "one" | 1 | 源颜色×1=源颜色 | 新颜色完全显示，覆盖背景。 | 118 | "src_color" | 源颜色 | 源颜色×源颜色 | 新颜色按自身颜色比例混合显示。 | 119 | "one_minus_src_color" | 1-源颜色 | 源颜色×(1-源颜色) | 新颜色按自身剩余颜色比例混合显示。 | 120 | "dst_color" | 目标颜色 | 源颜色×目标颜色 | 新颜色按背景颜色比例混合显示。 | 121 | "one_minus_dst_color" | 1-目标颜色 | 源颜色×(1-目标颜色) | 新颜色按背景剩余颜色比例混合显示。 | 122 | "src_alpha" | 源Alpha | 源颜色×源Alpha | 新颜色按自身Alpha比例混合显示。 | 123 | "one_minus_src_alpha" | 1-源Alpha | 源颜色×(1-源Alpha) | 新颜色按自身Alpha剩余比例混合显示。 | 124 | "dst_alpha" | 目标Alpha | 源颜色×目标Alpha | 新颜色按背景Alpha比例混合显示。 | 125 | "one_minus_dst_alpha" | 1-目标Alpha | 源颜色×(1-目标Alpha) | 新颜色按背景Alpha剩余比例混合显示。 | 126 | "constant_color" | 固定颜色常量 | 源颜色×固定颜色常量 | 新颜色按固定颜色比例混合显示。 | 127 | "one_minus_constant_color" | 1-固定颜色常量 | 源颜色×(1-固定颜色常量) | 新颜色按固定颜色剩余比例混合显示。 | 128 | "constant_alpha" | 固定Alpha常量 | 源颜色×固定Alpha常量 | 新颜色按固定Alpha比例混合显示。 | 129 | "one_minus_constant_alpha" | 1-固定Alpha常量 | 源颜色×(1-固定Alpha常量) | 新颜色按固定Alpha剩余比例混合显示。 | 130 | "src_alpha_saturate" | min(源Alpha, 1-目标Alpha) | 源颜色×min(源Alpha, 1-目标Alpha) | 新颜色按源Alpha与背景剩余Alpha最小值比例混合显示，避免叠加过强。 | 131 | "src1_color" | 第二源颜色 | 源颜色×第二源颜色 | 新颜色按第二源颜色比例混合显示。 | 132 | "one_minus_src1_color" | 1-第二源颜色 | 源颜色×(1-第二源颜色) | 新颜色按第二源颜色剩余比例混合显示。 | 133 | "src1_alpha" | 第二源Alpha | 源颜色×第二源Alpha | 新颜色按第二源Alpha比例混合显示。 | 134 | "one_minus-src1_alpha" | 1-第二源Alpha | 源颜色×(1-第二源Alpha) | 新颜色按第二源Alpha剩余比例混合显示。 | 135 136 - dstColorBlendFactor：指定渲染目标颜色通道的混合因子，可取值及含义见下表。 137 | 可取值 | 因子 | 结果 | 应用场景 | 138 | :----: | :----: | :----: | :----: | 139 | "zero" | 0 | 目标颜色×0=0 | 不显示背景颜色，相当于背景清零。 | 140 | "one" | 1 | 目标颜色×1=目标颜色 | 保留背景颜色原样，不受影响。 | 141 | "src_color" | 源颜色 | 目标颜色×源颜色 | 背景按新颜色比例混合显示。 | 142 | "one_minus_src_color" | 1-源颜色 | 目标颜色×(1-源颜色) | 背景按新颜色剩余比例混合显示。 | 143 | "dst_color" | 目标颜色 | 目标颜色×目标颜色 | 背景按自身比例混合显示。 | 144 | "one_minus_dst_color" | 1-目标颜色 | 目标颜色×(1-目标颜色) | 背景按自身剩余比例混合显示。 | 145 | "src_alpha" | 源Alpha | 目标颜色×源Alpha | 背景按源Alpha比例混合显示。 | 146 | "one_minus_src_alpha" | 1-源Alpha | 目标颜色×(1-源Alpha) | 背景按源Alpha剩余比例混合显示。 | 147 | "dst_alpha" | 目标Alpha | 目标颜色×目标Alpha | 背景按自身Alpha比例混合显示。 | 148 | "one_minus_dst_alpha" | 1-目标Alpha | 目标颜色×(1-目标Alpha) | 背景按自身Alpha剩余比例混合显示。 | 149 | "constant_color" | 固定颜色常量 | 目标颜色×固定颜色常量 | 背景按固定颜色比例混合显示。 | 150 | "one_minus_constant_color" | 1-固定颜色常量 | 目标颜色×(1-固定颜色常量) | 背景按固定颜色剩余比例混合显示。 | 151 | "constant_alpha" | 固定Alpha常量 | 目标颜色×固定Alpha常量 | 背景按固定Alpha比例混合显示。 | 152 | "one_minus_constant_alpha" | 1-固定Alpha常量 | 目标颜色×(1-固定Alpha常量) | 背景按固定Alpha剩余比例混合显示。 | 153 | "src_alpha_saturate" | min(源Alpha, 1-目标Alpha) | 目标颜色×min(源Alpha, 1-目标Alpha) | 背景按源Alpha与背景剩余Alpha最小值比例混合显示，避免叠加过强。 | 154 | "src1_color" | 第二源颜色 | 目标颜色×第二源颜色 | 背景按第二源颜色比例混合显示。 | 155 | "one_minus_src1_color" | 1-第二源颜色 | 目标颜色×(1-第二源颜色) | 背景按第二源颜色剩余比例混合显示。 | 156 | "src1_alpha" | 第二源Alpha | 目标颜色×第二源Alpha | 背景按第二源Alpha比例混合显示。 | 157 | "one_minus_src1_alpha" | 1-第二源Alpha | 目标颜色×(1-第二源Alpha) | 背景按第二源Alpha剩余比例混合显示。 | 158 159 - colorBlendOp：指定渲染源和渲染目标颜色通道的混合的混合方式，可取值及含义见下表。 160 | 可取值 | 说明 | 161 | :----: | :----: | 162 | "add" | 源颜色+目标颜色。 | 163 | "subtract" | 源颜色-目标颜色。 | 164 | "reverse_subtract" | 目标颜色-源颜色。 | 165 | "min" | 取源颜色与目标颜色的最小值。 | 166 | "max" | 取源颜色与目标颜色的最大值。 | 167 168 - srcAlphaBlendFactor：指定渲染源透明通道的混合因子，可取值及含义见下表。 169 | 可取值 | 因子 | 结果 | 应用场景 | 170 | :----: | :----: | :----: | :----: | 171 | "zero" | 0 | 源Alpha×0=0 | 不显示新颜色透明度，相当于透明度清零。 | 172 | "one" | 1 | 源Alpha×1=源Alpha | 保留新颜色透明度原样，不受影响。 | 173 | "src_color" | 源颜色 | 源Alpha×源颜色 | 新颜色透明度按自身颜色比例混合显示。 | 174 | "one_minus_src_color" | 1-源颜色 | 源Alpha×(1-源颜色) | 新颜色透明度按自身剩余颜色比例混合显示。 | 175 | "dst_color" | 目标颜色 | 源Alpha×目标颜色 | 新颜色透明度按背景颜色比例混合显示。 | 176 | "one_minus_dst_color" | 1-目标颜色 | 源Alpha×(1-目标颜色) | 新颜色透明度按背景剩余颜色比例混合显示。 | 177 | "src_alpha" | 源Alpha | 源Alpha×源Alpha | 新颜色透明度按自身Alpha比例混合显示。 | 178 | "one_minus_src_alpha" | 1-源Alpha | 源Alpha×(1-源Alpha) | 新颜色透明度按自身剩余Alpha比例混合显示。 | 179 | "dst_alpha" | 目标Alpha | 源Alpha×目标Alpha | 新颜色透明度按背景Alpha比例混合显示。 | 180 | "one_minus_dst_alpha" | 1-目标Alpha | 源Alpha×(1-目标Alpha) | 新颜色透明度按背景剩余Alpha比例混合显示。 | 181 | "constant_color" | 固定颜色常量 | 源Alpha×固定颜色常量 | 新颜色透明度按固定颜色比例混合显示。 | 182 | "one_minus_constant_color" | 1-固定颜色常量 | 源Alpha×(1-固定颜色常量) | 新颜色透明度按固定颜色剩余比例混合显示。 | 183 | "constant_alpha" | 固定Alpha常量 | 源Alpha×固定Alpha常量 | 新颜色透明度按固定Alpha比例混合显示。 | 184 | "one_minus_constant_alpha" | 1-固定Alpha常量 | 源Alpha×(1-固定Alpha常量) | 新颜色透明度按固定Alpha剩余比例混合显示。 | 185 | "src_alpha_saturate" | min(源Alpha, 1-目标Alpha) | 源Alpha×min(源Alpha, 1-目标Alpha) | 新颜色透明度按源Alpha与背景剩余Alpha最小值比例混合显示，避免叠加过强。 | 186 | "src1_color" | 第二源颜色 | 源Alpha×第二源颜色 | 新颜色透明度按第二源颜色比例混合显示。 | 187 | "one_minus_src1_color" | 1-第二源颜色 | 源Alpha×(1-第二源颜色) | 新颜色透明度按第二源颜色剩余比例混合显示。 | 188 | "src1_alpha" | 第二源Alpha | 源Alpha×第二源Alpha | 新颜色透明度按第二源Alpha比例混合显示。 | 189 | "one_minus-src1_alpha" | 1-第二源Alpha | 源Alpha×(1-第二源Alpha) | 新颜色透明度按第二源Alpha剩余比例混合显示。 | 190 191 - dstAlphaBlendFactor：指定渲染目标透明通道的混合因子，可取值及含义见下表。 192 | 可取值 | 因子 | 结果 | 应用场景 | 193 | :----: | :----: | :----: | :----: | 194 | "zero" | 0 | 目标Alpha×0=0 | 不显示背景透明度，相当于透明度清零。 | 195 | "one" | 1 | 目标Alpha×1=目标Alpha | 保留背景透明度原样，不受影响。 | 196 | "src_color" | 源颜色 | 目标Alpha×源颜色 | 背景透明度按新颜色比例混合显示。 | 197 | "one_minus_src_color" | 1-源颜色 | 目标Alpha×(1-源颜色) | 背景透明度按新颜色剩余比例混合显示。 | 198 | "dst_color" | 目标颜色 | 目标Alpha×目标颜色 | 背景透明度按自身比例混合显示。 | 199 | "one_minus_dst_color" | 1-目标颜色 | 目标Alpha×(1-目标颜色) | 背景透明度按自身剩余比例混合显示。 | 200 | "src_alpha" | 源Alpha | 目标Alpha×源Alpha | 背景透明度按源Alpha比例混合显示。 | 201 | "one_minus_src_alpha" | 1-源Alpha | 目标Alpha×(1-源Alpha) | 背景透明度按源Alpha剩余比例混合显示。 | 202 | "dst_alpha" | 目标Alpha | 目标Alpha×目标Alpha | 背景透明度按自身Alpha比例混合显示。 | 203 | "one_minus_dst_alpha" | 1-目标Alpha | 目标Alpha×(1-目标Alpha) | 背景透明度按自身剩余Alpha比例混合显示。 | 204 | "constant_color" | 固定颜色常量 | 目标Alpha×固定颜色常量 | 背景透明度按固定颜色比例混合显示。 | 205 | "one_minus_constant_color" | 1-固定颜色常量 | 目标Alpha×(1-固定颜色常量) | 背景透明度按固定颜色剩余比例混合显示。 | 206 | "constant_alpha" | 固定Alpha常量 | 目标Alpha×固定Alpha常量 | 背景透明度按固定Alpha比例混合显示。 | 207 | "one_minus_constant_alpha" | 1-固定Alpha常量 | 目标Alpha×(1-固定Alpha常量) | 背景透明度按固定Alpha剩余比例混合显示。 | 208 | "src_alpha_saturate" | min(源Alpha, 1-目标Alpha) | 目标Alpha×min(源Alpha, 1-目标Alpha) | 背景透明度按源Alpha与背景剩余Alpha最小值比例混合显示，避免叠加过强。 | 209 | "src1_color" | 第二源颜色 | 目标Alpha×第二源颜色 | 背景透明度按第二源颜色比例混合显示。 | 210 | "one_minus_src1_color" | 1-第二源颜色 | 目标Alpha×(1-第二源颜色) | 背景透明度按第二源颜色剩余比例混合显示。 | 211 | "src1_alpha" | 第二源Alpha | 目标Alpha×第二源Alpha | 背景透明度按第二源Alpha比例混合显示。 | 212 | "one_minus-src1_alpha" | 1-第二源Alpha | 目标Alpha×(1-第二源Alpha) | 背景透明度按第二源Alpha剩余比例混合显示。 | 213 214 - alphaBlendOp：指定渲染源和渲染目标透明通道的混合方式，可取值及含义见下表。 215 | 可取值 | 说明 | 216 | :----: | :----: | 217 | "add" | 源alpha+目标alpha。 | 218 | "subtract" | 源alpha-目标alpha。 | 219 | "reverse_subtract" | 目标alpha-源alpha。 | 220 | "min" | 取源alpha与目标alpha的最小值。 | 221 | "max" | 取源alpha与目标alpha的最大值。 | 222 223## materialMetadata 224 - 类型：`array<MaterialMetadata>` 225 - 说明：指定渲染材质的元数据。MaterialMetadata对象包含材质名称`name`及自定义属性`customProperties`。 226 227### name 228用于标识材质组件名称，当前有效值为"MaterialComponent"。 229 230### customProperties 231用于指定渲染中传入的自定义属性。包括data数组，用于指定渲染中传入的自定义数据。data数组中的对象包含以下属性： 232 - name：用于指定渲染中传入的自定义数据名字与自定义渲染中的数据名对应。 233 - displayName：用于指定3D编辑器中显示的名字。 234 - type：用于指定数据类型，可取值及含义见下表。 235 | 可取值 | 说明 | 236 | :----: | :----: | 237 | "vec4" | 4维向量`[x, y, z, w]`。 | 238 | "vec3" | 3维向量`[x, y, z]`。 | 239 | "vec2" | 2维向量`[x, y]`。 | 240 | "float" | 浮点数。 | 241 | "int" | 整数。 | 242 243 - value：属性默认值。 244 245## 示例 246```json 247{ 248 "compatibility_info" : { "version" : "22.00", "type" : "shader" }, 249 "vert": "3dshaders://shader/core3d_dm_fw.vert.spv", 250 "frag": "appshaders://custom_shader/custom_material_sample.frag.spv", 251 "vertexInputDeclaration": "3dvertexinputdeclarations://core3d_dm_fw.shadervid", 252 "state": { 253 "rasterizationState": { 254 "enableDepthClamp": false, 255 "enableDepthBias": false, 256 "enableRasterizerDiscard": true, 257 "polygonMode": "line", 258 "cullModeFlags": "back", 259 "frontFace": "counter_clockwise" 260 }, 261 "depthStencilState": { 262 "enableDepthTest": true, 263 "enableDepthWrite": true, 264 "enableDepthBoundsTest": false, 265 "enableStencilTest": false, 266 "depthCompareOp": "less_or_equal" 267 }, 268 "colorBlendState": { 269 "colorAttachments": [ 270 { 271 "enableBlend": true, 272 "colorWriteMask": "g_bit|b_bit", 273 "srcColorBlendFactor": "one", 274 "dstColorBlendFactor": "one_minus_src_alpha", 275 "colorBlendOp": "add", 276 "srcAlphaBlendFactor": "one", 277 "dstAlphaBlendFactor": "one_minus_src_alpha", 278 "alphaBlendOp": "add" 279 } 280 ] 281 } 282 }, 283 "materialMetadata": [ 284 { 285 "name": "MaterialComponent", 286 "customProperties": [ 287 { 288 "data": [ 289 { 290 "name": "vec_1", 291 "displayName": "Color", 292 "type": "vec4", 293 "value" : [1.0,1.0,1.0,1.0] 294 }, 295 { 296 "name": "time", 297 "displayName": "Time", 298 "type": "float", 299 "value": 0.0 300 }, 301 { 302 "name": "dof", 303 "displayName": "Dof", 304 "type": "int", 305 "value": 1 306 }, 307 { 308 "name": "motionblur", 309 "displayName": "MotionBlur", 310 "type": "int", 311 "value": 1 312 } 313 ] 314 } 315 ] 316 } 317 ] 318} 319```