.material

From TargetWiki

Contents 1 File Layout 2 Passes 3 States 3.1 General States 3.1.1 alphatest 3.1.2 blend 3.1.3 color 3.1.4 colormaterial 3.1.5 cullface 3.1.6 depthtest 3.1.7 lighting 3.1.8 lines 3.1.9 mask 3.1.10 material 3.1.11 pointparams 3.1.12 points 3.1.13 polygonoffset 3.1.14 polygons 3.1.15 shader 3.1.16 shaderpoints 3.1.17 stencil 3.2 Texture States 3.2.1 pointsprite 3.2.2 texgen 3.2.3 texmat 3.2.4 texture 4 Initial Material 4.1 General Default States 4.2 Texture Unit Default States 5 Texture Flags 6 Test Functions 7 Factors 8 Stencil Operations

File Layout

A material file is a standard TW2 configuration file. Material files contain two things at the top level:

• A 'version' entry. Currently, this must be 1.
• A collection of unnamed tables. Each table represents a pass.

Passes

While TW2 specifically allows multi-pass materials, they should always be avoided. Each pass requires the object to be rendered again, which can place a heavy load on the rendering system. Think of it this way: each time you add a pass, it's the equivalent of more than doubling the number of triangles in your model.

Each pass contains a collection of unnamed tables. Each of these tables represents a state that's being set for that pass.

States

States are what drive a material. There are many types of state, each with its own configuration. Essentially, any type of rendering state that can be set with OpenGL can be set in a TW2 .material file.

Each stat is contained in its own, unnamed table. This table will contain a 'type' entry, which decides what type of state is being defined. This is followed by the configuration information for that type.

Example code:

{
  type = "texture"
  unit = 0
  target = "2D"
  file = "tt_barham_df.dds"
}

Note that you will never need the vast majority of these states. The states you will usually use are material, texture and shader.

General States

Each sub-heading that follows can be used as a state type. Within the sub-heading is a brief description of the options for that state. This section assumes that you are familiar enough with 3D modeling to already know what most of these states do. If you aren't familiar with them, the OpenGL reference documentation contains complete descriptions.

alphatest

Example code:

{
  type = "alphatest"          
  enabled = true
  ref = 13
  func = see description for optional tests
}

Description:

• enabled = boolean. Set to "true" to enable per-pixel alpha testing.
• ref = number. Reference value to use for alpha testing, should be a unique whole number. The func compares the incoming alpha value of the pixel with the reference value specified if it passes, it's drawn to the screen, otherwise it isn't.
• func = string. A test function for the options on alpha testing.

Using this means you must set values for the entries.

Default states:

• enabled = false

---

blend

Example code:

{
  type = "blend"          
  enabled = true
  sfactor = "src_color"
  dfactor = "one_minus_scr_color"
}

Description:

Used to draw pixels in color depending on the RGBA (Red, Green, Blue and Alpha) settings within the texture in use. The two scaling functions, sfactor and dfactor allow variations between source and destination color scales. Blending can help with transparacies and optimization of polygon antialiasing. There is a lot to understand for this option, reading the OpenGL documents will assist.

• enabled = boolean. Set to "true" to enable blending.
• sfactor = string. A Factors used to scale the source color components.
• dfactor = string. A Factors used to scale the destinition color components.

Default states:

• enabled = true
• sfactor = src_alpha
• dfactor = one_minus_src_alpha

---

color

Example code:

{
  type = "color"          
  color = {1, 1, 1, 1}
}

Description:

Defines the color depending on the RGBA (Red, Green, Blue and Alpha) settings in the table.

• color = {1, 1, 1, 1}, numbers are floating-point format, ranging from 0 to 1. Where 1 = full intensity and 0 = no intensitity.

Note that a color state is almost never what you want, unless lighting is disabled on the material.

Default states:

• color = {1, 1, 1, 1}

---

colormaterial

Example code:

{
  type = "colormaterial"          
  enabled = true
  face = "back"
  mode = "emission"
}

Description:

Used to define the materials color settings.

Note that, like color states, this is almost never what you want.

• enabled = boolean. If enabled, colors are controlled by color states, not material states.
• face = string. This can be 'front', 'back' or 'front_and_back'. Defines if front, back or both use the color stated.
• mode = string. This can be 'emission', 'ambient', 'diffuse', 'specular' or 'ambient_and_diffuse'. Sets the material parameters used. Only one can be defined.

Default states:

• enabled = false
• face = "front_and_back"
• mode = "ambient_and_diffuse"

---

cullface

Example code:

{
  type = "cullface"          
  enabled = true
  mode = "front"
}

Description:

Used to cull faces (polys, triangles, quads and rectangles) from either front or back facing facets.

• enabled = boolean. Set true to cull some object faces.
• mode = string. This can be 'front', 'back', or 'front_and_back'. If front_and_back are used not faces are drawn, but points and lines are drawn.

