Documentation Talk:Reference Section 3.1 - Revision history

Jholsenback: wording and format changes

2010-05-05T09:37:24Z

wording and format changes

Jholsenback: wording and organization

2010-05-01T10:15:27Z

wording and organization

Jholsenback: PPM addition

2010-04-30T23:43:06Z

PPM addition

Jholsenback: v3.7 changes

2010-04-30T09:41:57Z

v3.7 changes

Jholsenback: v3.7 changes

2010-04-30T09:32:24Z

v3.7 changes

Jholsenback: WIP changes/additions

2010-04-23T10:16:52Z

WIP changes/additions

Show changes

Jholsenback: assumed gamma work

2010-04-19T19:36:43Z

assumed gamma work

Jholsenback: oops spelling

2010-04-17T19:38:20Z

oops spelling

Jholsenback: WIP notations

2010-04-17T19:35:56Z

WIP notations

Jholsenback: added sig and t/d

2010-04-17T19:12:20Z

added sig and t/d

@@ Line 227: / Line 227: @@
 <!--<indexentry "Gamma, scene file">--->
-<p>The image file gamma problem itself is just a result of how scenes
+<p>The image file gamma problem itself is just a result of how scenes themselves are generated in POV-Ray. When you start out with a new scene and are placing light sources and adjusting surface textures and colors, you generally make several attempts before the lighting is how you like it. How you choose these settings depends upon the preview image or the image file stored to disk, which in turn is dependent upon the overall gamma of the display hardware being used.</p>
-themselves are generated in POV-Ray. When you start out with a new scene and
+<p>This means that as the artist you are doing gamma correction in the POV-Ray scene file for your particular hardware. This scene file will generate an image file that is also gamma corrected for your hardware and will display correctly on systems similar to your own. However, when this scene is rendered on another platform, it may be too bright or too dim, regardless of the output file format used. Rather than have you change all the scene files to have a single fixed gamma value, POV-Ray allows you to specify in the scene file the display gamma of the system that the scene was created on.</p>
-are placing light sources and adjusting surface textures and colors, you
+<p>The <code>file_gamma</code> global setting, in conjunction with the <code>Display_Gamma</code> INI setting lets POV-Ray know how to do gamma correction on a given scene so that the preview and output image files will appear the correct brightness on any system. Since the gamma correction is done internally to POV-Ray, it will produce output image files that are the correct brightness for the current display, regardless of what output format is used.</p>
 ====HF_Gray_16====

@@ Line 262: / Line 262: @@
 <!--<indexentry "hf_gray_16, global_settings">--->
 <!--<indexentry primary "hf_gray_16">--->
 <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>
