Difference between revisions of "Documentation:Tutorial Section 1"

From POV-Wiki
Jump to navigation Jump to search
m (link repair associated with section moves)
m (Precision about 40 char limited version number)
 
(84 intermediate revisions by 4 users not shown)
Line 10: Line 10:
 
==Introduction==
 
==Introduction==
 
<!--<sectiondesc desc=<"tutorial introduction">--->
 
<!--<sectiondesc desc=<"tutorial introduction">--->
<p>This book provides a tutorial for the Persistence of Vision Ray-Tracer
+
<p>This document provides a tutorial for the Persistence of Vision Ray-Tracer&trade;
 
(POV-Ray). The documentation applies to all platforms to which this version of POV-Ray
 
(POV-Ray). The documentation applies to all platforms to which this version of POV-Ray
 
is ported. The platform-specific documentation is available for each platform separately.</p>
 
is ported. The platform-specific documentation is available for each platform separately.</p>
  
<p>This book is divided into five main parts:</p>
+
<p>The tutorial is divided into five main parts:</p>
  
 
<ol>
 
<ol>
Line 35: Line 35:
 
</ol>
 
</ol>
  
<p>POV-Ray runs on Windows 9x/ME/NT/2000/XP/Vista/7, Macintosh Mac OS and Mac OS X, x86
+
<p>
Linux, UNIX, and other platforms.</p>
+
The current release of POV-Ray runs on 32 and 64-bit versions of Microsoft Windows from XP through Windows 8, Mac OS X, Linux/UNIX, and numerous other platforms (when compiled from source).
 +
</p>
  
<p>We assume that if you are reading this document then you already have
+
<p>If you do not yet have POV-Ray installed or are not sure you have the official version or the latest version, see appendix  
POV-Ray installed and running. However the POV-Team does distribute this file
+
<!--<linkto "What to do if you don't have POV-Ray">What to do if you don't have POV-Ray</linkto>--->[[Documentation:Tutorial Section 5.1#What to do if you don't have POV-Ray|What to do if you don't have POV-Ray]].</p>
by itself in various formats including online on the Internet. If you
 
do not have POV-Ray or are not sure you have the official version or the latest version, see appendix  
 
<!--<linkto "What to do if you don't have POV-Ray">What to do if you don't have POV-Ray</linkto>--->[[Documentation:Tutorial Section 5#What to do if you don't have POV-Ray|What to do if you don't have POV-Ray]].</p>
 
  
 
<p>This book covers only the generic parts of the program which are common
 
<p>This book covers only the generic parts of the program which are common
 
to each version.</p>
 
to each version.</p>
<p class="Note"><strong>Note:</strong> Each version has platform-specific documentation not included here.</p>
+
<p class="Note"><strong>Note:</strong> Each version has platform-specific documentation not included in this section.</p>
<p>We recommend you finish reading this introductory section then read the platform-specific information before reading this tutorial.</p>
+
<p>We recommend you finish reading this introductory section then read the platform-specific information before reading the rest of the tutorial. The platform-specific docs will show you how to render a sample scene and
 
+
will give you detailed descriptions of the platform-specific features.</p>
<p>The platform-specific docs will show you how to render a sample scene and
 
will give you detailed description of the platform-specific features.</p>
 
  
 
<p>The Windows version documentation is available on the POV-Ray program's
 
<p>The Windows version documentation is available on the POV-Ray program's
 
Help menu or by pressing the F1 key while in the program.</p>
 
Help menu or by pressing the F1 key while in the program.</p>
 
<p>The Mac platform documentation is available via the <em>Help</em> menu
 
as well as for viewing using a regular web browser.  Details may be found in
 
the <em>POV-Ray MacOS Read Me</em> which contains information
 
specific to the Mac version of POV-Ray. It is best to read this document
 
first.</p>
 
  
 
<p>The Unix / Linux version documentation can be found at the same place as
 
<p>The Unix / Linux version documentation can be found at the same place as
 
the platform independent part.  Usually that is
 
the platform independent part.  Usually that is
<code>/usr/local/share/povray-3.?/html</code></p>
+
<code>/usr/local/share/povray-3.?</code></p>
  
 
===Program Description===
 
===Program Description===
Line 75: Line 65:
  
 
===What is Ray-Tracing?===
 