Default states:

• enabled = true
• mode = "back"

---

depthtest

Example code:

{
  type = "depthtest"          
  enabled = true
  func = "src_color"
}

Description: Used to test the depth of a named parameter. Not sure where one would use this.

• enabled = boolean. Set to true to enable depth testing.
• func = string. A test function for depth testing.

Default states:

• enabled = false

---

lighting

Example code:

{
  type = "lighting"          
  enabled = true
  local_viewer = true
  two_sided = true
  ambient = {0.55, 0.85, 0.75, 1.0}
}

Description:

Used to set the reflective values from the material.

• enabled = boolean. Set to true to enable lighting.
• local_viewer = boolean. If true viewer will see reflections according to eye line.
• two_sided = boolean. If true uses back and front lighting, else front only.
• ambient = table with 4 numbers. Defines an RGBA color, with values ranging from 0 to 1.

Default states:

• enabled = true
• local_viewer = false
• two_sided = false
• ambient = {0.2, 0.2, 0.2, 1.0}

---

lines

Example code:

{
  type = "lines"          
  smooth = true
  width = 2
}

Description:

Used to control the smoothness and width of lines, for both rasterized and antiaialised.

Note there may be some different effects if a width other then 1 is used.

• smooth = boolean.
• width = number. Line width in pixels.

Default states:

• smooth = false
• width = 1

---

mask

Example code:

{
  type = "mask"
  red = true
  green = true
  blue = true
  alpha = false
  depth = true 
}

Description:

Used to set channels to false when you don't want that channel written to the frame buffer. Only setting is true or false for each channel.

• red = boolean.
• green = boolean.
• blue = boolean.
• alpha = boolean.
• depth = boolean.

Default states:

• red = true
• green = true
• blue = true
• alpha = true
• depth = true

---

material

Example code:

{
  type = "material"          
  ambient = {0.2, 0.2, 0.2, 1.0}
  diffuse = {0.8, 0.8, 08, 1.0}
  specular = {0.2, 0.2, 0.2, 1}
  emission = {0, 0, 0, 1.0}
  shininess = 25
}

Description:

Used to set the materials lighting values across the range of parameters.

• ambient = table with 4 numbers. Defines an RGBA color, with values ranging from 0 to 1.
• diffuse = table with 4 numbers. Defines an RGBA color, with values ranging from 0 to 1.
• specular = table with 4 numbers. Defines an RGBA color, with values ranging from 0 to 1.
• emission = table with 4 numbers. Defines an RGBA color, with values ranging from 0 to 1.
• shininess = number. Ranges from 0 to 128.

Default states:

• ambient { 1, 1, 1, 1 }
• diffuse { 1, 1, 1, 1 }
• specular { 0, 0, 0, 1 }
• emission { 0, 0, 0, 1 }
• shininess 0.

---

pointparams

Example code:

{
  type = "pointparams"          
  min_size = 0.2
  max_size = 8.5
  fade_theshold = 9.0
  distance_attenuation = {1, 1, 0}
}

Description:

• min_size = number. Sets the minimium point size.
• max_size = number. Sets the maximum point size.
• fade_threshold = number. Clamps point size if exceeds specific value.
• distance_attenuation = a table with 3 numbers. Used for scaling the point size.

Default states:

• min_size = 0
• max_size = unlimited
• fade_threshold = 1
• distance_attenuation = {1, 0, 0}

---

points

Example code:

{
  type = "points"          
  smooth = true
  size = 2
}

Description:

• smooth = boolean.
• size = number. Point size in pixels. Using point size other then 1 has different effects, depending on wheather the point antialiasing is enabled.

Default states:

• smooth = false
• size = 1

---

polygonoffset

Example code:

{
  type = "polygonoffset"          
  enabled = true
  fill = true
  line = false
  point = true
  factor = 3
  units = 2
}

Description:

Used to render hidden-line images, for applying decals to surfaces, and for rendering solids with highlighted edges.

• fill = boolean. True to enable polygon offsetting.
• line = boolean. True to enable line offsetting.
• point = boolean. True to enable point offsetting.
• factor = number. Used for scaling to create variable depth offset for each poly.
• units = number. Used to create a constant depth offset value.

Default states:

• enabled = false

---

polygons

Example code:

{
  type = "polygons"          
  smooth = true
  front = "fill"
  back = "line"
}

Description:

• smooth = boolean.
• front = string. Can be 'point', 'line' or 'fill'. Used for front facing polygons, from viewers perspctive.
• back = string. Can be 'point', 'line' or 'fill'. Used for back facing polygons.

Point means verticies are marked. Line means the boundary edges are drawn as line segments. Fill means the polygons interior is filled.

Default states:

• smooth = true
• front = "fill"
• back = "fill"

---

shader

Example code:

{
  type = "shader"         
  file = "data/mod/shaders/shade1.shader    
}

Description:

• file = string. Name of the .shader file to use.

