source: OGRE/trunk/ogrenew/Docs/manual/manual_14.html @ 692

Revision 692, 11.1 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies
Line 
1<HTML>
2<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3<!-- Created on , 12 2006 by texi2html 1.64 -->
4<!--
5Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6            Karl Berry  <karl@freefriends.org>
7            Olaf Bachmann <obachman@mathematik.uni-kl.de>
8            and many others.
9Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
10Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
11 
12-->
13<HEAD>
14<TITLE>OGRE Manual v1.2.0 ('Dagon'): Material Scripts</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Material Scripts">
17<META NAME="keywords" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Material Scripts">
18<META NAME="resource-type" CONTENT="document">
19<META NAME="distribution" CONTENT="global">
20<META NAME="Generator" CONTENT="texi2html 1.64">
21<LINK TYPE="text/css" rel="stylesheet" href="../style.css"> 
22</HEAD>
23
24<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
25
26<A NAME="SEC23"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC31"> &gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36<HR SIZE=1>
37<H2> 3.1 Material Scripts </H2>
38<!--docid::SEC23::-->
39<P>
40
41Material scripts offer you the ability to define complex materials in a script which can be reused easily. Whilst you could set up all materials for a scene in code using the methods of the Material and TextureLayer classes, in practice it's a bit unwieldy. Instead you can store material definitions in text files which can then be loaded whenever required.<BR><BR>
42</P><P>
43
44<A NAME="SEC24"></A>
45<H2> Loading scripts </H2>
46<!--docid::SEC24::-->
47<P>
48
49Material scripts are loaded when resource groups are initialised: OGRE looks in all resource locations associated with the group (see Root::addResourceLocation) for files with the '.material' extension and parses them. If you want to parse files manually, use MaterialSerializer::parseScript.<BR><BR>
50</P><P>
51
52It's important to realise that materials are not loaded completely by this parsing process: only the definition is loaded, no textures or other resources are loaded. This is because it is common to have a large library of materials, but only use a relatively small subset of them in any one scene. To load every material completely in every script would therefore cause unnecessary memory overhead. You can access a 'deferred load' Material in the normal way (MaterialManager::getSingleton().getByName()), but you must call the 'load' method before trying to use it. Ogre does this for you when using the normal material assignment methods of entities etc.<BR><BR>
53</P><P>
54
55Another important factor is that material names must be unique throughout ALL scripts loaded by the system, since materials are always identified by name.<BR><BR>
56</P><P>
57
58<A NAME="SEC25"></A>
59<H2> Format </H2>
60<!--docid::SEC25::-->
61<P>
62
63Several materials may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces ('{', '}'), and comments indicated by starting a line with '//' (note, no nested form comments allowed). The general format is shown below in the example below (note that to start with, we only consider fixed-function materials which don't use vertex or fragment programs, these are covered later):<BR><BR>
64<TABLE><tr><td>&nbsp;</td><td class=example><pre>// This is a comment
65material walls/funkywall1
66{
67    // first, preferred technique
68    technique
69    {
70        // first pass
71        pass
72        {
73            ambient 0.5 0.5 0.5
74            diffuse 1.0 1.0 1.0
75                       
76            // Texture unit 0
77            texture_unit
78            {
79                texture wibbly.jpg
80                scroll_anim 0.1 0.0
81                wave_xform scale sine 0.0 0.7 0.0 1.0
82            }
83            // Texture unit 1 (this is a multitexture pass)
84            texture_unit
85            {
86                texture wobbly.png
87                rotate_anim 0.25
88                colour_op add
89            }
90        }
91    }
92
93    // Second technique, can be used as a fallback or LOD level
94    technique
95    {
96        // .. and so on
97    }
98               
99}
100</pre></td></tr></table></P><P>
101
102Every material in the script must be given a name, which is the line 'material &#60;blah&#62;' before the first opening '{'. This name must be globally unique. It can include path characters (as in the example) to logically divide up your materials, and also to avoid duplicate names, but the engine does not treat the name as hierarchical, just as a string.<BR><BR>
103</P><P>
104
105<STRONG> NOTE: ':' is the delimiter for specifying material copy in the script so it can't be used as part of the material name.</STRONG>
106<BR><BR>
107</P><P>
108
109A material can copy from a previously defined material by using a <EM>colon</EM> <STRONG>:</STRONG> after the material name followed by the name of the reference material to copy. If the reference material can not be found then it is ignored.  (See section <A HREF="manual_20.html#SEC106">3.1.6 Copying Materials</A>)<BR><BR>
110</P><P>
111
112A material can be made up of many techniques (See section <A HREF="manual_15.html#SEC31">3.1.1 Techniques</A>)- a technique is one way of achieving the effect you are looking for. You can supply more than one technique in order to provide fallback approaches where a card does not have the ability to render the preferred technique, or where you wish to define lower level of detail versions of the material in order to conserve rendering power when objects are more distant. <BR><BR>
113</P><P>
114
115Each technique can be made up of many passes (See section <A HREF="manual_16.html#SEC35">3.1.2 Passes</A>), that is a complete render of the object can be performed multiple times with different settings in order to produce composite effects. Ogre may also split the passes you have defined into many passes at runtime, if you define a pass which uses too many texture units for the card you are currently running on (note that it can only do this if you are not using a fragment program). Each pass has a number of top-level attributes such as 'ambient' to set the amount &#38; colour of the ambient light reflected by the material. Some of these options do not apply if you are using vertex programs, See section <A HREF="manual_16.html#SEC35">3.1.2 Passes</A> for more details. <BR><BR>
116</P><P>
117
118Within each pass, there can be zero or many texture units in use (See section <A HREF="manual_17.html#SEC61">3.1.3 Texture Units</A>). These define the texture to be used, and optionally some blending operations (which use multitexturing) and texture effects.<BR><BR>
119</P><P>
120
121You can also reference vertex and fragment programs (or vertex and pixel shaders, if you want to use that terminology) in a pass with a given set of parameters. Programs themselves are declared in separate .program scripts (See section <A HREF="manual_18.html#SEC85">3.1.4 Declaring Vertex and Fragment Programs</A>) and are used as described in <A HREF="manual_19.html#SEC99">3.1.5 Using Vertex and Fragment Programs in a Pass</A>.
122</P><P>
123
124<A NAME="SEC26"></A>
125<H3> Top-level material attributes </H3>
126<!--docid::SEC26::-->
127The outermost section of a material definition does not have a lot of attributes of its own (most of the configurable parameters are within the child sections. However, it does have some, and here they are:<BR><BR>
128<A NAME="lod_distances"></A>
129<A NAME="SEC27"></A>
130<H3> lod_distances </H3>
131<!--docid::SEC27::-->
132This attribute controls the distances at which different Techniques can come into effect. See section <A HREF="manual_15.html#SEC31">3.1.1 Techniques</A> for a full discussion of this option.
133<BR><BR>
134<A NAME="receive_shadows"></A>
135<A NAME="SEC28"></A>
136<H3> receive_shadows </H3>
137<!--docid::SEC28::-->
138This attribute controls whether objects using this material can have shadows cast upon them.<BR><BR>
139<P>
140
141Format: receive_shadows &#60;on|off&#62;<BR>
142Default: on<BR><BR>
143</P><P>
144
145Whether or not an object receives a shadow is the combination of a number of factors, See section <A HREF="manual_62.html#SEC270">7. Shadows</A> for full details; however this allows you to make a material opt-out of receiving shadows if required. Note that transparent materials never receive shadows so this option only has an effect on solid materials.
146</P><P>
147
148<A NAME="transparency_casts_shadows"></A>
149<A NAME="SEC29"></A>
150<H3> transparency_casts_shadows </H3>
151<!--docid::SEC29::-->
152This attribute controls whether transparent materials can cast certain kinds of shadow.<BR><BR>
153<P>
154
155Format: transparency_casts_shadows &#60;on|off&#62;<BR>
156Default: off<BR><BR>
157Whether or not an object casts a shadow is the combination of a number of factors, See section <A HREF="manual_62.html#SEC270">7. Shadows</A> for full details; however this allows you to make a transparent material cast shadows, when it would otherwise not. For example, when using texture shadows, transparent materials are normally not rendered into the shadow texture because they should not block light. This flag overrides that.
158</P><P>
159
160<A NAME="set_texture_alias"></A>
161<A NAME="SEC30"></A>
162<H3> set_texture_alias </H3>
163<!--docid::SEC30::-->
164This attribute associates a texture alias with a texture name.<BR><BR>
165<P>
166
167Format: set_texture_alias &#60;alias name&#62; &#60;texture name&#62;<BR><BR>
168</P><P>
169
170This attribute is used to set the textures used in texture unit states that were copied from another material.(See section <A HREF="manual_20.html#SEC106">3.1.6 Copying Materials</A>)<BR><BR>
171</P><P>
172
173<A NAME="Techniques"></A>
174<HR SIZE=1>
175<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
176<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> &lt; </A>]</TD>
177<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> Up </A>]</TD>
178<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_15.html#SEC31"> &gt; </A>]</TD>
179<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
180<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
181<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
182<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
183</TR></TABLE>
184<BR> 
185<FONT SIZE="-1">
186This document was generated
187by <I>Steve Streeting</I> on <I>, 12 2006</I>
188using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
189"><I>texi2html</I></A>
190
191</BODY>
192</HTML>
Note: See TracBrowser for help on using the repository browser.