Templates - Revision history

JRAD: /* Templates */

2007-11-21T12:18:24Z

‎Templates

JRAD at 12:13, 21 November 2007

2007-11-21T12:13:49Z

MoP at 13:33, 17 October 2007

2007-10-17T13:33:10Z

New page

=== Templates ===
Templates provide away to avoid repetitive copy and paste of declarations such as materials and sound shaders.
Templates are defined in the templates folder, in files with ".template" as an extension. A template is basically a fancy way of replacing one piece of placeholder text with another.

A sample template for a material is shown below:

template material/generic {
parameters < '''TextureParm''',
'''BumpBehavior''' = "useTemplate hasHeightMap< '''TextureParm''', 1.0 >" >
text {
'''BumpBehavior'''
diffusemap '''TextureParm'''_d
specularmap '''TextureParm'''_s
}
}

==== Keywords ====
===== template =====
First we have the keyword <i>template</i>. This lets the engine know that we're defining a new template. Next is the name of the template. Templates follow the same naming rules as other declarations in the engine.

===== parameters =====
Next we have the ''parameters'' block. This is a list of names that will be replaced when the template is evaluated. Think of them as placeholders for real information. Each name is separated by a comma (,) and can optionally have a ''default value''. The whole block is enclosed in < > to make it more readable.

Default parameters allow you to specify things that aren't often changed. As soon as you specify a default value for a parameter, all parameters following it must also have defaults. If you leave off a default parameter when one is needed you will get a warning about it in the console.

If you want to override a default parameter, but don't want to specify custom values for any preceding default parameters, give them a value of "__default" to automatically use their default value.

===== text =====
The ''text'' block contains the actual text that is inserted into your declaration. Parameters that match text exactly (that is, case matters) will be replaced by the values that are passed into the template.

==== Terminology ====
''Parameter'' - This is a named placeholder that we use to mark where we want substitute in values.

''Argument'' - This is the value that we give to the parameter.
The argument is what is actually substituted into the the text.

==== Using Templates ====
Using a template to insert text into your declarations a simple process. In this example we create a material.

material textures/jrad/templateTest {
useTemplate material/generic< "textures/sand/dry_beach_sand_footprints" >
}

When the material is loaded it will turn into this:
material textures/jrad/templateTest {
bumpmap addnormals ( '''textures/sand/dry_beach_sand_footprints'''_local.tga,
heightmap ( '''textures/sand/dry_beach_sand_footprints'''_h.tga, 1.0 ) )
diffusemap '''textures/sand/dry_beach_sand_footprints'''_d.tga
specularmap '''textures/sand/dry_beach_sand_footprints'''_s.tga
}

Ignore for the moment where the ''bumpmap'' line came from. You'll see that anywhere the first parameter "TextureParm" appeared it has been replaced by the first ( and only, in the case ) thing that we included in the useTemplate line.

All arguments should be enclosed within quotes "", even numbers. This is to ensure that the proper values are loaded into the appropriate arguments.

==== Including Other Templates ====
You might have noticed that the bumpmap line in the above shader has come from
'''BumpBehavior''' = "useTemplate hasHeightMap< '''TextureParm''', '''ScaleParm''' >"

When the template is evaluated, all of the arguments that you pass in are first applied to all of the other arguments that you pass in. Before we start replacing text in the main body of the material we evaluate '''BumpBehavior''' with the other arguments that are passed in and end up with
useTemplate hasHeightMap< '''textures/sand/dry_beach_sand_footprints''', 1.0 >

This is what is then used to replace text in the main body of the material.

Before we get any further, here is the definition of the template ''hasHeightmap''
template hasHeightmap {
parameters < '''TextureParm''', '''ScaleParm''' >
text {
bumpmap addnormals ( '''TextureParm'''_local.tga, heightmap ( '''TextureParm'''_h.tga, '''ScaleParm''' ) )
}
}

This is one of several behaviors that are available for the bumpmap stage of materials. This provides an easy way to customize the behavior of a single template in a flexible manner instead of having an excessive number of copy-pasted "almost-the-same" templates.

=== Commands ( Advanced ) ===
Commands allow for iterative or conditional generation of template result strings.
Commands work similar to text blocks, ''commands'' blocks can be interleaved with text blocks

text {
bleh bleh
}
commands {
meh meh
}
....

==== List of commands ====

===== Append =====
Just copies the text block to the template output.

append {
-uninterpreted text block-
}

===== If =====
Evaluates the condition and evaluates commands if true

if ( condition ) {
-commands-
}

Condition is one of the following forms
left operator right
Operator can be == or !=
Left and right can be either a string constant ( "string" ) or a template parameter name.

@@ Line 1: / Line 1: @@
 === Templates ===
-This style of template should not be used. The preferred method is to use the parser-based $template instead.
+'''This style of template should not be used. The preferred method is to use the parser-based $template instead.'''
 Templates provide away to avoid repetitive copy and paste of declarations such as materials and sound shaders.