Default states:

No default state. If line exists it is used.

---

shaderpoints

Example code:

{
  type = "shaderpoints"          
  enabled = true
}

Description:

• enabled = boolean.

This controls whether or not vertex programs can set the point size.

Default states:

• enabled = false

---

stencil

Example code:

{
  type = "stencil"          
  enabled = true 
  func = See description for values
  ref = 1
  write_mask = 2
  fail = See description for values
  zfail = See description for values 
  zpass = See description for values
}

Description:

Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. Stencil planes are first drawn into using GL drawing primitives, then geometry and images are rendered using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.

• enabled = boolean.
• func = string. A test function for stencil operations.
• ref = number. Reference value for stencil operations.
• write_mask = number. Write mask for stencil operations.
• fail = string. A stencil operation for stencil fail.
• zfail = string. A stencil operation for stencil zfail.
• zpass = string. A stencil operation for stencil zpass.

Default states:

• enabled = false

---

Texture States

These states are all applied to particular texture units. They all take this configuration value:

• unit = number. Ranges from 0 to one less than the maximum number of supported texture units. This varies by graphics card, but modern cards can usually support at least 8 texture units.

pointsprite

Example code:

{
  type = "pointsprite"          
  enabled = true
  See document for detailed parameters and settings
}

Description:

Used for example for particles, to allow sprites instead of quads for display. There are a number of specific parameters, contained in the spec: [1]

Default states:

No default, if defined it is used.

---

texgen

Example code:

{
  type = "texgen"
  enabled = true
  mode = "object_linear"
  plane_s = {1, 1, 1, 1}
  plane_t = {1, 1, 1, 1} 
  plane_r =  {1, 1, 1, 1}
  plane_q =  {1, 1, 1, 1}
}

Description:

• enabled = boolean.
• mode = string. This must be one of 'object_linear', 'eye_linear', 'sphere_map', 'normal_map' or 'reflection_map'.
• plane_s = table containing 4 numbers.
• plane_t = table containing 4 numbers.
• plane_r = table containing 4 numbers.
• plane_q = table containing 4 numbers.

The planes are only necessary for 'object_linear' and 'eye_linear' modes.

Note: This is a very complex control and reading the OpenGL documents may make it clearer, or it may not.

Default states:

No default, if defined it is used.

---

texmat

Example code:

{
  type = "matrix"          
  { 1, 0, 0, x }
  { 0, 1, 0, y }
  { 0, 0, 1, z }
  { 0, 0, 0, 1 }
}

Description:

This is a table of data, reflecting the states on the current matrix. It contains four lines of data each for:

• Modelview
• Projection
• Texture
• color

Note: Read the OpenGL document, section on glMatrixMode. This is unlikley to be used by contributors.

Default states:

No default, if defined it is used.

---

texture

Example code:

{
  type = "texture"
  unit = 0
  target = "2D"
  file = "../cwd/z_window_strip.tga"
}

Description:

• target = string. This must be one of '1D', '2D', '3D' or 'cube'.
• flags = an optional table containing 0 or more texture flags.
• file = string. The name of the texture file to use.

Default states:

No default, if defined it is used.

---

Initial Material

Material definitions modify the 'initial material'. If a state type isn't set in a material, it will default to these values.

General Default States

• alphatest: disabled.
• blend: enabled, sfactor of src_alpha, dfactor of one_minus_src_alpha.
• color: white { 1, 1, 1, 1 }
• colormaterial: disabled.
• cullface: enabled for back faces.
• depthtest: enabled, test function of less.
• lighting: enabled.
• lines: unsmoothed, width 1.
• mask: all channels enabled.
• material: ambient { 1, 1, 1, 1 }, diffuse { 1, 1, 1, 1 }, specular { 0, 0, 0, 1 }, emission { 0, 0, 0, 1 }, shininess 0.
• points: unsmoothed, size 1.
• pointparams: min_size 0, max_size unlimited, fade_threshold 1, distance_attenuation { 1, 0, 0 }
• polygons: smoothed, front mode fill, back mode fill.
• polygonoffset: disabled.
• shader: disabled.
• shaderpoints: disabled.
• stencil: disabled.

Texture Unit Default States

• pointsprite: disabled for all units.
• texture: disabled for all units.
• texgen: disabled for all units.
• texmat: disabled for all units.

Texture Flags

Textures can have flags applied that modify how they are rendered.

• nomipmap
• nosmoothing
• clamp_s
• clamp_t
• clamp_r
• mirror_s
• mirror_t
• mirror_r

Test Functions

Some states define a test function. This means using one of these strings:

• never
• less
• equal
• lequal
• greater
• notequal
• gequal
• always

Factors

Some states define factors. This means using one of these strings:

• 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

Stencil Operations

Stencil operations must be one of these strings:

• keep
• zero
• replace
• increment
• increment_wrap
• decrement
• decrement_wrap
• invert