File: pov3001c.htm

package info (click to toggle)
povray-manual 3.0.20-1
  • links: PTS
  • area: main
  • in suites: hamm, potato, slink
  • size: 2,724 kB
  • ctags: 1,285
  • sloc: makefile: 31
file content (281 lines) | stat: -rw-r--r-- 22,356 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
<html>
<body text="#000000" bgcolor="#C0C0C0" background="backgrnd.gif">
<a name="ref 1121 pri 0"><a name="ref 1122 pri 0"><a name="ref 103 pri 0"><center><h3><a name="section 7.2.1">
Section 7.2.1<br>Include Files</h3></center>
The language allows include files to be specified by placing the line<p>
<listing>
  #include &quot;filename.inc&quot;
</listing>
<p>
at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It may be up to 40 characters long (or your computer's limit), including the two double-quote characters.<p>
The include file is read in as if it were inserted at that point in the file. Using include is the same as actually cutting and pasting the entire contents of this file into your scene.<p>
Include files may be nested. You may have at most 10 nested include files. There is no limit on un-nested include files.<p>
Generally, include files have data for scenes but are not scenes in themselves. By convention scene files end in <b>.pov</b> and include files end with <b>.inc</b>.<p>
It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between various platforms.<p>
It is typical to put standard include files in a special sub-directory. POV-Ray can only read files in the current directory or one referenced by the <a name="ref 104 pri 2"><strong>Library_Path</strong> option (See section <a href="pov30016.htm#ref 722 pri 0">&quot;Library Paths&quot;</a>).<hr>
<a name="ref 1123 pri 0"><a name="ref 971 pri 0"><center><h3><a name="section 7.2.2">
Section 7.2.2<br>Declare</h3></center>
Identifiers may be declared and later referenced to make scene files more readable and to parametrize scenes so that changing a single declaration changes many values. There are several built-in identifiers which POV-Ray declares for you. See section <a href="pov3001b.htm#ref 1051 pri 0">&quot;Built-in Identifiers&quot;</a>  for details.<hr>
<a name="ref 1124 pri 0"><a name="ref 1125 pri 0"><a name="ref 1050 pri 0"><center><h3><a name="section 7.2.2.1">
Section 7.2.2.1<br>Declaring identifiers</h3></center>
An identifier is declared as follows.<p>
<listing>
  #declare IDENTIFIER = ITEM
</listing>
<p>
Where IDENTIFIER is the name of the identifier up to 40 characters long and ITEM is any of the following<p>
<listing>
  float, vector, color or string expressions
  objects (all kinds)
  texture, pigment, normal, finish or halo
  color_map, pigment_map, slope_map, normal_map
  camera, light_source
  atmosphere
  fog
  rainbow
  sky_sphere
  transform
</listing>
<p>
Here are some examples.<p>
<listing>
  #declare Rows = 5
  #declare Count = Count+1
  #declare Here = &lt;1,2,3&gt;
  #declare White = rgb &lt;1,1,1&gt;
  #declare Cyan = color blue 1.0  green 1.0
  #declare Font_Name = &quot;ariel.ttf&quot;
  #declare Ring = torus {5,1}
  #declare Checks = pigment { checker White, Cyan }

  object{ Rod scale y*5 }         // not &quot;cylinder { Rod }&quot;
  object {
    Ring
    pigment { Checks scale 0.5 }
    transform Skew
  }
</listing>
<p>
Declarations, like most language directives, can appear anywhere in the file - even within other statements. For example:<p>
<listing>
  #declare Here=&lt;1,2,3&gt;
  #declare Count=0                   // initialize Count

  union {
    object { Rod translate Here*Count }
    #declare Count=Count+1           // re-declare inside union
    object { Rod translate Here*Count }
    #declare Count=Count+1           // re-declare inside union
    object { Rod translate Here*Count }
  }
</listing>
<p>
As this example shows, you can re-declare an identifier and may use previously declared values in that re-declaration. However if you attempt to re-declare an identifier as anything other than its original type, it will generate a warning message.<p>
Declarations may be nested inside each other within limits. In the example in the previous section you could declare the entire union as a object. However for technical reasons you may not use any language directive inside the declaration of floats, vectors or color expressions.<hr>
<a name="ref 1126 pri 0"><a name="ref 1127 pri 0"><a name="ref 1110 pri 0"><center><h3><a name="section 7.2.3">
Section 7.2.3<br>Default Directive</h3></center>
POV-Ray creates a default texture when it begins processing. You may change those defaults as described below. Every time you specify a <strong>texture</strong> statement, POV-Ray creates a copy of the default texture. Anything you put in the texture statement overrides the default settings. If you attach a <a name="ref 294 pri 4"><strong>pigment</strong>, <a name="ref 324 pri 9"><strong>normal</strong> or <a name="ref 274 pri 11"><strong>finish</strong> to an object without any texture statement then POV-Ray checks to see if a texture has already been attached. If it has a texture then the pigment, normal or finish will modify the existing texture. If no texture has yet been attached to the object then the default texture is copied and the pigment, normal or finish will modify that texture.<p>
You may change the default texture, pigment, normal or finish using the language directive <strong>#default</strong> as follows:<p>
<a name="ref 974 pri 11"><listing>
  #default {
    texture {
      pigment {...}
      normal  {...}
      finish  {...}
    }
  }
