source: OGRE/trunk/ogrenew/Docs/manual/manual_15.html @ 657

Revision 657, 10.9 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources
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.0.7: Material Scripts</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.0.7: Material Scripts">
17<META NAME="keywords" CONTENT="OGRE Manual v1.0.7: 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="SEC24"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_16.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::SEC24::-->
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
44You can also use this facility to replace existing material definitions which get loaded in from resource files. For example, if you have a .3ds model which you converted using 3ds2oof, it contains a number of material definitions. You can replace any of the material definitions from the .3ds file with your own just by adding a material definition with the same name to a script (remember you can also rename materials in a .3ds file with the 3ds2oof utility with the -matnames option), which will override the one loaded from the .3ds file.<BR><BR>
45</P><P>
46
47<A NAME="SEC25"></A>
48<H2> Loading scripts </H2>
49<!--docid::SEC25::-->
50<P>
51
52Material scripts are loaded at initialisation time by the system: by default it looks in all common resource locations (see Root::addResourceLocation) for files with the '.material' extension and parses them. If you want to parse files with a different extension, use the MaterialManager::getSingleton().parseAllSources method with your own extension, or if you want to parse an individual file, use MaterialManager::getSingleton().parseScript.<BR><BR>
53</P><P>
54
55It'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 (getMaterial() from SceneManager, or 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>
56</P><P>
57
58Another 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>
59</P><P>
60
61<A NAME="SEC26"></A>
62<H2> Format </H2>
63<!--docid::SEC26::-->
64<P>
65
66Several 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>
67<TABLE><tr><td>&nbsp;</td><td class=example><pre>// This is a comment
68material walls/funkywall1
69{
70    // first, preferred technique
71    technique
72    {
73        // first pass
74        pass
75        {
76            ambient 0.5 0.5 0.5
77            diffuse 1.0 1.0 1.0
78                       
79            // Texture unit 0
80            texture_unit
81            {
82                texture wibbly.jpg
83                scroll_anim 0.1 0.0
84                wave_xform scale sine 0.0 0.7 0.0 1.0
85            }
86            // Texture unit 1 (this is a multitexture pass)
87            texture_unit
88            {
89                texture wobbly.png
90                rotate_anim 0.25
91                colour_op add
92            }
93        }
94    }
95
96    // Second technique, can be used as a fallback or LOD level
97    technique
98    {
99        // .. and so on
100    }
101               
102}
103</pre></td></tr></table></P><P>
104
105Every 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>
106</P><P>
107
108A material can be made up of many techniques (See section <A HREF="manual_16.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>
109</P><P>
110
111Each technique can be made up of many passes (See section <A HREF="manual_17.html#SEC34">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_17.html#SEC34">3.1.2 Passes</A> for more details. <BR><BR>
112</P><P>
113
114Within each pass, there can be zero or many texture units in use (See section <A HREF="manual_18.html#SEC54">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>
115</P><P>
116
117You 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_19.html#SEC76">3.1.4 Declaring Vertex and Fragment Programs</A>) and are used as described in <A HREF="manual_20.html#SEC86">3.1.5 Using Vertex and Fragment Programs in a Pass</A>.
118</P><P>
119
120<A NAME="SEC27"></A>
121<H3> Top-level material attributes </H3>
122<!--docid::SEC27::-->
123The 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>
124<A NAME="lod_distances"></A>
125<A NAME="SEC28"></A>
126<H3> lod_distances </H3>
127<!--docid::SEC28::-->
128This attribute controls the distances at which different Techniques can come into effect. See section <A HREF="manual_16.html#SEC31">3.1.1 Techniques</A> for a full discussion of this option.
129<BR><BR>
130<A NAME="receive_shadows"></A>
131<A NAME="SEC29"></A>
132<H3> receive_shadows </H3>
133<!--docid::SEC29::-->
134This attribute controls whether objects using this material can have shadows cast upon them.<BR><BR>
135<P>
136
137Format: receive_shadows &#60;on|off&#62;<BR>
138Default: on<BR><BR>
139</P><P>
140
141Whether or not an object receives a shadow is the combination of a number of factors, See section <A HREF="manual_57.html#SEC212">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.
142</P><P>
143
144<A NAME="transparency_casts_shadows"></A>
145<A NAME="SEC30"></A>
146<H3> transparency_casts_shadows </H3>
147<!--docid::SEC30::-->
148This attribute controls whether transparent materials can cast certain kinds of shadow.<BR><BR>
149<P>
150
151Format: transparency_casts_shadows &#60;on|off&#62;<BR>
152Default: off<BR><BR>
153Whether or not an object casts a shadow is the combination of a number of factors, See section <A HREF="manual_57.html#SEC212">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.
154</P><P>
155
156<A NAME="Techniques"></A>
157<HR SIZE=1>
158<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
159<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> &lt; </A>]</TD>
160<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
161<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_16.html#SEC31"> &gt; </A>]</TD>
162<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>
163<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
164<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
165<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
166</TR></TABLE>
167<BR> 
168<FONT SIZE="-1">
169This document was generated
170by <I>Steve Streeting</I> on <I>, 12 2006</I>
171using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
172"><I>texi2html</I></A>
173
174</BODY>
175</HTML>
Note: See TracBrowser for help on using the repository browser.