===What is Ray-Tracing?===
<!--<indexentry "Ray-Tracing, what is">--->
+
{{#indexentry:Ray-Tracing, what is}}
 
   <p>Ray-tracing is a rendering technique that calculates an image of a scene
 
   <p>Ray-tracing is a rendering technique that calculates an image of a scene
 
   by simulating the way rays of light travel in the real world. However it does
 
   by simulating the way rays of light travel in the real world. However it does
   its job backwards. In the real world, rays of light are emitted from a light
+
   this simulation backwards; in the real world, rays of light are emitted from a light
   source and illuminate objects. The light reflects off of the objects or
+
   source and then strike objects. Some of the light rays then bounce off the objects
   passes through transparent objects. This reflected light hits our eyes or
+
   and enter our eyes (or perhaps a camera). However, most of the rays never reach
  perhaps a camera lens. Because the vast majority of rays never hit an
+
   anything that 'observes' them; they either leave the area of interest or are
   observer, it would take forever to trace a scene.</p>
+
  absorbed by objects within it.
 +
</p>
 +
 
 
<p>
 
<p>
  Ray-tracing programs like POV-Ray start with their simulated camera and
+
  Because the vast majority of rays never reach an observer, it would take a very long
   trace rays backwards out into the scene. The user specifies the location of
+
  time for software to trace even a simple image if the rays were cast as they were in
   the camera, light sources, and objects as well as the surface texture
+
  the real world (because almost all of the calculations would end up going to waste).
  properties of objects, their interiors (if transparent) and any atmospheric
+
  For the purposes of drawing a representation of a scene as viewed from an imaginary
  media such as fog, haze, or fire.</p>
+
  camera, we are generally only interested in rays that reach that camera's lens.</p>
 +
 
 +
<p class="Note">A 'scene' is the virtual world which you wish to take a 'picture' of
 +
  with our simulated camera. There can be (and usually are) objects in the scene that
 +
  do not appear in the final image, just as objects outside the field of view of a real
 +
  camera do not directly appear in the final image. (They can still cast shadows or be
 +
  seen as reflections, though).</p>
 +
 
 +
<p>
 +
  Accordingly, ray-tracing programs like POV-Ray start with their simulated camera and
 +
   trace rays <i>backwards</i> out into the scene. The user specifies the location of
 +
   the camera and the type of lens it is using, the light sources that illuminate the scene, the objects within it, as
 +
  well as the surface texture properties of objects, their interiors (if transparent)
 +
  and any atmospheric media such as fog, haze, or fire.</p>
 
<p>
 
<p>
 
   For every pixel in the final image one or more viewing rays are shot from
 
   For every pixel in the final image one or more viewing rays are shot from
   the camera, into the scene to see if it intersects with any of the objects in
+
   the camera into the scene to see if it intersects with any of the objects in
   the scene. These &quot;viewing rays&quot; originate from the viewer,
+
   the scene. These &quot;viewing rays&quot; originate from the viewer
   represented by the camera, and pass through the viewing window (representing
+
   (represented by the camera), and pass through the viewing window (representing
   the final image).</p>
+
   the pixels of the final image).</p>
 
<p>
 
<p>
 
   Every time an object is hit, the color of the surface at that point is
 
   Every time an object is hit, the color of the surface at that point is
   calculated. For this purpose rays are sent backwards to each light source to
+
   calculated. For this purpose rays are sent from that point to each light source to
   determine the amount of light coming from the source. These &quot;shadow
+
   determine the amount of light coming from that source. These &quot;shadow
 
   rays&quot; are tested to tell whether the surface point lies in shadow or
 
   rays&quot; are tested to tell whether the surface point lies in shadow or
 
   not. If the surface is reflective or transparent new rays are set up and
 
   not. If the surface is reflective or transparent new rays are set up and
Line 107: Line 112:
 
   effects and area lights make it necessary to shoot a lot of additional rays
 
   effects and area lights make it necessary to shoot a lot of additional rays
 
   into the scene for every pixel.</p>
 
   into the scene for every pixel.</p>
 +
 
===What is POV-Ray?===
 
===What is POV-Ray?===
<p>The Persistence of Vision Ray-Tracer(tm) was developed from DKBTrace 2.12
+
<p>
 +
POV-Ray&trade; is short for the Persistence of Vision Raytracer&trade;, a tool for producing
 +
high-quality computer graphics. POV-Ray is Free Software (as per the definition of the Free
 +
Software Foundation) as its source code is licensed under the
 +
[http://www.gnu.org/licenses/agpl-3.0.html Affero General Public License] (AGPL).
 +
</p>
 +
<p>POV-Ray was developed from DKBTrace 2.12
 
(written by David K. Buck and Aaron A. Collins) by a bunch of people (called
 
(written by David K. Buck and Aaron A. Collins) by a bunch of people (called
 
the POV-Team&trade;) in their spare time. The headquarters of the POV-Team is on
 
the POV-Team&trade;) in their spare time. The headquarters of the POV-Team is on
Line 117: Line 129:
 
and creating scenes. Many stunning scenes are included with POV-Ray so you
 
and creating scenes. Many stunning scenes are included with POV-Ray so you
 
can start creating images immediately when you get the package. These scenes
 
can start creating images immediately when you get the package. These scenes
can be modified so you do not have to start from scratch.</p>
+
can also be modified so you do not have to start from scratch.</p>
  
<p>In addition to the pre-defined scenes, a large library of pre-defined shapes
+
<p>In addition to the pre-defined scenes, a library of pre-defined shapes
 
and materials is provided. You can include these shapes and materials in your
 
and materials is provided. You can include these shapes and materials in your
 
own scenes by just including the library file name at the top of your scene
 
own scenes by just including the library file name at the top of your scene
Line 129: Line 141:
 
   <ul>
 
   <ul>
 
   <li>Easy to use scene description language.</li>
 
   <li>Easy to use scene description language.</li>
 
 
   <li>Large library of stunning example scene files.</li>
 
   <li>Large library of stunning example scene files.</li>
 
 
   <li>Standard include files that pre-define many shapes, colors and textures.</li>
 
   <li>Standard include files that pre-define many shapes, colors and textures.</li>
 
 
   <li>Very high quality output image files (up to 48-bit color).</li>
 
   <li>Very high quality output image files (up to 48-bit color).</li>
 
  <li>16 and 24 bit color display on many computer platforms using appropriate
 
  hardware.</li>
 
 
 
   <li>Create landscapes using smoothed height fields.</li>
 
   <li>Create landscapes using smoothed height fields.</li>
 
+
   <li>Many camera types, including <!--<linkto "perspective">perspective</linkto>--->[[Reference:Camera#Perspective projection|perspective]], <!--<linkto "orthographic">orthographic</linkto>--->[[Reference:Camera#Orthographic projection|orthographic]], <!--<linkto "fisheye">fisheye</linkto>--->[[Reference:Camera#Fisheye projection|fisheye]], etc.</li>
   <li>Many camera types, including <!--<linkto "perspective">perspective</linkto>--->[[Documentation:Reference Section 3#Perspective projection|perspective]],
+
   <li><!--<linkto "Spotlights">Spotlights</linkto>--->[[Reference:Light Source#Spotlights|Spotlights]], <!--<linkto "cylindrical lights">cylindrical lights</linkto>--->[[Reference:Light Source#Cylindrical Lights|cylindrical lights]] and <!--<linkto "area lights">area lights</linkto>--->[[Reference:Light Source#Area Lights|area lights]] for sophisticated lighting.</li>
    <!--<linkto "orthographic">orthographic</linkto>--->[[Documentation:Reference Section 3#Orthographic projection|orthographic]], <!--<linkto "fisheye">fisheye</linkto>--->[[Documentation:Reference Section 3#Fisheye projection|fisheye]], etc.</li>
+
   <li><!--<linkto "photons">Photons</linkto>--->[[Reference:Photons|Photons]] for realistic, reflected and refracted, caustics. Photons also interact with media.</li>
 
+
   <li><!--<linkto "Phong">Phong</linkto>--->[[Reference:Finish#Phong Highlights|Phong]] and <!--<linkto "specular">specular highlighting</linkto>--->[[Reference:Finish#Specular Highlight|specular highlighting]] for more realistic-looking surfaces.</li>
   <li><!--<linkto "Spotlights">Spotlights</linkto>--->[[Documentation:Reference Section 4.4#Spotlights|Spotlights]], <!--<linkto "cylindrical lights">cylindrical lights</linkto>--->[[Documentation:Reference Section 4.4#Cylindrical Lights|cylindrical lights]]
+
   <li>Inter-diffuse reflection (<!--<linkto "radiosity">radiosity</linkto>--->[[Reference:Radiosity#Radiosity Basics|radiosity]]) for more realistic lighting.</li>
  and <!--<linkto "area lights">area lights</linkto>--->[[Documentation:Reference Section 4.4#Area Lights|area lights]] for sophisticated lighting.</li>
+
   <li>Atmospheric effects like <!--<linkto "atmosphere">atmosphere</linkto>--->[[Reference:Atmospheric Media|atmosphere]], <!--<linkto "ground fog">ground-fog</linkto>--->[[Reference:Fog|ground-fog]] and <!--<linkto "rainbow">rainbow</linkto>--->[[Reference:Rainbow|rainbow]].</li>
 
+
   <li><!--<linkto "media">Particle media</linkto>--->[[Reference:Media|Particle media]] to model effects like clouds, dust, fire and steam.</li>
   <li><!--<linkto "photons">Photons</linkto>--->[[Documentation:Reference Section 6.1#Photons|Photons]] for realistic, reflected and refracted, caustics. Photons also interact with media.</li>
+
   <li>Several image file <!--<linkto "output formats">output formats</linkto>--->[[Reference:File Output Options|output formats]] including BMP, PNG, JPG and OpenEXR.</li>
 
+
   <li>Basic shape primitives such as:</li>
   <li><!--<linkto "Phong">Phong</linkto>--->[[Documentation:Reference Section 5.1#Phong Highlights|Phong]] and <!--<linkto "specular">specular highlighting</linkto>--->[[Documentation:Reference Section 5.1#Specular Highlight|specular highlighting]]
+
    <ul><li><!--<linkto "sphere">spheres</linkto>--->[[Reference:Sphere|spheres]]</li>
    for more realistic-looking surfaces.</li>
+
    <li><!--<linkto "box">boxes</linkto>--->[[Reference:Box|boxes]]</li>
 
+
    <li><!--<linkto "quadric">quadrics</linkto>--->[[Reference:Superquadric Ellipsoid|quadrics]]</li>
   <li>Inter-diffuse reflection (<!--<linkto "radiosity">radiosity</linkto>--->[[Documentation:Reference Section 3.2#Radiosity Basics|radiosity]]) for more realistic lighting.</li>
+
    <li><!--<linkto "cylinder">cylinders</linkto>--->[[Reference:Cylinder|cylinders]]</li>
 
+
    <li><!--<linkto "cone">cones</linkto>--->[[Reference:Cone|cones]]</li>
   <li>Atmospheric effects like <!--<linkto "atmosphere">atmosphere</linkto>--->[[Documentation:Reference Section 6.1#Media|atmosphere]], <!--<linkto "ground fog">ground-fog</linkto>--->[[Documentation:Reference Section 3.1#Fog|ground-fog]]
+
    <li><!--<linkto "triangle">triangle</linkto>--->[[Reference:Triangle|triangle]]</li>
  and <!--<linkto "rainbow">rainbow</linkto>--->[[Documentation:Reference Section 3.1#Rainbow|rainbow]].</li>
+
    <li><!--<linkto "plane">planes</linkto>--->[[Reference:Plane|planes]]</li></ul>
 
+
   <li>Advanced shape primitives such as:</li>
   <li><!--<linkto "media">Particle media</linkto>--->[[Documentation:Reference Section 6.1#Media|Particle media]] to model effects like clouds, dust, fire and steam.</li>
+
    <ul><li><!--<linkto "torus">Tori</linkto>--->[[Reference:Torus|tori]] (donuts)</li>
 
+
    <li><!--<linkto "bezier">bezier patches</linkto>--->[[Reference:Bicubic Patch|bezier patches]]</li>
   <li>Several image file <!--<linkto "output formats">output formats</linkto>--->[[Documentation:Reference Section 1.1#Output File Type|output formats]] including Targa, BMP (Windows only), PNG and PPM.</li>
+
    <li><!--<linkto "height_field">height fields</linkto>--->[[Reference:Height Field|height fields]] (mountains)</li>
 
+
    <li><!--<linkto "blob">blobs</linkto>--->[[Reference:Blob|blobs]]</li>
   <li>Basic shape primitives such as ... <!--<linkto "sphere">spheres</linkto>--->[[Documentation:Reference Section 4.1#Sphere|spheres]], <!--<linkto "box">boxes</linkto>--->[[Documentation:Reference Section 4#Box|boxes]],
+
    <li><!--<linkto "quartic">quartics</linkto>--->[[Reference:Quartic|quartics]]</li>
  <!--<linkto "quadric">quadrics</linkto>--->[[Documentation:Reference Section 4.1#Superquadric Ellipsoid|quadrics]], <!--<linkto "cylinder">cylinders</linkto>--->[[Documentation:Reference Section 4#Cylinder|cylinders]], <!--<linkto "cone">cones</linkto>--->[[Documentation:Reference Section 4#Cone|cones]],
+
    <li><!--<linkto "smooth_triangle">smooth triangles</linkto>--->[[Reference:Smooth Triangle|smooth triangles]]</li>
  <!--<linkto "triangle">triangle</linkto>--->[[Documentation:Reference Section 4.2#Triangle and Smooth Triangle|triangle]] and <!--<linkto "plane">planes</linkto>--->[[Documentation:Reference Section 4.2#Plane|planes]].</li>
+
    <li><!--<linkto "ttf">text</linkto>--->[[Reference:Text|text]]</li>
 
+
    <li><!--<linkto "superquadric">superquadrics</linkto>--->[[Reference:Superquadric Ellipsoid|superquadrics]]</li>
   <li>Advanced shape primitives such as ... <!--<linkto "torus">Tori</linkto>--->[[Documentation:Reference Section 4.1#Torus|Tori]] (donuts), <!--<linkto "bezier">bezier patches</linkto>--->[[Documentation:Reference Section 4.1#Bicubic Patch|bezier patches]],
+
    <li><!--<linkto "sor">surfaces of revolution</linkto>--->[[Reference:Surface of Revolution|surface of revolution]]</li>
  <!--<linkto "height_field">height fields</linkto>--->[[Documentation:Reference Section 4#Height Field|height fields]] (mountains), <!--<linkto "blob">blobs</linkto>--->[[Documentation:Reference Section 4#Blob|blobs]], <!--<linkto "quartic">quartics</linkto>--->[[Documentation:Reference Section 4.2#Poly, Cubic and Quartic|quartics]],
+
    <li><!--<linkto "prism">prisms</linkto>--->[[Reference:Prism|prisms]]</li>
  <!--<linkto "smooth_triangle">smooth triangles</linkto>--->[[Documentation:Reference Section 4.2#Triangle and Smooth Triangle|smooth triangles]], <!--<linkto "ttf">text</linkto>--->[[Documentation:Reference Section 4.1#Text|text]], <!--<linkto "superquadric">superquadrics</linkto>--->[[Documentation:Reference Section 4.1#Superquadric Ellipsoid|superquadrics]],
+
    <li><!--<linkto "polygon">polygons</linkto>--->[[Reference:Polygon|polygons]]</li>
  <!--<linkto "sor">surfaces of revolution</linkto>--->[[Documentation:Reference Section 4.1#Surface of Revolution|surfaces of revolution]], <!--<linkto "prism">prisms</linkto>--->[[Documentation:Reference Section 4#Prism|prisms]], <!--<linkto "polygon">polygons</linkto>--->[[Documentation:Reference Section 4.2#Polygon|polygons]],
+
    <li><!--<linkto "lathe">lathes</linkto>--->[[Reference:Lathe|lathes]]</li>
  <!--<linkto "lathe">lathes</linkto>--->[[Documentation:Reference Section 4#Lathe|lathes]], <!--<linkto "fractal">fractals</linkto>--->[[Documentation:Reference Section 4#Julia Fractal|fractals]], <!--<linkto "isosurface">isosurfaces</linkto>--->[[Documentation:Reference Section 4#Isosurface|isosurfaces]] and the <!--<linkto "parametric">parametric</linkto>--->[[Documentation:Reference Section 4#Parametric|parametric]] object.</li>
+
    <li><!--<linkto "fractal">fractals</linkto>--->[[Reference:Julia Fractal|fractals]]</li>
 
+
    <li><!--<linkto "isosurface">isosurfaces</linkto>--->[[Reference:Isosurface|isosurfaces]]</li>
   <li>Shapes can easily be combined to create new complex shapes using
+
    <li><!--<linkto "parametric">parametric</linkto>--->[[Reference:Parametric|parametric]]</li></ul>
  <!--<linkto "Constructive Solid Geometry">Constructive Solid Geometry</linkto>--->[[Documentation:Reference Section 4.3#Constructive Solid Geometry|Constructive Solid Geometry]] (CSG). POV-Ray supports unions, merges,
+
   <li>Shapes can easily be combined to create new complex shapes using <!--<linkto "Constructive Solid Geometry">Constructive Solid Geometry</linkto>--->[[Reference:Constructive Solid Geometry|Constructive Solid Geometry]].</li>
  intersections and differences.</li>
+
    <li>POV-Ray supports [[Reference:Union|unions]], [[Reference:Merge|merges]], [[Reference:Intersection|intersections]] and [[Reference:Difference|differences]].</li>
 
+
   <li>Objects are assigned materials called <!--<linkto "texture">textures</linkto>--->[[Reference:Texture|textures]] and interior properties such as <!--<linkto "ior">index of refraction</linkto>--->[[Reference:Interior#Refraction|index of refraction]] and <!--<linkto "media">particle media</linkto>--->[[Reference:Media|particle media]].</li>
   <li>Objects are assigned materials called <!--<linkto "texture">textures</linkto>--->[[Documentation:Reference Section 5#Textures|textures]] (a texture describes the
+
   <li>Built-in color and normal patterns:</li>
  coloring and surface properties of a shape) and interior properties such as
+
  <ul><li><!--<linkto "Agate">Agate</linkto>--->[[Reference:Agate Pattern|Agate]]</li>
  <!--<linkto "ior">index of refraction</linkto>--->[[Documentation:Reference Section 6#Refraction|index of refraction]] and <!--<linkto "media">particle media</linkto>--->[[Documentation:Reference Section 6.1#Media|particle media]] (formerly known as
+
  <li><!--<linkto "Bozo">Bozo</linkto>--->[[Reference:Bozo Pattern|Bozo]]</li>
  &quot;halos&quot;).</li>
+
  <li><!--<linkto "Bumps">Bumps</linkto>--->[[Reference:Bumps Pattern|Bumps]]</li>
 
+
  <li><!--<linkto "Checker">Checker</linkto>--->[[Reference:Checker Pattern|Checker]]</li>
   <li>Built-in color and normal patterns: <!--<linkto "Agate">Agate</linkto>--->[[Documentation:Reference Section 5.3#Agate|Agate]], <!--<linkto "Bozo">Bozo</linkto>--->[[Documentation:Reference Section 5.3#Bozo|Bozo]], <!--<linkto "Bumps">Bumps</linkto>--->[[Documentation:Reference Section 5.3#Bumps|Bumps]], <!--<linkto "Checker">Checker</linkto>--->[[Documentation:Reference Section 5.3#Checker|Checker]], <!--<linkto "Crackle">Crackle</linkto>--->[[Documentation:Reference Section 5.3#Crackle Patterns|Crackle]], <!--<linkto "Dents">Dents</linkto>--->[[Documentation:Reference Section 5.3#Dents|Dents]], <!--<linkto "Granite">Granite</linkto>--->[[Documentation:Reference Section 5.4#Granite|Granite]],
+
  <li><!--<linkto "Crackle">Crackle</linkto>--->[[Reference:Crackle Pattern|Crackle]]</li>
   <!--<linkto "Gradient">Gradient</linkto>--->[[Documentation:Reference Section 5.4#Gradient|Gradient]], <!--<linkto "Hexagon">Hexagon</linkto>--->[[Documentation:Reference Section 5.4#Hexagon|Hexagon]], <!--<linkto "Leopard">Leopard</linkto>--->[[Documentation:Reference Section 5.4#Leopard|Leopard]], <!--<linkto "Mandel">Mandel</linkto>--->[[Documentation:Reference Section 5.4#Fractal Patterns|Mandel]],
+
  <li><!--<linkto "Dents">Dents</linkto>--->[[Reference:Dents Pattern|Dents]]</li>
   <!--<linkto "Marble">Marble</linkto>--->[[Documentation:Reference Section 5.4#Marble|Marble]], <!--<linkto "Onion">Onion</linkto>--->[[Documentation:Reference Section 5.4#Onion|Onion]], <!--<linkto "Quilted">Quilted</linkto>--->[[Documentation:Reference Section 5.5#Quilted|Quilted]], <!--<linkto "Ripples">Ripples</linkto>--->[[Documentation:Reference Section 5.5#Ripples|Ripples]],
+
  <li><!--<linkto "function">functions</linkto>--->[[Reference:Function Pattern|Functions]]</li>
  <!--<linkto "Spotted">Spotted</linkto>--->[[Documentation:Reference Section 5.5#Spotted|Spotted]], <!--<linkto "Spiral">Spiral</linkto>--->[[Documentation:Reference Section 5.5#Spiral1|Spiral]], <!--<linkto "Radial">Radial</linkto>--->[[Documentation:Reference Section 5.5#Radial|Radial]], <!--<linkto "Waves">Waves</linkto>--->[[Documentation:Reference Section 5.5#Waves|Waves]],
+
   <li><!--<linkto "Granite">Granite</linkto>--->[[Reference:Granite Pattern|Granite]]</li>
   <!--<linkto "Wood">Wood</linkto>--->[[Documentation:Reference Section 5.5#Wood|Wood]], <!--<linkto "Wrinkles">Wrinkles</linkto>--->[[Documentation:Reference Section 5.5#Wrinkles|Wrinkles]] and <!--<linkto "image_map">image file mapping</linkto>--->[[Documentation:Reference Section 5#Image Maps|image file mapping]]. Or build your own pattern using <!--<linkto "function">functions</linkto>--->[[Documentation:Reference Section 2.2#User-Defined Functions|functions]].</li>
+
  <li><!--<linkto "Gradient">Gradient</linkto>--->[[Reference:Gradient Pattern|Gradient]]</li>
 
+
  <li><!--<linkto "Hexagon">Hexagon</linkto>--->[[Reference:Hexagon Pattern|Hexagon]]</li>
   <li>Users can create their own textures or use pre-defined textures such as
+
  <li><!--<linkto "image_map">image file mapping</linkto>--->[[Reference:Image Pattern|Image]]</li>
  ... Brass, Chrome, Copper, Gold, Silver, Stone, Wood.</li>
+
   <li><!--<linkto "Leopard">Leopard</linkto>--->[[Reference:Leopard Pattern|Leopard]]</li>
 
+
  <li><!--<linkto "Mandel">Mandel</linkto>--->[[Reference:Fractal Pattern|Mandel]]</li>
   <li>Combine textures using layering of semi-transparent textures or tiles of
+
  <li><!--<linkto "Marble">Marble</linkto>--->[[Reference:Marble Pattern|Marble]]</li>
  textures or material map files.</li>
+
  <li><!--<linkto "Onion">Onion</linkto>--->[[Reference:Onion Pattern|Onion]]</li>
 
+
  <li><!--<linkto "Quilted">Quilted</linkto>--->[[Reference:Quilted Pattern|Quilted]]</li>
   <li>Display preview of image while rendering (not available on all
+
  <li><!--<linkto "Ripples">Ripples</linkto>--->[[Reference:Ripples Pattern|Ripples]]</li>
  platforms).</li>
+
  <li><!--<linkto "Spotted">Spotted</linkto>--->[[Reference:Spotted Pattern|Spotted]]</li>
 
+
  <li><!--<linkto "Spiral">Spiral</linkto>--->[[Reference:Spiral1 Pattern|Spiral]]</li>
   <li>Halt and save a render part way through, and continue rendering the
+
   <li><!--<linkto "Radial">Radial</linkto>--->[[Reference:Radial Pattern|Radial]]</li>
  halted partial render later.</li>
+
  <li><!--<linkto "Waves">Waves</linkto>--->[[Reference:Waves Pattern|Waves]]</li>
 +
  <li><!--<linkto "Wood">Wood</linkto>--->[[Reference:Wood Pattern|Wood]]</li>
 +
  <li><!--<linkto "Wrinkles">Wrinkles</linkto>--->[[Reference:Wrinkles Pattern|Wrinkles]]</li></ul>
 +
   <li>Users can create their own textures or use the pre-defined ones included with the distribution.</li>
 +
   <li>Combine textures using layering of semi-transparent textures or tiles of textures or material map files.</li>
 +
   <li>Display preview of image while rendering (on supported platforms).</li>
 +
   <li>Halt and save a render part way through, and continue rendering the halted partial render later.</li>
 
   </ul>
 
   </ul>
  
 
====Changes and New Features Summary====
 
====Changes and New Features Summary====
<p>This section covers version 3.7 <em>Changes</em> and <em>New Features</em> that apply no matter what platform you are using. Changes and information pertaining to your particular installation are covered in the platform specific documentation that's included with the distribution.</p>
+
<p>The following sections cover changes and new features that apply no matter what platform you are using. Changes and information pertaining to your particular installation are covered in the platform specific documentation that's included with the distribution.</p>
<p>The categorized list below outlines the additions, changes and improvements along with links (when appropriate) to their relevant passages in the <em>Reference Section</em>.</p>
+
<p>The categorized lists below outline the additions, changes and improvements along with links (when appropriate) to their relevant passages in the <em>Reference Section</em>.</p>
<p><strong>Look Here First</strong></p>
+
=====Version 3.8=====
<p>These items <em>definitely</em> deserve your attention, because some of them represent key changes or enhancements to the way POV-Ray operates or behaves.</p>
+
<p>These changes (in no particular order) pertain to the version 3.8 release.</p>
 +
<p><strong>General Changes</strong></p>
 +
<ol>
 +
  <li>For clarity and ease of maintenance, several new annotations now appear in the documentation. See: [[Reference:Notation and Basic Assumptions|Notation and Basic Assumptions]]</li>
 +
  <li>Bug tracking is now handled by the [https://github.com/POV-Ray/povray/issues issue tracker] on GitHub</li>
 +
  <li>Animation status messages now include the nominal frame number</li>
 +
</ol>
 +
<p><strong>Language Basics and Directives</strong></p>
 +
<ol>
 +
  <li>Important behavior changes concerning the: [[Reference:Version Directive|Version Directive]]</li>
 +
  <li>[[Reference:Identifiers|Identifiers]] are no longer limited to just 40 characters in length since version 3.6.2</li>
 +
  <li>Support for <code>tau</code> as a [[Reference:Numeric Expressions#Built-in Constants|Built-in Constant]] has been added</li>
 +
  <li>The <code>macro</code> directive has been extended. See [[Reference:User Defined Macros#Optional Parameters|Optional Parameters]] for details</li>
 +
  <li>A <em>cached macro</em> mechanism has been implemented. See: [[Reference:User Defined Macros#Macro Caching|Macro Caching]] for more information</li>
 +
  <li>Arrays now allow the creation of <code>dictionary</code> container types and <code>mixed</code> type elements. See: [[Reference:Array|Array]] </li>
 +
  <li>The addition of a <code>[[Reference:General Output Options#Resuming Options|Create_Continue_Trace_Log]]</code> option allows for greater resource control</li>
 +
  <li>The [[Reference:Declare and Local Directives|Declare and Local Directives]] have been extended to support <em>tuple-style</em> assignments</li>
 +
  <li>All instances of <code>gray</code> in keywords or INI file options can now alternatively be spelled <code>grey</code></li>
 +
  <li>Trailing white-space in INI files no longer causes a warning</li>
 +
  <li>The <code>version</code> pseudo-variable will now evaluate to the effective language version at the time the expression is parsed. See: [[Reference:Numeric Expressions#Built-in Variables|Built-in Variables]] and [[Reference:Version Directive|Version Directive]]</li>
 +
</ol>
 +
<p><strong>Patterns Pigments and Textures</strong></p>
 +
<ol>
 +
  <li>The default setting for <code>[[Reference:Finish#Ambient|ambient]]</code> has changed</li>
 +
  <li>A <code>repeat</code> option has been added to [[Reference:Crackle Pattern|Crackle Pattern]]</li>
 +
  <li>The map entry upper limit restriction for [[Reference:Color Map|Color Maps]] and [[Reference:Pigment Map|Pigment Maps]] has been removed</li>
 +
  <li>UV mapping [[Reference:UV Mapping#Supported Objects|support]] for the <code>cone</code>, <code>cylinder</code> and <code>lemon</code> was added and <code>ovus</code> mapping has been improved</li>
 +
  <li>A new finish parameter <code>[[Reference:Finish|use_alpha]]</code> has been added to suppress highlights and reflections depending on pigment transparency</li>
 +
  <li>Implemented a non-linear interpolation scheme for [[Reference:Color Map|Color Maps]] and [[Reference:Pigment Map|Pigment Maps]]</li>
 +
  <li>A new special pigment pattern <code>[[Reference:User Defined Pattern|user_defined]]</code> has been added to define the pigment color directly in terms of a set of functions</li>
 +
  <li>A new pattern <code>[[Reference:Potential Pattern|potential]]</code> has been added to aid in creating a pattern based on the <em>potential</em> field of a <code>blob</code> or <code>isosurface</code> object</li>
 +
  <li>[[Reference:Finish|Fresnel]] angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism</li>
 +
  <li>Radiosity now honors the <code>brilliance</code> setting of a surface</li>
 +
  <li>CIELAB  [[Reference:Colors.inc#Color macros|conversion macros]] have been added to <code>colors.inc</code></li>
 +
  <li>RAL Classic standard [[Reference:Colors ral.inc|predefined colors]] are now available</li>
 +
</ol>
 +
<p><strong>Images and Image Related</strong></p>
 +
<ol>
 +
  <li>A new [[Reference:Tracing Options#Anti-Aliasing Options|anti-aliasing]] method has been implemented.</li>
 +
  <li>Several changes to grayscale file output handling. See: [[Reference:File Output Options#Output File Type|Output File Type]]</li>
 +
  <li>A few changes and several additions to [[Reference:File Output Options#Output File Dithering|output file dithering]]</li>
 +
  <li>The default <code>up</code> and <code>right</code> vectors have changed. See: [[Reference:Camera#Aspect Ratio|Aspect Ratio]]</li>
 +
  <li>The <code>max_extent</code> [[Reference:Vector Expressions#Functions|function]] has been extended</li>
 +
  <li>Two gamma handling specifications have been added for:</li>
 +
    <ol type="a">
 +
      <li>the [[Reference:Display Output Options#Display Hardware Settings|display]] settings</li>
 +
      <li>the [[Reference:File Output Options#Output File Gamma|output]] file</li>
 +
      <li>image map [[Reference:Image Map#The Gamma Option|input]] file</li>
 +
      <li>image pattern [[Reference:Image Pattern|input]] file</li>
 +
      <li>height field [[Reference:Height Field|input]] file</li>
 +
      <li>bump map [[Reference:Bump Map#Specifying a Bump Map|input]] file</li>
 +
    </ol>
 +
  <li>The <code>[[Reference:Bitmap Modifiers#The map_type Option|map_type]]</code> keyword now supports the <em>angular map projection</em> for use with light probes</li>
 +
  <li>Default [[Reference:File Output Options#Output File Gamma|gamma handling]] of <em>NetPBM</em> (PPM/PGM) output files now complies with the official <em>NetBPM</em> standard</li>
 +
  <li>The <em>compression</em> setting now affects more file types. See: [[Reference:File Output Options#Output File Type|Output File Type]]</li>
 +
  <li>The [[Reference:Image Map|interaction]] of <code>transmit all</code> and <code>filter all</code> with an image's alpha channel has been changed</li>
 +
</ol>
 +
<p><strong>Objects and Object Related</strong></p>
 +
<ol>
 +
  <li>The <code>[[Reference:Lemon|lemon]]</code> object was added</li>
 +
  <li>The <code>[[Reference:Ovus|ovus]]</code> object has been extended and [[Reference:UV Mapping#Supported Objects|uv mapping]] has been improved</li>
 +
  <li>Support for a <em>spindle</em> <code>[[Reference:Torus|torus]]</code> was added</li>
 +
  <li>The number of components per <code>[[Reference:Blob|blob]]</code> is no longer artificially limited</li>
 +
  <li>A <code>[[Reference:Camera#User defined projection|user_defined]]</code> camera type was added</li>
 +
  <li>A new [[Reference:Light Source#Light Fading|Light Fading]] model has been added</li>
 +
</ol>
 +
 
 +
=====Version 3.7=====
 +
<p>These version 3.7 items <em>definitely</em> deserve your attention, because some of them represent key changes or enhancements to the way POV-Ray operates or behaves.</p>
 
<p>
 
<p>
 
<ol>
 
<ol>
<li>POV-Ray now supports [[Documentation:Reference Section 1.3#Symmetric MultiProcessing|Symmetric MultiProcessing]].</li>
+
<li>POV-Ray now supports [[Reference:Tracing Options#Symmetric MultiProcessing|Symmetric MultiProcessing]].</li>
<li>The addition of the <code>[[Documentation:Reference Section 3#Mesh projection|mesh_camera]]</code> makes texture baking possible.</li>
+
<li>The addition of the <code>[[Reference:Camera#Mesh projection|mesh_camera]]</code> permits simulation of arbitrary lenses and makes texture baking possible.</li>
<li>An <em>experimental</em> [[Documentation:Tutorial Section 3.3#Gamma Handling|gamma handling]] feature has been added, some of the highlights are:</li>
+
<li>An elaborate [[Documentation:Tutorial Section 3.3#Gamma Handling|gamma handling]] feature has been added, some of the highlights are:</li>
 
<ol TYPE=a>
 
<ol TYPE=a>
<li>a different role for <code>[[Documentation:Reference Section 3.1#Assumed_Gamma|assumed_gamma]]</code></li>
+
<li>mandatory <code>[[Reference:Global Settings#Assumed_Gamma|assumed_gamma]]</code></li>
<li>changes in the <code>[[Documentation:Reference Section 3.1#Global Settings|global_settings]]</code> section</li>
+
<li>the <code>[[Reference:Color Expressions#sRGB Colors|srgb]]</code> keyword and its kin can be used to specify gamma pre-corrected colors</li>
<li>the <code>[[Documentation:Reference Section 2.1#Specifying Colors|srgb]]</code> keyword and its kin can be used to specify gamma pre-corrected colors</li>
+
<li>a <code>[[Reference:File Output Options#Output File Gamma|File_Gamma]]</code> feature has been added</li>
<li>an <code>[[Documentation:Reference Section 1.3#Anti-Aliasing Options|Antialias_Gamma]]</code> feature has been added</li>
+
<li>an <code>[[Reference:Tracing Options#Anti-Aliasing Options|Antialias_Gamma]]</code> feature has been added</li>
<li>lastly you can also change the input file <code>[[Documentation:Reference Section 5#The Gamma Option|gamma]]</code> for individual input files</li>
+
<li>lastly you can also change the input file <code>[[Reference:Image Map#The Gamma Option|gamma]]</code> for individual input files</li>
 
</ol>
 
</ol>
 
<li>Make sure to review the <em>Images and Image Related</em> category below for <em>important</em> changes and additions.</li>
 
<li>Make sure to review the <em>Images and Image Related</em> category below for <em>important</em> changes and additions.</li>
<li>Redistribute the workload to render threads by specifying a [[Documentation:Reference Section 1.3#Render Block Size|render block size]].</li>
+
<li>Redistribute the workload to render threads by specifying a [[Reference:Tracing Options#Render Block Size|render block size]].</li>
<li>Binary Space Partitioning or [[Documentation:Reference Section 1.3#BSP Bounding|BSP]] tree bounding is now available.</li>
+
<li>Binary Space Partitioning or [[Reference:Tracing Options#BSP Bounding|BSP]] tree bounding is now available.</li>
<li>A resource control [[Documentation:Reference Section 1#Max Image Buffer Memory|option]] for output image caching has been added.</li>  
+
<li>A resource control [[Reference:General Output Options#Max Image Buffer Memory|option]] for output image caching has been added.</li>  
<li>An overall review of the <em>entire</em> [[Documentation:Reference Section 3.2#Radiosity|radiosity]] section is probably a good idea some of the highlights are:</li>
+
<li>An overall review of the <em>entire</em> [[Reference:Radiosity|radiosity]] section is probably a good idea; some of the highlights are:</li>
 
<ol TYPE=a>
 
<ol TYPE=a>
<li>see the revised [[Documentation:Tutorial Section 3.7#Radiosity|radiosity]] tutorial</li>
+
<li>a revised [[Documentation:Tutorial Section 3.7#Radiosity|radiosity]] tutorial</li>
<li>the <em>new</em> <code>[[Documentation:Reference Section 3.2#maximum_reuse|maximum_reuse]]</code> parameter</li>
+
<li>the <em>new</em> <code>[[Reference:Radiosity#maximum_reuse|maximum_reuse]]</code> parameter</li>
<li>also of interest the adaptive pretrace mode added to the <code> [[Documentation:Reference Section 3.2#nearest_count|nearest_count]]</code> parameter</li>
+
<li>adaptive pretrace mode added to the <code> [[Reference:Radiosity#nearest_count|nearest_count]]</code> parameter</li>
<li>the [[Documentation:Reference Section 3.2#Save and Load Radiosity Data|loading and saving]] of radiosity data has changed</li>
+
<li>the [[Reference:Tracing Options#Radiosity Load and Save|loading and saving]] of radiosity data has changed</li>
<li>these command line [[Documentation:Reference Section 1.3#Radiosity Options|options]] can help to further customize radiosity features</li>
+
<li>new command line [[Reference:Tracing Options#Radiosity Options|options]] can help to further customize radiosity features</li>
 
</ol>
 
</ol>
<li>The [[Documentation:Reference Section 4#Ovus|ovus]] object was added, along with support for <code>[[Documentation:Reference Section 5.2#Supported Objects|uv_mapping]]</code></li>
+
<li>The [[Reference:Ovus|ovus]] object was added, along with support for <code>[[Reference:UV Mapping|uv_mapping]]</code></li>
<li>Raised max order of the <code>[[Documentation:Reference Section 4.2#Poly, Cubic and Quartic|poly]]</code> object,  alternate syntax is also available.</li>
+
<li>Raised max order of the <code>[[Reference:Poly|poly]]</code>, <code>[[Reference:Cubic|cubic]]</code> and <code>[[Reference:Quartic|quartic]]</code> objects. Alternate syntax is also available.</li>
<li>Added multiple-thread support to [[Documentation:Reference Section 6.2#Photons and Light Sources|photon]] shooting code.</li>
+
<li>Added multiple-thread support to [[Reference:Photons#Photons and Light Sources|photon]] shooting code.</li>
<li>A <em>provisional</em> [[Documentation:Reference Section 1#Real-Time Raytracing|Real-Time Raytracing]] feature was added, some restrictions apply!</li>
+
<li>New thread-safe random number generator was added; this can cause slight differences in the render output.</li>
<li>New thread-safe random number generator was added.</li>
+
<li>The <em>buit-in</em> benchmark process now runs without any other distribution files. See the platform specific documentation for details.</li>
 +
<li>The <code>Draw_Vistas</code>, <code>Vista_Buffer</code> and <code>Light_Buffer</code> options have been deprecated. Look [[Reference:Display Output Options#Display Related Settings|here]] for additional details.
 
</ol>
 
</ol>
 
</p>
 
</p>
Line 239: Line 319:
 
<p>  
 
<p>  
 
<ol>
 
<ol>
<li>Added <code>[[Documentation:Reference Section 5.1#Diffuse|diffuse]]</code> backside illumination capability.</li>
+
<li>Added <code>[[Reference:Finish#Diffuse|diffuse]]</code> backside illumination capability.</li>
<li>An <em>experimental</em> [[Documentation:Reference Section 5.1#Subsurface Light Transport|subsurface scattering]] feature was added.</li>
+
<li>An <em>experimental</em> [[Reference:Finish#Subsurface Light Transport|subsurface scattering]] feature was added.</li>
<li>Support for <code>[[Documentation:Reference Section 4.4#Area Lights|area_light]]</code> diffuse and specular illumination was implemented.</li>
+
<li>Support for <code>[[Reference:Light Source#Area Lights|area_light]]</code> diffuse and specular illumination was implemented.</li>
 
<li>These list patterns, a warp, and a slope pattern extensions were added:</li>
 
<li>These list patterns, a warp, and a slope pattern extensions were added:</li>
 
<ol TYPE=a>
 
<ol TYPE=a>
<li><code>[[Documentation:Reference Section 5.3#Aoi|aoi]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Aoi Pattern|aoi]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.3#Cubic|cubic]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Cubic Pattern|cubic]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.6#Mapping using warps|cubic]]</code> <em>warp</em></li>
+
<li><code>[[Reference:Warp#Mapping using warps|cubic]]</code> <em>warp</em></li>
<li><code>[[Documentation:Reference Section 5.4#Pavement|pavement]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Pavement Pattern|pavement]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.5#Square|square]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Square Pattern|square]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.5#Tiling|tiling]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Tiling Pattern|tiling]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.5#Triangular|triangular]]</code> <em>pattern</em></li>
+
<li><code>[[Reference:Triangular Pattern|triangular]]</code> <em>pattern</em></li>
<li><code>[[Documentation:Reference Section 5.5#Slope|slope]]</code> <em>pattern extension</em></li>
+
<li><code>[[Reference:Slope Pattern|slope]]</code> <em>pattern extension</em></li>
 
</ol>
 
</ol>
<li>Improvements to <code>iterations</code> and two new <code>exterior</code> types were added. See [[Documentation:Reference Section 5.4#Fractal Patterns|Fractal Patterns]] for more details.</li>
+
<li>Improvements to <code>iterations</code> and two new <code>exterior</code> types were added. See [[Reference:Fractal Pattern|Fractal Patterns]] for more details.</li>
<li>The finish block now supports the <code>[[Documentation:Reference Section 5.1#Emission|emission]]</code> keyword.</li>
+
<li>The finish block now supports the <code>[[Reference:Finish#Emission|emission]]</code> keyword.</li>
<li>A <code>[[Documentation:Reference Section 3.1#Sky Sphere|sky_sphere]]</code> layered pigment related behavior change.</li>
+
<li>A <code>[[Reference:Sky Sphere|sky_sphere]]</code> layered pigment related behavior change.</li>
 
<li>A new [[Documentation:Tutorial Section 3.3#Slope Map Tutorial|Slope Map Tutorial]] has been added.</li>
 
<li>A new [[Documentation:Tutorial Section 3.3#Slope Map Tutorial|Slope Map Tutorial]] has been added.</li>
 +
<li>Re-enabled the [[Reference:Finish#Crand Graininess|crand]] <code>finish</code> attribute.</li>
 
</ol>
 
</ol>
 
</p>
 
</p>
Line 264: Line 345:
 
<ol>
 
<ol>
 
<li>Get your display gamma correct! See the new <code>[[Documentation:Tutorial Section 3.3#Gamma Handling|gamma handling]]</code> tutorial.</li>
 
<li>Get your display gamma correct! See the new <code>[[Documentation:Tutorial Section 3.3#Gamma Handling|gamma handling]]</code> tutorial.</li>
<li>There have been various changes regarding [[Documentation:Reference Section 1.1#Output File Type|output file types]] these are the highlights:</li>
+
<li>There have been various changes regarding [[Reference:File Output Options#Output File Type|output file types]] these are the highlights:</li>
 
<ol TYPE="a">
 
<ol TYPE="a">
 
<li>cross platform default output file type is PNG</li>
 
<li>cross platform default output file type is PNG</li>
Line 271: Line 352:
 
<li>output file type &quot;s&quot; has been deprecated</li>
 
<li>output file type &quot;s&quot; has been deprecated</li>
 
</ol>
 
</ol>
<li>An output file [[Documentation:Reference Section 1.1#Output File Dithering|dithering]] feature has been added.</li>
+
<li>An output file [[Reference:File Output Options#Output File Dithering|dithering]] feature has been added.</li>
<li>The <code>[[Documentation:Reference Section 5.6#The interpolate Option|interpolate]]</code> option now supports bicubic interpolation.</li>
+
<li>The <code>[[Reference:Bitmap Modifiers#The interpolate Option|interpolate]]</code> option now supports bicubic interpolation.</li>
<li>Use of the <code>[[Documentation:Reference Section 3.1#HF_Gray_16|hf_gray_16]]</code> keyword has been deprecated in the <code>global_settings</code> block.</li>
+
<li>Use of the <code>[[Reference:Global Settings#HF_Gray_16|hf_gray_16]]</code> keyword has been deprecated in the <code>global_settings</code> block.</li>
<li>A couple of <em>important</em> changes and additions regarding [[Documentation:Reference Section 5#Using the Alpha Channel|Alpha Channel]] usage.   
+
<li>A couple of <em>important</em> changes and additions regarding [[Reference:Image Map#Using the Alpha Channel|Alpha Channel]] usage.   
 
<li>Added &quot;out-of-the-box&quot; transparency support for GIF input files.</li>
 
<li>Added &quot;out-of-the-box&quot; transparency support for GIF input files.</li>
 
</ol>
 
</ol>
Line 282: Line 363:
 
<p>
 
<p>
 
<ol>
 
<ol>
<li>Now you can declare an identifier as <code>[[Documentation:Reference Section 2.4#Deprecation Support|deprecated]]</code>.</li>
+
<li>Now you can declare an identifier as <code>[[Reference:Declare and Local Directives#Deprecation Support|deprecated]]</code>.</li>
<li>Several <em>bitwise</em> [[Documentation:Reference Section 2#Functions|functions]] were added.</li>
+
<li>Several <em>bitwise</em> [[Reference:Vector Expressions#Functions|functions]] were added.</li>
<li>A string  function <code>[[Documentation:Reference Section 2.3#String Functions|datetime()]]</code> has also been added.</li>
+
<li>A string  function <code>[[Reference:Strings#String Functions|datetime()]]</code> has also been added.</li>
<li>Added a new pre-declared variable <code>[[Documentation:Reference Section 2.3#Built-in Variables|input_file_name]]</code>.</li>
+
<li>Added a new pre-declared variable <code>[[Reference:Strings#Built-in Variables|input_file_name]]</code>.</li>
<li>New [[Documentation:Reference Section 2.3#String Relational Operators|string relational operators]] have been added.</li>
+
<li>New [[Reference:Strings#String Relational Operators|string relational operators]] have been added.</li>
<li>Added binary <code>[[Documentation:Reference Section 2.5#The #write Directive|#write]]</code> capability, see the <code>[[Documentation:Reference Section 7#arrays.inc|ARRAYS_WriteDF3]]</code> macro for usage.</li>
+
<li>Added binary <code>[[Reference:File I/O Directives#The write Directive|#write]]</code> capability, see the <code>[[Reference:Arrays.inc|ARRAYS_WriteDF3]]</code> macro for usage.</li>
<li>The <code>[[Documentation:Reference Section 2.5#The #switch, #case, #range and #break Directives|#break]]</code> directive behavior has changed.</li>
+
<li>The <code>[[Reference:Conditional Directives#The switch, case, range and break Directives|#break]]</code> directive behavior has changed.</li>
<li>An <code>atand</code> function has been added to the [[Documentation:Reference Section 7.2#math.inc|math.inc]] file.</li>
+
<li>An <code>atand</code> function has been added to the [[Reference:Math.inc|math.inc]] file.</li>
<li>The <code>[[Documentation:Reference Section 2.1#Functions|max_extent]]</code> function can now return the pixel resolution of an image map.</li>
+
<li>The <code>[[Reference:Vector Expressions#Functions|max_extent]]</code> function can now return the pixel resolution of an image map.</li>
<li>A new <code>[[Documentation:Reference Section 2.5#The #version Directive|#version]]</code> directive requirement has been added.</li>
+
<li>A new <code>[[Reference:Version Directive|#version]]</code> directive requirement has been added.</li>
<li>The <code>#if</code> directive now supports an <code>[[Documentation:Reference Section 2.5#The #if...#else...#end Directives|#elseif]]</code> clause.</li>
+
<li>The <code>#if</code> directive now supports an <code>[[Reference:Conditional Directives#The if...else...end Directives|#elseif]]</code> clause.</li>
<li>A new <code>[[Documentation:Reference Section 2.5#The #for Directive|#for]]</code> loop directive has been added.</li>
+
<li>A new <code>[[Reference:Conditional Directives#The for Directive|#for]]</code> loop directive has been added.</li>
<li>The [[Documentation:Reference Section 1.1#CPU Utilization Histogram|CPU Utilization Histogram]] feature has been deprecated.</li>
+
<li>The [[Reference:File Output Options#CPU Utilization Histogram|CPU Utilization Histogram]] feature has been deprecated.</li>
 +
<li>Added a <code>+GP</code> option. See the section: [[Reference:Text Output Options#Directing Text Streams to Files|Directing Text Streams to Files]] for more information.</li>
 
</ol>
 
</ol>
 +
</p>
 +
 +
===Trademarks===
 +
<p>
 +
The terms 'POV-Ray', 'Persistence of Vision Ray Tracer', and 'POV-Team'
 +
are trademarks of Persistence of Vision Raytracer Pty. Ltd. All other trademarks are acknowledged
 +
as being the property of their respective owners.
 
</p>
 
</p>
  
 
===The Early History of POV-Ray===
 
===The Early History of POV-Ray===
<p>OK, here's a not-so brief history of POV-Ray (from the horse's mouth, so to speak):</p>
+
<p>Here's how POV-Ray came to be, as described by David Buck:</p>
  
 
<p>Back in 1986 or so, I had an Amiga.  A friend who also has an Amiga downloaded the C code for
 
<p>Back in 1986 or so, I had an Amiga.  A friend who also has an Amiga downloaded the C code for

Latest revision as of 20:53, 2 July 2021

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.


Introduction

This document provides a tutorial for the Persistence of Vision Ray-Tracer™ (POV-Ray). The documentation applies to all platforms to which this version of POV-Ray is ported. The platform-specific documentation is available for each platform separately.

The tutorial is divided into five main parts:

  1. This introduction which explains what POV-Ray is and what ray-tracing is. It gives a brief overview of how to create ray-traced images.
  2. A Beginning Tutorial which explains step by step how to use the different features of POV-Ray.
  3. An Advanced Tutorial which contains more advanced tutorial topics.
  4. POV-Ray questions and tips gives answers to many frequently-asked questions about POV-Ray.
  5. In the Appendices you will find some tips and hints, where to get the latest version and versions for other platforms, the POV-Ray licence, information on compiling custom versions of POV-Ray, suggested reading, contact addresses and legal information.

The current release of POV-Ray runs on 32 and 64-bit versions of Microsoft Windows from XP through Windows 8, Mac OS X, Linux/UNIX, and numerous other platforms (when compiled from source).

If you do not yet have POV-Ray installed or are not sure you have the official version or the latest version, see appendix What to do if you don't have POV-Ray.

This book covers only the generic parts of the program which are common to each version.

Note: Each version has platform-specific documentation not included in this section.

We recommend you finish reading this introductory section then read the platform-specific information before reading the rest of the tutorial. The platform-specific docs will show you how to render a sample scene and will give you detailed descriptions of the platform-specific features.

The Windows version documentation is available on the POV-Ray program's Help menu or by pressing the F1 key while in the program.

The Unix / Linux version documentation can be found at the same place as the platform independent part. Usually that is /usr/local/share/povray-3.?

Program Description

The Persistence of Vision Ray-Tracer creates three-dimensional, photo-realistic images using a rendering technique called ray-tracing. It reads in a text file containing information describing the objects and lighting in a scene and generates an image of that scene from the view point of a camera also described in the text file. Ray-tracing is not a fast process by any means, but it produces very high quality images with realistic reflections, shading, perspective and other effects.

What is Ray-Tracing?

Ray-tracing is a rendering technique that calculates an image of a scene by simulating the way rays of light travel in the real world. However it does this simulation backwards; in the real world, rays of light are emitted from a light source and then strike objects. Some of the light rays then bounce off the objects and enter our eyes (or perhaps a camera). However, most of the rays never reach anything that 'observes' them; they either leave the area of interest or are absorbed by objects within it.

Because the vast majority of rays never reach an observer, it would take a very long time for software to trace even a simple image if the rays were cast as they were in the real world (because almost all of the calculations would end up going to waste). For the purposes of drawing a representation of a scene as viewed from an imaginary camera, we are generally only interested in rays that reach that camera's lens.

A 'scene' is the virtual world which you wish to take a 'picture' of with our simulated camera. There can be (and usually are) objects in the scene that do not appear in the final image, just as objects outside the field of view of a real camera do not directly appear in the final image. (They can still cast shadows or be seen as reflections, though).

Accordingly, ray-tracing programs like POV-Ray start with their simulated camera and trace rays backwards out into the scene. The user specifies the location of the camera and the type of lens it is using, the light sources that illuminate the scene, the objects within it, as well as the surface texture properties of objects, their interiors (if transparent) and any atmospheric media such as fog, haze, or fire.

For every pixel in the final image one or more viewing rays are shot from the camera into the scene to see if it intersects with any of the objects in the scene. These "viewing rays" originate from the viewer (represented by the camera), and pass through the viewing window (representing the pixels of the final image).

Every time an object is hit, the color of the surface at that point is calculated. For this purpose rays are sent from that point to each light source to determine the amount of light coming from that source. These "shadow rays" are tested to tell whether the surface point lies in shadow or not. If the surface is reflective or transparent new rays are set up and traced in order to determine the contribution of the reflected and refracted light to the final surface color.

Special features like inter-diffuse reflection (radiosity), atmospheric effects and area lights make it necessary to shoot a lot of additional rays into the scene for every pixel.

What is POV-Ray?

POV-Ray™ is short for the Persistence of Vision Raytracer™, a tool for producing high-quality computer graphics. POV-Ray is Free Software (as per the definition of the Free Software Foundation) as its source code is licensed under the Affero General Public License (AGPL).

POV-Ray was developed from DKBTrace 2.12 (written by David K. Buck and Aaron A. Collins) by a bunch of people (called the POV-Team™) in their spare time. The headquarters of the POV-Team is on the internet (see Where to Find POV-Ray Files for more details).

The POV-Ray package includes detailed instructions on using the ray-tracer and creating scenes. Many stunning scenes are included with POV-Ray so you can start creating images immediately when you get the package. These scenes can also be modified so you do not have to start from scratch.

In addition to the pre-defined scenes, a library of pre-defined shapes and materials is provided. You can include these shapes and materials in your own scenes by just including the library file name at the top of your scene file, and by using the shape or material name in your scene.

Features

Here are some highlights of POV-Ray's features:

Changes and New Features Summary

The following sections cover changes and new features that apply no matter what platform you are using. Changes and information pertaining to your particular installation are covered in the platform specific documentation that's included with the distribution.

The categorized lists below outline the additions, changes and improvements along with links (when appropriate) to their relevant passages in the Reference Section.

Version 3.8

These changes (in no particular order) pertain to the version 3.8 release.

General Changes

  1. For clarity and ease of maintenance, several new annotations now appear in the documentation. See: Notation and Basic Assumptions
  2. Bug tracking is now handled by the issue tracker on GitHub
  3. Animation status messages now include the nominal frame number

Language Basics and Directives

  1. Important behavior changes concerning the: Version Directive
  2. Identifiers are no longer limited to just 40 characters in length since version 3.6.2
  3. Support for tau as a Built-in Constant has been added
  4. The macro directive has been extended. See Optional Parameters for details
  5. A cached macro mechanism has been implemented. See: Macro Caching for more information
  6. Arrays now allow the creation of dictionary container types and mixed type elements. See: Array
  7. The addition of a Create_Continue_Trace_Log option allows for greater resource control
  8. The Declare and Local Directives have been extended to support tuple-style assignments
  9. All instances of gray in keywords or INI file options can now alternatively be spelled grey
  10. Trailing white-space in INI files no longer causes a warning
  11. The version pseudo-variable will now evaluate to the effective language version at the time the expression is parsed. See: Built-in Variables and Version Directive

Patterns Pigments and Textures

  1. The default setting for ambient has changed
  2. A repeat option has been added to Crackle Pattern
  3. The map entry upper limit restriction for Color Maps and Pigment Maps has been removed
  4. UV mapping support for the cone, cylinder and lemon was added and ovus mapping has been improved
  5. A new finish parameter use_alpha has been added to suppress highlights and reflections depending on pigment transparency
  6. Implemented a non-linear interpolation scheme for Color Maps and Pigment Maps
  7. A new special pigment pattern user_defined has been added to define the pigment color directly in terms of a set of functions
  8. A new pattern potential has been added to aid in creating a pattern based on the potential field of a blob or isosurface object
  9. Fresnel angle-dependent attenuation can now also be applied to highlights and the diffuse component for more physical realism
  10. Radiosity now honors the brilliance setting of a surface
  11. CIELAB conversion macros have been added to colors.inc
  12. RAL Classic standard predefined colors are now available

Images and Image Related

  1. A new anti-aliasing method has been implemented.
  2. Several changes to grayscale file output handling. See: Output File Type
  3. A few changes and several additions to output file dithering
  4. The default up and right vectors have changed. See: Aspect Ratio
  5. The max_extent function has been extended
  6. Two gamma handling specifications have been added for:
    1. the display settings
    2. the output file
    3. image map input file
    4. image pattern input file
    5. height field input file
    6. bump map input file
  7. The map_type keyword now supports the angular map projection for use with light probes
  8. Default gamma handling of NetPBM (PPM/PGM) output files now complies with the official NetBPM standard
  9. The compression setting now affects more file types. See: Output File Type
  10. The interaction of transmit all and filter all with an image's alpha channel has been changed

Objects and Object Related

  1. The lemon object was added
  2. The ovus object has been extended and uv mapping has been improved
  3. Support for a spindle torus was added
  4. The number of components per blob is no longer artificially limited
  5. A user_defined camera type was added
  6. A new Light Fading model has been added
Version 3.7

These version 3.7 items definitely deserve your attention, because some of them represent key changes or enhancements to the way POV-Ray operates or behaves.

  1. POV-Ray now supports Symmetric MultiProcessing.
  2. The addition of the mesh_camera permits simulation of arbitrary lenses and makes texture baking possible.
  3. An elaborate gamma handling feature has been added, some of the highlights are:
    1. mandatory assumed_gamma
    2. the srgb keyword and its kin can be used to specify gamma pre-corrected colors
    3. a File_Gamma feature has been added
    4. an Antialias_Gamma feature has been added
    5. lastly you can also change the input file gamma for individual input files
  4. Make sure to review the Images and Image Related category below for important changes and additions.
  5. Redistribute the workload to render threads by specifying a render block size.
  6. Binary Space Partitioning or BSP tree bounding is now available.
  7. A resource control option for output image caching has been added.
  8. An overall review of the entire radiosity section is probably a good idea; some of the highlights are:
    1. a revised radiosity tutorial
    2. the new maximum_reuse parameter
    3. adaptive pretrace mode added to the nearest_count parameter
    4. the loading and saving of radiosity data has changed
    5. new command line options can help to further customize radiosity features
  9. The ovus object was added, along with support for uv_mapping
  10. Raised max order of the poly, cubic and quartic objects. Alternate syntax is also available.
  11. Added multiple-thread support to photon shooting code.
  12. New thread-safe random number generator was added; this can cause slight differences in the render output.
  13. The buit-in benchmark process now runs without any other distribution files. See the platform specific documentation for details.
  14. The Draw_Vistas, Vista_Buffer and Light_Buffer options have been deprecated. Look here for additional details.

Patterns Pigments and Textures

This category deals with items that are the building blocks of materials and textures and their appearance.

  1. Added diffuse backside illumination capability.
  2. An experimental subsurface scattering feature was added.
  3. Support for area_light diffuse and specular illumination was implemented.
  4. These list patterns, a warp, and a slope pattern extensions were added:
    1. aoi pattern
    2. cubic pattern
    3. cubic warp
    4. pavement pattern
    5. square pattern
    6. tiling pattern
    7. triangular pattern
    8. slope pattern extension
  5. Improvements to iterations and two new exterior types were added. See Fractal Patterns for more details.
  6. The finish block now supports the emission keyword.
  7. A sky_sphere layered pigment related behavior change.
  8. A new Slope Map Tutorial has been added.
  9. Re-enabled the crand finish attribute.

Images and Image Related

Image formats and handling issues are covered in this section.

  1. Get your display gamma correct! See the new gamma handling tutorial.
  2. There have been various changes regarding output file types these are the highlights:
    1. cross platform default output file type is PNG
    2. BOTH input and output support for two High Dynamic Range file types has been added
    3. JPEG default quality and chroma sub-sampling changes
    4. output file type "s" has been deprecated
  3. An output file dithering feature has been added.
  4. The interpolate option now supports bicubic interpolation.
  5. Use of the hf_gray_16 keyword has been deprecated in the global_settings block.
  6. A couple of important changes and additions regarding Alpha Channel usage.
  7. Added "out-of-the-box" transparency support for GIF input files.

Language Basics and Directives

A macro, a few functions and some programming directives completes this summary.

  1. Now you can declare an identifier as deprecated.
  2. Several bitwise functions were added.
  3. A string function datetime() has also been added.
  4. Added a new pre-declared variable input_file_name.
  5. New string relational operators have been added.
  6. Added binary #write capability, see the ARRAYS_WriteDF3 macro for usage.
  7. The #break directive behavior has changed.
  8. An atand function has been added to the math.inc file.
  9. The max_extent function can now return the pixel resolution of an image map.
  10. A new #version directive requirement has been added.
  11. The #if directive now supports an #elseif clause.
  12. A new #for loop directive has been added.
  13. The CPU Utilization Histogram feature has been deprecated.
  14. Added a +GP option. See the section: Directing Text Streams to Files for more information.

Trademarks

The terms 'POV-Ray', 'Persistence of Vision Ray Tracer', and 'POV-Team' are trademarks of Persistence of Vision Raytracer Pty. Ltd. All other trademarks are acknowledged as being the property of their respective owners.

The Early History of POV-Ray

Here's how POV-Ray came to be, as described by David Buck:

Back in 1986 or so, I had an Amiga. A friend who also has an Amiga downloaded the C code for a raytracer for Unix from the Internet and brought it over. I thought it looked interesting and I ported it to the Amiga and wrote the drivers to display it with Amiga graphics. The program only rendered untextured spheres with a planar floor in black and white, but I was still impressed by it. I played with it a bit adding support for color, but I eventually decided that I could do a better job writing a raytracer from scratch, so I scrapped the C program and started my own - DKBTrace had begun.

I decided to start with general quadric surfaces since they could represent spheres, ellipsoids, cylinders, planes, and more. I worked out the ray-quadric intersection calculations and used some calculus to work out the surface normal to a quadric surface at a point. For the program structure, I decided to use an object-oriented style since I had learned Smalltalk at university and it fit nicely. To make modeling more flexible, I added CSG and procedural textures. In the end, I had an interesting little raytracer and I decided to release it as freeware since I was planning to return to university to start my Master's degree and didn't have time to develop a commercial raytracer. Besides, there were already commercial renders for the Amiga that had user interfaces (not just text files) and I felt I couldn't sell it as a commercial product. I called it DKBTrace and released it to local BBS'es and to the Internet.

DKBTrace was an Amiga-only program, but it attracted quite a lot of interest. I released several versions of it adding in new features, better primitives, more texturing options, etc. Eventually I released version 2.01.

Sometime around 1987 or 1988, I was contacted by Aaron Collins. He had found the C code for DKBTrace and ported it to the PC. He also added a Phong lighting model and a few more goodies. I was interested in what he had done, so I contacted him to see if he wanted to help develop a new version of the program. This one would be portable across more platforms (at university I had access to Unix workstations). We eventually came up with version 2.12 which was the last version of DKBTrace ever released (1989).

While Aaron and I were working up to version 2.12, there was a group of people on CompuServe who were very excited about DKBTrace and were creating all sorts of neat scenes for it. They were also expressing frustration that Aaron and I weren't able to add new features into DKBTrace fast enough. They started talking about building a whole new raytracer from scratch that they could control and add the features they wanted. At that time, I was starting to pursue other areas and was starting to drift away from raytracing. So, I posted a message on CompuServe with the following offer: We could form a team to develop a new raytracer using DKBTrace as a base. I had three requirements for this team. The resulting code had to be freeware with the source code freely available, it had to remain portable between different platforms, and it had to have a different name than DKBTrace.

The name DKBTrace was, of course, based on my initials: David Kirk Buck (there's some little known trivia for you). With a package developed by a team of people, it was inappropriate to use my initials. I was also starting to drift away from raytracing (as I mentioned) and I didn't want people thinking that I was the head of the team forever. The name that was proposed was "Persistance Of Vision Raytracer" which was shortened to POV-Ray. It worked in three ways. It was the result of a persistent vision of the developers, it was a reference to the Salvador Dali work which depicted a distorted but realistic world, and the term "persistance of vision" in biology referred to the ability to see an image that was presented briefly - almost an after image.

In 1989, then, DKBTrace 2.12 was officially released and the POV-Ray project had begun. I worked with the team for a few years after that. I was responsible for the Amiga port among other things. Drew Wells was the project leader. Aaron Collins dropped out of the project around that time as well. Other early members included Chris Young, Steve Anger, Tim Wegner, Dan Farmer, Bill Pulver (IBM drivers), and Alexander Enzmann (quartics and cool math stuff). Chris Cason joined shortly after (my apologies if I left anyone out - lots of people were involved). The reference to Robert Skinner in the credits for POV-Ray was because we had a hard time finding a good noise function. In another raytracer, he had a great noise function written by Robert Skinner, so we asked for and received permission to use it in POV-Ray.

There was so much demand for us to release a new version that we created POV-Ray 0.5 and released it. It was basically an enhanced DKBTrace with a similar grammar but many more features. Eventually, we released POV-Ray 1.0 which had the new grammar and lots of new stuff. Drew dropped out later and Chris Young took over as project leader.

It was around that time that I started to drift away from the POV-Ray team. The project had momentum and could continue on without me. I was getting into different areas (physically based modeling and animation) and no longer had the time to continue with POV-Ray. Around the release of version 2.0, I left the project and the POV-Ray team developed it to its current state. Chris Cason is now the project leader.

Even though I'm no longer on the POV-Ray development team, I still like to follow its progress. I haven't built my own scene by hand for years now (although I occasionally use Moray). I still enjoy the one thing that drove me back in the DKBTrace days - I love seeing the works of other people who used my software. Even though I can no longer call POV-Ray "my software", I still enjoy admiring the artwork people create with it. I'm constantly amazed at what people can do. It was always the feedback from user community that drove me.

David Buck,
david [at] simberon.com

august 2001


Introduction The Original Creation Message


This document is protected, so submissions, corrections and discussions should be held on this documents talk page.