</listing>
<p>
Or you may change just part of it like this:<p>
<listing>
  #default {
    pigment {...}
  }
</listing>
<p>
This still changes the pigment of the default texture. At any time there is only one default texture made from the default pigment, normal and finish. The example above does not make a separate default for pigments alone. Note that the special textures <a name="ref 945 pri 13"><strong>tiles</strong> and <a name="ref 901 pri 14"><strong>material_map</strong> or a texture with a <a name="ref 934 pri 15"><strong>texture_map</strong> may not be used as defaults.<p>
You may change the defaults several times throughout a scene as you wish. Subsequent <a name="ref 1110 pri 16"><strong>#default</strong> statements begin with the defaults that were in effect at the time. If you wish to reset to the original POV-Ray defaults then you should first save them as follows:<p>
<listing>
  //At top of file
  #declare Original_Default = texture {}
</listing>
<p>
later after changing defaults you may restore it with...<p>
<listing>
  #default {texture {Original_Default}}
</listing>
<p>
If you do not specify a texture for an object then the default texture is attached when the object appears in the scene. It is not attached when an object is declared. For example:<p>
<listing>
  #declare My_Object =
    sphere{ &lt;0,0,0&gt;, 1 }  // Default texture not applied
  object { My_Object }    // Default texture added here
</listing>
<p>
You may force a default texture to be added by using an empty texture statement as follows:<p>
<listing>
  #declare My_Thing =
    sphere { &lt;0,0,0&gt;, 1 texture {} }  // Default texture applied
</listing>
<p>
The original POV-Ray defaults for all items are given throughout the documentation under each appropriate section.<hr>
<a name="ref 1128 pri 0"><a name="ref 728 pri 0"><a name="ref 725 pri 0"><center><h3><a name="section 7.2.4">
Section 7.2.4<br>Version Directive</h3></center>
While many language changes have been made for POV-Ray 3.0, all of version 2.0 syntax and most of version 1.0 syntax still works. Whenever possible we try to maintain backwards compatibility. One feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Setting <a name="ref 727 pri 2"><strong>+MV</strong>1.0 command line switch or the <a name="ref 726 pri 10"><strong>Version</strong>=1.0 INI option turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. The changes between 2.0 and 3.0 are not as extensive. Setting <a name="ref 726 pri 19"><strong>Version</strong>=2.0 is only necessary to eliminate some warning messages. Naturally the default setting for this option is <a name="ref 726 pri 29"><strong>Version</strong>=3.0.<p>
The <a name="ref 725 pri 30"><strong>#version</strong> language directive is used to change modes within scene files. This switch or INI options only affects the initial setting.<p>
Together with the built-in <a name="ref 726 pri 41"><strong>version</strong> identifier the <strong>#version</strong> directive allows you to save and restore the previous values of this compatibility setting. For example suppose <b>mystuff.inc</b> is in version 1.0 format. At the top of the file you could put:<p>
<listing>
  #declare Temp_Vers = version // Save previous value
  #version 1.0                    // Change to 1.0 mode

  ... // Version 1.0 stuff goes here ...

  #version Temp_Vers              // Restore previous version
