Materials

From Leadwerks Developer Wiki

Jump to: navigation, search

Contents

Introduction

Materials store information about the way which textures should be displayed. The engine will use a material file to choose a shader, display effects, and control some physics settings. Material files are just ASCII text files renamed with the file extension ".mat". You can edit these files by opening them in Windows Notepad or another text editor or using the LE material editor.

Material files are used instead of the textures assigned in the modeling program, they have to use the same name. E.g. if you assign a texture named "grass.dds" to your model, a material file called "grass.mat" will be loaded which should define this material.

Materials have many settings which can be altered directly within the mat file. And because you can specify your own shaders in addition to the surface shaders that come with the engine (including shaders for standard diffuse, bumpmap, specular and parallax mapping effects), the possibilities for material appearances are nearly endless.

Materials attached to/used by animated/skinned parts of meshes have to use the "mesh_..._skin.vert" vertex shaders.

Tutorials

Syntax

  • texturen

Specifies the texture to use for the nth texture unit (texture0, texture1, etc.). This can be a file path string, e.g. 

texture0="abstract::texture.dds"

or a texture tag name, e.g.: 

texture0="tag::renderdepth"

This texture can be set later on in the program using TagTexture() (e.g TagTexture(GetDepthBuffer(gbuffer),"renderdepth"))

  • clampn 
clampn=<clamp x?>,<clamp y?>[,<clamp z?>]

Specifies if clamping should be used on the u/v (x/y) axis of the specified texture unit. E.g. clamp0=1,1 Will clamp the texture on texture unit 0 (texture0) in both x and y direction.

Clamping means that, if a lookup on the texture is done outside the 0 - 1 uv range, it'll just return the pixel that is at the closest border (since uv values greater/smaller than 0 - 1 will get put back into that range -> so clamping disables texture wrapping).

See also Repeating and Clamping Textures.

  • color

Specifies the RGBA color for the surface. Something like: 

color=0.0,0.0,1.0,1.0
  • depthmask

If set to 0, this will disable depth-writing when this material is rendered. Use this for particle effects. The default value is 1.

  • colormask

If set to 0, this will disable color-writing when this material is rendered. The default value is 1.

  • alphatest

If set to 1, pixels with an alpha value less than 0.5 will be skipped. This is a no-cost effect that can be used large scenes with lots of trees and grass.
DISCONTINUED, use the ..._alphatest.frag shaders instead.

  • depthtest

If disabled the surface will be drawn on top of all previously rendered surfaces. However, triangles within a surface may not appear in correct order.

  • castshadows

If disabled (=0), surfaces using this material won't cast shadows. To hide an entity completely, use HideEntity.

  • invisible

If enabled (=1), surfaces using this material won't be drawn (this only skips standard rendering, the shadow will still be rendered and visible). To hide an entity completely, use HideEntity.

  • specular

Defines the specular intensity. This is multiplied with the alpha channel of the normal map, which specifies relative specularity. [0.0 - 1.0]. This is the uniform float specular value passed to the material's shaders.

  • gloss

Defines the gloss factor of the specular effect [with default shaders 0.0 - 1.0]. This sharpens the specular reflection (really low makes everything look white, really high makes it very sharp, only a small dot). This is the uniform float gloss value passed to the material's shaders.

  • bumpscale

Defines the intensity of the bump effect. 0 means no bump. This is the uniform float bumpscale value passed to the material's shaders.

  • zsort

If set to 1, the surface will be sorted with other z-sorted object in the scene. Sorted objects will be drawn last, from back to front. Use this setting with transparency.

In Leadwerks Engine 2.1, if zsort is set to -1, the surface will be drawn first. This can be used to create a depth-pass material which gets rendered first. The material can be applied to surfaces hidden inside walls and large objects. This will minimize fragment processing in scenes with a high overdraw factor: 

zsort=-1
cullface=0
colormask=0
castshadows=0
shader="abstract::mesh.vert"
  • cullface

If set to 0 surfaces will appear two-sided. The default setting is 1.

  • overlay

If set to 1 the surface will be drawn with a slight offset towards the camera. This setting can be used to render decals on top of another surface.

  • blend

Sets the material blend mode. Available blend modes are below: 

0 - solid (default)
1 - alpha
2 - light
3 - shade
4 - mod2x
  • shader

Specifies a shader to use with the material. The vertex and fragment shaders should be specified, as below: 

shader="mesh_diffuse_bumpmap.vert","mesh_diffuse_bumpmap.frag"
  • shadowshader

Specifies a shadow shader to use with the material. The vertex and fragment shaders should be specified, as below. If a fragment shader is not specified, none will be used: 

shadowshader="mesh_shadow.vert"
  • collisiontype

Sets the material collision type. This allows the the user to specify collision interactions on a submesh basis. The collision type will only affect submeshes it is applied to. Entities other than meshes will use the entity collision type. If a collision occurs with a submesh and no material is present, or the material does not have a specified collision type, the mesh entity collision type will be used.

Example Material Files

Diffuse Texture

Assuming you assigned a file called "texture.xxx" to the mesh (and have a converted dds version of this texture) in a modeling application, the material file (which should be ideally placed in the same folder as the converted gmf mesh) should look like: 

texture0="abstract::texture.dds"


shader="abstract::mesh_diffuse.vert","abstract::mesh_diffuse.frag"

The filename should be texture.mat.

Diffuse, Bumpmap and Specular

Assuming you assigned a file called "texture.xxx" to the meshin a modeling application:

  • You should have a dds version of the texture, which can have any name, but ideally the same as the texture you assigned (-> "texture.dds")
  • and a tangent space normal map (also in dds format, recommended filename "texturedot3.dds")
  • with the specular intensity in it's alpha channel (completely white alpha channel means full specular intensity everywhere, black means none)

