手册:材质

来自Minecraft基岩版开发Wiki

在原版附加包中，大部分的材质可以通过资源包materials文件夹中的.material扩展名文件来定义。该文件的代码遵循JSON的语法格式，仅仅是扩展名较为特殊。这些文件本是为HAL渲染引擎而设计的，不过在RenderDragon渲染引擎更新后也可在一定限制下（如不可自定义宏定义）适用于RenderDragon。不同附加包定义的同名.material文件在游戏引擎加载时会按顺序合并而不会互相覆盖。

文件格式[编辑]

  • ：一个.material文件。
    •  version：该材质文件的格式版本，当前最新为1.0.0，不填写时默认为0.0.0。
    •  <material_name>[:<inherited_material_name>]：一个材质。

材质格式[编辑]

材质字段的格式由格式版本控制。

该格式版本下允许字段继承。

  •  <material_name>[:<inherited_material_name>]：一个材质，可以使用:继承另一个材质。
    •  states：定义了该材质的渲染状态列表，决定了该材质提供的功能。该字段的前缀会影响该字段的继承类型。此时不添加前缀，为替换模式，将替换掉所继承的材质中所有的渲染状态。
    •  +states：定义了该材质相比于所继承的材质新增加的渲染状态列表。此时前缀为+，为增加模式，只有在 states字段不存在时才会解析，先于 -states的解析。
    •  -states：定义了该材质相比于所继承的材质要删去的渲染状态列表。此时前缀为-，为删去模式，只有在 states字段不存在时才会解析。
      • ：一个渲染状态。如果在所有 [+-]states解析结束时列表中存在EnableAlphaToCoverage渲染状态，将自动为该材质添加ALPHA_TO_COVERAGE宏定义，该操作先于 [+-]defines的解析。
    •  vertexShader：定义了该材质的顶点着色器路径，格式通常为shaders/<shader_name>.vertex。引擎会为GFX API插入中间值和追加后缀，对于HLSL，会在shaders后插入/hlsl，并在文件末追加.hlsl扩展名以构成完整路径；对于GLSL，会在shaders后插入/glsl以构成完整路径。该追加操作适用于以下所有类型的着色器路径。
    •  fragmentShader：定义了该材质的片元着色器路径，格式通常为shaders/<shader_name>.fragment。
    •  geometryShader：定义了该材质的几何着色器路径，格式通常为shaders/<shader_name>.geometry。
    •  vrGeometryShader：定义了该材质的VR几何着色器路径，格式通常为shaders/<shader_name>.geometry。
    •  defines：定义了该材质使用的宏定义列表，用于配合激活或切换着色器代码中的特定部分。该字段的前缀会影响该字段的继承类型。此时不添加前缀，为替换模式，将替换掉所继承的材质中所有的宏定义。
    •  +defines：定义了该材质相比于所继承的材质新增加的宏定义列表。此时前缀为+，为增加模式，只有在 defines字段不存在时才会解析，先于 -defines的解析。
    •  -defines：定义了该材质相比于所继承的材质要删去的宏定义列表。此时前缀为-，为删去模式，只有在 defines字段不存在时才会解析。
    •  depthFunc：该材质的深度模板测试中使用的深度函数，是一个比较函数，负责源深度值与深度缓冲区比较。
    •  depthStencilFaceName：该材质的模板测试中使用的面的名称，当前为一个占位符。
    •  frontFace：该材质正面的模板测试。
      •  stencilFunc：该材质正面的模板函数，是一个比较函数，负责模板参考值与模板缓冲区比较。
      •  stencilFailOp：该材质正面的模板失败操作，是一个模板操作，在模板测试失败时执行。
      •  stencilDepthFailOp：该材质正面的深度失败操作，是一个模板操作，在模板测试通过但深度测试失败时执行。
      •  stencilPassOp：该材质正面的模板通过操作，是一个模板操作，在模板测试与深度测试皆通过时执行。
    •  backFace：该材质背面的模板测试。
      •  stencilFunc：该材质背面的模板函数，是一个比较函数，负责模板参考值与模板缓冲区比较。
      •  stencilFailOp：该材质背面的模板失败操作，是一个模板操作，在模板测试失败时执行。
      •  stencilDepthFailOp：该材质背面的深度失败操作，是一个模板操作，在模板测试通过但深度测试失败时执行。
      •  stencilPassOp：该材质背面的模板通过操作，是一个模板操作，在模板测试与深度测试皆通过时执行。
    •  stencilRefOverride：该材质的模板测试中是否使用参考值覆写，如果为真，将使用 stencilRef的值为模板测试参考值，默认为假。
    •  stencilRef：该材质的模板测试的参考值覆写，接受非负整数。存在该字段时 stencilRefOverride默认为真。
    •  stencilReadMask：该材质的模板测试的读取掩码，会在模板测试比较前与参考值进行按位与运算，接受非负整数。
    •  stencilWriteMask：该材质的模板测试的写入掩码，会在模板测试比较后与参考值进行按位与运算，接受非负整数。
    •  blendSrc：颜色混合前源颜色需要采取的操作，是一个混合目标，默认为SourceAlpha。
    •  blendDst：颜色混合前缓冲区中的目标颜色需要采取的操作，是一个混合目标，默认为OneMinusSrcAlpha。
    •  alphaSrc：透明度混合前源颜色需要采取的操作，是一个混合目标，默认为One。
    •  alphaDst：透明度混合前缓冲区中的目标颜色需要采取的操作，是一个混合目标，默认为OneMinusSrcAlpha。
    •  samplerStates：定义了该材质使用的纹理采样状态列表，用于配置纹理的过滤与折绕。该字段的前缀会影响该字段的继承类型。此时不添加前缀，为替换模式，将替换掉所继承的材质中所有的纹理采样状态。
    •  +samplerStates：定义了该材质相比于所继承的材质新增加的纹理采样状态列表。此时前缀为+，为增加模式，只有在 samplerStates字段不存在时才会解析。
    •  -samplerStates：纹理采样状态列表的删去功能尚不可用，该字段此时为占位符。
      •  [0-7]：一个纹理采样状态。一个材质最多只支持存在8个纹理采样状态。
        •  samplerIndex：采样索引，代表第几张纹理。
        •  textureFilter：纹理过滤模式，决定源纹理与实际显示的缩放过的纹理间点的映射关系。
        •  textureWrap：纹理折绕模式，决定了纹理的UV超过[0,1]时折行或环绕的模式。
        •  shaderStage：着色器阶段。
        •  comparisonFunc：比较函数。
    •  vertexFields：该材质使用的顶点场列表，用于决定该材质渲染时网格的每个顶点都存有何种信息。
    •  depthBias：该材质光栅化时使用的深度偏差。
    •  slopeScaledDepthBias：该材质光栅化时使用的斜率缩放深度偏差。
    •  depthBiasOGL：OpenGL平台上该材质光栅化时使用的深度偏差。
    •  slopeScaledDepthBiasOGL：OpenGL平台上该材质光栅化时使用的斜率缩放深度偏差。
    •  msaaSupport：材质光栅化时是否支持多重采样抗锯齿（MSAA），支持的值见MSAA支持。
    •  primitiveMode：该材质的基本图元模式，默认为TriangleList。
    •  renderTargetFormats：该材质的渲染目标格式列表。
      • ：一个渲染目标格式列表。
    •  isAnimatedTexture：该材质的渲染目标是否是动态纹理。
    •  varients：定义了该材质的变体，变体会继承本体定义的所有属性，并支持覆写、添加或删去一些属性。该字段的前缀会影响该字段的继承类型。此时不添加前缀，为替换模式，将替换掉所继承的材质中所有变体。
    •  +varients：定义了该材质相比于所继承的材质新增加的变体。此时前缀为+，为增加模式，只有在 states字段不存在时才会解析。
    •  -varients：变体的删去功能尚不可用，该字段此时为占位符。
    •  varient：相当于 varients。
    •  +varient：相当于 +varients。
    •  -varient：相当于 -varients。
      • ：变体列表中的一个元素。
        •  <variant_name>：一个变体，变体列表中每个元素只允许定义一个变体，最终变体的可以用于引用的完整名称将为<material_name>.<variant_name>。