</listing>
<p>
Previous versions of POV-Ray would not allow you to change versions inside an object or declaration but that restriction has been lifted for POV-Ray 3.0.<p>
Future versions of POV-Ray may not continue to maintain full backward compatibility even with the <strong>#version</strong> directive. We strongly encourage you to phase in 3.0 syntax as much as possible.<hr>
<a name="ref 1129 pri 0"><a name="ref 1130 pri 0"><center><h3><a name="section 7.2.5">
Section 7.2.5<br>Conditional Directives</h3></center>
POV-Ray 3.0 allows a variety of new language directives to implement conditional parsing of various sections of your scene file. This is especially useful in describing the motion for animations but it has other uses as well. Also available is a <strong>#while</strong> loop directive. You may nest conditional directives 200 levels deep.<hr>
<a name="ref 1131 pri 0"><a name="ref 1132 pri 0"><center><h3><a name="section 7.2.5.1">
Section 7.2.5.1<br>IF ELSE Directives</h3></center>
The simplest conditional directive is a traditional <a name="ref 1133 pri 0"><strong>#if</strong> directive. It is of the form...<p>
<a name="ref 845 pri 0"><a name="ref 997 pri 0"><a name="ref 1000 pri 0"><listing>
  #if (COND)
    // This section is
    //  parsed if COND is true
  #else
    // This section is
    // parsed if COND is false
  #end // End of conditional part
</listing>
<p>
where <strong>(COND)</strong> is a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the condition are required. The <a name="ref 1113 pri 0"><strong>#else</strong> directive is optional. The <a name="ref 1116 pri 0"><strong>#end</strong> directive is required.<hr>
<a name="ref 1134 pri 0"><a name="ref 1135 pri 0"><center><h3><a name="section 7.2.5.2">
Section 7.2.5.2<br>IFDEF Directives</h3></center>
The <a name="ref 1136 pri 0"><strong>#ifdef</strong> directive is similar to the <strong>#if</strong> directive however it is used to determine if an identifier has been previously declared. After the <a name="ref 1136 pri 1"><strong>#ifdef</strong> directive instead of a boolean expression you put a lone identifier enclosed in parentheses. For example:<p>
<a name="ref 848 pri 1"><a name="ref 997 pri 2"><a name="ref 1000 pri 3"><listing>
 #ifdef (User_Thing)
   // This section is parsed if the
   // identifier &quot;User_Thing&quot; was
   // previously declared
   object{User_Thing} // invoke identifier
 #else
   // This section is parsed if the
   // identifier &quot;User_Thing&quot; was not
   // previously declared
   box{&lt;0,0,0&gt;,&lt;1,1,1&gt;} // use a default
 #end
   // End of conditional part
</listing>
<p>
The <a name="ref 1113 pri 4"><strong>#else</strong> directive is optional. The <a name="ref 1116 pri 5"><strong>#end</strong> directive is required.<hr>
<a name="ref 1137 pri 0"><a name="ref 1138 pri 0"><center><h3><a name="section 7.2.5.3">
Section 7.2.5.3<br>IFNDEF Directives</h3></center>
The <a name="ref 1139 pri 0"><strong>#ifndef</strong> directive is similar to the <strong>#ifdef</strong> directive however it is used to determine if the given identifier isn't declared yet. For example:<p>
<a name="ref 1140 pri 0"><a name="ref 997 pri 2"><a name="ref 1000 pri 4"><listing>
 #ifndef (User_Thing)
   // This section is parsed if the
   // identifier &quot;User_Thing&quot; was not
   // previously declared
   box{&lt;0,0,0&gt;,&lt;1,1,1&gt;} // use a default
 #else
   // This section is parsed if the
   // identifier &quot;User_Thing&quot; was
   // previously declared
   object{User_Thing} // invoke identifier
 #end
   // End of conditional part
