Difference between revisions of "Reference:Global Settings"

From POV-Wiki
Jump to navigation Jump to search
m (a sub-section header was missing)
(→‎Noise_generator: canonicalize a version number)
 
(17 intermediate revisions by 2 users not shown)
Line 70: Line 70:
 
item are given in the following sections.</p>
 
item are given in the following sections.</p>
  
 +
==ADC_Bailout==
 
{{#indexentry:adc_bailout, global_settings}}
 
{{#indexentry:adc_bailout, global_settings}}
 
{{#indexentry:keyword, adc_bailout}}
 
{{#indexentry:keyword, adc_bailout}}
==ADC_Bailout==
 
 
<p>In scenes with many reflective and transparent surfaces, POV-Ray can get
 
<p>In scenes with many reflective and transparent surfaces, POV-Ray can get
 
bogged down tracing multiple reflections and refractions that contribute very
 
bogged down tracing multiple reflections and refractions that contribute very
Line 90: Line 90:
 
setting is perfectly adequate and should be left alone. Setting
 
setting is perfectly adequate and should be left alone. Setting
 
<code>adc_bailout</code> to 0 will disable ADC, relying completely on
 
<code>adc_bailout</code> to 0 will disable ADC, relying completely on
<code>[[Reference:Global_Settings#Max_Trace_Level|:max_trace_level|max_trace_level]]</code> to set an
+
<code>max_trace_level</code> to set an upper limit on the number of rays spawned.</p>
upper limit on the number of rays spawned.</p>
 
 
<p>
 
<p>
See the section [[Reference:Global_Settings#Max_Trace_Level|:max_trace_level|Max_Trace_Level]] for details on how ADC and <code>max_trace_level</code> interact.</p>
+
See the section [[Reference:Global Settings#Max_Trace_Level|Max_Trace_Level]] for details on how ADC and <code>max_trace_level</code> interact.</p>
  
 +
==Ambient_Light==
 
{{#indexentry:ambient_light, global_settings}}
 
{{#indexentry:ambient_light, global_settings}}
 
{{#indexentry:keyword, ambient_light}}
 
{{#indexentry:keyword, ambient_light}}
==Ambient_Light==
 
 
<p>Ambient light is used to simulate the effect of inter-diffuse reflection
 
<p>Ambient light is used to simulate the effect of inter-diffuse reflection
 
that is responsible for lighting areas that partially or completely lie in
 
that is responsible for lighting areas that partially or completely lie in
Line 111: Line 110:
 
&lt;1,1,1&gt;</code>. Only the rgb components are used. The actual ambient
 
&lt;1,1,1&gt;</code>. Only the rgb components are used. The actual ambient
 
used is: <em>Ambient = Finish_Ambient * Global_Ambient</em>.</p>
 
used is: <em>Ambient = Finish_Ambient * Global_Ambient</em>.</p>
<p>
+
<p>See the section [[Reference:Finish#Ambient|Ambient]] for more information.</p>
See the section [[Reference:Finish#Ambient|:Ambient|Ambient]] for more information.</p>
 
  
 +
==Assumed_Gamma==
 
{{#indexentry:assumed_gamma, keyword}}
 
{{#indexentry:assumed_gamma, keyword}}
 
{{#indexentry:keyword, assumed_gamma}}
 
{{#indexentry:keyword, assumed_gamma}}
==Assumed_Gamma==
 
 
<p>The <code>assumed_gamma</code> statement specifies a dsiplay gamma for which all color literals in the scene are presumed to be pre-corrected; at the same time it also defines the <em>working gamma space</em> in which POV-Ray will perform all its color computations.</p>
 
<p>The <code>assumed_gamma</code> statement specifies a dsiplay gamma for which all color literals in the scene are presumed to be pre-corrected; at the same time it also defines the <em>working gamma space</em> in which POV-Ray will perform all its color computations.</p>
  
 
<p class="Note"><strong>Note:</strong> Using any value other than 1.0 will produce physically inaccurate results. Furthermore, if you decide to go for a different value for convenience, it is highly recommended to set this value to the same as your <code>Display_Gamma</code>. Using this parameter for artistic purposes is strongly discouraged.</p>
 
<p class="Note"><strong>Note:</strong> Using any value other than 1.0 will produce physically inaccurate results. Furthermore, if you decide to go for a different value for convenience, it is highly recommended to set this value to the same as your <code>Display_Gamma</code>. Using this parameter for artistic purposes is strongly discouraged.</p>
  
<p class="Note"><strong>Note:</strong> As of POV-Ray 3.7, this keyword is considered mandatory except in legacy scenes. Future versions of POV-Ray may treat the absence of this keyword in non-legacy scenes as an error.</p>
+
<p class="Note"><strong>Note:</strong> As of POV-Ray v3.7 this keyword is considered mandatory (except in legacy scenes) and consequently enables the <em>experimental</em> gamma handling feature. Future versions of POV-Ray may treat the absence of this keyword in non-legacy scenes as an error.</p>
  
 
<p>See section [[Documentation:Tutorial Section 3.3#Gamma Handling|Gamma Handling]] for more information about gamma.</p>
 
<p>See section [[Documentation:Tutorial Section 3.3#Gamma Handling|Gamma Handling]] for more information about gamma.</p>
  
 +
==HF_Gray_16==
 
{{#indexentry:hf_gray_16, global_settings}}
 
{{#indexentry:hf_gray_16, global_settings}}
{{#indexentry:keyword, hf_gray_16}}  
+
{{#indexentry:keyword, hf_gray_16}}
==HF_Gray_16==
+
<p>A {{Change}} as of version 3.7 has deprecated the <code>hf_gray_16</code> keyword in the <code>global_settings</code> block. If encountered, it has no effect on the output type and will additionally generate a warning message. Grayscale output can still be used to generate heightfields for use in other POV-Ray scenes. See: [[Reference:File Output Options#Output File Type|Output File Type]] for details.</p>
<p>Grayscale output can be used to generate heightfields for use in other POV-Ray scenes, and may be specified via <code>Grayscale_Output=true</code> as an INI option, or <code>+Fxg</code> (for output type 'x') as a command-line option. For example, <code>+Fng</code> for PNG and <code>+Fpg</code> for PPM (effectively PGM) grayscale output. By default this option is off.</p>
 
 
 
<p class="Note"><strong>Note:</strong> In version 3.7 the <code>hf_gray_16</code> keyword in the <code>global_settings</code> block has been deprecated. If encountered, it has no effect on the output type and will additionally generate a warning message.</p>
 
 
 
<p>With <code>Grayscale_Output=true</code>, the output file will be in the form of a heightfield, with the height at any point being dependent on the brightness of the pixel. The brightness of a pixel is calculated in the same way that color images are converted to grayscale images:<em><code> height = 0.3 * red + 0.59 * green + 0.11 * blue</code></em>.</p>
 
 
 
<p>
 
Setting the <code>Grayscale_Output=true</code> option will cause the preview display, if used, to be grayscale rather than color. This is to allow you to see how the heightfield will look because some file formats store heightfields in a way that is difficult to understand afterwards. See the section [[Reference:Height Field|:Height Field|Height Field]] for a description of how POV-Ray heightfields are stored for each file type.</p>
 
 
 
<p class="Warning"><strong>Caveat:</strong> Grayscale output implies the maximum bit-depth the format supports is 16, it is not valid to specify bits per color channel with 'g' (e.g. <code>+Fng16</code> is not allowed, and nor for that matter is <code>+Fn16g</code>). If bits per channel is provided via an INI option, it is ignored.</p>
 
 
 
<p>Currently PNG, and PPM are the only file formats that support grayscale output.</p>
 
  
 +
==Irid_Wavelength==
 
{{#indexentry:irid_wavelength, global_settings}}
 
{{#indexentry:irid_wavelength, global_settings}}
 
{{#indexentry:keyword, irid_wavelength}}
 
{{#indexentry:keyword, irid_wavelength}}
==Irid_Wavelength==
 
 
<p>Iridescence calculations depend upon the dominant wavelengths of the
 
<p>Iridescence calculations depend upon the dominant wavelengths of the
 
primary colors of red, green and blue light. You may adjust the values using
 
primary colors of red, green and blue light. You may adjust the values using
Line 158: Line 145:
 
option as a means to experiment with other values.</p>
 
option as a means to experiment with other values.</p>
  
 +
==Charset==
 
{{#indexentry:charset, global_settings}}
 
{{#indexentry:charset, global_settings}}
 
{{#indexentry:keyword, charset}}
 
{{#indexentry:keyword, charset}}
Line 166: Line 154:
 
{{#indexentry:sys, global_settings}}
 
{{#indexentry:sys, global_settings}}
 
{{#indexentry:keyword, sys}}
 
{{#indexentry:keyword, sys}}
 
==Charset==
 
 
<p>This allows you to specify the assumed character set of all text strings.
 
<p>This allows you to specify the assumed character set of all text strings.
 
If you specify <code>ascii</code> only standard ASCII character codes in the
 
If you specify <code>ascii</code> only standard ASCII character codes in the
Line 181: Line 167:
 
specific documentation.</p>
 
specific documentation.</p>
  
 +
==Max_Trace_Level==
 
{{#indexentry:max_trace_level, global_settings}}
 
{{#indexentry:max_trace_level, global_settings}}
 
{{#indexentry:keyword, max_trace_level}}  
 
{{#indexentry:keyword, max_trace_level}}  
==Max_Trace_Level==
 
 
<p>In scenes with many reflective and transparent surfaces POV-Ray can get
 
<p>In scenes with many reflective and transparent surfaces POV-Ray can get
 
bogged down tracing multiple reflections and refractions that contribute very
 
bogged down tracing multiple reflections and refractions that contribute very
Line 220: Line 206:
 
approximately 0.0039 since a change smaller than that could not be visible in
 
approximately 0.0039 since a change smaller than that could not be visible in
 
a 24 bit image. Generally this setting is perfectly adequate and should be
 
a 24 bit image. Generally this setting is perfectly adequate and should be
left alone. Setting <code>[[Reference:Global_Settings#ADC_Bailout|:adc_bailout|adc_bailout]]</code> to 0 will disable ADC, relying
+
left alone. Setting <code>[[Reference:Global Settings#ADC_Bailout|adc_bailout]]</code> to 0 will disable ADC, relying
 
completely on <code> max_trace_level</code> to set an upper limit on the
 
completely on <code> max_trace_level</code> to set an upper limit on the
 
number of rays spawned.</p>
 
number of rays spawned.</p>
Line 242: Line 228:
 
</p>
 
</p>
  
 +
==Max_Intersections==
 
{{#indexentry:max_intersections, global_settings}}
 
{{#indexentry:max_intersections, global_settings}}
 
{{#indexentry:keyword, max_intersections}}
 
{{#indexentry:keyword, max_intersections}}
==Max_Intersections==
+
<p>Previous versions of POV-Ray used a set of internal stacks to collect ray/object intersection points. As of version 3.7 <code>max_intersections</code> has been deprecated, and using it in the global settings blocks now produces a warning at parse time.</p>
<p>POV-Ray uses a set of internal stacks to collect ray/object intersection points. The usual maximum number of entries in these <em>I-Stacks</em> is 64. Complex scenes may cause these stacks to overflow. POV-Ray does not stop but it may incorrectly render your scene. When POV-Ray finishes rendering, a number of statistics are displayed. If you see <code>I-Stack overflows</code> reported in the statistics you should increase the stack size. Add a global setting to your scene as follows:</p>
 
<pre>
 
global_settings { max_intersections Integer }
 
</pre>
 
 
 
<p>If the <code>I-Stack Overflows</code> remain increase this value until they stop.</p>
 
  
 +
==Mm_Per_Unit==
 
{{#indexentry:mm_per_unit, global_settings}}
 
{{#indexentry:mm_per_unit, global_settings}}
 
{{#indexentry:keyword, mm_per_unit}}
 
{{#indexentry:keyword, mm_per_unit}}
==Mm_Per_Unit==
+
<p>See the section [[Reference:Finish#Subsurface Light Transport|Subsurface Light Transport]] for more information about the role of <code>mm_per_unit</code> in the global settings block.</p>
<p>See the section [[Reference:Finish#Subsurface_Light_Transport|Subsurface Light Transport]] for more information about the role of <code>mm_per_unit</code> in the global settings block.</p>
 
  
 +
==Number_Of_Waves==
 
{{#indexentry:number_of_waves, global_settings}}
 
{{#indexentry:number_of_waves, global_settings}}
 
{{#indexentry:keyword, number_of_waves}}
 
{{#indexentry:keyword, number_of_waves}}
==Number_Of_Waves==
+
<p>The <code>[[Reference:Waves Pattern|waves]]</code> and <code>[[Reference:Ripples Pattern|ripples]]</code>
<p>The <code>[[Reference:Waves Pattern|:waves|waves]]</code> and <code>[[Reference:Ripples Pattern|:ripples|ripples]]</code>
 
 
patterns are generated by summing a series of waves, each with a slightly different center and size. By default, ten waves are summed but this amount can be globally controlled by changing the <code>number_of_waves</code> setting.</p>
 
patterns are generated by summing a series of waves, each with a slightly different center and size. By default, ten waves are summed but this amount can be globally controlled by changing the <code>number_of_waves</code> setting.</p>
 
<pre>
 
<pre>
Line 268: Line 249:
 
<p>Changing this value affects both waves and ripples alike on all patterns in the scene.</p>
 
<p>Changing this value affects both waves and ripples alike on all patterns in the scene.</p>
  
 +
==Noise_generator==
 
{{#indexentry:noise_generator, global_settings}}
 
{{#indexentry:noise_generator, global_settings}}
 
{{#indexentry:keyword, noise_generator}}
 
{{#indexentry:keyword, noise_generator}}
==Noise_generator==
 
 
<p> There are three noise generators implemented. </p>
 
<p> There are three noise generators implemented. </p>
 
<ul>
 
<ul>
<li><code>noise_generator 1</code> the noise that was used in POV_Ray 3.1</li>
+
<li><code>noise_generator 1</code> the noise that was used in POV_Ray v3.1</li>
 
<li><code>noise_generator 2</code> 'range corrected' version of the old noise, it does not show the plateaus seen with <code>noise_generator 1</code> </li>
 
<li><code>noise_generator 2</code> 'range corrected' version of the old noise, it does not show the plateaus seen with <code>noise_generator 1</code> </li>
 
<li><code>noise_generator 3</code> generates Perlin noise</li>
 
<li><code>noise_generator 3</code> generates Perlin noise</li>
Line 280: Line 261:
 
<p class="Note"><strong>Note:</strong> The noise_generators can also be used within the pigment/normal/etc. statement.</p>
 
<p class="Note"><strong>Note:</strong> The noise_generators can also be used within the pigment/normal/etc. statement.</p>
  
 +
==Subsurface==
 
{{#indexentry:subsurface, global_settings}}
 
{{#indexentry:subsurface, global_settings}}
==Subsurface==
+
<p>See the section [[Reference:Finish#Subsurface Light Transport|Subsurface Light Transport]] for more information about the role of <code>subsurface</code> in the global settings block.</p>
<p>See the section [[Reference:Finish#Subsurface_Light_Transport|Subsurface Light Transport]] for more information about the role of <code>subsurface</code> in the global settings block.</p>
 

Latest revision as of 14:37, 9 June 2021

The global_settings statement is a catch-all statement that gathers together a number of global parameters. The statement may appear anywhere in a scene as long as it is not inside any other statement. You may have multiple global_settings statements in a scene. Whatever values were specified in the last global_settings statement override any previous settings.

Note: Some items which were language directives in earlier versions of POV-Ray have been moved inside the global_settings statement so that it is more obvious to the user that their effect is global. The old syntax is permitted but generates a warning.

The new syntax is:

GLOBAL_SETTINGS:
  global_settings { [GLOBAL_SETTINGS_ITEMS...] }
GLOBAL_SETTINGS_ITEM:
  adc_bailout Value | ambient_light COLOR | assumed_gamma GAMMA_VALUE | 
  hf_gray_16 [Bool] | irid_wavelength COLOR | charset GLOBAL_CHARSET |
  max_intersections Number | max_trace_level Number |
  mm_per_unit Number | number_of_waves Number | noise_generator Number |
  radiosity { RADIOSITY_ITEMS... } | subsurface { SUBSURFACE_ITEMS } |
  photon { PHOTON_ITEMS... }
GLOBAL_CHARSET:
  ascii | utf8 | sys
GAMMA_VALUE:
  Value | srgb

Global setting default values:

charset		   : ascii
adc_bailout	   : 1/255
ambient_light	   : <1,1,1>
assumed_gamma	   : 1.0 (undefined for legacy scenes)
hf_gray_16	   : deprecated
irid_wavelength	   : <0.25,0.18,0.14>
max_trace_level	   : 5
max_intersections  : 64
mm_per_unit        : 10
number_of_waves	   : 10
noise_generator	   : 2

Radiosity:
adc_bailout	   : 0.01
always_sample	   : off
brightness	   : 1.0
count		   : 35  (supports adaptive mode)
error_bound	   : 1.8
gray_threshold	   : 0.0
low_error_factor   : 0.5
max_sample	   : non-positive value
maximum_reuse      : 0.2
minimum_reuse	   : 0.015
nearest_count	   : 5   (max = 20; supports adaptive mode)
normal		   : off 
pretrace_start	   : 0.08
pretrace_end	   : 0.04
recursion_limit	   : 2
subsurface 	   : off

Subsurface:
radiosity	   : off
samples		   : 50,50 

Each item is optional and may appear in any order. If an item is specified more than once, the last setting overrides previous values. Details on each item are given in the following sections.

ADC_Bailout

In scenes with many reflective and transparent surfaces, POV-Ray can get bogged down tracing multiple reflections and refractions that contribute very little to the color of a particular pixel. The program uses a system called Adaptive Depth Control (ADC) to stop computing additional reflected or refracted rays when their contribution is insignificant.

You may use the global setting adc_bailout keyword followed by float value to specify the point at which a ray's contribution is considered insignificant. For example:

global_settings { adc_bailout 0.01 }

The default value is 1/255, or approximately 0.0039, since a change smaller than that could not be visible in a 24 bit image. Generally this setting is perfectly adequate and should be left alone. Setting adc_bailout to 0 will disable ADC, relying completely on max_trace_level to set an upper limit on the number of rays spawned.

See the section Max_Trace_Level for details on how ADC and max_trace_level interact.

Ambient_Light

Ambient light is used to simulate the effect of inter-diffuse reflection that is responsible for lighting areas that partially or completely lie in shadow. POV-Ray provides the ambient_light keyword to let you easily change the brightness of the ambient lighting without changing every ambient value in all finish statements. It also lets you create interesting effects by changing the color of the ambient light source. The syntax is:

global_settings { ambient_light COLOR }

The default is a white ambient light source set at rgb <1,1,1>. Only the rgb components are used. The actual ambient used is: Ambient = Finish_Ambient * Global_Ambient.

See the section Ambient for more information.

Assumed_Gamma

The assumed_gamma statement specifies a dsiplay gamma for which all color literals in the scene are presumed to be pre-corrected; at the same time it also defines the working gamma space in which POV-Ray will perform all its color computations.

Note: Using any value other than 1.0 will produce physically inaccurate results. Furthermore, if you decide to go for a different value for convenience, it is highly recommended to set this value to the same as your Display_Gamma. Using this parameter for artistic purposes is strongly discouraged.

Note: As of POV-Ray v3.7 this keyword is considered mandatory (except in legacy scenes) and consequently enables the experimental gamma handling feature. Future versions of POV-Ray may treat the absence of this keyword in non-legacy scenes as an error.

See section Gamma Handling for more information about gamma.

HF_Gray_16

A Change as of version 3.7 has deprecated the hf_gray_16 keyword in the global_settings block. If encountered, it has no effect on the output type and will additionally generate a warning message. Grayscale output can still be used to generate heightfields for use in other POV-Ray scenes. See: Output File Type for details.

Irid_Wavelength

Iridescence calculations depend upon the dominant wavelengths of the primary colors of red, green and blue light. You may adjust the values using the global setting irid_wavelength as follows...

global_settings { irid_wavelength COLOR }

The default value is rgb <0.70,0.52,0.48> and any filter or transmit values are ignored. These values are proportional to the wavelength of light but they represent no real world units.

In general, the default values should prove adequate but we provide this option as a means to experiment with other values.

Charset

This allows you to specify the assumed character set of all text strings. If you specify ascii only standard ASCII character codes in the range from 0 to 127 are valid. You can easily find a table of ASCII characters on the internet. The option utf8 is a special Unicode text encoding and it allows you to specify characters of nearly all languages in use today. We suggest you use a text editor with the capability to export text to UTF8 to generate input files. You can find more information, including tables with codes of valid characters on the Unicode website The last possible option is to use a system specific character set. For details about the sys character set option refer to the platform specific documentation.

Max_Trace_Level

In scenes with many reflective and transparent surfaces POV-Ray can get bogged down tracing multiple reflections and refractions that contribute very little to the color of a particular pixel. The global setting max_trace_level defines the integer maximum number of recursive levels that POV-Ray will trace a ray.

global_settings { max_trace_level Level }

This is used when a ray is reflected or is passing through a transparent object and when shadow rays are cast. When a ray hits a reflective surface, it spawns another ray to see what that point reflects. That is trace level one. If it hits another reflective surface another ray is spawned and it goes to trace level two. The maximum level by default is five.

One speed enhancement added to POV-Ray in version 3.0 is Adaptive Depth Control (ADC). Each time a new ray is spawned as a result of reflection or refraction its contribution to the overall color of the pixel is reduced by the amount of reflection or the filter value of the refractive surface. At some point this contribution can be considered to be insignificant and there is no point in tracing any more rays. Adaptive depth control is what tracks this contribution and makes the decision of when to bail out. On scenes that use a lot of partially reflective or refractive surfaces this can result in a considerable reduction in the number of rays fired and makes it safer to use much higher max_trace_level values.

This reduction in color contribution is a result of scaling by the reflection amount and/or the filter values of each surface, so a perfect mirror or perfectly clear surface will not be optimizable by ADC. You can see the results of ADC by watching the Rays Saved and Highest Trace Level displays on the statistics screen.

The point at which a ray's contribution is considered insignificant is controlled by the adc_bailout value. The default is 1/255 or approximately 0.0039 since a change smaller than that could not be visible in a 24 bit image. Generally this setting is perfectly adequate and should be left alone. Setting adc_bailout to 0 will disable ADC, relying completely on max_trace_level to set an upper limit on the number of rays spawned.

If max_trace_level is reached before a non-reflecting surface is found and if ADC has not allowed an early exit from the ray tree the color is returned as black. Raise max_trace_level if you see black areas in a reflective surface where there should be a color.

The other symptom you could see is with transparent objects. For instance, try making a union of concentric spheres with a clear texture on them. Make ten of them in the union with radius's from 1 to 10 and render the scene. The image will show the first few spheres correctly, then black. This is because a new level is used every time you pass through a transparent surface. Raise max_trace_level to fix this problem.

Note: Raising max_trace_level will use more memory and time and it could cause the program to crash with a stack overflow error, although ADC will alleviate this to a large extent.

Values for max_trace_level can be set up to a maximum of 256. If there is no max_trace_level set and during rendering the default value is reached, a warning is issued.

Max_Intersections

Previous versions of POV-Ray used a set of internal stacks to collect ray/object intersection points. As of version 3.7 max_intersections has been deprecated, and using it in the global settings blocks now produces a warning at parse time.

Mm_Per_Unit

See the section Subsurface Light Transport for more information about the role of mm_per_unit in the global settings block.

Number_Of_Waves

The waves and ripples patterns are generated by summing a series of waves, each with a slightly different center and size. By default, ten waves are summed but this amount can be globally controlled by changing the number_of_waves setting.

global_settings { number_of_waves Integer }

Changing this value affects both waves and ripples alike on all patterns in the scene.

Noise_generator

There are three noise generators implemented.

  • noise_generator 1 the noise that was used in POV_Ray v3.1
  • noise_generator 2 'range corrected' version of the old noise, it does not show the plateaus seen with noise_generator 1
  • noise_generator 3 generates Perlin noise

The default is noise_generator 2

Note: The noise_generators can also be used within the pigment/normal/etc. statement.

Subsurface

See the section Subsurface Light Transport for more information about the role of subsurface in the global settings block.