@@ Line 272: / Line 272: @@
 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 section &quot;<!--<linkto "Height Field">Height Field</linkto>--->[[Documentation:Reference Section 4#Height Field|Height Field]]&quot; for a description of how POV-Ray heightfields are stored for each file type.</p>
-<p>Currently only PNG, and PPM files support grayscale output; others will be added over time.</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 class="Warning"><strong>Caveat:</strong> grayscale output implies the maximum bit-depth the format supports for PNG this 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>

@@ Line 265: / Line 265: @@
 <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>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 grayscale output. By default this option is off.</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 grayscale output. By default this option is off.</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>
@@ Line 272: / Line 272: @@
 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 section &quot;<!--<linkto "Height Field">Height Field</linkto>--->[[Documentation:Reference Section 4#Height Field|Height Field]]&quot; for a description of how POV-Ray heightfields are stored for each file type.</p>
-<p>Currently only PNG file support is provided with grayscale output; others will be added over time.</p>
+<p>Currently only PNG, and PPM files support grayscale output; others will be added over time.</p>
 <p class="Warning"><strong>Caveat:</strong> grayscale output implies the maximum bit-depth the format supports for PNG this 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>

@@ Line 68: / Line 68: @@
 adc_bailout	   : 1/255
 ambient_light	   : &lt;1,1,1&gt;
-assumed_gamma	   : on
+assumed_gamma	   : deprecated
 file_gamma	   : sRGB
-hf_gray_16	   : off
+hf_gray_16	   : deprecated
 irid_wavelength	   : &lt;0.25,0.18,0.14&gt;
 max_trace_level	   : 5

@@ Line 263: / Line 263: @@
 <!--<indexentry primary "hf_gray_16">--->
-=====The OLD Way=====
+<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>The <code>hf_gray_16</code> setting is useful when using POV-Ray to
-generate heightfields for use in other POV-Ray scenes. The syntax is...
+<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 grayscale output. By default this option is off.</p>
-global_settings { hf_gray_16 [Bool] }</p>
 <p>
-Setting the <code> hf_gray_16</code> option will cause the preview display,
+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 section &quot;<!--<linkto "Height Field">Height Field</linkto>--->[[Documentation:Reference Section 4#Height Field|Height Field]]&quot; for a description of how POV-Ray heightfields are stored for each file type.</p>
 <p>Currently only PNG file support is provided with grayscale output; others will be added over time.</p>
-<p>Grayscale output 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 grayscale output.</p>
-<p class="Warning"><strong>Caveat:</strong> grayscale output implies the maximum bit-depth the format supports for PNG this 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 class="Warning"><strong>Caveat:</strong> grayscale output implies the maximum bit-depth the format supports for PNG this 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>

@@ Line 7: / Line 7: @@
 <!--<indexentry primary "ambient_light, global_settings">--->
 <!--<indexentry "Keyword, ambient_light">--->
 <!--<indexentry primary "file_gamma, global_settings">--->
 <!--<indexentry "Keyword, file_gamma">--->
@@ Line 51: / Line 49: @@
    global_settings { [GLOBAL_SETTINGS_ITEMS...] }
 GLOBAL_SETTINGS_ITEM:
-   adc_bailout Value | ambient_light COLOR | assumed_gamma Value |
+   adc_bailout Value | ambient_light COLOR | file_gamma Value |
-   file_gamma Value | hf_gray_16 [Bool] | irid_wavelength COLOR |
+   hf_gray_16 [Bool] | irid_wavelength COLOR |
    charset GLOBAL_CHARSET | max_intersections Number |
    max_trace_level Number | number_of_waves Number |
@@ Line 68: / Line 66: @@
 adc_bailout	   : 1/255
 ambient_light	   : &lt;1,1,1&gt;
 file_gamma	   : sRGB
 hf_gray_16	   : off
@@ Line 101: / Line 98: @@
 ====Assumed_Gamma====
 <!--<indexentry primary "assumed_gamma">--->
-<p>Many people may have noticed at one time or another that some images are
+<p></p>
-too bright or dim when displayed on their system. As a rule, Macintosh users
+<p class="Warning"><strong>Note:</strong> The way POV-Ray 3.7 handles the <code>assumed_gamma</code> keyword has changed!</p>
-find that images created on a PC are too bright, while PC users find that
+<p>Previously the presence of this keyword in <code>global_settings</code> caused a <em>possible error</em> warning and its presence was ignored. In addition no gamma correction was available in previous versions. Starting with version 3.7 however, gamma correction is performed on both the display and file output, subject to the following criteria:</p>
-images created on a Macintosh are too dim.</p>
+<ul>
 <p>
 The <code>assumed_gamma</code> global setting works in conjunction with the
@@ Line 113: / Line 126: @@
 to ensure that scene files render the same way across the wide variety of
 hardware platforms that POV-Ray is used on. The assumed gamma setting is used
-in a scene file by adding</p>
+in an INI file by adding</p>
 <pre>
 global_settings { assumed_gamma Value }
@@ Line 162: / Line 175: @@
 </p>
+<p class="BeAware">... probably should be <em>entirely</em> deleted!</p>
 =====Monitor Gamma=====

@@ Line 163: / Line 163: @@
 </p>
-* The above section needs some work. There are some comments from a recent newsgroup [news://news.povray.org:119/4bc44342$1@news.povray.org posting] that probably need to be worked into the above narritive. --[[User:Jholsenback|jholsenback]] 19:12, 17 April 2010 (UTC)
+* The above section needs some work. There are some comments from a recent newsgroup [news://news.povray.org:119/4bc44342$1@news.povray.org posting] that probably need to be worked into the above narrative. --[[User:Jholsenback|jholsenback]] 19:12, 17 April 2010 (UTC)
 =====Monitor Gamma=====

@@ Line 97: / Line 97: @@
 more than once, the last setting overrides previous values. Details on each
 item are given in the following sections.</p>
 ====Assumed_Gamma====
@@ Line 161: / Line 163: @@
 </p>
-* This section needs some work. These comments from a recent newsgroup [news://news.povray.org:119/4bc44342$1@news.povray.org posting] probably need to be worked into the above section. --[[User:Jholsenback|jholsenback]] 19:12, 17 April 2010 (UTC)
+* The above section needs some work. There are some comments from a recent newsgroup [news://news.povray.org:119/4bc44342$1@news.povray.org posting] that probably need to be worked into the above narritive. --[[User:Jholsenback|jholsenback]] 19:12, 17 April 2010 (UTC)
 =====Monitor Gamma=====
@@ Line 215: / Line 217: @@
 application to do any gamma correction needed.</p>
 =====Image File Gamma=====
 <!--<indexentry "Gamma, image file">--->
@@ Line 242: / Line 245: @@
 only one that has any gamma correction features and is therefore preferred
 for images that will be displayed on a wide variety of platforms.</p>
 <p class="Note"><strong>Note:</strong> Non-legacy scene default gamma handling for image input files has changed significantly from previous betas, affecting all file formats except OpenEXR, Radiance HDR and (with minor differences) most flavors of PNG; there will be NO corresponding warnings. See below for more detail.</p>
 <p>Input image files not carrying unambiguous gamma information will now be assumed to match a common gamma setting, and gamma-adjusted accordingly; this common input file gamma setting can be specified in the scene file using the following syntax:</p>
@@ Line 303: / Line 310: @@
 and without an <code>assumed_gamma</code> setting, the assumed gamma is
 important if the scene is ever rendered on another platform.</p>