枚举[编辑]

继承类型[编辑]

继承类型枚举
键名 值 接口字符串 描述
Subtract 0 - 删去
Add 1 + 增加
Replace 2 空字符串 替换

渲染状态[编辑]

渲染状态枚举
键名 值 值（BIN） 接口字符串 国际版 中国版 描述
None 0 0000 0000 0000 0000 — N/A N/A
DisableDepthTest 1 0000 0000 0000 0001 DisableDepthTest 可用 可用
Blending 2 0000 0000 0000 0010 Blending 可用 可用
DisableCulling 4 0000 0000 0000 0100 DisableCulling 可用 可用
DisableColorWrite 8 0000 0000 0000 1000 DisableColorWrite 可用 可用
DisableAlphaWrite 16 0000 0000 0001 0000 DisableAlphaWrite 可用 可用
DisableDepthWrite 32 0000 0000 0010 0000 DisableDepthWrite 可用 可用
StencilWrite 64 0000 0000 0100 0000 StencilWrite 可用 可用
InvertCulling 128 0000 0000 1000 0000 InvertCulling 可用 可用
EnableStencilTest 256 0000 0001 0000 0000 EnableStencilTest 可用 可用
EnableAlphaToCoverage 512 0000 0010 0000 0000 EnableAlphaToCoverage 可用 可用
Wireframe 1024 0000 0100 0000 0000 Wireframe 可用 可用
PolygonOffset — — PolygonOffset 已移除 已移除
DisableRGBWrite 2048 0000 1000 0000 0000 DisableRGBWrite 不可用 可用

定义[编辑]