the material file (which should be ideally placed in the same folder as the converted gmf mesh) should look like: 

texture0="abstract::texture.dds"
texture1="abstract::texturedot3.dds"


shader="abstract::mesh_diffuse_bumpmap.vert","abstract::mesh_diffuse_bumpmap_specular.frag"

The filename should be texture.mat

Diffuse, Bumpmap and Specular Animated

The same as above, but the "mesh_diffuse_bumpmap_skin.vert" vertex shader and the "mesh_shadow_skin.vert" shadow vertex shader have to be used: 

texture0="abstract::texture.dds"
texture1="abstract::texturedot3.dds"


shader="abstract::mesh_diffuse_bumpmap_skin.vert","abstract::mesh_diffuse_bumpmap_specular.frag"
shadowshader="mesh_shadow_skin.vert"

Commands

CreateMaterial

  • C: TMaterial CreateMaterial(void)
  • C++: void Material::Create( void )
  • Pascal: function CreateMaterial: THandle;
Creates a new material.
[Examples]

LoadMaterial

  • C: TMaterial LoadMaterial( str filepath )
  • C++: virtual void Material::Load( const_str filepath )
  • BlitzMax: LoadMaterial:TMaterial( filepath:String )
  • Pascal: function LoadMaterial ( name:PAnsiChar ): THandle;
Loads a material from a file. If a material with this filename has already been loaded, it'll return a reference to that to avoid loading assets twice.
[Examples]

MaterialName

  • C: str MaterialName( TMaterial material )
  • C++: std::string Material::GetName( void ) const
  • BlitzMax: MaterialName:String( material:TMaterial )
  • Pascal: function MaterialName ( material:THandle ): PAnsiChar;
Returns the name of the specified material.
[Examples]

GetMaterialShader

  • C: TShader GetMaterialShader(TMaterial material, int shadow=0)
  • C++: Shader Material::GetShader( bool shadow ) const
  • Pascal: function GetMaterialShader ( material:THandle; shadow:Integer=0 ): THandle;
Returns a handle to the shader of the specified material.
[Examples]

GetMaterialKey

  • C: str GetMaterialKey(TMaterial material, str key)
  • C++: str Material::GetKey( const_str key )
  • Pascal: function GetMaterialKey ( material:THandle; key:PAnsiChar ): PAnsiChar;
Returns the value of a material key as a string.
[Examples]

GetMaterialTexture

  • C: TTexture GetMaterialTexture( TMaterial material, int stage )
  • BlitzMax: GetMaterialTexture:TTexture( material:TMaterial, stage:Int )
  • Pascal: function GetMaterialTexture ( material:THandle; stage:Integer=0 ): THandle;
Retrieves the material's texture for the specified texture unit, if it exists.
[Examples]

SetMaterialTexture

  • C: void SetMaterialTexture( TMaterial material, TTexture texture, int stage )
  • C++: void Material::SetTexture( const Texture& rTexture, int stage = 0 )
  • BlitzMax: SetMaterialTexture( material:TMaterial, texture:TTexture, stage:Int )
  • Pascal: procedure SetMaterialTexture ( material:THandle; texture:THandle; stage:Integer=0 );
Sets the individual textures for a material the same way as the .mat file does with texture0, texture1, texture2, texture3.
[Examples]

SetMaterialShader

  • C: void SetMaterialShader( TMaterial material, TShader shader, int shadow=0 )
  • C++: void Material::SetShader( const Shader& rShader, bool shadow )
  • Pascal: procedure SetMaterialShader ( material:THandle; shader:THandle; shadow:Integer=0 );
Sets the material's shader. Use the shadow parameter to tell if you want to set the 'shadowshader' (1) or just the 'shader' (0).
[Examples]

SetMaterialColor

  • C: void SetMaterialColor( TMaterial material, TVec4& color )
  • C++: void Material::SetColor( const TVec4& color )
  • Pascal: procedure SetMaterialColor ( material:THandle; const color:TVec4 );
Sets the material's color.
[Examples]

SetMaterialKey

  • C: void SetMaterialKey( TMaterial material, str key, str value )
  • C++: void Material::SetKey( const_str key, const_str value )
  • Pascal: procedure SetMaterialKey ( material:THandle; key:PAnsiChar; value:PAnsiChar );
Sets a material's key and its value.
[Examples]

FreeMaterial

  • C: void FreeMaterial(TMaterial material)
  • C++: void Material::Free(void) Note: Also called from destructor
  • Pascal: procedure FreeMaterial ( material:THandle );
Frees the specified material from memory.
[Examples]

SetMaterialCallback

  • C: void SetMaterialCallback(TMaterial material, byte* callback, int callbackID )
  • BlitzMax: SetMaterialCallback( material:TMaterial, callback:Byte Ptr, callbackID:Int )
Sets a callback function for the material. callbackID can be one of the following (links to how the functions has to be declared):
[Examples]

Callback Functions

EnableMaterialCallback

  • C: void EnableMaterialCallback( TMaterial material )
  • BlitzMax: EnableMaterialCallback( material:TMaterial )
This will be called whenever the material is enabled. That is, when drawing with this material is started.
[Examples]

DisableMaterialCallback

  • C: void DisableMaterialCallback( TMaterial material )
  • BlitzMax: DisableMaterialCallback( material:TMaterial )
This will be called whenever the material is disabled. That is, when drawing with this material ends.
[Examples]
Retrieved from "http://www.leadwerks.com/wiki/index.php?title=Materials"
Personal tools