Darkplaces material system

Revision as of 10:07, 20 July 2012

Introduction

Darkplaces material system is created to put more direct control over the surfaces qualities of textures into the hands of designers and artists.

This article will contain a parts of Quake 3 Shader Manual by By Paul Jaquays and Brian Hook adapted for Darkplaces engine.

What is a Material?

Materials are short text scripts that define the properties of a surface as it appears and functions in a game world (or compatible editing tool). By convention, the documents that contain these scripts usually has the same name as the texture set which contains the textures being modified (e.g; textures_inn, models_mapobjects_crypt, etc,). Several specific script documents have also been created to handle special cases, like liquids, environments and special effects.

For Darkplaces, material scripts are located in 'Path_To_The_Game/gamedir/scripts'.

A Darkplaces material file consists of a series of surface attribute and rendering instructions formatted within braces ("{" and "}"). Below you can see a simple example of syntax and format for a single process, including the Q3MAP keywords or "Surface Parameters", which follow the first bracket and a single bracketed "stage":

// material definition
textures/mymaterial
{
   // parameters
   qer_editorImage radiant/textures/mymaterial
   q3map_textureImage radiant/textures/mymaterial
   dpglossexponentmod 0.5
   surfaceparm stone
   // base stage
   {
       map textures/mymaterial // engine will search fo textures/mymaterial.tga, textures/mymaterial.jpeg
   }
   // lighting stage
   {
       map $lightmap
   }
}

Material names & Conventions

The first line is the material name. Material names can be up to 63 characters long. The names are often a mirror of a pathname to a .tga file without the extension or basedir (/Blood Omnicide/kain in our case), but they do not need to be. Materials that are only going to be referenced by the game code, not modeling tools, often are just a single world, like "collision" or "dpbihclip". Materials that are used on characters or other polygon models need to mirror a .tga file, which allows the modelers to build with normal textures, then have the special effects show up when the model is loaded into the game. Materials that are placed on surfaces in the map editor commonly mirror a .tga file, but the "qer_editorimage" shader parameter can force the editor to use an arbitrary image for display.

Material pathnames have a case sensitivity issue - on windows, they aren't case sensitive, but on unix they are. Try to always use lowercase for filenames, and always use forward slashes "/" for directory separators.

Inspired by Quake 3

Quake 3 shader scripts was an inspiration for darkplaces material system and visual look of material scripts is very very close to quake 3. So if you are familiar with Id Tech 3 shaders system, you will be right home with materials. Therefore there is some serious differences because Darkplaces material system was written independently and aimed to realtime lightning rendering and OpenGL 2.0.