</listing>
<p>
The <a name="ref 1113 pri 6"><strong>#else</strong> directive is optional. The <a name="ref 1116 pri 8"><strong>#end</strong> directive is required.<hr>
<a name="ref 1141 pri 0"><a name="ref 1142 pri 0"><center><h3><a name="section 7.2.5.4">
Section 7.2.5.4<br>SWITCH CASE and RANGE Directives</h3></center>
A more powerful conditional is the <a name="ref 1114 pri 0"><strong>#switch</strong> directive. The syntax is as follows...<p>
<a name="ref 908 pri 0"><a name="ref 911 pri 0"><a name="ref 997 pri 3"><a name="ref 879 pri 3"><a name="ref 1000 pri 6"><a name="ref 1039 pri 6"><listing>
  #switch (VALUE)
    #case (TEST_1)
      // This section is parsed if VALUE=TEST_1
    #break  //First case ends

    #case (TEST_2)
      // This section is parsed if VALUE=TEST_2
    #break  //Second case ends

    #range (LOW_1,HIGH_1)
      // This section is parsed if (VALUE&gt;=LOW_1)&amp;(VALUE&lt;=HIGH_1)
    #break  //Third case ends

    #range (LOW_2,HIGH_2)
      // This section is parsed if (VALUE&gt;=LOW_2)&amp;(VALUE&lt;=HIGH_2)
    #break  //Fourth case ends

    #else
      // This section is parsed if no other case or
      // range is true.
  #end // End of conditional part
</listing>
<p>
The float expression VALUE following the <a name="ref 1114 pri 7"><strong>#switch</strong> directive is evaluated and compared to the values in the <a name="ref 1112 pri 7"><strong>#case</strong> or <a name="ref 1143 pri 7"><strong>#range</strong> directives. When using <a name="ref 1112 pri 8"><strong>#case</strong>, it is followed by a float expression TEST_1 in parentheses. It is compared to the VALUE. As usual in POV-Ray, float comparisons are considered equal if their difference is under 1e-10. If the values are equal, parsing continues normally until a <a name="ref 1109 pri 8"><strong>#break</strong>, <a name="ref 1113 pri 11"><strong>#else</strong> or <a name="ref 1116 pri 14"><strong>#end</strong> directive is reached. If the comparison fails POV-Ray skips until another <a name="ref 1112 pri 16"><strong>#case</strong> or <a name="ref 1143 pri 17"><strong>#range</strong> is found.<p>
If you use the <a name="ref 1143 pri 19"><strong>#range</strong> directive it is followed by two float expressions LOW_1 and HIGH_1 which are enclosed in parentheses and separated by a comma. If the switch VALUE is in the range specified then parsing continues normally until a <a name="ref 1109 pri 20"><strong>#break</strong>, <a name="ref 1113 pri 24"><strong>#else</strong> or <a name="ref 1116 pri 28"><strong>#end</strong> directive is reached. If the VALUE is outside the range the comparison fails and POV-Ray skips until another <a name="ref 1112 pri 31"><strong>#case</strong> or <a name="ref 1143 pri 34"><strong>#range</strong> is found.<p>
If no <a name="ref 1112 pri 38"><strong>#case</strong> or <a name="ref 1143 pri 42"><strong>#range</strong> succeeds the <a name="ref 1113 pri 47"><strong>#else</strong> section is parsed. The <a name="ref 1113 pri 53"><strong>#else</strong> directive is optional. If no <a name="ref 1113 pri 60"><strong>#else</strong> is specified and no match succeeds then parsing resumes after the <a name="ref 1116 pri 65"><strong>#end</strong> directive.<p>
There may be any number of <a name="ref 1112 pri 70"><strong>#case</strong> or <a name="ref 1143 pri 75"><strong>#range</strong> directives in any order you want. If a segment evaluates true but no <a name="ref 1109 pri 77"><strong>#break</strong> is specified, the parsing will fall through to the next <a name="ref 1112 pri 83"><strong>#case</strong> or <a name="ref 1143 pri 89"><strong>#range</strong> and will continue until a <a name="ref 1109 pri 92"><strong>#break</strong>, <a name="ref 1113 pri 100"><strong>#else</strong> or <a name="ref 1116 pri 106"><strong>#end</strong>. Hitting a <a name="ref 1109 pri 110"><strong>#break</strong> while parsing a successful section causes an immediate jump to the <a name="ref 1116 pri 117"><strong>#end</strong> without processing subsequent sections, even if a subsequent condition would also have been satisfied.<hr>
<a name="ref 1144 pri 0"><a name="ref 1145 pri 0"><center><h3><a name="section 7.2.5.5">
Section 7.2.5.5<br>WHILE Directive</h3></center>
The <a name="ref 1146 pri 0"><strong>#while</strong> directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses. The <a name="ref 1146 pri 1"><strong>#while</strong> directive is followed by a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the expression are required. If the condition is true parsing continues normally until an <a name="ref 1116 pri 9"><strong>#end</strong> directive is reached. At the end, POV-Ray loops back to the <a name="ref 1146 pri 11"><strong>#while</strong> directive and the condition is re-evaluated. Looping continues until the condition fails. When it fails, parsing continues after the <a name="ref 1116 pri 20"><strong>#end</strong> directive. For example:<p>
<a name="ref 1027 pri 20"><a name="ref 1000 pri 24"><listing>
  #declare Count=0
  #while (Count &lt; 5)
    object{MyObject translate x*3*Count}
    #declare Count=Count+1
  #end
