Change output handling.

- Add support for bit depths as low as 1 bpc.
- Add support for low-depth greyscale output.
- Add support for greyscale preview.
- Change PGM gamma handling.
- Add more dither algorithms, including blue noise ordered dither.

Also refactor some related code.

Author: c-lipka

.gitignore

@@ -222,6 +222,13 @@ $RECYCLE.BIN/
 # Files created by make in various subdirectories
 .dirstamp
 
+# ===========================
+# POV-Ray meta-build detritus
+# ===========================
+
+# Byte-compiled python modules
+*.pyc
+
 # =====================
 # POV-Ray Miscellaneous
 # =====================

changes.txt

@@ -68,6 +68,12 @@ Changed Behaviour
     `mixed`. See the documentation for details.
   - The dithering implementation has been modified, and may produce slightly
     different results for otherwise identical scenes.
+  - The PGM (greyscale variant of PPM) output gamma handling now matches that
+    of regular PPM, honoring `File_Gamma` defaulting to ITU-R BT.709. To get
+    linear greyscale output, explicitly specify `File_Gamma=1.0`.
+  - Greyscale output no longer automatically forces bit depth to 16 bpc. To get
+    16 bpp greyscale output, explicitly specify `Bits_Per_Color=16`.
+  - Preview now reflects greyscale setting.
 
 New Features
 ------------
@@ -85,6 +91,13 @@ New Features
     the list of control points.
   - The `matrix` syntax now allows allows for a trailing comma at the end of
     the list of coefficients.
+  - File formats supporting variable bit depths (PNG and PPM/PGM) now allow for
+    bit depths as low as 1 bit per colour channel. (1-bit greyscale PPM/PGM will
+    still be written as PGM, not PBM.)
+  - Command-line option `+F` now allows specifying both the `G` greyscale flag
+    and the bit depth.
+  - Support for blue noise dithering has been added, plus a couple more error
+    diffusion dithering filters.
 
 Performance Improvements
 ------------------------

distribution/scenes/output/dither_showcase.pov

@@ -0,0 +1,118 @@
+// POV-Ray 3.8 Scene File "dither_showcase.pov"
+// author:  Christoph Lipka
+// date:    2018-09-30
+//
+//--------------------------------------------------------------------------
+#version 3.8;
+
+#ifndef (Glow)
+  #declare Glow = on;
+#end
+#ifndef (Brightness)
+  #declare Brightness = 4.0;
+#end
+
+global_settings {
+  max_trace_level 5
+  assumed_gamma 1.0
+  radiosity {
+    pretrace_start 0.08
+    pretrace_end   0.01
+    count 150
+    nearest_count 20
+    error_bound 0.5
+    recursion_limit 2
+    low_error_factor .5
+    gray_threshold 0.0
+    minimum_reuse 0.015
+    brightness 1
+    adc_bailout 0.01/2
+  }
+}
+
+#default {
+  texture {
+    pigment {rgb 1}
+    finish {
+      ambient 0.0
+      diffuse 0.8
+      specular albedo 1.0 roughness 0.001
+      reflection { 1.0 fresnel on }
+      conserve_energy
+      fresnel on
+    }
+  }
+}
+
+// ----------------------------------------
+
+#local TestRed   = <1.0,.03,.03>;
+#local TestGreen = <.03,1.0,.03>;
+#local TestBlue  = <.03,.03,1.0>;
+
+#local CameraFocus = <0,1,1>;
+#local CameraDist  = 8;
+#local CameraDepth = 3.0;
+#local CameraTilt  = 5;
+
+camera {
+  location  <0,0,0>
+  direction z*CameraDepth
+  right     x*image_width/image_height
+  up        y
+  translate <0,0,-CameraDist>
+  rotate    x*CameraTilt
+  translate CameraFocus
+}
+
+#macro LightSource(Pos,Color)
+  light_source {
+    Pos
+    color Color
+    area_light x*vlength(Pos)/10, y*vlength(Pos)/10, 9,9 adaptive 1 jitter circular orient
+  }
+  
+#end
+
+LightSource(<-500,500,-500>, rgb Brightness)
+
+// ----------------------------------------
+
+plane {
+  y, 0
+  texture { pigment { color rgb 0.2 } }
+  interior { ior 1.5 }
+}
+
+#macro TestSphere(Pos,Radius,TargetColor,Hole)
+  #if (Hole)
+    union {
+      #local Th = 20;
+      #local R = 0.05;
+      #local SinTh = sin(Th*pi/180);
+      #local CosTh = cos(Th*pi/180);
+      difference {
+        sphere { <0,0,0>, 1 }
+        cylinder { y, y*(1-R)*CosTh, SinTh }
+        cylinder {-y,-y*(1-R)*CosTh, SinTh }
+        cylinder { y,-y,(1-R)*SinTh-R }
+      }
+      torus { (1-R)*SinTh, R translate  y*(1-R)*CosTh }
+      torus { (1-R)*SinTh, R translate -y*(1-R)*CosTh }
+  #else
+    sphere { <0,0,0>, 1
+  #end
+    texture { pigment { color  TargetColor }
+      finish { emission Glow * Brightness * 0.5 }
+    }
+    interior { ior 1.5 }
+    rotate z*30
+    rotate y*clock*360 - y*45
+    scale Radius
+    translate Pos + y*Radius
+  }
+#end
+
+TestSphere(<-2,0,1>, 1, TestRed,   false)
+TestSphere(< 0,0,1>, 1, TestBlue,  true)
+TestSphere(< 2,0,1>, 1, TestGreen, false)

source/base/data/bluenoise64a.cpp

@@ -0,0 +1,48 @@
+//******************************************************************************
+///
+/// @file base/data/bluenoise64a.h
+///
+/// Blue noise pattern data
+/// Auto-generated using metagen-bluenoise.py.
+///
+/// @copyright
+/// @parblock
+///
+/// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
+///
+/// POV-Ray is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU Affero General Public License as
+/// published by the Free Software Foundation, either version 3 of the
+/// License, or (at your option) any later version.
+///
+/// POV-Ray is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+/// GNU Affero General Public License for more details.
+///
+/// You should have received a copy of the GNU Affero General Public License
+/// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+///
+/// ----------------------------------------------------------------------------
+///
+/// POV-Ray is based on the popular DKB raytracer version 2.12.
+/// DKBTrace was originally written by David K. Buck.
+/// DKBTrace Ver 2.0-2.12 were written by David K. Buck & Aaron A. Collins.
+///
+/// @endparblock
+///
+//******************************************************************************
+
+/// @file
+/// @attention
+///     **DO NOT EDIT THIS FILE!**
+///     Instead, if this file needs fixing, modify metagen-bluenoise.py
+///     or its invocation in `tools/meta-make/Makefile` accordingly,
+///     and re-generate this file as described in @ref tools-metamake (`tools/meta-make/readme.md`).
+
+namespace pov_base {
+
+extern const unsigned short kBlueNoise64a[4096];
+
+}