定义枚举
键名 值 接口字符串 描述
AlphaTest 0 ALPHA_TEST
ColorSecondTexture 1 COLOR_SECOND_TEXTURE
ColorBased 2 COLOR_BASED
DisableTinting 3 DISABLE_TINTING
Fancy 4 FANCY
EnableFog 5 ENABLE_FOG
EnableLight 6 ENABLE_LIGHT
Glint 7 GLINT
ItemInHand 8 ITEM_IN_HAND
MultiColorTint 9 MULTI_COLOR_TINT
MultiplicativeTint 10 MULTIPLICATIVE_TINT
NoTexture 11 NO_TEXTURE
TintedAlphaTest 12 TINTED_ALPHA_TEST
UIEntity 13 UI_ENTITY
UseColorMask 14 USE_COLOR_MASK
UseEmissive 15 USE_EMISSIVE
UseMultitexture 16 USE_MULTITEXTURE
MaskedMultitexture 17 MASKED_MULTITEXTURE
UseOnlyEmissive 18 USE_ONLY_EMISSIVE
UseOverlay 19 USE_OVERLAY
UseSkinning 20 USE_SKINNING
UseUVAnim 21 USE_UV_ANIM

比较函数[编辑]

比较函数枚举
键名 值 接口字符串 描述
Equal 0 Equal 源值等于目标值时通过
NotEqual 1 NotEqual 源值不等于目标值时通过
Always 2 Always 源值总是通过
Less 3 Less 源值小于目标值时通过
Greater 4 Greater 源值大于目标值时通过
GreaterEqual 5 GreaterEqual 源值大于或等于目标值时通过
LessEqual 6 LessEqual 源值小于或等于目标值时通过
Never 7 — 源值总不通过

模板操作[编辑]

模板操作枚举
键名 值 接口字符串 解释
StencilOpKeep 1 Keep 保留
StencilOpZero 2 — 置0
StencilOpReplace 3 Replace 替换
— 4 — 自增饱和
— 5 — 自减饱和
— 6 — 按位取反
StencilOpIncr 7 — 自增折绕
StencilOpDecr 8 — 自减折绕

混合目标[编辑]

混合目标枚举
键名 值 接口字符串 描述
DestColor 0 DestColor 置源色
SourceColor 1 SourceColor 置目标色
Zero 2 Zero 置(0,0,0)
One 3 One 置(1,1,1)
OneMinusDestColor 4 OneMinusDestColor 置(1,1,1)减目标色
OneMinusSrcColor 5 OneMinusSrcColor 置(1,1,1)减源色
SourceAlpha 6 SourceAlpha 置源透明度
DestAlpha 7 DestAlpha 置目标透明度
OneMinusSrcAlpha 8 OneMinusSrcAlpha 置1减源透明度

纹理过滤[编辑]

纹理过滤枚举
键名 值 接口字符串 描述
PointFiltering 0 Point 点采样
BilinearFiltering 1 Bilinear 双线性采样
TrilinearFiltering 2 Trilinear 三线性采样
MipMapBilinearFiltering 3 MipMapBilinear MIP映射采样
TexelAA 4 TexelAA 纹素抗锯齿采样
PCF 5 PCF 通过比较函数采样

纹理折绕[编辑]

纹理折绕枚举
键名 值 接口字符串 描述
ClampToEdge 0 Clamp 钳制拉伸
Repeat 1 Repeat 重复平铺
MirroredRepeat 2 — 镜像重复平铺

着色器阶段位[编辑]

着色器阶段位枚举
键名 值 值（BIN） 接口字符串 描述
NoShaderStagesBit 0 0000 0000 — 无着色器阶段
VertexShaderStageBit 1 0000 0001 Vertex 顶点着色器阶段
PixelShaderStageBit 2 0000 0010 Pixel 像素着色器阶段
GeometryShaderStageBit 4 0000 0100 Geometry 几何着色器阶段

顶点场[编辑]

顶点场枚举
键名 值 接口字符串 描述
Position 0 Position 位置
Color 1 Color 颜色
Normal 2 Normal 法向
Tangent 3 Tangent 切向
UV0 4 UV0 第0张纹理UV
UV1 5 UV1 第1张纹理UV
UV2 6 UV2 第2张纹理UV
PBRTextureIdx 7 PBRTextureIdx PBR纹理索引
BoneId0 8 BoneId0 第0个骨骼ID
PreviousPosition 9 PreviousPosition 先前位置
HummingbirdPosition 10 HummingbirdPosition 蜂鸟位置
HummingbirdColor 11 HummingbirdColor 蜂鸟颜色
HummingbirdAdditional 12 HummingbirdAdditional 蜂鸟额外

MSAA支持[编辑]

MSAA支持枚举
键名 值 接口字符串 描述
NonMSAA 1 NonMSAA 不支持MSAA
MSAA 2 MSAA 仅支持MSAA
Both 3 Both MSAA是否开启皆支持

基本图元模式[编辑]

基本图元模式
键名 值 接口字符串 描述
None 0 None 不渲染
QuadList 1 QuadList 四边形列表
TriangleList 2 TriangleList 三角形列表
TriangleStrip 3 TriangleStrip 三角形条带
LineList 4 LineList 线段列表
LineStrip 5 Line 线段条带

纹理格式[编辑]

检索自“https://wiki.mcbe-dev.net/w/index.php?title=Manual:材质&oldid=18196”