W4 Material File Format

From Ciliz|W4

W4 Engine Wiki > Complex subsystems > Material System > File Format:

Scope[edit]

The material file (.mat) might have settings for the shader parameters, which are used in the following cases:

  • by default for all instances of this material;
  • as render and texture instructions (blending, wrapping and filtering).

Detailed Description[edit]

File Structure[edit]

Example .mat file:

 {
     "vertexFile" : "<path from the project root directory to the vertex shader file (.vs)>",
     "fragmentFile" : "<path from the project root directory to the fragment shader file(.fs)>",
     ["blending" : <enable blending (true/false)>,]
     ["blending" : {"src" : "<blending function for the result of your shader>", "dst" : "<blending function for background>"},]
     "params" : {
         "texture0": {"type": "TEXTURE", "data": {"path": "<path from the project root directory to the texture file>", "type": "file"}[, "sWrapping": "{Repeat|MirroredRepeat|ClampToEdge}"][, "tWrapping" : "{Repeat|MirroredRepeat|ClampToEdge}"][, "filtering": "{Level0|Level1|Level2|Level3}"]},
         "texture1": {"type": "TEXTURE", "data": {"generator": "[default] color", "params": {"type": "Vec4", "value": { "x": 1.0, "y": 1.0 , "z": 1.0, "w": 1.0 }}, "type": "generator"}},
         "cubemap0": {"type": "CUBEMAP", "data": {
                 "0": {"path": "<path from the project root directory to the X+ texture file>", "type": "file"},
                 "1": {"path": "<path from the project root directory to the X- texture file>", "type": "file"},
                 "2": {"path": "<path from the project root directory to the Y+ texture file>", "type": "file"},
                 "3": {"path": "<path from the project root directory to the Y- texture file>", "type": "file"},
                 "4": {"path": "<path from the project root directory to the Z+ texture file>", "type": "file"},
                 "5": {"path": "<path from the project root directory to the Z- texture file>", "type": "file"}
             }
         },
         "intParam": { "type": "INT", "data": -42 },
         "floatParam": { "type": "BOOL", "data": 3.14159259 },
         "boolParam": { "type": "BOOL", "data": true },
         "vec2Param": { "type": "VEC2", "data": { "x": 0.1, "y": 0.2 }},
         "vec3Param": { "type": "VEC3", "data": { "x": 0.1, "y": 0.2 , "z": 0.3 }},
         "vec4Param": { "type": "VEC4", "data": { "x": 0.1, "y": 0.2 , "z": 0.3, "w": 0.4 }}
     }
 }

The following values ​​are mandatory:

  • vertexFile
  • fragmentFile

The rest is optional.

Hints[edit]

1) In order not to set the same parameters every time, you can set default values for any parameter in the material file. These parameters will be set for each new MatInstance. The following parameter types are supported: INT, FLOAT, BOOL, VEC2, VEC3, VEC4, TEXTURE, СUBEMAP.

2) By default, the transparency of the material is disabled. There are two ways to enable it:

  1. Set "blending" key to "true". In this case, the following functions are set for the material: SRC_ALPHA functions for the shader result and ONE_MINUS_SRC_ALPHA for the background.
  2. Define an entry using the "blending" key (see File Structure above) containing "src" and "dst" values, accordingly. Possible values are: ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR, SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR, CONSTANT_ALPHA, ONE_MINUS_CONSTANT_ALPHA, SRC_ALPHA_SATURATE.

3) The entry for the TEXTURE and CUBEMAP types consists of the following key-value pairs:

  • "type" - TEXTURE or CUBEMAP .
  • "data" - description of the data source (for CUBEMAP type "data" contains 6 data sources, marked by numbers from 0 to 6 (respectively X +, X-, Y +, Y-, Z +, Z-)). This can be set by any of the following:
  1. From a file with keys "path" and "type" = "file";
  2. Through a generator compiled into the engine. In this case, "generator" ("type" = "generator") and "params" (the generator parameters) keys are used. The actual version of the engine contains the generator to which a parameter of type 'Vec4' is set (do not confuse with 'vec4'). The generator can be used to create a single color texture - "[default] color".
  • "sWrapping" (optional) is used for setting the type of texture filling (Repeat, MirroredRepeat, ClampToEdge) according to the S coordinate.
  • "tWrapping" (optional) is used for setting the type of texture filling (Repeat, MirroredRepeat, ClampToEdge) according to the T coordinate.
  • "filtering" (optional) is used for setting the texture filtering mode (Level0 - Level3).