</listing>
<p>
This example places five copies of <strong>MyObject</strong> in a row spaced three units apart in the x-direction.<hr>
<a name="ref 1147 pri 0"><a name="ref 1148 pri 0"><center><h3><a name="section 7.2.6">
Section 7.2.6<br>User Message Directives</h3></center>
With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.<hr>
<a name="ref 1149 pri 0"><a name="ref 761 pri 0"><center><h3><a name="section 7.2.6.1">
Section 7.2.6.1<br>Text Message Streams</h3></center>
The syntax for a text message is any of the following:<p>
<listing>
  #debug      STRING
  #error      STRING
  #render     STRING
  #statistics STRING
  #warning    STRING
</listing>
<p>
Where STRING is any valid string of text including string identifiers or functions which return strings. For example:<p>
<listing>
  #switch (clock*360)
    #range (0,180)
      #render &quot;Clock in 0 to 180 range\n&quot;
    #break

    #range (180,360)
      #render &quot;Clock in 180 to 360 range\n&quot;
    #break

    #else
      #warning &quot;Clock outside expected range\n&quot;
      #warning concat(&quot;Value is:&quot;,str(clock*360,5,0),&quot;\n&quot;)
  #end
</listing>
<p>
There are seven distinct text streams that POV-Ray uses for output. You may output only to five of them. On some versions of POV-Ray, each stream is designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-back buffer. See <a href="pov30018.htm#ref 768 pri 0">&quot;Console Text Output&quot;</a> for details on re-directing the streams to a text file.<p>
Here is a description of how POV-Ray uses each stream. You may use them for whatever purpose you want except note that use of the <a name="ref 1150 pri 1"><strong>#error</strong> stream causes a fatal error after the text is displayed.<p>
<a name="ref 969 pri 1"><a name="ref 1115 pri 1"><strong>DEBUG:</strong> <a name="ref 760 pri 2">This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files.<p>
<a name="ref 1003 pri 2"><a name="ref 1150 pri 2"><strong>FATAL:</strong> <a name="ref 762 pri 3">This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error.<p>
<a name="ref 827 pri 3"><a name="ref 1117 pri 3"><strong>RENDER:</strong> <a name="ref 763 pri 4">This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options such as scene name, resolution, animation settings, anti-aliasing and others.<p>
<a name="ref 887 pri 4"><a name="ref 1111 pri 4"><strong>STATISTICS:</strong> <a name="ref 764 pri 5">This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time of the processing and other information.<p>
<a name="ref 1018 pri 5"><a name="ref 1118 pri 5"><strong>WARNING:</strong> <a name="ref 766 pri 6">This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene.<p>
<a name="ref 758 pri 7"><a name="ref 765 pri 8">The <strong>BANNER</strong> and <strong>STATUS</strong> streams can not be accessed by the user.<hr>

<center>
<a href="pov3001d.htm">Next Section</a><br>
<a href="povray.htm#Table of Contents">Table Of Contents</a><br>
</center>
</body>
</html>