% ****************************************************************************
%
% POV-Ray 3.6 documentation in LaTeX format
% HTML, PDF and PostScript versions of the POV-ray documentation are
% available for download on our webserver http://www.povray.org!
%
% from Persistence of Vision(tm) Ray Tracer version 3.6.
% Copyright 1991-2003 Persistence of Vision Team
% Copyright 2003-2004 Persistence of Vision Raytracer Pty. Ltd.
%
%----------------------------------------------------------------------------
%
% There are strict rules regarding how you are permitted to use this file. 
% These rules are contained in the distribution and derivative versions
% licenses which should have been provided with this file.
%
% These licences may be found online, linked from the end-user license
% agreement that is located at http://www.povray.org/povlegal.html
%
% ----------------------------------------------------------------------------
%
% This an automatically generated LaTeX version of the POV-Ray documentation.
% This file is by no means perfect as it was generated completely automatic!
% It is *not* the basis of the POV-Ray documentation.  It is only provided
% for those whow wish to output the documentation in special formats.  It has
% also been used to generate the PDF and PostScript versions of the official
% POV-Ray documentation.  The master documentation format of POV-Ray is not
% available. If you which to write extensions to the POV-Ray documentation,
% please use HTML without layout. Only mathematical equations may be supplied
% in TeX format.
%
% NOTE: The POV-Team cannot make use individual changes to this file because
% it was generated automatically, without manual changes afterwards. If you
% have practical changes you think would help to make this file and the PDF
% and PostScript versions of the documentation better, please post such
% suggestion on our news server news.povray.org in the newsgroups
% povray.documentation.inbuilt together with the suggested LaTeX.  However,
% please be not disappointed if we cannot make use of extensive suggested
% changes for some reason. As such, it is recommended to ask in the newsgroup
% prior to putting extensive work into any such extension as we might simply
% not be able to integrate it into our automatic build process for this file.
%
% ****************************************************************************

\documentclass[letterpaper,10pt,twoside]{book}

\addtolength{\hoffset}{-72pt}
\addtolength{\voffset}{-72pt}
\setlength{\textwidth}{\paperwidth}
\addtolength{\textwidth}{-6.00cm}
\setlength{\oddsidemargin}{3.00cm}
\setlength{\evensidemargin}{3.00cm}
\setlength{\marginparwidth}{3.00cm}
\setlength{\marginparsep}{0.00cm}
\setlength{\marginparpush}{0.00cm}
\setlength{\topmargin}{2.50cm}
\setlength{\headsep}{0.75cm}
\setlength{\textheight}{\paperheight}
\addtolength{\textheight}{-7.25cm}

\usepackage{txfonts}
\usepackage{pslatex}
\usepackage{textcomp} 
\usepackage{parskip}
\usepackage{makeidx}
\usepackage{float}
\usepackage{afterpage}
\usepackage{multicol}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage[latin1]{inputenc}

\makeindex

\restylefloat{figure} 
\restylefloat{table} 
\newfloat{mathequ}{htbp}{loe}[chapter]
\floatname{mathequ}{Equation}
\floatplacement{figure}{tbhp}
\floatname{mathequ}{Figure}
\floatplacement{table}{htbp}
\floatname{mathequ}{Table}

\pagestyle{fancy}

% with this we ensure that the chapter and section headings are in lowercase.
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}

% delete current setting for header and footer
\fancyhf{}
\fancyhead[LE,RO]{\bfseries\thepage}
\fancyhead[LO]{\bfseries\rightmark}
\fancyhead[RE]{\bfseries\leftmark}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt}

% make space for the rule
\addtolength{\headheight}{0.5pt}

% get rid of headers and the line on plain pages
\fancypagestyle{plain}{\fancyhead{}\renewcommand{\headrulewidth}{0pt}}

% allow sightly more sloppy layout than the default
\pretolerance=125
\tolerance=250
\setlength{\emergencystretch}{2em}

% adjust figure placement to decrease number of figures on dedicated pages
\renewcommand{\topfraction}{0.85}
\renewcommand{\textfraction}{0.1}
\renewcommand{\floatpagefraction}{0.75}


\begin{document}

\author{POV-Team}
\date{for POV-Ray Version 3.6.1}

\title{POV-\discretionary{}{}{}Ray Reference} \pagenumbering{roman} \maketitle \tableofcontents \listof{figure}{Figures} \listof{table}{Tables} \cleardoublepage \pagenumbering{arabic}

\clearpage \chapter{Introduction}

% reference/000528.html



   This book provides a reference for the Persistence of Vision Ray-\discretionary{}{}{}Tracer (POV-\discretionary{}{}{}Ray). The documentation applies to all platforms to which this version of 
 POV-\discretionary{}{}{}Ray is ported. The platform-\discretionary{}{}{}specific documentation is available for each platform separately. 



   This book is divided into these main parts: 


\begin{enumerate}
 
 \item 
   This introduction together with a complete reference on ``POV-\discretionary{}{}{}Ray Options'' which explains options (set either by command line switches or by 
  INI file keywords) that tell POV-\discretionary{}{}{}Ray how to render the scenes. 
 

 \item 
   A complete reference on ``Scene Description Language'' in which you describe the scene. 
 

 \item 
   A complete reference on the ``Standard Include Files'' that come with the POV-\discretionary{}{}{}Ray package, to be used in your scenes. 
 

 \item 
   Finally, a consolidation of the POV-\discretionary{}{}{}Ray Scene Description Language in the ``Quick Reference''. 
 

\end{enumerate}


   This book covers only the generic parts of the program which are common to each version. \textbf{Each version has platform-\discretionary{}{}{}specific documentation not 
 included here.} We recommend you finish reading the tuorial book then read the platform-\discretionary{}{}{}specific information before using this reference. 



   The platform-\discretionary{}{}{}specific docs will show you how to render a sample scene and will give you detailed description of the platform-\discretionary{}{}{}specific features. 



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



   The Mac platform documentation is available via the ``Help'' menu as well as for viewing using a regular web browser. Details may be found in the 
 ``{\small\texttt{POV-\discretionary{}{}{}Ray MacOS Read Me}}'' which contains information specific to the Mac version of POV-\discretionary{}{}{}Ray. It is best to read this document first. 



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


\section{Notation and Basic Assumptions}

% reference/000529.html



   Throughout the tutorial and reference books, the consistent notation is used to mark keywords of the scene description language, command line switches, INI 
 file keywords and file names. All POV-\discretionary{}{}{}Ray scene descriptionlanguage keywords, punctuation and command-\discretionary{}{}{}line switches are mono-\discretionary{}{}{}spaced. For example {\small\texttt{sphere}}, 
 {\small\texttt{4.0 * sin(45.0)}} or {\small\texttt{+W640 +H480}}. Syntax descriptions are mono-\discretionary{}{}{}spaced and all caps. For example required syntax items are 
 written like {\small\texttt{SYNTAX\_\-ITEM}}, while optional syntax items are written in square braces like {\small\texttt{[SYNTAX\_\-ITEM]}}. If one or more syntax 
 items are required, the ellipsis will be appended like {\small\texttt{SYNTAX\_\-ITEM...}}. In case zero or more syntax items are allowed, the syntax item will be 
 written in square braces with appended ellipsis like {\small\texttt{[SYNTAX\_\-ITEM...]}}. A float value or expression is written mixed case like {\small\texttt{Value\_\-1}}, 
 while a vector value or expression is written in mixed case in angle braces like {\small\texttt{$<$Value\_\-1$>$}}. Choices are represented by a vertical bar 
 between syntax items. For example a choice between three items would be written as {\small\texttt{ITEM1 | ITEM2 | ITEM3}}. Further, a certain lists and arrays 
 also require square braces as part of the language rather than the language description. When square braces are required as part of the syntax, they will be 
 separated from the contained syntax item specification with a spaces like {\small\texttt{[ ITEM ]}}. 



   \textbf{Note:} POV-\discretionary{}{}{}Ray is a command-\discretionary{}{}{}line program on Unix and other text-\discretionary{}{}{}based operating systems and is menu-\discretionary{}{}{}driven on Windows and Macintosh platforms. Some 
 of these operating systems use folders to store files while others use directories. Some separate the folders and sub-\discretionary{}{}{}folders with a slash character ({\small\texttt{/}}), 
 back-\discretionary{}{}{}slash character ({\small\texttt{$\backslash$}}), or others. 



   We have tried to make this documentation as generic as possible but sometimes we have to refer to folders, files, options etc. and there is no way to escape 
 it. Here are some assumptions we make... 


\begin{enumerate}
 
 \item 
   You installed POV-\discretionary{}{}{}Ray in the ``{\small\texttt{C:$\backslash$POVRAY36}}'' directory. For MS-\discretionary{}{}{}Dos this is probably true but for Unix it might be ``{\small\texttt{/usr/povray3}}'', 
  or for Windows it might be ``{\small\texttt{C:$\backslash$Program Files$\backslash$\discretionary{}{}{}POV-\discretionary{}{}{}Ray for Windows v3.6}}'', for Mac it might be ``{\small\texttt{\discretionary{MyHD:}{}{MyHD:}\discretionary{Apps:}{}{Apps:}POV-\discretionary{}{}{}Ray 
  36:}}'', or you may have used some other drive or directory. So if we tell you that ``Include files are stored in the {\small\texttt{$\backslash$povray36$\backslash$\discretionary{}{}{}include}} 
  directory,'' we assume you can translate that to something like ``{\small\texttt{::\discretionary{POVRAY36:}{}{POVRAY36:}INCLUDE}}'' or ``{\small\texttt{C:$\backslash$Program 
  Files$\backslash$\discretionary{}{}{}POV-\discretionary{}{}{}Ray for Windows v3.6$\backslash$\discretionary{}{}{}include}}'' or whatever is appropriate for your platform, operating 
  system and installation. 
 

 \item 
   POV-\discretionary{}{}{}Ray uses INI files and/or command-\discretionary{}{}{}line switches (if available) to choose options in all versions, but Windows and Mac also use dialog boxes or menu 
  choices to set options. We will describe options assuming you are using switches or INI files when describing what the options do. We have taken care to use 
  the same terminology in designing menus and dialogs as we use in describing switches or INI keywords. See your version-\discretionary{}{}{}specific documentation on menu and 
  dialogs. 
 

 \item 
   Some of you are reading this using a help-\discretionary{}{}{}reader, built-\discretionary{}{}{}in help, web-\discretionary{}{}{}browser, formatted printout, or plain text file. We assume you know how to get 
  around in which ever medium you are using. We will say ``See the chapter on ''Setting POV-\discretionary{}{}{}Ray Options`` we assume you can click, scroll, browse, 
  flip pages or whatever to get there. 
 

\end{enumerate}

\section{Command-\discretionary{}{}{}line Options}

% reference/000484.html



   The reference section describes all command line switches and INI file keywords that are used to set the options of POV-\discretionary{}{}{}Ray. It is supposed to be used as a 
 reference for looking up things. It does not contain detailed explanations on how scenes are written or how POV-\discretionary{}{}{}Ray is used. It just explains all features, 
 their syntax, applications, limits, drawbacks, etc. 



   Options may be specified by switches or INI-\discretionary{}{}{}style options. Almost all INI-\discretionary{}{}{}style options have equivalent {\small\texttt{ +}}/ {\small\texttt{-}} switches and 
 most switches have equivalent INI-\discretionary{}{}{}style option. The following sections give a detailed description of each POV-\discretionary{}{}{}Ray option. It includes both the INI-\discretionary{}{}{}style 
 settings and the {\small\texttt{ +}}/ {\small\texttt{-}} switches. 



   The notation and terminology used is described in the tables below. 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Keyword=}}bool 
  } & 
{\raggedleft  Turn {\small\texttt{Keyword}} on if bool equals {\small\texttt{true}}, {\small\texttt{ yes}}, {\small\texttt{on}} or {\small\texttt{1}} and Turn 
  it off if it is any other value. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Keyword=true}} 
  } & 
{\raggedleft  Do this option if {\small\texttt{true}}, {\small\texttt{yes}}, {\small\texttt{ on}} or {\small\texttt{1}} is specified. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Keyword=false}} 
  } & 
{\raggedleft  Do this option if {\small\texttt{false}}, {\small\texttt{no}}, {\small\texttt{ off}} or {\small\texttt{0}} is specified. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Keyword=}}filename 
  } & 
{\raggedleft  Set {\small\texttt{Keyword}} to filename where filename is any valid file name. 
  
    \textbf{Note:} some options prohibit the use of any of the above {\small\texttt{ true}} or {\small\texttt{false}} values as a file name. They are noted in 
   later sections. 
  
} \\ 
 

 
  
  {\raggedleft 
    n 
  } & 
{\raggedleft  Any integer such as in {\small\texttt{+W320}} } \\ 
 

 
  
  {\raggedleft 
    \discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Any float such as in {\small\texttt{Clock=3.45}} } \\ 
 

 
  
  {\raggedleft 
    \discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Any float $<$ 1.0 even if it has no leading 0 } \\ 
 

 
  
  {\raggedleft 
    s 
  } & 
{\raggedleft  Any string of text } \\ 
 

 
  
  {\raggedleft 
    x or y 
  } & 
{\raggedleft  Any single character } \\ 
 

 
  
  {\raggedleft 
    path 
  } & 
{\raggedleft  Any directory name, drive optional, no final path separator (''$\backslash$`` or ''/``, depending on the operating system) } \\ 
 

\end{tabular*} \end{table}


   Unless otherwise specifically noted, you may assume that either a plus or minus sign before a switch will produce the same results. 


\subsection{Animation Options}

% reference/000485.html

\index{Animation! options}\index{Options! animation}

   Internal animation loop, automatic output file name numbering and the ability to shell out to the operating system to external utilities which can assemble 
 individual frames into an animation, greatly improved the animation capability. The internal animation loop is simple yet flexible. You may still use external 
 programs or batch files to create animations without the internal loop. 


\subsubsection{External Animation Loop}

% reference/000488.html

\index{Animation! external loop}\index{+k}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Clock=}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Sets {\small\texttt{clock}} float identifier to \discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+K}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Same as {\small\texttt{Clock=}}\discretionary{n.}{}{n.}n } \\ 
 

\end{tabular*} \end{table}
\index{Clock! ini-\discretionary{}{}{}option}

   The {\small\texttt{Clock=}}\textit{\discretionary{n.}{}{n.}n} option or the {\small\texttt{ +K}}\textit{\discretionary{n.}{}{n.}n} switch may be used to pass a single float value to the program for 
 basic animation. The value is stored in the float identifier {\small\texttt{clock}}. If an object had a {\small\texttt{rotate $<$\discretionary{0,}{}{0,}\discretionary{clock,}{}{clock,}0$>$}} attached 
 then you could rotate the object by different amounts over different frames by setting {\small\texttt{ +K10.0}},{\small\texttt{+K20.0}}... etc. on successive 
 renderings. It is up to the user to repeatedly invoke POV-\discretionary{}{}{}Ray with a different {\small\texttt{ Clock}} value and a different {\small\texttt{ Output\_\-File\_\-Name}} 
 for each frame. 


\subsubsection{Internal Animation Loop}

% reference/000487.html

\index{Animation! internal loop}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Initial\_\-Frame=}}n\index{Initial\_\-Frame! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets initial frame number to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Final\_\-Frame=}}n\index{Final\_\-Frame! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets final frame number to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Initial\_\-Clock=}}\discretionary{n.}{}{n.}n\index{Initial\_\-Clock! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets initial clock value to \discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Final\_\-Clock=}}\discretionary{n.}{}{n.}n\index{Final\_\-Clock! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets final clock value to \discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+KFI}}n\index{+kfi} 
  } & 
{\raggedleft  Same as {\small\texttt{Initial\_\-Frame=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+KFF}}n\index{+kff} 
  } & 
{\raggedleft  Same as {\small\texttt{Final\_\-Frame=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+KI}}\discretionary{n.}{}{n.}n\index{+ki} 
  } & 
{\raggedleft  Same as {\small\texttt{Initial\_\-Clock=}}\discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+KF}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Same as {\small\texttt{Final\_\-Clock=}}\discretionary{n.}{}{n.}n } \\ 
 

\end{tabular*} \end{table}


   The internal animation loop relieves the user of the task of generating complicated sets of batch files to invoke POV-\discretionary{}{}{}Ray multiple times with different 
 settings. While the multitude of options may look intimidating, the clever set of default values means that you will probably only need to specify the {\small\texttt{Final\_\-Frame}}=\textit{n} 
 or the {\small\texttt{+KFF}}\textit{n} option to specify the number of frames. All other values may remain at their defaults. 



   Any {\small\texttt{Final\_\-Frame}} setting other than -1 will trigger POV-\discretionary{}{}{}Ray's internal animation loop. For example {\small\texttt{ Final\_\-Frame=10}} or {\small\texttt{+KFF10}} 
 causes POV-\discretionary{}{}{}Ray to render your scene 10 times. If you specified {\small\texttt{Output\_\-File\_\-Name=\discretionary{file.}{}{file.}tga}} then each frame would be output as {\small\texttt{\discretionary{file01.}{}{file01.}tga}}, 
 {\small\texttt{\discretionary{file02.}{}{file02.}tga}}, {\small\texttt{\discretionary{file03.}{}{file03.}tga}} etc. The number of zero-\discretionary{}{}{}padded digits in the file name depends upon the final frame number. For 
 example {\small\texttt{+KFF100}} would generate {\small\texttt{\discretionary{file001.}{}{file001.}tga}} through {\small\texttt{\discretionary{file100.}{}{file100.}tga}}. The frame number may encroach upon the file 
 name. On MS-\discretionary{}{}{}DOS with an eight character limit, {\small\texttt{\discretionary{myscene.}{}{myscene.}pov}} would render to {\small\texttt{\discretionary{mysce001.}{}{mysce001.}tga}} through {\small\texttt{\discretionary{mysce100.}{}{mysce100.}tga}}. 
 



   The default {\small\texttt{Initial\_\-Frame=1}} will probably never have to be changed. You would only change it if you were assembling a long animation 
 sequence in pieces. One scene might run from frame 1 to 50 and the next from 51 to 100. The {\small\texttt{Initial\_\-Frame}}=\textit{n} or {\small\texttt{ +KFI}}\textit{n} 
 option is for this purpose. 



   \textbf{Note:} if you wish to render a subset of frames such as 30 through 40 out of a 1 to 100 animation, you should not change {\small\texttt{Initial\_\-Frame}} 
 or {\small\texttt{Final\_\-Frame}}. Instead you should use the subset commands described in section ''Subsets of Animation Frames``. 



   Unlike some animation packages, the action in POV-\discretionary{}{}{}Ray animated scenes does not depend upon the integer frame numbers. Rather you should design your scenes 
 based upon the float identifier {\small\texttt{clock}}. By default, the clock value is 0.0 for the initial frame and 1.0 for the final frame. All other frames 
 are interpolated between these values. For example if your object is supposed to rotate one full turn over the course of the animation, you could specify {\small\texttt{rotate 
 360*clock*y}}. Then as clock runs from 0.0 to 1.0, the object rotates about the y-\discretionary{}{}{}axis from 0 to 360 degrees. 



   The major advantage of this system is that you can render a 10 frame animation or a 100 frame or 500 frame or 329 frame animation yet you still get one full 
 360 degree rotation. Test renders of a few frames work exactly like final renders of many frames. 



   In effect you define the motion over a continuous float valued parameter (the clock) and you take discrete samples at some fixed intervals (the frames). If 
 you take a movie or video tape of a real scene it works the same way. An object's actual motion depends only on time. It does not depend on the frame rate of 
 your camera. 



   Many users have already created scenes for POV-\discretionary{}{}{}Ray 2 that expect clock values over a range other than the default 0.0 to 1.0. For this reason we provide the {\small\texttt{Initial\_\-Clock}}=\textit{\discretionary{n.}{}{n.}n} 
 or {\small\texttt{+KI}}\textit{\discretionary{n.}{}{n.}n} and {\small\texttt{Final\_\-Clock}}=\textit{\discretionary{n.}{}{n.}n} or {\small\texttt{+KF}}\textit{\discretionary{n.}{}{n.}n} options. For example to run the clock 
 from 25.0 to 75.0 you would specify {\small\texttt{Initial\_\-Clock=25.0}} and {\small\texttt{Final\_\-Clock=75.0}}. Then the clock would be set to 25.0 for the 
 initial frame and 75.0 for the final frame. In-\discretionary{}{}{}between frames would have clock values interpolated from 25.0 through 75.0 proportionally. 



   Users who are accustomed to using frame numbers rather than clock values could specify {\small\texttt{ Initial\_\-Clock=1.0}} and {\small\texttt{Final\_\-Clock=10.0}} 
 and {\small\texttt{Frame\_\-Final=10}} for a 10 frame animation. 



   For new scenes, we recommend you do not change the {\small\texttt{ Initial\_\-Clock}} or {\small\texttt{ Final\_\-Clock}} from their default 0.0 to 1.0 values. If 
 you want the clock to vary over a different range than the default 0.0 to 1.0, we recommend you handle this inside your scene file as follows... 


{\small\begin{verbatim}
  #declare Start    = 25.0;
  #declare End      = 75.0;
  #declare My_Clock = Start+(End-Start)*clock;
\end{verbatim}}


   Then use {\small\texttt{My\_\-Clock}} in the scene description. This keeps the critical values 25.0 and 75.0 in your .pov file. 



   \textbf{Note:} more details concerning the inner workings of the animation loop are in the section on shell-\discretionary{}{}{}out operating system commands in section ``Shell-\discretionary{}{}{}out 
 to Operating System''. 


\subsubsection{Subsets of Animation Frames}

% reference/000489.html

\index{Animation! subsets of frames}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Subset\_\-Start\_\-Frame=}}n\index{Subset\_\-Start\_\-Frame}\index{Subset\_\-Start\_\-Frame! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set subset starting frame to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Subset\_\-Start\_\-Frame=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set subset starting frame to n percent } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Subset\_\-End\_\-Frame=}}n\index{Subset\_\-End\_\-Frame}\index{Subset\_\-End\_\-Frame! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set subset ending frame to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Subset\_\-End\_\-Frame=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set subset ending frame to n percent } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+SF}}\discretionary{0.}{}{0.}n\index{+sf} 
  } & 
{\raggedleft  Same as {\small\texttt{Subset\_\-Start\_\-Frame}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+EF}}\discretionary{0.}{}{0.}n\index{+ef} 
  } & 
{\raggedleft  Same as {\small\texttt{Subset\_\-End\_\-Frame}} } \\ 
 

\end{tabular*} \end{table}


   When creating a long animation, it may be handy to render only a portion of the animation to see what it looks like. Suppose you have 100 frames but only 
 want to render frames 30 through 40. If you set {\small\texttt{Initial\_\-Frame=30}} and {\small\texttt{Final\_\-Frame=40}} then the clock would vary from 0.0 to 
 1.0 from frames 30 through 40 rather than 0.30 through 0.40 as it should. Therefore you should leave {\small\texttt{ Initial\_\-Frame=1}} and {\small\texttt{Final\_\-Frame=100}} 
 and use {\small\texttt{Subset\_\-Start\_\-Frame=30}} and {\small\texttt{Subset\_\-End\_\-Frame=40}} to selectively render part of the scene. POV-\discretionary{}{}{}Ray will then properly 
 compute the clock values. 



   Usually you will specify the subset using the actual integer frame numbers however an alternate form of the subset commands takes a float value in the range \textit{0.0 
 $<$=\discretionary{n.}{}{n.}nnn $<$=1.0} which is interpreted as a fraction of the whole animation. For example, {\small\texttt{ Subset\_\-Start\_\-Frame=0.333}} 
 and {\small\texttt{Subset\_\-End\_\-Frame=0.667}} would render the middle 1/3rd of a sequence regardless of the number of frames. 


\subsubsection{Cyclic Animation}

% reference/000490.html

\index{Animation! cyclic}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Cyclic\_\-Animation=}}bool\index{Cyclic\_\-Animation} 
  } & 
{\raggedleft  Turn cyclic animation on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+KC}}\index{+kc} 
  } & 
{\raggedleft  Turn cyclic animation on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-KC}}\index{-kc} 
  } & 
{\raggedleft  Turn cyclic animation off } \\ 
 

\end{tabular*} \end{table}


   Many computer animation sequences are designed to be run in a continuous loop. Suppose you have an object that rotates exactly 360 degrees over the course of 
 your animation and you did {\small\texttt{rotate 360*clock*y}} to do so. Both the first and last frames would be identical. Upon playback there would be a 
 brief one frame jerkiness. To eliminate this problem you need to adjust the clock so that the last frame does not match the first. For example a ten frame 
 cyclic animation should not use clock 0.0 to 1.0. It should run from 0.0 to 0.9 in 0.1 increments. However if you change to 20 frames it should run from 0.0 
 to 0.95 in 0.05 increments. This complicates things because you would have to change the final clock value every time you changed {\small\texttt{Final\_\-Frame}}. 
 Setting {\small\texttt{Cyclic\_\-Animation=on}} or using {\small\texttt{+KC}} will cause POV-\discretionary{}{}{}Ray to automatically adjust the final clock value for cyclic 
 animation regardless of how many total frames. The default value for this setting is off. 


\subsubsection{Field Rendering}

% reference/000491.html

\index{Animation! field rendering}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Field\_\-Render=}}bool\index{Field\_\-Render} 
  } & 
{\raggedleft  Turn field rendering on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Odd\_\-Field=}}bool\index{Odd\_\-Field} 
  } & 
{\raggedleft  Set odd field flag } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UF}}\index{+uf} 
  } & 
{\raggedleft  Turn field rendering on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UF}}\index{-uf} 
  } & 
{\raggedleft  Turn field rendering off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UO}}\index{+uo} 
  } & 
{\raggedleft  Set odd field flag on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UO}}\index{-uo} 
  } & 
{\raggedleft  Set odd field flag off } \\ 
 

\end{tabular*} \end{table}


   Field rendering is sometimes used for animations when the animation is being output for television. TVs only display alternate scan lines on each vertical 
 refresh. When each frame is being displayed the fields are interlaced to give the impression of a higher resolution image. The even scan lines make up the 
 even field, and are drawn first (\discretionary{i.}{}{i.}e. scan lines 0, 2, 4, etc.), followed by the odd field, made up of the odd numbered scan lines are drawn afterwards. If 
 objects in an animation are moving quickly, their position can change noticeably from one field to the next. As a result, it may be desirable in these cases 
 to have POV-\discretionary{}{}{}Ray render alternate fields at the actual field rate (which is twice the frame rate), rather than rendering full frames at the normal frame rate. 
 This would save a great deal of time compared to rendering the entire animation at twice the frame rate, and then only using half of each frame. 



   By default, field rendering is not used. Setting {\small\texttt{ Field\_\-Render=on}} or using {\small\texttt{ +UF}} will cause alternate frames in an animation 
 to be only the even or odd fields of an animation. By default, the first frame is the even field, followed by the odd field. You can have POV-\discretionary{}{}{}Ray render the 
 odd field first by specifying {\small\texttt{ Odd\_\-Field=on}}, or by using the {\small\texttt{ +UO}} switch. 


\subsection{General Output Options}

% reference/000486.html

\index{Options! general output}
\subsubsection{Height and Width of Output}

% reference/000492.html

\index{Options! height and width}\index{Resolution}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Height=}}n\index{Height! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets screen height to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Width=}}n\index{Width! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets screen width to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+H}}n\index{+h} 
  } & 
{\raggedleft  Same as {\small\texttt{Height=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+W}}n\index{+w} 
  } & 
{\raggedleft  Same as {\small\texttt{Width=}}n } \\ 
 

\end{tabular*} \end{table}


   These switches set the height and width of the image in pixels. This specifies the image size for file output. The preview display, if on, will generally 
 attempt to pick a video mode to accommodate this size but the display settings do not in any way affect the resulting file output. 


\subsubsection{Partial Output Options}

% reference/000493.html

\index{Options! partial output}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Start\_\-Column=}}n\index{Start\_\-Column! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set first column to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Start\_\-Column=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set first column to n percent of width } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+SC}}\discretionary{0.}{}{0.}n\index{+sc} 
  } & 
{\raggedleft  Same as {\small\texttt{Start\_\-Column}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Start\_\-Row=}}n\index{Start\_\-Row! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set first row to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Start\_\-Row=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set first row to n percent of height } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+S}}n\index{+sr} 
  } & 
{\raggedleft  Same as {\small\texttt{Start\_\-Row=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+SR}}\discretionary{0.}{}{0.}n or {\small\texttt{+S}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Same as {\small\texttt{Start\_\-Row=}}\discretionary{0.}{}{0.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{End\_\-Column=}}n\index{End\_\-Column! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set last column to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{End\_\-Column=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set last column to n percent of width } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+EC}}\discretionary{0.}{}{0.}n\index{+ec} 
  } & 
{\raggedleft  Same as {\small\texttt{End\_\-Column}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{End\_\-Row=}}n\index{End\_\-Row}\index{End\_\-Row! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set last row to n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{End\_\-Row=}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Set last row to n percent of height } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+E}}n\index{+er} 
  } & 
{\raggedleft  Same as {\small\texttt{End\_\-Row=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+ER}}\discretionary{0.}{}{0.}n or {\small\texttt{+E}}\discretionary{0.}{}{0.}n 
  } & 
{\raggedleft  Same as {\small\texttt{End\_\-Row=}}\discretionary{0.}{}{0.}n } \\ 
 

\end{tabular*} \end{table}


   When doing test rendering it is often convenient to define a small, rectangular sub-\discretionary{}{}{}section of the whole screen so you can quickly check out one area of the 
 image. The {\small\texttt{Start\_\-Row}}, {\small\texttt{End\_\-Row}}, {\small\texttt{ Start\_\-Column}} and {\small\texttt{End\_\-Column}} options allow you to define 
 the subset area to be rendered. The default values are the full size of the image from (\discretionary{1,}{}{1,}1) which is the upper left to (\discretionary{w,}{}{w,}h) on the lower right where w and h 
 are the {\small\texttt{Width=}}\textit{n} and {\small\texttt{ Height=}}\textit{n} values you have set. 



   \textbf{Note:} if the number specified is greater than 1 then it is interpreted as an absolute row or column number in pixels. If it is a decimal value 
 between 0.0 and 1.0 then it is interpreted as a percent of the total width or height of the image. 



   For example: {\small\texttt{ Start\_\-Row=0.75}} and {\small\texttt{ Start\_\-Column=0.75}} starts on a row 75\% down from the top at a column 75\% from the left. 
 Thus it renders only the lower-\discretionary{}{}{}right 25\% of the image regardless of the specified width and height. 



   The {\small\texttt{+SR}}, {\small\texttt{+ER}}, {\small\texttt{ +SC}} and {\small\texttt{ +EC}} switches work in the same way as the corresponding INI-\discretionary{}{}{}style 
 settings for both absolute settings or percentages. Early versions of POV-\discretionary{}{}{}Ray allowed only start and end rows to be specified with {\small\texttt{ +S}}\textit{n} 
 and {\small\texttt{ +E}}\textit{n} so they are still supported in addition to {\small\texttt{ +SR}} and {\small\texttt{+ER}}. 



   When rendering a subset of *columns* ({\small\texttt{+sc/+ec}}) POV-\discretionary{}{}{}Ray generates a full width image and fills the not rendered columns with black pixels. 
 This should not be a problem for any image reading program no matter what file format is used. 



   when rendering a subset of *rows* ({\small\texttt{+sr/+er}}) POV-\discretionary{}{}{}Ray writes the full height into the image file header and only writed those lines into the 
 image that are rendered. This can cause problems with image reading programs that are not checking the file while reading and just read over the end. 



   if POV-\discretionary{}{}{}Ray wrote the actual height of the partial image into the image header there would be no way to continue the trace in a later run. 


\subsubsection{Interrupting Options}

% reference/000494.html

\index{Options! interruption}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Test\_\-Abort=}}bool\index{Test\_\-Abort! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn test for user abort on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+X}}\index{+x} 
  } & 
{\raggedleft  Turn test abort on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-X}}\index{-x} 
  } & 
{\raggedleft  Turn test abort off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Test\_\-Abort\_\-Count=}}n\index{Test\_\-Abort\_\-Count! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set to test for abort every n pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+X}}n 
  } & 
{\raggedleft  Set to test for abort every n pixels on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-X}}n 
  } & 
{\raggedleft  Set to test for abort off (in future test every n pixels) } \\ 
 

\end{tabular*} \end{table}


   On some operating systems once you start a rendering you must let it finish. The {\small\texttt{Test\_\-Abort=on}} option or {\small\texttt{+X}} switch causes 
 POV-\discretionary{}{}{}Ray to test the keyboard for keypress. If you have pressed a key, it will generate a controlled user abort. Files will be flushed and 
 closed but only data through the last full row of pixels is saved. POV-\discretionary{}{}{}Ray exits with an error code 2 (normally POV-\discretionary{}{}{}Ray returns 0 for a successful run or 1 
 for a fatal error). 



   When this option is on, the keyboard is polled on every line while parsing the scene file and on every pixel while rendering. Because polling the keyboard 
 can slow down a rendering, the {\small\texttt{ Test\_\-Abort\_\-Count=}}\textit{n} option or {\small\texttt{+X}}\textit{n} switch causes the test to be performed 
 only every \textit{n} pixels rendered or scene lines parsed. 


\subsubsection{Resuming Options}

% reference/000495.html

\index{Options! resuming}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Continue\_\-Trace=}}bool\index{Continue\_\-Trace! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets continued trace on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+C}}\index{+c} 
  } & 
{\raggedleft  Sets continued trace on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-C}}\index{-c} 
  } & 
{\raggedleft  Sets continued trace off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Create\_\-Ini=}}file\index{Create\_\-Ini! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Generate an INI file to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Create\_\-Ini=}}true 
  } & 
{\raggedleft  Generate \discretionary{file.}{}{file.}ini where file is scene name. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Create\_\-Ini=}}false 
  } & 
{\raggedleft  Turn off generation of previously set \discretionary{file.}{}{file.}ini } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GI}}file\index{+gi} 
  } & 
{\raggedleft  Same as {\small\texttt{Create\_\-Ini=}}file } \\ 
 

\end{tabular*} \end{table}


   If you abort a render while it is in progress or if you used the {\small\texttt{End\_\-Row}} option to end the render prematurely, you can use {\small\texttt{Continue\_\-Trace=on}} 
 or {\small\texttt{+C}} option to continue the render later at the point where you left off. This option reads in the previously generated output file, 
 displays the partial image rendered so far, then proceeds with the ray-\discretionary{}{}{}tracing. This option cannot be used if file output is disabled with {\small\texttt{Output\_\-to\_\-file=off}} 
 or {\small\texttt{-F}}. 



   The {\small\texttt{Continue\_\-Trace}} option may not work if the {\small\texttt{Start\_\-Row}} option has been set to anything but the top of the file, depending 
 on the output format being used. Also POV-\discretionary{}{}{}Ray cannot continue the file once it has been opened and saved again by any program 



   POV-\discretionary{}{}{}Ray tries to figure out where to resume an interrupted trace by reading any previously generated data in the specified output file. All file formats 
 contain the image size, so this will override any image size settings specified. Some file formats (namely TGA and PNG) also store information about where the 
 file started (i. e. {\small\texttt{ +SC}}\textit{n} and {\small\texttt{ +SR}}\textit{n} options), alpha output {\small\texttt{+UA}}, and bit-\discretionary{}{}{}depth {\small\texttt{+FN}}\textit{n}, 
 which will override these settings. It is up to the user to make sure that all other options are set the same as the original render. 



   The {\small\texttt{Create\_\-Ini}} option or {\small\texttt{+GI}} switch provides an easy way to create an INI file with all of the rendering options, so you 
 can re-\discretionary{}{}{}run files with the same options, or ensure you have all the same options when resuming. This option creates an INI file with every option set at the 
 value used for that rendering. This includes default values which you have not specified. For example if you run POV-\discretionary{}{}{}Ray with... 


{\small\begin{verbatim}
 POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS
\end{verbatim}}


   POV-\discretionary{}{}{}Ray will create a file called {\small\texttt{\discretionary{rerun.}{}{rerun.}ini}} with all of the options used to generate this scene. The file is not written until all options 
 have been processed. This means that in the above example, the file will include options from both {\small\texttt{\discretionary{myopts.}{}{myopts.}ini}} and {\small\texttt{ \discretionary{moreopts.}{}{moreopts.}ini}} 
 despite the fact that the {\small\texttt{+GI}} switch is specified between them. You may now re-\discretionary{}{}{}run the scene with... 


{\small\begin{verbatim}
 POVRAY RERUN
\end{verbatim}}


   or resume an interrupted trace with 


{\small\begin{verbatim}
 POVRAY RERUN +C
\end{verbatim}}


   If you add other switches with the {\small\texttt{\discretionary{rerun.}{}{rerun.}ini}} reference, they will be included in future re-\discretionary{}{}{}runs because the file is re-\discretionary{}{}{}written every time 
 you use it. 



   The {\small\texttt{Create\_\-Ini}} option is also useful for documenting how a scene was rendered. If you render {\small\texttt{ \discretionary{waycool.}{}{waycool.}pov}} with {\small\texttt{ 
 Create\_\-Ini=on}} then it will create a file {\small\texttt{\discretionary{waycool.}{}{waycool.}ini}} that you could distribute along with your scene file so other users can exactly 
 re-\discretionary{}{}{}create your image. 


\subsection{Display Output Options}

% reference/000501.html

\index{Options! display}
\subsubsection{Display Hardware Settings}

% reference/000496.html

\index{Options! display}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Display=}}bool\index{Display! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turns graphic display on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+D}}\index{+d} 
  } & 
{\raggedleft  Turns graphic display on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-D}}\index{-d} 
  } & 
{\raggedleft  Turns graphic display off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Video\_\-Mode=}}x\index{Video\_\-Mode! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set video mode to x; does not affect on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+D}}x 
  } & 
{\raggedleft  Set display on; Set mode to x } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-D}}x 
  } & 
{\raggedleft  Set display off; but for future use mode x } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Palette=}}y\index{Palette! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set display palette to y; does not affect on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+D}}xy 
  } & 
{\raggedleft  Set display on; Set mode x; Set palette y } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-D}}xy 
  } & 
{\raggedleft  Set display off; use mode x, palette y in future } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Display\_\-Gamma=}}\discretionary{n.}{}{n.}n\index{Display\_\-Gamma}\index{Display\_\-Gamma! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets the display gamma to \discretionary{n.}{}{n.}n } \\ 
 

\end{tabular*} \end{table}


   The {\small\texttt{Display=on}} or {\small\texttt{+D}} switch will turn on the graphics display of the image while it is being rendered. Even on some 
 non-\discretionary{}{}{}graphics systems, POV-\discretionary{}{}{}Ray may display an 80 by 24 character \textit{ ``ASCII-\discretionary{}{}{}Art''} version of your image. Where available, 
 the display may be full, 24-bit true color. Setting {\small\texttt{Display=off}} or using the {\small\texttt{-D}} switch will turn off the graphics display 
 which is the default. 



   On the Windows platform, the default is {\small\texttt{Display=on}}. Turning display off does not, of course, turn off the actual video display. Instead, 
 POV-\discretionary{}{}{}Ray will not open the output window that it normally shows a render in. 



   The {\small\texttt{Video\_\-Mode=}}\textit{x} option sets the display mode or hardware type chosen where \textit{x} is a single digit or letter that is machine 
 dependent. Generally {\small\texttt{Video\_\-Mode=0}} means the default or an auto-\discretionary{}{}{}detected setting should be used. When using switches, this character 
 immediately follows the switch. For example the {\small\texttt{+D0}} switch will turn on the graphics display in the default mode. 



   The {\small\texttt{ Palette=}}\textit{y} option selects the palette to be used. Typically the single character parameter \textit{y} is a digit which selects 
 one of several fixed palettes or a letter such {\small\texttt{G}} for gray scale, {\small\texttt{ H}} for 15-bit or 16-bit high color or {\small\texttt{ T}} 
 for 24-bit true color. When using switches, this character is the 2nd character after the switch. For example the {\small\texttt{+D0T}} switch will turn on 
 the graphics display in the default mode with a true color palette. The {\small\texttt{ Display\_\-Gamma=}}\textit{\discretionary{n.}{}{n.}n} setting is not available as a 
 command-\discretionary{}{}{}line switch. 



   The {\small\texttt{ Display\_\-Gamma}} setting overcomes the problem of images (whether ray-\discretionary{}{}{}traced or not) having different brightness when being displayed on 
 different monitors, different video cards, and under different operating systems. 



   \textbf{Note:} the {\small\texttt{Display\_\-Gamma}} is a setting based on your computer's display hardware, and should be set correctly once and not changed. 



   The {\small\texttt{ Display\_\-Gamma}} INI setting works in conjunction with the new {\small\texttt{ assumed\_\-gamma}} global setting to ensure that POV scenes 
 and the images they create look the same on all systems. See section ``Assumed\_\-Gamma'' which describes the {\small\texttt{ assumed\_\-gamma}} global 
 setting and describes gamma more thoroughly. 



   While the {\small\texttt{ Display\_\-Gamma}} can be different for each system, there are a few general rules that can be used for setting {\small\texttt{ 
 Display\_\-Gamma}} if you do not know it exactly. If the {\small\texttt{ Display\_\-Gamma}} keyword does not appear in the INI file, POV-\discretionary{}{}{}Ray assumes that the 
 display gamma is 2.2. This is because most PC monitors have a gamma value in the range 1.6 to 2.6 (newer models seem to have a lower gamma value). Mac has the 
 ability to do gamma correction inside the system software (based on a user setting in the gamma control panel). If the gamma control panel is turned off, or 
 is not available, the default Macintosh system gamma is 1.8. Many newer PC graphics cards can do hardware gamma correction and should use the current 
 Display\_\-Gamma setting, usually 1.0. 


\subsubsection{Setting your Display Gamma}

% reference/000497.html

\index{gamma! determining your display}\index{Display\_\-Gamma! for your display}

   The following gamma test image can be used to help you set your {\small\texttt{Display\_\-Gamma}} accurately. 



   Before viewing the gamma image darken the room and set the monitor brightness and contrast to maximum. While viewing a black screen, lower the brightness 
 gradually until the ``background'' is no longer noticeable (ie when it just fades from view). This may be difficult on monitors that use overscanning, 
 unless you change the viewable area settings.\index{gamma! test image} 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/gamma} \caption{Display gamma test image.} \end{figure} 



   Now, lower the contrast until the alternating white and black bars on the left edge of each column are equal in width. This is trying to get a 50\% gray by 
 using half white and half black. If this is not possible, choose a contrast setting which is about in the middle. While viewing the image from a distance, or 
 with squinted eyes, one of the numbered ``swatches'' will best match the gray value approximated by the white and black bars. The number in this 
 ``swatch'' is your display's actual gamma value. 



   Normal display gamma values are in the range 2.0 to 2.6. If your monitor is usually used in a dim environment, we often use a gamma value that is 15\% - 25\% 
 lower than the actual display gamma to give the images more contrast. Some systems, such as Macs and SGIs, already do gamma correction, so they may have 
 display gammas of 1.0 or 1.8. 



   For scene files that do not contain an {\small\texttt{assumed\_\-gamma}} global setting the INI file option {\small\texttt{Display\_\-Gamma}} will not have any 
 affect on the preview output of POV-\discretionary{}{}{}Ray or for most output file formats. However, the {\small\texttt{Display\_\-Gamma}} value is used when creating PNG format 
 output files, and also when rendering the POV-\discretionary{}{}{}Ray example files (because they have an {\small\texttt{assumed\_\-gamma}}), so it should still be correctly set for 
 your system to ensure proper results. 


\subsubsection{Display Related Settings}

% reference/000498.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Pause\_\-When\_\-Done=}}bool\index{Pause\_\-When\_\-Done! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets pause when done on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+P}}\index{+p} 
  } & 
{\raggedleft  Sets pause when done on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-P}}\index{-p} 
  } & 
{\raggedleft  Sets pause when done off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Verbose=}}bool\index{Verbose! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set verbose messages on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+V}}\index{+v} 
  } & 
{\raggedleft  Set verbose messages on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-V}}\index{-v} 
  } & 
{\raggedleft  Set verbose messages off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Draw\_\-Vistas=}}bool\index{Draw\_\-Vistas! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn draw vistas on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UD}}\index{+ud} 
  } & 
{\raggedleft  Turn draw vistas on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UD}}\index{-ud} 
  } & 
{\raggedleft  Turn draw vistas off } \\ 
 

\end{tabular*} \end{table}


   On some systems, when the image is complete, the graphics display is cleared and POV-\discretionary{}{}{}Ray switches back into text mode to print the final statistics and to 
 exit. Normally when the graphics display is on, you want to look at the image awhile before continuing. Using {\small\texttt{Pause\_\-When\_\-Done=on}} or {\small\texttt{+P}} 
 causes POV-\discretionary{}{}{}Ray to pause in graphics mode until you press a key to continue. The default is not to pause ({\small\texttt{-P}}). 



   When the graphics display is not used, it is often desirable to monitor progress of the rendering. Using {\small\texttt{ Verbose=on}} or {\small\texttt{+V}} 
 turns on verbose reporting of your rendering progress. This reports the number of the line currently being rendered, the elapsed time for the current frame 
 and other information. On some systems, this textual information can conflict with the graphics display. You may need to turn this off when the display is on. 
 The default setting is off ({\small\texttt{-V}}). 



   The option {\small\texttt{Draw\_\-Vistas=on}} or {\small\texttt{+UD}} was originally a debugging help for POV-\discretionary{}{}{}Ray's vista buffer feature but it was such fun we 
 decided to keep it. Vista buffering is a spatial sub-\discretionary{}{}{}division method that projects the 2-D extents of bounding boxes onto the viewing window. POV-\discretionary{}{}{}Ray tests 
 the 2-D x, y pixel location against these rectangular areas to determine quickly which objects, if any, the viewing ray will hit. This option shows you the 
 2-D rectangles used. The default setting is off ({\small\texttt{-UD}}) because the drawing of the rectangles can take considerable time on complex scenes and 
 it serves no critical purpose. See section ``Automatic Bounding Control'' for more details. 


\subsubsection{Mosaic Preview}

% reference/000499.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Preview\_\-Start\_\-Size=}}n\index{Preview\_\-Start\_\-Size! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set mosaic preview start size to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+SP}}n\index{+sp} 
  } & 
{\raggedleft  Same as Preview\_\-Start\_\-Size=n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Preview\_\-End\_\-Size=}}n\index{Preview\_\-End\_\-Size! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set mosaic preview end size to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+EP}}n\index{+ep} 
  } & 
{\raggedleft  Same as Preview\_\-End\_\-Size=n } \\ 
 

\end{tabular*} \end{table}


   Typically, while you are developing a scene, you will do many low resolution test renders to see if objects are placed properly. Often this low resolution 
 version does not give you sufficient detail and you have to render the scene again at a higher resolution. A feature called \textit{ ``mosaic preview''} 
 solves this problem by automatically rendering your image in several passes. 



   The early passes paint a rough overview of the entire image using large blocks of pixels that look like mosaic tiles. The image is then refined using higher 
 resolutions on subsequent passes. This display method very quickly displays the entire image at a low resolution, letting you look for any major problems with 
 the scene. As it refines the image, you can concentrate on more details, like shadows and textures. You do not have to wait for a full resolution render to 
 find problems, since you can interrupt the rendering early and fix the scene, or if things look good, you can let it continue and render the scene at high 
 quality and resolution. 



   To use this feature you should first select a {\small\texttt{ Width}} and {\small\texttt{ Height}} value that is the highest resolution you will need. Mosaic 
 preview is enabled by specifying how big the mosaic blocks will be on the first pass using {\small\texttt{ Preview\_\-Start\_\-Size=}}\textit{n} or {\small\texttt{ 
 +SP}}\textit{n}. The value n should be a number greater than zero that is a power of two (1, 2, 4, 8, 16, 32, etc.) If it is not a power of two, the nearest 
 power of two less than n is substituted. This sets the size of the squares, measured in pixels. A value of 16 will draw every 16th pixel as a 16*16 pixel 
 square on the first pass. Subsequent passes will use half the previous value (such as 8*8, 4*4 and so on.) 



   The process continues until it reaches 1*1 pixels or until it reaches the size you set with {\small\texttt{ Preview\_\-End\_\-Size=}}\textit{n} or {\small\texttt{ 
 +EP}}\textit{n}. Again the value n should be a number greater than zero that is a power of two and less than or equal to {\small\texttt{ Preview\_\-Start\_\-Size}}. 
 If it is not a power of two, the nearest power of two less than n is substituted. The default ending value is 1. If you set {\small\texttt{Preview\_\-End\_\-Size}} 
 to a value greater than 1 the mosaic passes will end before reaching 1*1, but POV-\discretionary{}{}{}Ray will always finish with a 1*1. For example, if you want a single 8*8 
 mosaic pass before rendering the final image, set {\small\texttt{ Preview\_\-Start\_\-Size=8}} and {\small\texttt{ Preview\_\-End\_\-Size=8}}. 



   No file output is performed until the final 1*1 pass is reached. Although the preliminary passes render only as many pixels as needed, the 1*1 pass 
 re-\discretionary{}{}{}renders every pixel so that anti-\discretionary{}{}{}aliasing and file output streams work properly. This makes the scene take up to 25\% longer than the 
 regular 1*1 pass to render, so it is suggested that mosaic preview not be used for final rendering. Also, the lack of file output until the final pass means 
 that renderings which are interrupted before the 1*1 pass can not be resumed without starting over from the beginning. 


\subsection{File Output Options}

% reference/000500.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Output\_\-to\_\-File=}}bool\index{Output\_\-to\_\-File! ini-\discretionary{}{}{}option}\index{Output\_\-to\_\-File} 
  } & 
{\raggedleft  Sets file output on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+F}} 
  } & 
{\raggedleft  Sets file output on (use default type) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-F}} 
  } & 
{\raggedleft  Sets file output off } \\ 
 

\end{tabular*} \end{table}


   By default, POV-\discretionary{}{}{}Ray writes an image file to disk. When you are developing a scene and doing test renders, the graphic preview may be sufficient. To save time 
 and disk activity you may turn file output off with {\small\texttt{ Output\_\-to\_\-File=off}} or {\small\texttt{-F}}. 


\subsubsection{Output File Type}

% reference/000502.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Output\_\-File\_\-Type=}}x\index{Output\_\-File\_\-Type! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets file output format to x } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+F}}xn\index{+f} 
  } & 
{\raggedleft  Sets file output on; sets format x, depth n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-F}}xn\index{-f} 
  } & 
{\raggedleft  Sets file output off; but in future use format x, depth n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Output\_\-Alpha=}}bool\index{Output\_\-Alpha! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets alpha output on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UA}}\index{+ua} 
  } & 
{\raggedleft  Sets alpha output on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UA}}\index{-ua} 
  } & 
{\raggedleft  Sets alpha output off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Bits\_\-Per\_\-Color=}}n\index{Bits\_\-Per\_\-Color! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets file output bits/color to n } \\ 
 

\end{tabular*} \end{table}
\index{output formats}

   The default type of image file depends on which platform you are using. MS-\discretionary{}{}{}DOS and most others default to 24-bit uncompressed Targa. Windows defaults to 
 'sys', which is 24-bit BMP. See your platform-\discretionary{}{}{}specific documentation to see what your default file type is. You may select one of several different file types 
 using {\small\texttt{Output\_\-File\_\-Type=}}\textit{x} or {\small\texttt{+F}}\textit{x} where \textit{x} is one of the following... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{.. C}}\index{Targa output! compressed}\index{Output! Targa, compressed}\index{+fc} 
  } & 
{\raggedleft  \textbf{C}ompressed Targa-24 format (RLE, run length encoded) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{.. N}}\index{PNG output}\index{Output! PNG}\index{+fn} 
  } & 
{\raggedleft  P\textbf{N}G (portable network graphics) format } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{.. P}}\index{PPM output}\index{Output! PPM}\index{+fp} 
  } & 
{\raggedleft  Unix \textbf{P}PM format } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{.. S}}\index{System-\discretionary{}{}{}specific output}\index{Output! system-\discretionary{}{}{}specific}\index{Output! BMP}\index{BMP output}\index{+fs} 
   
  } & 
{\raggedleft  \textbf{S}ystem-\discretionary{}{}{}specific such as Mac Pict or Windows BMP } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{.. T}}\index{Targa output! uncompressed}\index{Output! Targa, uncompressed}\index{+ft} 
  } & 
{\raggedleft  Uncompressed \textbf{T}arga-24 format } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} the obsolete {\small\texttt{+FD}} dump format and {\small\texttt{+FR}} raw format have been dropped because they were rarely used and no 
 longer necessary. PPM, PNG, and system specific formats have been added. PPM format images are uncompressed, and have a simple text header, which makes it a 
 widely portable image format. PNG is an image format designed not only to replace GIF, but to improve on its shortcomings. PNG offers the highest compression 
 available without loss for high quality applications, such as ray-\discretionary{}{}{}tracing. The system specific format depends on the platform used and is covered in the 
 appropriate system specific documentation. 



   Most of these formats output 24 bits per pixel with 8 bits for each of red, green and blue data. PNG and PPM allow you to optionally specify the output bit 
 depth from 5 to 16 bits for each of the red, green, and blue colors, giving from 15 to 48 bits of color information per pixel. The default output depth for 
 all formats is 8 bits/color (16 million possible colors), but this may be changed for PNG and PPM format files by setting {\small\texttt{Bits\_\-Per\_\-Color=}}\textit{n} 
 or by specifying {\small\texttt{+FN}}\textit{n} or {\small\texttt{+FP}}\textit{n}, where n is the desired bit depth. 



   Specifying a smaller color depth like 5 bits/color (32768 colors) may be enough for people with 8- or 16-bit (256 or 65536 color) displays, and will improve 
 compression of the PNG file. Higher bit depths like 10 or 12 may be useful for video or publishing applications, and 16 bits/color is good for grayscale 
 height field output (See section ``Height Field'' for details on height fields). 



   Targa format also allows 8 bits of alpha transparency data to be output, while PNG format allows 5 to 16 bits of alpha transparency data, depending on the 
 color bit depth as specified above. You may turn this option on with {\small\texttt{ Output\_\-Alpha=on}} or {\small\texttt{+UA}}. The default is off or {\small\texttt{ 
 -UA}}. 



   The alpha channel stores a transparency value for each pixel, just like there is also stored a value for red green and blue light for each pixel. In POV-\discretionary{}{}{}Ray, 
 when the alpha channel is turned on, all areas of the image where the background is partly or fully visible will be partly or fully transparent. Refractions 
 of the background will also be transparent, but not reflections. Also anti-\discretionary{}{}{}aliasing is taken into account 



   The philosophy of the alpha channel feature in POV-\discretionary{}{}{}Ray is that the background color should not be present in the color of the image when the alpha channel is 
 used. Instead, the amount of visible background is kept in the alpha and *only* in the alpha channel. That ensures that images look correct when viewed with 
 the alpha channel. 



   See section ``Using the Alpha Channel'' for further details on using transparency in imagemaps in your scene. 



   In addition to support for variable bit-\discretionary{}{}{}depths, alpha channel, and grayscale formats, PNG files also store the {\small\texttt{ Display\_\-Gamma}} value so the 
 image displays properly on all systems (see section ``Display Hardware Settings''). The {\small\texttt{hf\_\-gray\_\-16}} global setting, as described in 
 section ``HF\_\-Gray\_\-16'' will also affect the type of data written to the output file. 


\subsubsection{Output File Name}

% reference/000503.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Output\_\-File\_\-Name=}}file\index{Output\_\-File\_\-Name! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets output file to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+O}}file\index{+o} 
  } & 
{\raggedleft  Same as {\small\texttt{Output\_\-File\_\-Name=}}file } \\ 
 

\end{tabular*} \end{table}


   The default output filename is created from the scene name and need not be specified. The scene name is the input name with all drive, path, and extension 
 information stripped. For example if the input file name is {\small\texttt{ c:$\backslash$povray3$\backslash$\discretionary{}{}{}mystuff$\backslash$\discretionary{myfile.}{}{myfile.}pov}} the scene name is {\small\texttt{ myfile}}. The 
 proper extension is appended to the scene name based on the file type. For example {\small\texttt{\discretionary{myfile.}{}{myfile.}tga}} or {\small\texttt{ \discretionary{myfile.}{}{myfile.}png}} might be used. 



   You may override the default output name using {\small\texttt{ Output\_\-File\_\-Name=}}\textit{file} or {\small\texttt{ +O}}\textit{file}. For example: 


{\small\begin{verbatim}
 Input_File_Name=myinput.pov
 Output_File_Name=myoutput.tga
\end{verbatim}}


   If an output file name of ``-'' is specified (a single minus sign), then the image will be written to standard output, usually the screen. The output 
 can then be piped into another program or to a GUI if desired. 



   \index{Default Output Directory}\index{Directory! default output}\index{Output File! placing in a default directory} If the file specified is actually a path 
 or directory or folder name and not a file name, then the default output name is used but it is written to the specified directory. For example: 


{\small\begin{verbatim}
 Input_File_Name=myscene.pov
 Output_File_Name=c:\povray3\myimages\
\end{verbatim}}


   This will create {\small\texttt{c:$\backslash$povray3$\backslash$\discretionary{}{}{}myimages$\backslash$\discretionary{myscene.}{}{myscene.}tga}} as the output file. 


\subsubsection{Output File Buffer}
\index{Buffer\_\-Output}\index{+b}\index{-b}\index{Buffer\_\-Size}

   The output-\discretionary{}{}{}file buffer options {\small\texttt{Buffer\_\-Output}} and {\small\texttt{Buffer\_\-Size}} are removed per POV-\discretionary{}{}{}Ray 3.6 



   \textbf{Note:} the options are still accepted, but ignored, in order to be backward compatible with old INI files. 


\subsubsection{CPU Utilization Histogram}

% reference/000504.html



   The CPU utilization histogram is a way of finding out where POV-\discretionary{}{}{}Ray is spending its rendering time, as well as an interesting way of generating heightfields. 
 The histogram splits up the screen into a rectangular grid of blocks. As POV-\discretionary{}{}{}Ray renders the image, it calculates the amount of time it spends rendering each 
 pixel and then adds this time to the total rendering time for each grid block. When the rendering is complete, the histogram is a file which represents how 
 much time was spent computing the pixels in each grid block. 



   Not all versions of POV-\discretionary{}{}{}Ray allow the creation of histograms. The histogram output is dependent on the file type and the system that POV-\discretionary{}{}{}Ray is being run on. 


\subsubsection{File Type}

\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Histogram\_\-Type=}}y\index{Histogram\_\-Type! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set histogram type to y (Turn off if type is '{\small\texttt{X}}') } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HT}}y\index{+ht} 
  } & 
{\raggedleft  Same as {\small\texttt{Histogram\_\-Type=}}y } \\ 
 

\end{tabular*} \end{table}


   The histogram output file type is nearly the same as that used for the image output file types in ``Output File Type''. The available histogram file 
 types are as follows. 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{+HTC}}\index{+htc} 
  } & 
{\raggedleft  Comma separated values (CSV) often used in spreadsheets } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HTN}}\index{+htn} 
  } & 
{\raggedleft  PNG (portable network graphics) format grayscale } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HTP}}\index{+htp} 
  } & 
{\raggedleft  Unix PPM format } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HTS}}\index{+hts} 
  } & 
{\raggedleft  System-\discretionary{}{}{}specific such as Mac Pict or Windows BMP } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HTT}}\index{+htt} 
  } & 
{\raggedleft  Uncompressed Targa-24 format (TGA) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HTX}}\index{+htx} 
  } & 
{\raggedleft  No histogram file output is generated } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} {\small\texttt{+HTC}} does not generate a compressed Targa-24 format output file but rather a text file with a comma-\discretionary{}{}{}separated list of the 
 time spent in each grid block, in left-\discretionary{}{}{}to-\discretionary{}{}{}right and top-\discretionary{}{}{}to bottom order. The units of time output to the CSV file are system dependent. See the system 
 specific documentation for further details on the time units in CSV files. 



   The Targa and PPM format files are in the POV heightfield format (see ``Height Field''), so the histogram information is stored in both the red and 
 green parts of the image, which makes it unsuitable for viewing. When used as a height field, lower values indicate less time spent calculating the pixels in 
 that block, while higher indicate more time spent in that block. 



   PNG format images are stored as grayscale images and are useful for both viewing the histogram data as well as for use as a heightfield. In PNG files, the 
 darker (lower) areas indicate less time spent in that grid block, while the brighter (higher) areas indicate more time spent in that grid block. 


\subsubsection{File Name}

% reference/000505.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Histogram\_\-Name=}}file\index{Histogram\_\-Name! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set histogram name to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HN}}file\index{+hn} 
  } & 
{\raggedleft  Same as {\small\texttt{Histogram\_\-Name=}}file } \\ 
 

\end{tabular*} \end{table}


   The histogram file name is the name of the file in which to write the histogram data. If the file name is not specified it will default to {\small\texttt{ 
 \discretionary{histogram.}{}{histogram.}ext}}, where {\small\texttt{ext}} is based on the file type specified previously. 



   \textbf{Note:} that if the histogram name is specified the file name extension should match the file type. 


\subsubsection{Grid Size}

% reference/000506.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Histogram\_\-Grid\_\-Size=}} \discretionary{nn.}{}{nn.}mm\index{Histogram\_\-Grid\_\-Size! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set histogram grid to nn by mm } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HS}}\discretionary{nn.}{}{nn.}mm\index{+hs} 
  } & 
{\raggedleft  Same as {\small\texttt{Histogram\_\-Grid\_\-Size=}}\discretionary{nn.}{}{nn.}mm } \\ 
 

\end{tabular*} \end{table}


   The histogram grid size gives the number of times the image is split up in both the horizontal and vertical directions. For example 


{\small\begin{verbatim}
 povray +Isample +W640 +H480 +HTN +HS160.120 +HNhistogram.png
\end{verbatim}}


   will split the image into 160*120 grid blocks, each of size 4*4 pixels, and output a PNG file, suitable for viewing or for use as a heightfield. Smaller 
 numbers for the grid size mean more pixels are put into the same grid block. With CSV output, the number of values output is the same as the number of grid 
 blocks specified. For the other formats the image size is identical to the rendered image rather than the specified grid size, to allow easy comparison 
 between the histogram and the rendered image. If the histogram grid size is not specified, it will default to the same size as the image, so there will be one 
 grid block per pixel. 



   \textbf{Note:} on systems that do task-\discretionary{}{}{}switching or multi-\discretionary{}{}{}tasking the histogram may not exactly represent the amount of time POV-\discretionary{}{}{}Ray spent in a given grid 
 block since the histogram is based on real time rather than CPU time. As a result, time may be spent for operating system overhead or on other tasks running 
 at the same time. This will cause the histogram to have speckling, noise or large spikes. This can be reduced by decreasing the grid size so that more pixels 
 are averaged into a given grid block. 


\subsection{Scene Parsing Options}

% reference/000507.html

\index{Options! parsing}

   POV-\discretionary{}{}{}Ray reads in your scene file and processes it to create an internal model of your scene. The process is called {\small\texttt{parsing}}. As your file is 
 parsed other files may be read along the way. This section covers options concerning what to parse, where to find it and what version specific assumptions it 
 should make while parsing it. 


\subsubsection{Constant}

% reference/000508.html

\index{ini files! constant}\index{Declare! ini-\discretionary{}{}{}option}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Declare=IDENTIFIER=FLOAT}} 
  } & 
{\raggedleft  Declares an identifier with a float value } \\ 
 

\end{tabular*} \end{table}


   You can now declare a constant in an INI file, and that constant will be available to the scene. Since INI file statements may also be laced on the 
 command-\discretionary{}{}{}line, you can therefore also declare on the command-\discretionary{}{}{}line (though there is no switch for it). 


{\small\begin{verbatim}  Declare=MyValue=24 \end{verbatim}}


   This would be the same as a {\small\texttt{\#declare MyValue=24;}} in a scene file. The value on the right-\discretionary{}{}{}hand side must be a constant float value. 



   A possible use could be switching off radiosity or photons from commandline: 


{\small\begin{verbatim}
  --in INI-file / on command-line

  Declare=RAD=0

  --in scenefile

  global_settings {
     #if (RAD)
        radiosity {
           ...
        }
     #end
  }
\end{verbatim}}

\subsubsection{Input File Name}

% reference/000509.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Input\_\-File\_\-Name=}}file\index{Input\_\-File\_\-Name! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets input file name to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+I}}file\index{+i} 
  } & 
{\raggedleft  Same as {\small\texttt{Input\_\-File\_\-Name=}}file } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} there may be no space between {\small\texttt{+I}} and {\small\texttt{file}}. 



   You will probably always set this option but if you do not the default input filename is {\small\texttt{\discretionary{object.}{}{object.}pov}}. If you do not have an extension then {\small\texttt{.pov}} 
 is assumed. On case-\discretionary{}{}{}sensitive operating systems both {\small\texttt{.pov}} and {\small\texttt{.POV}} are tried. A full path specification may be used (on 
 MS-\discretionary{}{}{}DOS systems {\small\texttt{ +Ic:$\backslash$povray3$\backslash$\discretionary{}{}{}mystuff$\backslash$\discretionary{myfile.}{}{myfile.}pov}} is allowed for example). In addition to specifying the input file name 
 this also establishes the \textit{scene name}. 



   The scene name is the input name with drive, path and extension stripped. In the above example the scene name is {\small\texttt{myfile}}. This name is used 
 to create a default output file name and it is referenced other places. 



   \textbf{Note:} as per version 3.5 you can now specify a POV file on the command-\discretionary{}{}{}line without the use of the +i switch (\discretionary{i.}{}{i.}e. it works the same way as 
 specifying an INI file without a switch), the POV file then should be the last on the commandline. 



   If you use "-" as the input file name the input will be read from standard input. Thus you can pipe a scene created by a program to POV-\discretionary{}{}{}Ray and 
 render it without having a scene file. 



   Under MS-\discretionary{}{}{}DOS you can try this feature by typing. 


{\small\begin{verbatim}
 type ANYSCENE.POV | povray +I-
\end{verbatim}}

\subsubsection{Include File Name}

% reference/000510.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Include\_\-Header=}}file\index{Include\_\-Header! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets primary include file name to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+HI}}file\index{+hi} 
  } & 
{\raggedleft  Same as {\small\texttt{Include\_\-Header=}}file } \\ 
 

\end{tabular*} \end{table}


   This option allows you to include a file as the first include file of a scene file. You can for example use this option to always include a specific set of 
 default include files used by all your scenes. 


\subsubsection{Library Paths}

% reference/000511.html

\index{Include Path}\index{Include Files! finding}\index{Finding include files}\index{Search Path}\index{Path! includ files}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Library\_\-Path=}}path\index{Library\_\-Path! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Add path to list of library paths } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+L}}path\index{+l} 
  } & 
{\raggedleft  Same as {\small\texttt{Library\_\-Path=}}path } \\ 
 

\end{tabular*} \end{table}


   POV-\discretionary{}{}{}Ray looks for files in the current directory. If it does not find a file it needs it looks in various other library directories which you specify. 
 POV-\discretionary{}{}{}Ray does not search your operating system path. It only searches the current directory and directories which you specify with this 
 option. For example the standard include files are usually kept in one special directory. You tell POV-\discretionary{}{}{}Ray to look there with... 


{\small\begin{verbatim}
 Library_Path=c:\povray3\include
\end{verbatim}}


   You must not specify any final path separators ("$\backslash$" or "/") at the end. 



   Multiple uses of this option switch do not override previous settings. Up to twenty unique paths may be specified. If you specify the exact same path twice 
 it is only counted once. The current directory will be searched first followed by the indicated library directories in the order in which you specified them. 


\subsubsection{Language Version}

% reference/000512.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Version=}}\discretionary{n.}{}{n.}n\index{Version! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set initial language compatibility to version \discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+MV}}\discretionary{n.}{}{n.}n\index{+mv} 
  } & 
{\raggedleft  Same as {\small\texttt{Version=}}\discretionary{n.}{}{n.}n } \\ 
 

\end{tabular*} \end{table}


   As POV-\discretionary{}{}{}Ray has evolved from version 1.0 through to today we have made every effort to maintain some amount of backwards compatibility with earlier versions. 
 Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at 
 all. However \textit{some} old features can still be used if you warn POV-\discretionary{}{}{}Ray that this is an older scene. In the POV-\discretionary{}{}{}Ray scene language you can use the {\small\texttt{\#version}} 
 directive to switch version compatibility to different settings. See section "The \#version Directive" for more details about the language version 
 directive. Additionally you may use the {\small\texttt{Version=}}\textit{\discretionary{n.}{}{n.}n} option or the {\small\texttt{+MV}}\textit{\discretionary{n.}{}{n.}n} switch to establish the \textit{initial} 
 setting. For example one feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Setting {\small\texttt{ 
 Version=1.0}} or using {\small\texttt{+MV1.0}} turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. 
 Naturally the default setting for this option is the current version number. 



   \textbf{Note:} some obsolete or re-\discretionary{}{}{}designed features \textit{are totally unavailable in the current version of POV-\discretionary{}{}{}Ray REGARDLES OF THE VERSION SETTING.} 
 Details on these features are noted throughout this documentation. 


\subsection{Shell-\discretionary{}{}{}out to Operating System}

% reference/000513.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Pre\_\-Scene\_\-Command=}}s\index{Pre\_\-Scene\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command before entire scene } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Pre\_\-Frame\_\-Command=}}s\index{Pre\_\-Frame\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command before each frame } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Post\_\-Scene\_\-Command=}}s\index{Post\_\-Scene\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command after entire scene } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Post\_\-Frame\_\-Command=}}s\index{Post\_\-Frame\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command after each frame } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{User\_\-Abort\_\-Command=}}s\index{User\_\-Abort\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command when user aborts POV-\discretionary{}{}{}Ray } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-Error\_\-Command=}}s\index{Fatal\_\-Error\_\-Command! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set command when POV-\discretionary{}{}{}Ray has fatal error } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} no {\small\texttt{+}} or {\small\texttt{-}} switches are available for these options. They cannot be used from the command line. They may only 
 be used from INI files. 



   POV-\discretionary{}{}{}Ray offers you the opportunity to shell-\discretionary{}{}{}out to the operating system at several key points to execute another program or batch file. Usually this is used 
 to manage files created by the internal animation loop however the shell commands are available for any scene. The string \textit{s} is a single line of text 
 which is passed to the operating system to execute a program. For example 


{\small\begin{verbatim}
 Post_Scene_Command=tga2gif -d -m myfile
\end{verbatim}}


   would use the utility {\small\texttt{tga2gif}} with the {\small\texttt{-D}} and {\small\texttt{-M}} parameters to convert {\small\texttt{\discretionary{myfile.}{}{myfile.}tga}} to {\small\texttt{ 
 \discretionary{myfile.}{}{myfile.}gif}} after the scene had finished rendering. 



   \textbf{Note:} individual platforms may provide means of preventing shell-\discretionary{}{}{}outs from occurring. For example, the Windows version provides a menu command to 
 turn shell-\discretionary{}{}{}outs off (which is the default setting for that platform). The reason for this (along with file I/O restrictions) is to attempt to prevent 
 untrusted INI files from doing harm to your system. 


\subsubsection{String Substitution in Shell Commands}

% reference/000514.html



   It could get cumbersome to change the {\small\texttt{Post\_\-Scene\_\-Command}} every time you changed scene names. POV-\discretionary{}{}{}Ray can substitute various values into a 
 command string for you. For example: 


{\small\begin{verbatim}
 Post_Scene_Command=tga2gif -d -m \%s
\end{verbatim}}


   POV-\discretionary{}{}{}Ray will substitute the {\small\texttt{\%s}} with the scene name in the command. The \textit{scene name} is the {\small\texttt{Input\_\-File\_\-Name}} or {\small\texttt{+I}} 
 setting with any drive, directory and extension removed. For example: 


{\small\begin{verbatim}
 Input_File_Name=c:\povray3\scenes\waycool.pov
\end{verbatim}}


   is stripped down to the scene name {\small\texttt{waycool}} which results in... 


{\small\begin{verbatim}
 Post_Scene_Command=tga2gif -d -m waycool
\end{verbatim}}


   In an animation it may be necessary to have the exact output file name with the frame number included. The string {\small\texttt{\%o}} will substitute the 
 output file name. Suppose you want to save your output files in a zip archive using the utility program {\small\texttt{pkzip}}. You could do... 


{\small\begin{verbatim}
 Post_Frame_Command=pkzip -m \%s \%o
\end{verbatim}}


   After rendering frame 12 of {\small\texttt{\discretionary{myscene.}{}{myscene.}pov}} POV-\discretionary{}{}{}Ray would shell to the operating system with 


{\small\begin{verbatim}
 pkzip -m myscene mysce012.tga
\end{verbatim}}


   The {\small\texttt{-M}} switch in {\small\texttt{pkzip}} moves {\small\texttt{ \discretionary{mysce012.}{}{mysce012.}tga}} to {\small\texttt{\discretionary{myscene.}{}{myscene.}zip}} and removes it from the 
 directory. Note that {\small\texttt{\%o}} includes frame numbers only when in an animation loop. During the {\small\texttt{Pre\_\-Scene\_\-Command}} and {\small\texttt{ 
 Post\_\-Scene\_\-Command}} there is no frame number so the original, unnumbered {\small\texttt{Output\_\-File\_\-Name}} is used. Any {\small\texttt{ 
 User\_\-Abort\_\-Command}} or {\small\texttt{Fatal\_\-Error\_\-Command}} not inside the loop will similarly give an unnumbered {\small\texttt{\%o}} substitution. 



   Here is the complete list of substitutions available for a command string. 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{\%o}} 
  } & 
{\raggedleft  Output file name with extension and embedded frame number if any } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%s}} 
  } & 
{\raggedleft  Scene name derived by stripping path and ext from input name } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%n}} 
  } & 
{\raggedleft  Frame number of this frame } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%k}} 
  } & 
{\raggedleft  Clock value of this frame } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%h}} 
  } & 
{\raggedleft  Height of image in pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%w}} 
  } & 
{\raggedleft  Width of image in pixels } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{\%\%}} 
  } & 
{\raggedleft  A single \% sign. } \\ 
 

\end{tabular*} \end{table}

\subsubsection{Shell Command Sequencing}

% reference/000515.html



   Here is the sequence of events in an animation loop. Non-\discretionary{}{}{}animated scenes work the exact same way except there is no loop. 


\begin{enumerate}
 
 \item 
   Process all INI file keywords and command line switches just once. 
 

 \item 
   Open any text output streams and do Create\_\-INI if any. 
 

 \item 
   Execute Pre\_\-Scene\_\-Command if any. 
 

 \item 
   Loop through frames (or just do once on non-\discretionary{}{}{}animation). 
  \begin{enumerate}
   
   \item 
     Execute Pre\_\-Frame\_\-Command if any. 
   

   \item 
     Parse entire scene file, open output file and read settings, turn on display, render the frame, destroy all objects, textures etc., close output 
    file, close display. 
   

   \item 
     Execute Post\_\-Frame\_\-Command if any. 
   

   \item 
     Repeat above steps until all frames are done. 
   

  \end{enumerate}
   
 

 \item 
   Execute Post\_\-Scene\_\-Command if any. 
 

 \item 
   Finish 
 

\end{enumerate}


   If the user interrupts processing the {\small\texttt{User\_\-Abort\_\-Command}}, if any, is executed. User aborts can only occur during the parsing and rendering 
 parts of step (4b) above. If a fatal error occurs that POV-\discretionary{}{}{}Ray notices the {\small\texttt{Fatal\_\-Error\_\-Command}}, if any, is executed. Sometimes an unforeseen 
 bug or memory error could cause a total crash of the program in which case there is no chance to shell out. Fatal errors can occur just about anywhere 
 including during the processing of switches or INI files. If a fatal error occurs before POV-\discretionary{}{}{}Ray has read the {\small\texttt{ Fatal\_\-Error\_\-Command}} string 
 then obviously no shell can occur. 



   \textbf{Note:} the entire scene is re-\discretionary{}{}{}parsed for every frame. Future versions of POV-\discretionary{}{}{}Ray may allow you to hold over parts of a scene from one frame to the 
 next but for now it starts from scratch every time. 



   \textbf{Note:} that the {\small\texttt{Pre\_\-Frame\_\-Command}} occurs before the scene is parsed. You might use this to call some custom scene generation utility 
 before each frame. This utility could rewrite your {\small\texttt{ .pov}} or {\small\texttt{.inc}} files if needed. Perhaps you will want to generate new {\small\texttt{.gif}} 
 or {\small\texttt{.tga}} files for image maps or height fields on each frame. 


\subsubsection{Shell Command Return Actions}

% reference/000516.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Pre\_\-Scene\_\-Return=}}s\index{Pre\_\-Scene\_\-Return} 
  } & 
{\raggedleft  Set pre scene return actions } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Pre\_\-Frame\_\-Return=}}s\index{Pre\_\-Frame\_\-Return} 
  } & 
{\raggedleft  Set pre frame return actions } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Post\_\-Scene\_\-Return=}}s\index{Post\_\-Scene\_\-Return} 
  } & 
{\raggedleft  Set post scene return actions } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Post\_\-Frame\_\-Return=}}s\index{Post\_\-Frame\_\-Return} 
  } & 
{\raggedleft  Set post frame return actions } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{User\_\-Abort\_\-Return=}}s\index{User\_\-Abort\_\-Return} 
  } & 
{\raggedleft  Set user abort return actions } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-Error\_\-Return=}}s\index{Fatal\_\-Error\_\-Return} 
  } & 
{\raggedleft  Set fatal return actions } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} that no {\small\texttt{+}} or {\small\texttt{-}} switches are available for these options. They cannot be used from the command line. They may 
 only be used from INI files. 



   Most operating systems allow application programs to return an error code if something goes wrong. When POV-\discretionary{}{}{}Ray executes a shell command it can make use of 
 this error code returned from the shell process and take some appropriate action if the code is zero or non-\discretionary{}{}{}zero. POV-\discretionary{}{}{}Ray itself returns such codes. It 
 returns 0 for success, 1 for fatal error and 2 for user abort. 



   The actions are designated by a single letter in the different {\small\texttt{ ...\_Return}}=s options. The possible actions are: 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{I}} 
  } & 
{\raggedleft  ignore the code } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{S}} 
  } & 
{\raggedleft  skip one step } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{A}} 
  } & 
{\raggedleft  all steps skipped } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Q}} 
  } & 
{\raggedleft  quit POV-\discretionary{}{}{}Ray immediately } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{U}} 
  } & 
{\raggedleft  generate a user abort in POV-\discretionary{}{}{}Ray } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{F}} 
  } & 
{\raggedleft  generate a fatal error in POV-\discretionary{}{}{}Ray } \\ 
 

\end{tabular*} \end{table}


   For example if your {\small\texttt{Pre\_\-Frame\_\-Command}} calls a program which generates your height field data and that utility fails then it will return a 
 non-\discretionary{}{}{}zero code. We would probably want POV-\discretionary{}{}{}Ray to abort as well. The option {\small\texttt{Pre\_\-Frame\_\-Return=F}} will cause POV-\discretionary{}{}{}Ray to do a 
 fatal abort if the {\small\texttt{Pre\_\-Frame\_\-Command}} returns a non-\discretionary{}{}{}zero code. 



   Sometimes a non-\discretionary{}{}{}zero code from the external process is a good thing. Suppose you want to test if a frame has already been rendered. You could use the {\small\texttt{S}} 
 action to skip this frame if the file is already rendered. Most utilities report an error if the file is not found. For example the command... 


{\small\begin{verbatim}
 pkzip -V myscene mysce012.tga
\end{verbatim}}


   tells pkzip you want to view the catalog of {\small\texttt{\discretionary{myscene.}{}{myscene.}zip}} for the file {\small\texttt{\discretionary{mysce012.}{}{mysce012.}tga}}. If the file is not in the archive {\small\texttt{pkzip}} 
 returns a non-\discretionary{}{}{}zero code. 



   However we want to skip if the file is found. Therefore we need to reverse the action so it skips on zero and does not skip on non-\discretionary{}{}{}zero. To reverse the zero 
 vs. non-\discretionary{}{}{}zero triggering of an action precede it with a "{\small\texttt{-}}" sign (note a "{\small\texttt{!}}" will also work since it is 
 used in many programming languages as a negate operator). 



   {\small\texttt{ Pre\_\-Frame\_\-Return=S}} will skip if the code shows error (non-\discretionary{}{}{}zero) and will proceed normally on no error (zero). {\small\texttt{ 
 Pre\_\-Frame\_\-Return=-S}} will skip if there is no error (zero) and will proceed normally if there is an error (non-\discretionary{}{}{}zero). 



   The default for all shells is {\small\texttt{I}} which means that the return action is ignored no matter what. POV-\discretionary{}{}{}Ray simply proceeds with whatever it was 
 doing before the shell command. The other actions depend upon the context. You may want to refer back to the animation loop sequence chart in the previous 
 section "Shell Command Sequencing". The action for each shell is as follows. 



   On return from any User\_\-Abort\_\-Command if there is an action triggered... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    ...and you have specified... 
  } & 
{\raggedleft  ...then POV-\discretionary{}{}{}Ray will.. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{F}} 
  } & 
{\raggedleft  Then turn this user abort into a fatal error. Do the {\small\texttt{ Fatal\_\-Error\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with error code 1. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{S}}, {\small\texttt{A}}, {\small\texttt{Q}}, or {\small\texttt{ U}} 
  } & 
{\raggedleft  Then proceed with the user abort. Exit POV-\discretionary{}{}{}Ray with error code 2. } \\ 
 

\end{tabular*} \end{table}


   On return from any {\small\texttt{Fatal\_\-Error\_\-Command}} then POV-\discretionary{}{}{}Ray will proceed with the fatal error no matter what. It will exit POV-\discretionary{}{}{}Ray with error code 
 1. 



   On return from any {\small\texttt{Pre\_\-Scene\_\-Command}}, {\small\texttt{ Pre\_\-Frame\_\-Command}}, {\small\texttt{Post\_\-Frame\_\-Command}} or {\small\texttt{ 
 Post\_\-Scene\_\-Commands}} if there is an action triggered... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    ...and you have specified... 
  } & 
{\raggedleft  ...then POV-\discretionary{}{}{}Ray will... } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{F}} 
  } & 
{\raggedleft  ...turn this user abort into a fatal error. Do the {\small\texttt{ Fatal\_\-Error\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with error code 1. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{U}} 
  } & 
{\raggedleft  ...generate a user abort. Do the {\small\texttt{User\_\-Abort\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with an error code 2. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Q}} 
  } & 
{\raggedleft  ..quit POV-\discretionary{}{}{}Ray immediately. Acts as though POV-\discretionary{}{}{}Ray never really ran. Do no further shells, (not even a {\small\texttt{Post\_\-Scene\_\-Command}}) and 
  exit POV-\discretionary{}{}{}Ray with an error code 0. } \\ 
 

\end{tabular*} \end{table}


   On return from a {\small\texttt{Pre\_\-Scene\_\-Command}} if there is an action triggered... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    ...and you have specified... 
  } & 
{\raggedleft  ...then POV-\discretionary{}{}{}Ray will... } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{S}} 
  } & 
{\raggedleft  ...skip rendering all frames. Acts as though the scene completed all frames normally. Do not do any {\small\texttt{Pre\_\-Frame\_\-Command}} or {\small\texttt{ 
  Post\_\-Frame\_\-Commands}}. Do the {\small\texttt{ Post\_\-Scene\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with error code 0. On the earlier chart this means skip step 
  \#4. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{A}} 
  } & 
{\raggedleft  ...skip all scene activity. Works exactly like {\small\texttt{Q}} quit. On the earlier chart this means skip to step \#6. Acts as though POV-\discretionary{}{}{}Ray 
  never really ran. Do no further shells, (not even a {\small\texttt{ Post\_\-Scene\_\-Command}}) and exit POV-\discretionary{}{}{}Ray with an error code 0. } \\ 
 

\end{tabular*} \end{table}


   On return from a {\small\texttt{Pre\_\-Frame\_\-Command}} if there is an action triggered... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    ...and you have specified... 
  } & 
{\raggedleft  ...then POV-\discretionary{}{}{}Ray will... } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{S}} 
  } & 
{\raggedleft  ...skip only this frame. Acts as though this frame never existed. Do not do the {\small\texttt{Post\_\-Frame\_\-Command}}. Proceed with the next frame. 
  On the earlier chart this means skip steps (4b) and (4c) but loop back as needed in (4d). } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{A}} 
  } & 
{\raggedleft  ...skip rendering this frame and all remaining frames. Acts as though the scene completed all frames normally. Do not do any further {\small\texttt{ 
  Post\_\-Frame\_\-Commands}}. Do the {\small\texttt{Post\_\-Scene\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with error code 0. On the earlier chart this means skip the 
  rest of step (4) and proceed at step (5). } \\ 
 

\end{tabular*} \end{table}


   On return from a {\small\texttt{Post\_\-Frame\_\-Command}} if there is an action triggered... 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    ...and you have specified... 
  } & 
{\raggedleft  ...then POV-\discretionary{}{}{}Ray will... } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{S}} or {\small\texttt{A}} 
  } & 
{\raggedleft  ...skip all remaining frames. Acts as though the scene completed all frames normally. Do not do any further {\small\texttt{ Post\_\-Frame\_\-Commands}}. 
  Do the {\small\texttt{Post\_\-Scene\_\-Command}}, if any. Exit POV-\discretionary{}{}{}Ray with error code 0. On the earlier chart this means skip the rest of step (4) and proceed at 
  step (5). } \\ 
 

\end{tabular*} \end{table}


   On return from any {\small\texttt{Post\_\-Scene\_\-Command}} if there is an action triggered and you have specified {\small\texttt{S}} or {\small\texttt{A}} then 
 no special action occurs. This is the same as {\small\texttt{I}} for this shell command. 


\subsection{Text Output}

% reference/000517.html

\index{Options! text output}

   Text output is an important way that POV-\discretionary{}{}{}Ray keeps you informed about what it is going to do, what it is doing and what it did. The program splits its text 
 messages into 7 separate streams. Some versions of POV-\discretionary{}{}{}Ray color-\discretionary{}{}{}codes the various types of text. Some versions allow you to scroll back several pages of 
 messages. All versions allow you to turn some of these text streams off/on or to direct a copy of the text output to one or several files. This section 
 details the options which give you control over text output. 


\subsubsection{Text Streams}

% reference/000518.html

\index{streams}\index{text streams}\index{output! streams}

   There are seven distinct text streams that POV-\discretionary{}{}{}Ray uses for output. On some versions each stream is designated by a particular color. Text from these streams 
 are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the 
 streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-\discretionary{}{}{}back buffer. 



   Here is a description of each stream. 



   \textbf{ Banner:} This stream displays the program's sign-\discretionary{}{}{}on banner, copyright, contributor's list, and some help screens. It cannot be turned off or 
 directed to a file because most of this text is displayed before any options or switches are read. Therefore you cannot use an option or switch to control it. 
 There are switches which display the help screens. They are covered in section "Help Screen Switches". 



   \textbf{ Debug:} This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to 
 display messages from within their scene files. See section "Text Message Streams" for details on this feature. This stream may be turned off and/or 
 directed to a text file. 



   \textbf{Fatal:} This stream displays fatal error messages. After displaying this text, POV-\discretionary{}{}{}Ray will terminate. When the error is a scene parsing error, you 
 may be shown several lines of scene text that leads up to the error. This stream may be turned off and/or directed to a text file. 



   \textbf{Render:} This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options 
 such as scene name, resolution, animation settings, anti-\discretionary{}{}{}aliasing and others. This stream may be turned off and/or directed to a text file. 



   \textbf{ Statistics:} This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time 
 of the processing and other information. This stream may be turned off and/or directed to a text file. 



   \textbf{Status:} This stream displays one-\discretionary{}{}{}line status messages that explain what POV-\discretionary{}{}{}Ray is doing at the moment. On some systems this stream is displayed on 
 a status line at the bottom of the screen. This stream cannot be directed to a file because there is generally no need to. The text displayed by the {\small\texttt{ 
 Verbose}} option or {\small\texttt{+V}} switch is output to this stream so that part of the status stream may be turned off. 



   \textbf{ Warning:} This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-\discretionary{}{}{}Ray can continue to 
 render the scene. You will be informed if POV-\discretionary{}{}{}Ray has made any assumptions about your scene so that it can proceed. In general any time you see a warning, you 
 should also assume that this means that future versions of POV-\discretionary{}{}{}Ray will not allow the warned action. Therefore you should attempt to eliminate warning 
 messages so your scene will be able to run in future versions of POV-\discretionary{}{}{}Ray. This stream may be turned off and/or directed to a text file. 


\subsubsection{Console Text Output}

% reference/000519.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Debug\_\-Console=}}bool\index{Debug\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn console display of debug info text on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GD}}\index{+gd} 
  } & 
{\raggedleft  Same as {\small\texttt{Debug\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GD}}\index{-gd} 
  } & 
{\raggedleft  Same as {\small\texttt{Debug\_\-Console=Off}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-Console=}}bool\index{Fatal\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn console display of fatal error text on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GF}}\index{+gf} 
  } & 
{\raggedleft  Same as {\small\texttt{Fatal\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GF}}\index{-gf} 
  } & 
{\raggedleft  Same as {\small\texttt{Fatal\_\-Console=Off}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Render\_\-Console=}}bool\index{Render\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn console display of render info text on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GR}}\index{+gr} 
  } & 
{\raggedleft  Same as {\small\texttt{Render\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GR}}\index{-gr} 
  } & 
{\raggedleft  Same as {\small\texttt{Render\_\-Console=Off}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Statistic\_\-Console=}}bool\index{Statistic\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn console display of statistic text on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GS}}\index{+gs} 
  } & 
{\raggedleft  Same as {\small\texttt{Statistic\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GS}}\index{-gs} 
  } & 
{\raggedleft  Same as {\small\texttt{Statistic\_\-Console=Off}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Warning\_\-Console=}}bool\index{Warning\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn console display of warning text on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GW}}\index{+gw} 
  } & 
{\raggedleft  Same as {\small\texttt{Warning\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GW}}\index{-gw} 
  } & 
{\raggedleft  Same as {\small\texttt{Warning\_\-Console=Off}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{All\_\-Console=}}bool\index{All\_\-Console! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn on/off all debug, fatal, render, statistic and warning text to console. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GA}}\index{+ga} 
  } & 
{\raggedleft  Same as {\small\texttt{All\_\-Console=On}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GA}}\index{-ga} 
  } & 
{\raggedleft  Same as {\small\texttt{All\_\-Console=Off}} } \\ 
 

\end{tabular*} \end{table}


   You may suppress the output to the console of the debug, fatal, render, statistic or warning text streams. For example the {\small\texttt{ 
 Statistic\_\-Console=off}} option or the {\small\texttt{-GS}} switch can turn off the statistic stream. Using {\small\texttt{on}} or {\small\texttt{+GS}} you 
 may turn it on again. You may also turn all five of these streams on or off at once using the {\small\texttt{All\_\-Console}} option or {\small\texttt{+GA}} 
 switch. 



   \textbf{Note:} that these options take effect immediately when specified. Obviously any error or warning messages that might occur before the option is read 
 are not be affected. 


\subsubsection{Directing Text Streams to Files}

% reference/000520.html

\index{redirecting stream output}\index{streams! redirecting}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Debug\_\-File=true}}\index{Debug\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo debug info text to \discretionary{DEBUG.}{}{DEBUG.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Debug\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of debug info } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Debug\_\-File=file}} 
  } & 
{\raggedleft  Echo debug info text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GDfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Debug\_\-Console=On, Debug\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GDfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Debug\_\-Console=Off, Debug\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-File=true}}\index{Fatal\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo fatal text to \discretionary{FATAL.}{}{FATAL.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of fatal } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Fatal\_\-File=file}} 
  } & 
{\raggedleft  Echo fatal info text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GFfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Fatal\_\-Console=On, Fatal\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GFfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Fatal\_\-Console=Off, Fatal\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Render\_\-File=true}}\index{Render\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo render info text to \discretionary{RENDER.}{}{RENDER.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Render\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of render info } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Render\_\-File=}}file 
  } & 
{\raggedleft  Echo render info text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GR}}file 
  } & 
{\raggedleft  Both {\small\texttt{Render\_\-Console=On, Render\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GRfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Render\_\-Console=Off, Render\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Statistic\_\-File=true}}\index{Statistic\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo statistic text to \discretionary{STATS.}{}{STATS.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Statistic\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of statistics } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Statistic\_\-File=file}} 
  } & 
{\raggedleft  Echo statistic text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GS}}file 
  } & 
{\raggedleft  Both {\small\texttt{Statistic\_\-Console=On, Statistic\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GS}}file 
  } & 
{\raggedleft  Both {\small\texttt{Statistic\_\-Console=Off, Statistic\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Warning\_\-File=true}}\index{Warning\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo warning info text to \discretionary{WARNING.}{}{WARNING.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Warning\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of warning info } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Warning\_\-File=file}} 
  } & 
{\raggedleft  Echo warning info text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GWfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Warning\_\-Console=On, Warning\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GWfile}} 
  } & 
{\raggedleft  Both {\small\texttt{Warning\_\-Console=Off, Warning\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{All\_\-File=true}}\index{All\_\-File! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Echo all debug, fatal, render, statistic, and warning text to \discretionary{ALLTEXT.}{}{ALLTEXT.}OUT } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{All\_\-File=false}} 
  } & 
{\raggedleft  Turn off file output of all debug, fatal, render, statistic, and warning text. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{All\_\-File=file}} 
  } & 
{\raggedleft  Echo all debug, fatal, render, statistic, and warning text to file } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+GAfile}} 
  } & 
{\raggedleft  Both {\small\texttt{All\_\-Console=On, All\_\-File=file}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-GAfile}} 
  } & 
{\raggedleft  Both {\small\texttt{All\_\-Console=Off, All\_\-File=file}} } \\ 
 

\end{tabular*} \end{table}


   You may direct a copy of the text streams to a text file for the debug, fatal, render, statistic, or warning text streams. For example the {\small\texttt{ 
 Statistic\_\-File}}=\textit{s} option or the {\small\texttt{+GS}}\textit{s} switch. If the string \textit{s} is {\small\texttt{true}} or any of the other 
 valid {\small\texttt{true}} strings then that stream is redirected to a file with a default name. Valid {\small\texttt{true}} values are {\small\texttt{true}}, 
 {\small\texttt{ yes}}, {\small\texttt{on}} or {\small\texttt{1}}. If the value is {\small\texttt{ false}} the direction to a text file is turned off. Valid {\small\texttt{ 
 false}} values are {\small\texttt{false}}, {\small\texttt{no}}, {\small\texttt{ off}} or {\small\texttt{0}}. Any other string specified turns on file output 
 and the string is interpreted as the output file name. 



   Similarly you may specify such a true, false or file name string after a switch such as {\small\texttt{ +GS}}\textit{file}. You may also direct all five 
 streams to the same file using the {\small\texttt{All\_\-File}} option or {\small\texttt{ +GA}} switch. You may not specify the same file for two or more streams 
 because POV-\discretionary{}{}{}Ray will fail when it tries to open or close the same file twice. 



   \textbf{Note:} that these options take effect immediately when specified. Obviously any error or warning messages that might occur before the option is read 
 will not be affected. 


\subsubsection{Warning Level}

% reference/000521.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Warning\_\-Level=n}}\index{Warning\_\-Level! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Allows you to turn off classes of warnings. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+WLn}}\index{+wl} 
  } & 
{\raggedleft  Same as {\small\texttt{Warning\_\-Level=n}} } \\ 
 

\end{tabular*} \end{table}


   Level 0 turns off all warnings. Level 5 turns off all language version related warnings. The default is level 10 and it enables all warnings. All other 
 levels are reserved and should not be specified. 


\subsubsection{Help Screen Switches}

% reference/000522.html

\index{Options! help screen}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{-?}}\index{-h} 
  } & 
{\raggedleft  Show help screen 0 if this is the only switch } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} there are no INI style equivalents to these options. 



   After displaying the help screens, POV-\discretionary{}{}{}Ray terminates. Because some operating systems do not permit a question mark as a command line switch you may also use 
 the {\small\texttt{+H}} switch. 



   \textbf{Note:} this switch is also used to specify the height of the image in pixels. Therefore the {\small\texttt{ +H}} switch is only interpreted as a help 
 switch if it is the only switch on the command line. 



   Graphical interface versions of POV-\discretionary{}{}{}Ray such as Mac or Windows have extensive online help. 


\subsection{Tracing Options}

% reference/000523.html

\index{Options! tracing}\index{Options! rendering}

   There is more than one way to trace a ray. Sometimes there is a trade-\discretionary{}{}{}off between quality and speed. Sometimes options designed to make tracing faster can 
 slow things down. This section covers options that tell POV-\discretionary{}{}{}Ray how to trace rays with the appropriate speed and quality settings. 


\subsubsection{Quality Settings}

% reference/000524.html


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Quality=}}n\index{Quality! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set quality value to n (0 $<$= n $<$= 11) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+Q}}n\index{+q} 
  } & 
{\raggedleft  Same as {\small\texttt{Quality=}}n } \\ 
 

\end{tabular*} \end{table}


   The {\small\texttt{Quality=}}\textit{n} option or {\small\texttt{+Q}}\textit{n} switch allows you to specify the image rendering quality. You may choose to 
 lower the quality for test rendering and raise it for final renders. The quality adjustments are made by eliminating some of the calculations that are 
 normally performed. For example settings below 4 do not render shadows. Settings below 8 do not use reflection or refraction. The duplicate values allow for 
 future expansion. The values correspond to the following quality levels: 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{0, 1}} 
  } & 
{\raggedleft  Just show quick colors. Use full ambient lighting only. Quick colors are used only at 5 or below. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{2, 3}} 
  } & 
{\raggedleft  Show specified diffuse and ambient light. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{4}} 
  } & 
{\raggedleft  Render shadows, but no extended lights. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{5}} 
  } & 
{\raggedleft  Render shadows, including extended lights. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{6, 7}} 
  } & 
{\raggedleft  Compute texture patterns, compute photons } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{8}} 
  } & 
{\raggedleft  Compute reflected, refracted, and transmitted rays. } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{9, 10, 11}} 
  } & 
{\raggedleft  Compute media and radiosity } \\ 
 

\end{tabular*} \end{table}


   The default is 9 if not specified. 


\subsubsection{Automatic Bounding Control}

% reference/000525.html

\index{Options! bounding, automatic}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Bounding=}}bool\index{Bounding! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn bounding on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+MB}}\index{+mb} 
  } & 
{\raggedleft  Turn bounding on; Set threshold to 25 or previous amount } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-MB}}\index{-mb} 
  } & 
{\raggedleft  Turn bounding off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Bounding\_\-Threshold=}}n\index{Bounding\_\-Threshold! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Set bound threshold to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+MB}}n 
  } & 
{\raggedleft  Turn bounding on; bound threshold to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-MB}}n 
  } & 
{\raggedleft  Turn bounding off; set future threshold to n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Light\_\-Buffer=}}bool\index{Light\_\-Buffer! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn light buffer on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UL}}\index{+ul} 
  } & 
{\raggedleft  Turn light buffer on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UL}}\index{-ul} 
  } & 
{\raggedleft  Turn light buffer off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Vista\_\-Buffer=}}bool\index{Vista\_\-Buffer! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn vista buffer on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UV}}\index{+uv} 
  } & 
{\raggedleft  Turn vista buffer on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UV}}\index{-uv} 
  } & 
{\raggedleft  Turn vista buffer off } \\ 
 

\end{tabular*} \end{table}


   POV-\discretionary{}{}{}Ray uses a variety of spatial sub-\discretionary{}{}{}division systems to speed up ray-\discretionary{}{}{}object intersection tests. The primary system uses a hierarchy of nested bounding 
 boxes. This system compartmentalizes all finite objects in a scene into invisible rectangular boxes that are arranged in a tree-\discretionary{}{}{}like hierarchy. Before testing 
 the objects within the bounding boxes the tree is descended and only those objects are tested whose bounds are hit by a ray. This can greatly improve 
 rendering speed. However for scenes with only a few objects the overhead of using a bounding system is not worth the effort. The {\small\texttt{ Bounding=off}} 
 option or {\small\texttt{-MB}} switch allows you to force bounding off. The default value is on. 



   The {\small\texttt{ Bounding\_\-Threshold=}}\textit{n} or {\small\texttt{ +MB}}\textit{n} switch allows you to set the minimum number of objects necessary 
 before bounding is used. The default is {\small\texttt{+MB25}} which means that if your scene has fewer than 25 objects POV-\discretionary{}{}{}Ray will automatically turn 
 bounding off because the overhead is not worth it. Generally it is a good idea to use a much lower threshold like {\small\texttt{+MB5}}. 



   Additionally POV-\discretionary{}{}{}Ray uses systems known as \textit{vista buffers} and \textit{ light buffers} to further speed things up. These systems only work when 
 bounding is on and when there are a sufficient number of objects to meet the bounding threshold. The vista buffer is created by projecting the bounding box 
 hierarchy onto the screen and determining the rectangular areas that are covered by each of the elements in the hierarchy. Only those objects whose rectangles 
 enclose a given pixel are tested by the primary viewing ray. The vista buffer can only be used with perspective and orthographic cameras because they rely on 
 a fixed viewpoint and a reasonable projection (i. e. straight lines have to stay straight lines after the projection). 



   The light buffer is created by enclosing each light source in an imaginary box and projecting the bounding box hierarchy onto each of its six sides. Since 
 this relies on a fixed light source, light buffers will not be used for area lights. 



   Reflected and transmitted rays do not take advantage of the light and vista buffer. 



   The default settings are {\small\texttt{ Vista\_\-Buffer=on}} or {\small\texttt{+UV}} and {\small\texttt{ Light\_\-Buffer=on}} or {\small\texttt{+UL}}. The option 
 to turn these features off is available to demonstrate their usefulness and as protection against unforeseen bugs which might exist in any of these bounding 
 systems. 



   In general, any finite object and many types of CSG of finite objects will properly respond to this bounding system. In addition blobs and meshes use an 
 additional internal bounding system. These systems are not affected by the above switch. They can be switched off using the appropriate syntax in the scene 
 file (see "Blob" and "Mesh" for details). 



   Text objects are split into individual letters that are bounded using the bounding box hierarchy. Some CSG combinations of finite and infinite objects are 
 also automatically bound. The end result is that you will rarely need to add manual bounding objects as was necessary in earlier versions of POV-\discretionary{}{}{}Ray unless 
 you use many infinite objects. 


\subsubsection{Removing User Bounding}

% reference/000526.html

\index{Options! bounding, manual}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Remove\_\-Bounds=}}bool\index{Remove\_\-Bounds! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn unnecessary bounds removal on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+UR}}\index{+ur} 
  } & 
{\raggedleft  Turn unnecessary bounds removal on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-UR}}\index{-ur} 
  } & 
{\raggedleft  Turn unnecessary bounds removal off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Split\_\-Unions=}}bool\index{Split\_\-Unions! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turn split bounded unions on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+SU}}\index{+su} 
  } & 
{\raggedleft  Turn split bounded unions on } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-SU}}\index{-su} 
  } & 
{\raggedleft  Turn split bounded unions off } \\ 
 

\end{tabular*} \end{table}


   Early versions of POV-\discretionary{}{}{}Ray had no system of automatic bounding or spatial sub-\discretionary{}{}{}division to speed up ray-\discretionary{}{}{}object intersection tests. Users had to manually create 
 bounding boxes to speed up the rendering. Since version 3.0, POV-\discretionary{}{}{}Ray has had more sophisticated automatic bounding than any previous version. In many cases 
 the manual bounding on older scenes is slower than the new automatic systems. Therefore POV-\discretionary{}{}{}Ray removes manual bounding when it knows it will help. In rare 
 instances you may want to keep manual bounding. Some older scenes incorrectly used bounding when they should have used clipping. If POV-\discretionary{}{}{}Ray removes the bounds 
 in these scenes the image will not look right. To turn off the automatic removal of manual bounds you should specify {\small\texttt{ Remove\_\-Bounds=off}} or 
 use {\small\texttt{ -UR}}. The default is {\small\texttt{ Remove\_\-Bounds=on}}. 



   One area where the jury is still out is the splitting of manually bounded unions. Unbounded unions are always split into their component parts so that 
 automatic bounding works better. Most users do not bound unions because they know that doing so is usually slower. If you do manually bound a union we presume 
 you really want it bound. For safety sake we do not presume to remove such bounds. If you want to remove manual bounds from unions you should specify {\small\texttt{Split\_\-Unions=on}} 
 or use {\small\texttt{ +SU}}. The default is {\small\texttt{Split\_\-Unions=off}}. 


\subsubsection{Anti-\discretionary{}{}{}Aliasing Options}

% reference/000527.html

\index{Options! anti-\discretionary{}{}{}aliasing}
\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{Antialias=}}bool\index{Antialias! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Turns anti-\discretionary{}{}{}aliasing on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+A}}\index{+a} 
  } & 
{\raggedleft  Turns aa on with threshold 0.3 or previous amount } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-A}}\index{-a} 
  } & 
{\raggedleft  Turns anti-\discretionary{}{}{}aliasing off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Sampling\_\-Method=}}n\index{Sampling\_\-Method! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}sampling method (only {\small\texttt{1}} or {\small\texttt{2}} are valid) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+AM}}n\index{+am} 
  } & 
{\raggedleft  Same as {\small\texttt{Sampling\_\-Method=}}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Antialias\_\-Threshold=}}\discretionary{n.}{}{n.}n\index{Antialias\_\-Threshold! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets anti-\discretionary{}{}{}aliasing threshold } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+A}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Sets aa on with aa-\discretionary{}{}{}threshold at \discretionary{n.}{}{n.}n } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-A}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Sets aa off (aa-\discretionary{}{}{}threshold \discretionary{n.}{}{n.}n in future) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Jitter=}}bool\index{Jitter! ini-\discretionary{}{}{}option}\index{jitter! anti-\discretionary{}{}{}aliasing} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter on/off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+J}}\index{+j} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter on with 1.0 or previous amount } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-J}}\index{-j} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Jitter\_\-Amount=}}\discretionary{n.}{}{n.}n\index{Jitter\_\-Amount! \discretionary{ini.}{}{ini.}option} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter amount to \discretionary{n.}{}{n.}n. If \discretionary{n.}{}{n.}n $<$= 0 aa-\discretionary{}{}{}jitter is set off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+J}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter on; jitter amount to \discretionary{n.}{}{n.}n. If \discretionary{n.}{}{n.}n $<$= 0 aa-\discretionary{}{}{}jitter is set off } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{-J}}\discretionary{n.}{}{n.}n 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}jitter off (jitter amount \discretionary{n.}{}{n.}n in future) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{Antialias\_\-Depth=}}n\index{Antialias\_\-Depth! ini-\discretionary{}{}{}option} 
  } & 
{\raggedleft  Sets aa-\discretionary{}{}{}depth (1 $<$= n $<$= 9) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+R}}n\index{+r} 
  } & 
{\raggedleft  Same as {\small\texttt{Antialias\_\-Depth=}}n } \\ 
 

\end{tabular*} \end{table}


   The ray-\discretionary{}{}{}tracing process is in effect a discrete, digital sampling of the image with typically one sample per pixel. Such sampling can introduce a variety of 
 errors. This includes a jagged, stair-\discretionary{}{}{}step appearance in sloping or curved lines, a broken look for thin lines, moir\'{e} patterns of interference and lost 
 detail or missing objects, which are so small they reside between adjacent pixels. The effect that is responsible for those errors is called \textit{aliasing}. 
 



   Anti-\discretionary{}{}{}aliasing is any technique used to help eliminate such errors or to reduce the negative impact they have on the image. In general, anti-\discretionary{}{}{}aliasing makes 
 the ray-\discretionary{}{}{}traced image look \textit{ smoother}. The {\small\texttt{ Antialias=on}} option or {\small\texttt{+A}} switch turns on POV-\discretionary{}{}{}Ray's anti-\discretionary{}{}{}aliasing system. 



   When anti-\discretionary{}{}{}aliasing is turned on, POV-\discretionary{}{}{}Ray attempts to reduce the errors by shooting more than one viewing ray into each pixel and averaging the results to 
 determine the pixel's apparent color. This technique is called super-\discretionary{}{}{}sampling and can improve the appearance of the final image but it drastically increases 
 the time required to render a scene since many more calculations have to be done. 



   POV-\discretionary{}{}{}Ray gives you the option to use one of two alternate super-\discretionary{}{}{}sampling methods. The {\small\texttt{ Sampling\_\-Method=}}\textit{n} option or {\small\texttt{ 
 +AM}}\textit{n} switch selects either type {\small\texttt{1}} or type {\small\texttt{ 2}}. Selecting one of those methods does not turn anti-\discretionary{}{}{}aliasing on. This 
 has to be done by using the {\small\texttt{+A}} command line switch or {\small\texttt{ Antialias=on}} option. 



   Type 1 is an adaptive, non-\discretionary{}{}{}recursive, super-\discretionary{}{}{}sampling method. It is \textit{ adaptive} because not every pixel is super-\discretionary{}{}{}sampled. Type 2 is an adaptive and 
 recursive super-\discretionary{}{}{}sampling method. It is \textit{recursive} because the pixel is sub-\discretionary{}{}{}divided and sub-\discretionary{}{}{}sub-\discretionary{}{}{}divided recursively. The \textit{adaptive} nature of 
 type 2 is the variable depth of recursion. 



   In the default, non-\discretionary{}{}{}recursive method ({\small\texttt{+AM1}}), POV-\discretionary{}{}{}Ray initially traces one ray per pixel. If the color of a pixel differs from its neighbors 
 (to the left or above) by at least the set threshold value then the pixel is super-\discretionary{}{}{}sampled by shooting a given, fixed number of additional rays. The default 
 threshold is 0.3 but it may be changed using the {\small\texttt{ Antialias\_\-Threshold=}}\textit{\discretionary{n.}{}{n.}n} option. When the switches are used, the threshold may 
 optionally follow the {\small\texttt{+A}}. For example {\small\texttt{ +A0.1}} turns anti-\discretionary{}{}{}aliasing on and sets the threshold to 0.1. 



   The threshold comparison is computed as follows. If r1, g1, b1 and r2, g2, b2 are the rgb components of two pixels then the difference between pixels is 
 computed by 


{\small\begin{verbatim}
  diff = abs(r1-r2) + abs(g1-g2) + abs(b1-b2)
\end{verbatim}}


   If this difference is greater than the threshold then both pixels are super-\discretionary{}{}{}sampled. The rgb values are in the range from 0.0 to 1.0 thus the most two pixels 
 can differ is 3.0. If the anti-\discretionary{}{}{}aliasing threshold is 0.0 then every pixel is super-\discretionary{}{}{}sampled. If the threshold is 3.0 then no anti-\discretionary{}{}{}aliasing is done. Lower 
 threshold means more anti-\discretionary{}{}{}aliasing and less speed. Use anti-\discretionary{}{}{}aliasing for your final version of a picture, not the rough draft. The lower the contrast, the 
 lower the threshold should be. Higher contrast pictures can get away with higher tolerance values. Good values seem to be around 0.2 to 0.4. 



   When using the non-\discretionary{}{}{}recursive method, the default number of super-\discretionary{}{}{}samples is nine per pixel, located on a 3*3 grid. The {\small\texttt{ Antialias\_\-Depth=}}\textit{n} 
 option or {\small\texttt{ +R}}\textit{n} switch controls the number of rows and columns of samples taken for a super-\discretionary{}{}{}sampled pixel. For example {\small\texttt{+R4}} 
 would give 4*4=16 samples per pixel. 



   The second, adaptive, recursive super-\discretionary{}{}{}sampling method starts by tracing four rays at the corners of each pixel. If the resulting colors differ more than the 
 threshold amount additional samples will be taken. This is done recursively, \discretionary{i.}{}{i.}e. the pixel is divided into four sub-\discretionary{}{}{}pixels that are separately traced and 
 tested for further subdivision. The advantage of this method is the reduced number of rays that have to be traced. Samples that are common among adjacent 
 pixels and sub-\discretionary{}{}{}pixels are stored and reused to avoid re-\discretionary{}{}{}tracing of rays. The recursive character of this method makes the super-\discretionary{}{}{}sampling concentrate on those 
 parts of the pixel that are more likely to need super-\discretionary{}{}{}sampling (see figure below).\begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/recsuper} \caption{Example of how the recursive super-\discretionary{}{}{}sampling works.} \end{figure} 
 



   The maximum number of subdivisions is specified by the {\small\texttt{ Antialias\_\-Depth=}}\textit{n} option or {\small\texttt{+R}}\textit{n} switch. This is 
 different from the adaptive, non-\discretionary{}{}{}recursive method where the total number of super-\discretionary{}{}{}samples is specified. A maximum number of \textit{n} subdivisions results in 
 a maximum number of samples per pixel that is given by the following table. 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{82pt}@{} p{164pt}@{} p{164pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{+R}}n 
  } & 

  {\raggedleft 
    Number of additional samples per super-\discretionary{}{}{}sampled pixel for the non-\discretionary{}{}{}recursive method {\small\texttt{+AM1}} 
  } & 
{\raggedleft  Maximum number of samples per super-\discretionary{}{}{}sampled pixel for the recursive method {\small\texttt{+AM2}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{1}} 
  } & 

  {\raggedleft 
    1 
  } & 
{\raggedleft  9 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{2}} 
  } & 

  {\raggedleft 
    4 
  } & 
{\raggedleft  25 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{3}} 
  } & 

  {\raggedleft 
    9 
  } & 
{\raggedleft  81 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{4}} 
  } & 

  {\raggedleft 
    16 
  } & 
{\raggedleft  289 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{5}} 
  } & 

  {\raggedleft 
    25 
  } & 
{\raggedleft  1089 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{6}} 
  } & 

  {\raggedleft 
    36 
  } & 
{\raggedleft  4225 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{7}} 
  } & 

  {\raggedleft 
    49 
  } & 
{\raggedleft  16641 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{8}} 
  } & 

  {\raggedleft 
    64 
  } & 
{\raggedleft  66049 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{9}} 
  } & 

  {\raggedleft 
    81 
  } & 
{\raggedleft  263169 } \\ 
 

\end{tabular*} \end{table}


   \textbf{Note:} the maximum number of samples in the recursive case is hardly ever reached for a given pixel. If the recursive method is used with no 
 anti-\discretionary{}{}{}aliasing each pixel will be the average of the rays traced at its corners. In most cases a recursion level of three is sufficient. 



   Another way to reduce aliasing artefacts is to introduce noise into the sampling process. This is called \textit{jittering} and works because the human 
 visual system is much more forgiving to noise than it is to regular patterns. The location of the super-\discretionary{}{}{}samples is jittered or wiggled a tiny amount when 
 anti-\discretionary{}{}{}aliasing is used. Jittering is used by default but it may be turned off with the {\small\texttt{Jitter=off}} option or {\small\texttt{-J}} 
 switch. The amount of jittering can be set with the {\small\texttt{ Jitter\_\-Amount=}}\textit{\discretionary{n.}{}{n.}n} option. When using switches the jitter scale may be specified 
 after the {\small\texttt{+J}}\textit{\discretionary{n.}{}{n.}n} switch. For example {\small\texttt{+J0.5}} uses half the normal jitter. The default amount of 1.0 is the maximum 
 jitter which will insure that all super-\discretionary{}{}{}samples remain inside the original pixel. 



   \textbf{Note:} the jittering noise is random and non-\discretionary{}{}{}repeatable so you should avoid using jitter in animation sequences as the anti-\discretionary{}{}{}aliased pixels will vary 
 and flicker annoyingly from frame to frame. 



   If anti-\discretionary{}{}{}aliasing is not used one sample per pixel is taken regardless of the super-\discretionary{}{}{}sampling method specified. 


\clearpage \chapter{Scene Description Language}

% reference/000001.html

\index{Scene Description Language}\index{scene! description language}

   The reference section describes the POV-\discretionary{}{}{}Ray \textit{scene description language}. It is supposed to be used as a reference for looking up things. It does not 
 contain detailed explanations on how scenes are written or how POV-\discretionary{}{}{}Ray is used. It just explains all features, their syntax, applications, limits, drawbacks, 
 etc. 



   The scene description language allows you to describe the world in a readable and convenient way. Files are created in plain ASCII text using an editor of 
 your choice. The input file name is specified using the {\small\texttt{ Input\_\-File\_\-Name}}=\textit{file} option or {\small\texttt{+I}}\textit{file} switch. By 
 default the files have the extension {\small\texttt{.pov}}. POV-\discretionary{}{}{}Ray reads the file, processes it by creating an internal model of the scene and then renders 
 the scene. 



   The overall syntax of a scene is shown below. See "Notation and Basic Assumptions" for more information on syntax notation. 


{\small\begin{verbatim}
SCENE:
    SCENE_ITEM...
SCENE_ITEM:
    LANGUAGE_DIRECTIVES        |
    camera { CAMERA_ITEMS... } |
    OBJECTS                    |
    ATMOSPHERIC_EFFECTS        |
    global_settings { GLOBAL_ITEMS }
\end{verbatim}}


   In plain English, this means that a scene contains one or more scene items and that a scene item may be any of the five items listed below it. The items may 
 appear in any order. None is a required item. In addition to the syntax depicted above, a \textit{LANGUAGE\_\-DIRECTIVE} may also appear anywhere embedded in 
 other statements between any two tokens. There are some restrictions on nesting directives also. 



   For details on those five items see section "Language Directives", section "Objects", section "Camera", section "Atmospheric 
 Effects" and section "Global Settings" for details. 


\section{Language Basics}

% reference/000002.html



   The POV-\discretionary{}{}{}Ray language consists of identifiers, reserved keywords, floating point expressions, strings, special symbols and comments. The text of a POV-\discretionary{}{}{}Ray 
 scene file is free format. You may put statements on separate lines or on the same line as you desire. You may add blank lines, spaces or indentations as long 
 as you do not split any keywords or identifiers. 


\subsection{Identifiers and Keywords}

% reference/000003.html

\index{Identifiers}\index{identifier}\index{keywords}\index{keyword}

   POV-\discretionary{}{}{}Ray allows you to define identifiers for later use in the scene file. An identifier may be 1 to 40 characters long. It may consist of upper and lower 
 case letters, the digits 0 through 9 or an underscore character ("\_"). the first character must be an alphabetic character. The declaration of 
 identifiers is covered later. 



   POV-\discretionary{}{}{}Ray has a number of reserved keywords which are listed below. 

\begin{multicols}{3}\textbf{a}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{aa\_\-level}}\newline  {\small\texttt{aa\_\-threshold}}\newline  {\small\texttt{abs}}\newline  
{\small\texttt{absorption}}\newline  {\small\texttt{accuracy}}\newline  {\small\texttt{acos}}\newline  {\small\texttt{acosh}}\newline  {\small\texttt{adaptive}}\newline  
{\small\texttt{adc\_\-bailout}}\newline  {\small\texttt{agate}}\newline  {\small\texttt{agate\_\-turb}}\newline  {\small\texttt{all}}\newline   {\small\texttt{all\_\-intersections}}\newline  
{\small\texttt{alpha}}\newline  {\small\texttt{altitude}}\newline  {\small\texttt{always\_\-sample}}\newline  {\small\texttt{ambient}}\newline  {\small\texttt{ambient\_\-light}}\newline  
{\small\texttt{angle}}\newline  {\small\texttt{aperture}}\newline  {\small\texttt{append}}\newline  {\small\texttt{arc\_\-angle}}\newline  {\small\texttt{area\_\-light}}\newline  
{\small\texttt{array}}\newline   {\small\texttt{asc}}\newline  {\small\texttt{ascii}}\newline  {\small\texttt{asin}}\newline  {\small\texttt{asinh}}\newline  {\small\texttt{assumed\_\-gamma}}\newline  
{\small\texttt{atan}}\newline  {\small\texttt{atan2}}\newline  {\small\texttt{atanh}}\newline  {\small\texttt{autostop}}\newline  {\small\texttt{average}}\newline  
\end{multicols}\begin{multicols}{3}\textbf{b}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{b\_\-spline}}\newline  {\small\texttt{background}}\newline  
{\small\texttt{bezier\_\-spline}}\newline  {\small\texttt{bicubic\_\-patch}}\newline  {\small\texttt{black\_\-hole}}\newline  {\small\texttt{blob}}\newline  {\small\texttt{blue}}\newline  
 {\small\texttt{blur\_\-samples}}\newline  {\small\texttt{bounded\_\-by}}\newline  {\small\texttt{box}}\newline  {\small\texttt{boxed}}\newline  {\small\texttt{bozo}}\newline  
{\small\texttt{break}}\newline  {\small\texttt{brick}}\newline   {\small\texttt{brick\_\-size}}\newline  {\small\texttt{brightness}}\newline  {\small\texttt{brilliance}}\newline  
{\small\texttt{bump\_\-map}}\newline  {\small\texttt{bump\_\-size}}\newline  {\small\texttt{bumps}}\newline  \end{multicols}\begin{multicols}{3}\textbf{c}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{camera}}\newline  {\small\texttt{case}}\newline  {\small\texttt{caustics}}\newline  {\small\texttt{ceil}}\newline  {\small\texttt{cells}}\newline  
{\small\texttt{charset}}\newline  {\small\texttt{checker}}\newline  {\small\texttt{chr}}\newline  {\small\texttt{circular}}\newline  {\small\texttt{clipped\_\-by}}\newline  
{\small\texttt{clock}}\newline  {\small\texttt{clock\_\-delta}}\newline  {\small\texttt{clock\_\-on}}\newline  {\small\texttt{collect}}\newline   {\small\texttt{color}}\newline  
{\small\texttt{color\_\-map}}\newline  {\small\texttt{colour}}\newline  {\small\texttt{colour\_\-map}}\newline  {\small\texttt{component}}\newline  {\small\texttt{composite}}\newline  
{\small\texttt{concat}}\newline  {\small\texttt{cone}}\newline  {\small\texttt{confidence}}\newline  {\small\texttt{conic\_\-sweep}}\newline  {\small\texttt{conserve\_\-energy}}\newline  
{\small\texttt{contained\_\-by}}\newline  {\small\texttt{control0}}\newline  {\small\texttt{control1}}\newline   {\small\texttt{coords}}\newline  {\small\texttt{cos}}\newline  
{\small\texttt{cosh}}\newline  {\small\texttt{count}}\newline  {\small\texttt{crackle}}\newline  {\small\texttt{crand}}\newline  {\small\texttt{cube}}\newline  {\small\texttt{cubic}}\newline  
{\small\texttt{cubic\_\-spline}}\newline  {\small\texttt{cubic\_\-wave}}\newline  {\small\texttt{cutaway\_\-textures}}\newline  {\small\texttt{cylinder}}\newline  {\small\texttt{cylindrical}}\newline  
\end{multicols}\begin{multicols}{3}\textbf{d}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{debug}}\newline  {\small\texttt{declare}}\newline  
{\small\texttt{default}}\newline  {\small\texttt{defined}}\newline  {\small\texttt{degrees}}\newline  {\small\texttt{density}}\newline  {\small\texttt{density\_\-file}}\newline  
{\small\texttt{density\_\-map}}\newline   {\small\texttt{dents}}\newline  {\small\texttt{df3}}\newline  {\small\texttt{difference}}\newline  {\small\texttt{diffuse}}\newline  
{\small\texttt{dimension\_\-size}}\newline  {\small\texttt{dimensions}}\newline  {\small\texttt{direction}}\newline  {\small\texttt{disc}}\newline   {\small\texttt{dispersion}}\newline  
{\small\texttt{dispersion\_\-samples}}\newline  {\small\texttt{dist\_\-exp}}\newline  {\small\texttt{distance}}\newline  {\small\texttt{div}}\newline  {\small\texttt{double\_\-illuminate}}\newline  
\end{multicols}\begin{multicols}{3}\textbf{e}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{eccentricity}}\newline  {\small\texttt{else}}\newline  
{\small\texttt{emission}}\newline  {\small\texttt{end}}\newline   {\small\texttt{error}}\newline  {\small\texttt{error\_\-bound}}\newline  {\small\texttt{evaluate}}\newline  
{\small\texttt{exp}}\newline   {\small\texttt{expand\_\-thresholds}}\newline  {\small\texttt{exponent}}\newline  {\small\texttt{exterior}}\newline  {\small\texttt{extinction}}\newline  
\end{multicols}\begin{multicols}{3}\textbf{f}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{face\_\-indices}}\newline  {\small\texttt{facets}}\newline  
{\small\texttt{fade\_\-color}}\newline  {\small\texttt{fade\_\-colour}}\newline  {\small\texttt{fade\_\-distance}}\newline  {\small\texttt{fade\_\-power}}\newline  {\small\texttt{falloff}}\newline  
{\small\texttt{falloff\_\-angle}}\newline  {\small\texttt{false}}\newline  {\small\texttt{fclose}}\newline   {\small\texttt{file\_\-exists}}\newline  {\small\texttt{filter}}\newline  
{\small\texttt{final\_\-clock}}\newline  {\small\texttt{final\_\-frame}}\newline  {\small\texttt{finish}}\newline  {\small\texttt{fisheye}}\newline  {\small\texttt{flatness}}\newline  
{\small\texttt{flip}}\newline  {\small\texttt{floor}}\newline  {\small\texttt{focal\_\-point}}\newline   {\small\texttt{fog}}\newline  {\small\texttt{fog\_\-alt}}\newline  
{\small\texttt{fog\_\-offset}}\newline  {\small\texttt{fog\_\-type}}\newline  {\small\texttt{fopen}}\newline  {\small\texttt{form}}\newline  {\small\texttt{frame\_\-number}}\newline  
{\small\texttt{frequency}}\newline  {\small\texttt{fresnel}}\newline  {\small\texttt{function}}\newline  \end{multicols}\begin{multicols}{3}\textbf{g}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{gather}}\newline  {\small\texttt{gif}}\newline  {\small\texttt{global\_\-lights}}\newline   {\small\texttt{global\_\-settings}}\newline  {\small\texttt{gradient}}\newline  
{\small\texttt{granite}}\newline   {\small\texttt{gray}}\newline  {\small\texttt{gray\_\-threshold}}\newline  {\small\texttt{green}}\newline  \end{multicols}\begin{multicols}{3}\textbf{h}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{height\_\-field}}\newline  {\small\texttt{hexagon}}\newline   {\small\texttt{hf\_\-gray\_\-16}}\newline  {\small\texttt{hierarchy}}\newline   {\small\texttt{hypercomplex}}\newline  
{\small\texttt{hollow}}\newline  \end{multicols}\begin{multicols}{3}\textbf{i}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{if}}\newline  {\small\texttt{ifdef}}\newline  
{\small\texttt{iff}}\newline  {\small\texttt{ifndef}}\newline  {\small\texttt{image\_\-height}}\newline  {\small\texttt{image\_\-map}}\newline  {\small\texttt{image\_\-pattern}}\newline  
{\small\texttt{image\_\-width}}\newline  {\small\texttt{include}}\newline   {\small\texttt{initial\_\-clock}}\newline  {\small\texttt{initial\_\-frame}}\newline  {\small\texttt{inside}}\newline  
{\small\texttt{inside\_\-vector}}\newline  {\small\texttt{int}}\newline  {\small\texttt{interior}}\newline  {\small\texttt{interior\_\-texture}}\newline  {\small\texttt{internal}}\newline  
{\small\texttt{interpolate}}\newline   {\small\texttt{intersection}}\newline  {\small\texttt{intervals}}\newline  {\small\texttt{inverse}}\newline  {\small\texttt{ior}}\newline  
{\small\texttt{irid}}\newline  {\small\texttt{irid\_\-wavelength}}\newline  {\small\texttt{isosurface}}\newline  \end{multicols}\begin{multicols}{3}\textbf{j}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{jitter}}\newline  {\small\texttt{jpeg}}\newline   {\small\texttt{julia}}\newline  {\small\texttt{julia\_\-fractal}}\newline   \end{multicols}\begin{multicols}{3}\textbf{l}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{lambda}}\newline  {\small\texttt{lathe}}\newline  {\small\texttt{leopard}}\newline  {\small\texttt{light\_\-group}}\newline  {\small\texttt{light\_\-source}}\newline  
 {\small\texttt{linear\_\-spline}}\newline  {\small\texttt{linear\_\-sweep}}\newline  {\small\texttt{ln}}\newline  {\small\texttt{load\_\-file}}\newline  {\small\texttt{local}}\newline  
 {\small\texttt{location}}\newline  {\small\texttt{log}}\newline  {\small\texttt{look\_\-at}}\newline  {\small\texttt{looks\_\-like}}\newline  {\small\texttt{low\_\-error\_\-factor}}\newline  
\end{multicols}\begin{multicols}{3}\textbf{m}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{macro}}\newline  {\small\texttt{magnet}}\newline  
{\small\texttt{major\_\-radius}}\newline  {\small\texttt{mandel}}\newline  {\small\texttt{map\_\-type}}\newline  {\small\texttt{marble}}\newline  {\small\texttt{material}}\newline  
{\small\texttt{material\_\-map}}\newline  {\small\texttt{matrix}}\newline  {\small\texttt{max}}\newline  {\small\texttt{max\_\-extent}}\newline   {\small\texttt{max\_\-gradient}}\newline  
{\small\texttt{max\_\-intersections}}\newline  {\small\texttt{max\_\-iteration}}\newline  {\small\texttt{max\_\-sample}}\newline  {\small\texttt{max\_\-trace}}\newline  {\small\texttt{max\_\-trace\_\-level}}\newline  
{\small\texttt{media}}\newline  {\small\texttt{media\_\-attenuation}}\newline  {\small\texttt{media\_\-interaction}}\newline  {\small\texttt{merge}}\newline  {\small\texttt{mesh}}\newline  
 {\small\texttt{mesh2}}\newline  {\small\texttt{metallic}}\newline  {\small\texttt{method}}\newline  {\small\texttt{metric}}\newline  {\small\texttt{min}}\newline  
{\small\texttt{min\_\-extent}}\newline  {\small\texttt{minimum\_\-reuse}}\newline  {\small\texttt{mod}}\newline  {\small\texttt{mortar}}\newline  \end{multicols}\begin{multicols}{3}\textbf{n}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{natural\_\-spline}}\newline  {\small\texttt{nearest\_\-count}}\newline  {\small\texttt{no}}\newline  {\small\texttt{no\_\-bump\_\-scale}}\newline  {\small\texttt{no\_\-image}}\newline  
 {\small\texttt{no\_\-reflection}}\newline  {\small\texttt{no\_\-shadow}}\newline  {\small\texttt{noise\_\-generator}}\newline  {\small\texttt{normal}}\newline  {\small\texttt{normal\_\-indices}}\newline  
 {\small\texttt{normal\_\-map}}\newline  {\small\texttt{normal\_\-vectors}}\newline  {\small\texttt{number\_\-of\_\-waves}}\newline  \end{multicols}\begin{multicols}{3}\textbf{o}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{object}}\newline  {\small\texttt{octaves}}\newline  {\small\texttt{off}}\newline  {\small\texttt{offset}}\newline  {\small\texttt{omega}}\newline  
 {\small\texttt{omnimax}}\newline  {\small\texttt{on}}\newline  {\small\texttt{once}}\newline  {\small\texttt{onion}}\newline  {\small\texttt{open}}\newline   {\small\texttt{orient}}\newline  
{\small\texttt{orientation}}\newline  {\small\texttt{orthographic}}\newline  \end{multicols}\begin{multicols}{3}\textbf{p}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{panoramic}}\newline  {\small\texttt{parallel}}\newline  {\small\texttt{parametric}}\newline  {\small\texttt{pass\_\-through}}\newline  {\small\texttt{pattern}}\newline  
{\small\texttt{perspective}}\newline  {\small\texttt{pgm}}\newline  {\small\texttt{phase}}\newline  {\small\texttt{phong}}\newline  {\small\texttt{phong\_\-size}}\newline  
{\small\texttt{photons}}\newline   {\small\texttt{pi}}\newline  {\small\texttt{pigment}}\newline  {\small\texttt{pigment\_\-map}}\newline  {\small\texttt{pigment\_\-pattern}}\newline  
{\small\texttt{planar}}\newline  {\small\texttt{plane}}\newline  {\small\texttt{png}}\newline  {\small\texttt{point\_\-at}}\newline  {\small\texttt{poly}}\newline  
{\small\texttt{poly\_\-wave}}\newline  {\small\texttt{polygon}}\newline   {\small\texttt{pot}}\newline  {\small\texttt{pow}}\newline  {\small\texttt{ppm}}\newline  
{\small\texttt{precision}}\newline  {\small\texttt{precompute}}\newline  {\small\texttt{pretrace\_\-end}}\newline  {\small\texttt{pretrace\_\-start}}\newline  {\small\texttt{prism}}\newline  
{\small\texttt{prod}}\newline  {\small\texttt{projected\_\-through}}\newline  {\small\texttt{pwr}}\newline  \end{multicols}\begin{multicols}{3}\textbf{q}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{quadratic\_\-spline}}\newline  {\small\texttt{quadric}}\newline  {\small\texttt{quartic}}\newline   {\small\texttt{quaternion}}\newline  {\small\texttt{quick\_\-color}}\newline  
{\small\texttt{quick\_\-colour}}\newline   {\small\texttt{quilted}}\newline  \end{multicols}\begin{multicols}{3}\textbf{r}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{radial}}\newline  {\small\texttt{radians}}\newline  {\small\texttt{radiosity}}\newline  {\small\texttt{radius}}\newline  {\small\texttt{rainbow}}\newline  
{\small\texttt{ramp\_\-wave}}\newline  {\small\texttt{rand}}\newline  {\small\texttt{range}}\newline  {\small\texttt{ratio}}\newline   {\small\texttt{read}}\newline  
{\small\texttt{reciprocal}}\newline  {\small\texttt{recursion\_\-limit}}\newline  {\small\texttt{red}}\newline  {\small\texttt{reflection}}\newline  {\small\texttt{reflection\_\-exponent}}\newline  
{\small\texttt{refraction}}\newline  {\small\texttt{render}}\newline  {\small\texttt{repeat}}\newline   {\small\texttt{rgb}}\newline  {\small\texttt{rgbf}}\newline  
{\small\texttt{rgbft}}\newline  {\small\texttt{rgbt}}\newline  {\small\texttt{right}}\newline  {\small\texttt{ripples}}\newline  {\small\texttt{rotate}}\newline  
{\small\texttt{roughness}}\newline  \end{multicols}\begin{multicols}{3}\textbf{s}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{samples}}\newline  
{\small\texttt{save\_\-file}}\newline  {\small\texttt{scale}}\newline  {\small\texttt{scallop\_\-wave}}\newline  {\small\texttt{scattering}}\newline  {\small\texttt{seed}}\newline  
{\small\texttt{select}}\newline  {\small\texttt{shadowless}}\newline  {\small\texttt{sin}}\newline  {\small\texttt{sine\_\-wave}}\newline  {\small\texttt{sinh}}\newline  
{\small\texttt{size}}\newline  {\small\texttt{sky}}\newline  {\small\texttt{sky\_\-sphere}}\newline  {\small\texttt{slice}}\newline  {\small\texttt{slope}}\newline  
 {\small\texttt{slope\_\-map}}\newline  {\small\texttt{smooth}}\newline  {\small\texttt{smooth\_\-triangle}}\newline  {\small\texttt{solid}}\newline  {\small\texttt{sor}}\newline  
{\small\texttt{spacing}}\newline  {\small\texttt{specular}}\newline  {\small\texttt{sphere}}\newline  {\small\texttt{sphere\_\-sweep}}\newline  {\small\texttt{spherical}}\newline  
{\small\texttt{spiral1}}\newline  {\small\texttt{spiral2}}\newline  {\small\texttt{spline}}\newline  {\small\texttt{split\_\-union}}\newline  {\small\texttt{spotlight}}\newline  
{\small\texttt{spotted}}\newline   {\small\texttt{sqr}}\newline  {\small\texttt{sqrt}}\newline  {\small\texttt{statistics}}\newline  {\small\texttt{str}}\newline  
{\small\texttt{strcmp}}\newline  {\small\texttt{strength}}\newline  {\small\texttt{strlen}}\newline  {\small\texttt{strlwr}}\newline  {\small\texttt{strupr}}\newline  
{\small\texttt{sturm}}\newline  {\small\texttt{substr}}\newline  {\small\texttt{sum}}\newline  {\small\texttt{superellipsoid}}\newline  {\small\texttt{switch}}\newline  
{\small\texttt{sys}}\newline  \end{multicols}\begin{multicols}{3}\textbf{t}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{t}}\newline  {\small\texttt{tan}}\newline  
{\small\texttt{tanh}}\newline  {\small\texttt{target}}\newline  {\small\texttt{text}}\newline  {\small\texttt{texture}}\newline  {\small\texttt{texture\_\-list}}\newline  
{\small\texttt{texture\_\-map}}\newline  {\small\texttt{tga}}\newline  {\small\texttt{thickness}}\newline   {\small\texttt{threshold}}\newline  {\small\texttt{tiff}}\newline  
{\small\texttt{tightness}}\newline  {\small\texttt{tile2}}\newline  {\small\texttt{tiles}}\newline  {\small\texttt{tolerance}}\newline  {\small\texttt{toroidal}}\newline  
{\small\texttt{torus}}\newline  {\small\texttt{trace}}\newline  {\small\texttt{transform}}\newline   {\small\texttt{translate}}\newline  {\small\texttt{transmit}}\newline  
{\small\texttt{triangle}}\newline  {\small\texttt{triangle\_\-wave}}\newline  {\small\texttt{true}}\newline  {\small\texttt{ttf}}\newline  {\small\texttt{turb\_\-depth}}\newline  
{\small\texttt{turbulence}}\newline  {\small\texttt{type}}\newline  \end{multicols}\begin{multicols}{3}\textbf{u}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{u}}\newline  {\small\texttt{u\_\-steps}}\newline  {\small\texttt{ultra\_\-wide\_\-angle}}\newline  {\small\texttt{undef}}\newline  {\small\texttt{union}}\newline  
 {\small\texttt{up}}\newline  {\small\texttt{use\_\-alpha}}\newline  {\small\texttt{use\_\-color}}\newline  {\small\texttt{use\_\-colour}}\newline  {\small\texttt{use\_\-index}}\newline  
 {\small\texttt{utf8}}\newline  {\small\texttt{uv\_\-indices}}\newline  {\small\texttt{uv\_\-mapping}}\newline  {\small\texttt{uv\_\-vectors}}\newline  \end{multicols}\begin{multicols}{3}\textbf{v}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{v}}\newline  {\small\texttt{v\_\-steps}}\newline  {\small\texttt{val}}\newline  {\small\texttt{variance}}\newline  {\small\texttt{vaxis\_\-rotate}}\newline  
 {\small\texttt{vcross}}\newline  {\small\texttt{vdot}}\newline  {\small\texttt{version}}\newline  {\small\texttt{vertex\_\-vectors}}\newline  {\small\texttt{vlength}}\newline  
 {\small\texttt{vnormalize}}\newline  {\small\texttt{vrotate}}\newline  {\small\texttt{vstr}}\newline  {\small\texttt{vturbulence}}\newline  \end{multicols}\begin{multicols}{3}\textbf{w}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{warning}}\newline  {\small\texttt{warp}}\newline  {\small\texttt{water\_\-level}}\newline   {\small\texttt{waves}}\newline  {\small\texttt{while}}\newline  
{\small\texttt{width}}\newline   {\small\texttt{wood}}\newline  {\small\texttt{wrinkles}}\newline  {\small\texttt{write}}\newline  \end{multicols}\begin{multicols}{3}\textbf{x}\nopagebreak[4] \end{multicols}\begin{multicols}{3} 
{\small\texttt{x}}\newline    \end{multicols}\begin{multicols}{3}\textbf{y}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{y}}\newline   {\small\texttt{yes}}\newline  
 \end{multicols}\begin{multicols}{3}\textbf{z}\nopagebreak[4] \end{multicols}\begin{multicols}{3} {\small\texttt{z}}\newline    \end{multicols}

   All reserved words are fully lower case. Therefore it is recommended that your identifiers contain at least one upper case character so it is sure to avoid 
 conflict with reserved words. 


\subsection{Comments}

% reference/000004.html

\index{comment}

   Comments are text in the scene file included to make the scene file easier to read or understand. They are ignored by the ray-\discretionary{}{}{}tracer and are there for your 
 information. There are two types of comments in POV-\discretionary{}{}{}Ray. 



   Two slashes are used for single line comments. Anything on a line after a double slash ({\small\texttt{//}}) is ignored by the ray-\discretionary{}{}{}tracer. For example: 


{\small\begin{verbatim}
 // This line is ignored
\end{verbatim}}


   You can have scene file information on the line in front of the comment as in: 


{\small\begin{verbatim}
 object { FooBar } // this is an object
\end{verbatim}}


   The other type of comment is used for multiple lines. It starts with "{\small\texttt{/*}}" and ends with "{\small\texttt{*/}}". 
 Everything in-\discretionary{}{}{}between is ignored. For example: 


{\small\begin{verbatim}
 /* These lines
    are ignored
    by the
    ray-tracer */
\end{verbatim}}


   This can be useful if you want to temporarily remove elements from a scene file. {\small\texttt{/*}} ... {\small\texttt{*/}} comments can \textit{comment out} 
 lines containing other {\small\texttt{//}} comments and thus can be used to temporarily or permanently comment out parts of a scene. {\small\texttt{ /*}} ... {\small\texttt{*/}} 
 comments can be nested, the following is legal: 


{\small\begin{verbatim}
 /* This is a comment
 // This too
 /* This also */
 */
\end{verbatim}}


   Use comments liberally and generously. Well used, they really improve the readability of scene files. 


\subsection{Float Expressions}

% reference/000005.html

\index{Expressions! float}\index{Float! expressions}

   Many parts of the POV-\discretionary{}{}{}Ray language require you to specify one or more floating point numbers. A floating point number is a number with a decimal point. 
 Floats may be specified using literals, identifiers or functions which return float values. You may also create very complex float expressions from 
 combinations of any of these using various familiar operators. 



   Where POV-\discretionary{}{}{}Ray needs an integer value it allows you to specify a float value and it truncates it to an integer. When POV-\discretionary{}{}{}Ray needs a logical or boolean value 
 it interprets any non-\discretionary{}{}{}zero float as true and zero as false. Because float comparisons are subject to rounding errors POV-\discretionary{}{}{}Ray accepts values extremely close to 
 zero as being false when doing boolean functions. Typically values whose absolute values are less than a preset value \textit{ epsilon} are considered false 
 for logical expressions. The value of \textit{ epsilon} is system dependent but is generally about 1.0e-10. Two floats \textit{a} and \textit{b} are 
 considered to be equal if \textit{abs(a-\discretionary{}{}{}b) $<$ epsilon.} 



   The full syntax for float expressions is given below. Detailed explanations are given in the following sub-\discretionary{}{}{}sections. 


{\small\begin{verbatim}
FLOAT:
    NUMERIC_TERM [SIGN NUMERIC_TERM]...
SIGN:
    + | -
NUMERIC_TERM:
    NUMERIC_FACTOR [MULT NUMERIC_FACTOR]...
MULT:
    * | /
NUMERIC_FACTOR:
    FLOAT_LITERAL        |
    FLOAT_IDENTIFIER     |
    SIGN NUMERIC_FACTOR  |
    FLOAT_FUNCTION       |
    FLOAT_BUILT-IN_IDENT |
    ( FULL_EXPRESSION )  |
    ! NUMERIC_FACTOR
VECTOR DECIMAL_POINT DOT_ITEM FLOAT_LITERAL:
    [DIGIT...] [DECIMAL_POINT] DIGIT... [EXP [SIGN] DIGIT...]
DIGIT:
    0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
DECIMAL_POINT:
    .
EXP:
    e | E
DOT_ITEM:
    x | y | z | t | u | v | red | blue | green | filter |
    transmit | gray
FLOAT_FUNCTION:
    abs( FLOAT ) | acos( FLOAT ) | acosh( FLOAT ) | asc( STRING ) |
    asin( FLOAT ) | asinh( FLOAT ) | atan( FLOAT) | atanh( FLOAT) |
    atan2( FLOAT , FLOAT ) | ceil( FLOAT ) | cos( FLOAT ) | 
    cosh( FLOAT ) | defined(IDENTIFIER ) | degrees( FLOAT ) | 
    dimensions( ARRAY_IDENTIFIER ) |
    dimension_size( ARRAY_IDENTIFIER , FLOAT ) | 
    div( FLOAT , FLOAT ) | exp( FLOAT ) | file_exists( STRING ) |
    floor( FLOAT ) | int( FLOAT ) | ln(Float | log( FLOAT ) |
    max( FLOAT , FLOAT, ... ) | min( FLOAT , FLOAT, ... ) |
    mod( FLOAT , FLOAT ) | pow( FLOAT , FLOAT ) |
    radians( FLOAT ) | rand( FLOAT ) | seed( FLOAT ) |
    select( FLOAT, FLOAT, FLOAT [,FLOAT]) | sin( FLOAT ) |
    sinh( FLOAT ) | sqrt( FLOAT ) | strcmp( STRING , STRING ) |
    strlen( STRING ) | tan( FLOAT ) | tanh( FLOAT ) |
    val( STRING ) | vdot( VECTOR , VECTOR ) | vlength( VECTOR ) | 
    FLOAT_BUILT-IN_IDENT:
    clock | clock_delta | clock_on | false | final_clock |
    final_frame | frame_number | initial_clock | initial_frame |
    image_width | image_height | no | off | on | pi | true |
    version | yes |
FULL_EXPRESSION:
    LOGICAL_EXPRESSION [? FULL_EXPRESSION : FULL_EXPRESSION]
LOGICAL_EXPRESSION:
    REL_TERM [LOGICAL_OPERATOR REL_TERM]...
LOGICAL_OPERATOR:
    \& | | (note: this means an ampersand or a 
               vertical bar is a logical operator) 
REL_TERM:
    FLOAT [REL_OPERATOR FLOAT]...
REL_OPERATOR:
    < | <= | = | >= | > | !=
INT:
    FLOAT (note: any syntax which requires a
           integer INT will accept a FLOAT
           and it will be truncated to an
           integer internally by POV-Ray).
\end{verbatim}}


   \textbf{Note:} \textit{FLOAT\_\-IDENTIFIERS} are identifiers previously declared to have float values. The \textit{DOT\_\-ITEM} syntax is actually a vector or 
 color operator but it returns a float value. See "Vector Operators" or "Color Operators" for details. An \textit{ ARRAY\_\-IDENTIFIER} is 
 just the identifier name of a previously declared array, it does not include the {\small\texttt{[]}} braces nor the index. The syntax for \textit{STRING} is 
 in the section "Strings". 


\subsubsection{Literals}

% reference/000006.html

\index{Literals! float}\index{Float! literals}

   Float literals are represented by an optional sign ("+" or "-") digits, an optional decimal point and more digits. If the number is an 
 integer you may omit the decimal point and trailing zero. If it is all fractional you may omit the leading zero. POV-\discretionary{}{}{}Ray supports scientific notation for very 
 large or very small numbers. The following are all valid float literals: 



   {\small\texttt{ -2.0 -4 34 3.4e6 2e-5 .3 0.6}} 


\subsubsection{Identifiers}

% reference/000007.html

\index{Identifiers! float}\index{Float! identifiers}

   Float identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
FLOAT_DECLARATION:
    #declare IDENTIFIER = EXPRESSION;    |
    #local IDENTIFIER = EXPRESSION;
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{EXPRESSION} is any valid expression which evaluates to a float 
 value. 



   \textbf{Note:} there should be a semi-\discretionary{}{}{}colon after the expression in a float declaration. If omitted, it generates a warning and some macros may not work 
 properly. See " \#declare vs. \#local" for information on identifier scope. 



   Here are some examples. 


{\small\begin{verbatim}
 #declare Count = 0;
 #declare Rows = 5.3;
 #declare Cols = 6.15;
 #declare Number = Rows*Cols;
 #declare Count = Count+1;
\end{verbatim}}


   As the last example shows, you can re-\discretionary{}{}{}declare a float identifier and may use previously declared values in that re-\discretionary{}{}{}declaration. There are several built-\discretionary{}{}{}in 
 identifiers which POV-\discretionary{}{}{}Ray declares for you. See "Float Expressions: Built-\discretionary{}{}{}in Variables" for details. 


\subsubsection{Operators}

% reference/000008.html

\index{Operators! float}\index{Float! operators}

   \textbf{Arithmetic expressions:} Basic math expressions can be created from float literals, identifiers or functions using the following operators in this 
 order of precedence... 


\begin{table} \centering\begin{tabular*}{308pt}[t]{@{} p{92pt}@{} p{215pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{( )}} 
  } & 
{\raggedleft  expressions in parentheses first } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{+A -A !A}} 
  } & 
{\raggedleft  unary minus, unary plus and logical "not" } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{A*B A/B}} 
  } & 
{\raggedleft  multiplication and division } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{A+B A-\discretionary{}{}{}B}} 
  } & 
{\raggedleft  addition and subtraction } \\ 
 

\end{tabular*} \caption{Arithmetic expressions} \end{table}


   Relational, logical and conditional expressions may also be created. However there is a restriction that these types of expressions must be enclosed in 
 parentheses first. This restriction, which is not imposed by most computer languages, is necessary because POV-\discretionary{}{}{}Ray allows mixing of float and vector 
 expressions. Without the parentheses there is an ambiguity problem. Parentheses are not required for the unary logical not operator "!" as shown 
 above. The operators and their precedence are shown here. 



   \textbf{ Relational expressions:} The operands are arithmetic expressions and the result is always boolean with 1 for true and 0 for false. All relational 
 operators have the same precedence. 


\begin{table} \centering\begin{tabular*}{308pt}[t]{@{} p{92pt}@{} p{215pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{(A $<$ B)}} 
  } & 
{\raggedleft  A is less than B } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A $<$= B)}} 
  } & 
{\raggedleft  A is less than or equal to B } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A = B)}} 
  } & 
{\raggedleft  A is equal to B (actually abs(A-\discretionary{}{}{}B)$<$EPSILON) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A != B)}} 
  } & 
{\raggedleft  A is not equal to B (actually abs(A-\discretionary{}{}{}B)$>$=EPSILON) } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A $>$= B)}} 
  } & 
{\raggedleft  A is greater than or equal to B } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A $>$ B)}} 
  } & 
{\raggedleft  A is greater than B } \\ 
 

\end{tabular*} \caption{Relational expressions} \end{table}


   \textbf{Logical expressions:} The operands are converted to boolean values of 0 for false and 1 for true. The result is always boolean. All logical operators 
 have the same precedence. 



   \textbf{Note:} these are not bit-\discretionary{}{}{}wise operations, they are logical. 


\begin{table} \centering\begin{tabular*}{308pt}[t]{@{} p{92pt}@{} p{215pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{(A \& B)}} 
  } & 
{\raggedleft  true only if both A and B are true, false otherwise } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{(A | B)}} 
  } & 
{\raggedleft  true if either A or B or both are true } \\ 
 

\end{tabular*} \caption{Logical expressions} \end{table}


   \textbf{Conditional expressions:} The operand C is boolean while operands A and B are any expressions. The result is of the same type as A and B. 


\begin{table} \centering\begin{tabular*}{308pt}[t]{@{} p{92pt}@{} p{215pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{(C ? A : B)}} 
  } & 
{\raggedleft  if C then A else B } \\ 
 

\end{tabular*} \caption{Conditional expressions} \end{table}


   Assuming the various identifiers have been declared, the following are examples of valid expressions... 


{\small\begin{verbatim}
 1+2+3    2*5     1/3     Row*3    Col*5
 (Offset-5)/2      This/That+Other*Thing
 ((This<That) \& (Other>=Thing)?Foo:Bar)
\end{verbatim}}


   Expressions are evaluated left to right with innermost parentheses evaluated first, then unary +, - or !, then multiply or divide, then add or subtract, then 
 relational, then logical, then conditional. 


\subsubsection{Functions}

% reference/000015.html

\index{Float! functions}\index{Functions! float}

   POV-\discretionary{}{}{}Ray defines a variety of built-\discretionary{}{}{}in functions for manipulating floats, vectors and strings. Function calls consist of a keyword which specifies the name of 
 the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example: 


{\small\begin{verbatim}
 keyword(param1,param2)
\end{verbatim}}


   The following are the functions which return float values. They take one or more float, integer, vector, or string parameters. Assume that {\small\texttt{ A}} 
 and {\small\texttt{B}} are any valid expression that evaluates to a float; {\small\texttt{I}} is a float which is truncated to integer internally, {\small\texttt{S}}, 
 {\small\texttt{S1}}, {\small\texttt{S2}} etc. are strings, and {\small\texttt{ V}}, {\small\texttt{V1}}, {\small\texttt{V2}} etc. are any vector expressions.{\small\texttt{O}} 
 is an object identifier to a pre-\discretionary{}{}{}declared object. 



   \index{abs} {\small\texttt{abs(A)}} Absolute value of {\small\texttt{A}}. If {\small\texttt{A}} is negative, returns {\small\texttt{-A}} otherwise returns {\small\texttt{A}}. 
 



   \index{acos} {\small\texttt{ acos(A)}} Arc-\discretionary{}{}{}cosine of {\small\texttt{A}}. Returns the angle, measured in radians, whose cosine is {\small\texttt{A}}. 



   \index{acosh} {\small\texttt{acosh(A)}} inverse hyperbolic cosine of {\small\texttt{A}}. 



   \index{asc} {\small\texttt{ asc(S)}} Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of the string {\small\texttt{S}}. 
 For example {\small\texttt{ asc("ABC")}} is 65 because that is the value of the character "A". 



   \index{asin} {\small\texttt{asin(A)}} Arc-\discretionary{}{}{}sine of {\small\texttt{ A}}. Returns the angle, measured in radians, whose sine is {\small\texttt{ A}}. 



   \index{asinh} {\small\texttt{asinh(A)}} invers hyperbolic sine of {\small\texttt{A}} 



   \index{atan2} {\small\texttt{ atan2(\discretionary{A,}{}{A,}B)}} Arc-\discretionary{}{}{}tangent of {\small\texttt{(A/B)}}. Returns the angle, measured in radians, whose tangent is {\small\texttt{ 
 (A/B)}}. Returns appropriate value even if {\small\texttt{B}} is zero. Use {\small\texttt{atan2(\discretionary{A,}{}{A,}1)}} to compute usual atan(A) function. 



   \index{atanh} {\small\texttt{atanh(A)}} invers hyperbolic tangent of {\small\texttt{A}} 



   \index{ceil} {\small\texttt{ ceil(A)}} Ceiling of {\small\texttt{ A}}. Returns the smallest integer greater than {\small\texttt{A}}. Rounds up to the next 
 higher integer. 



   \index{cos} {\small\texttt{cos(A)}} Cosine of {\small\texttt{A}}. Returns the cosine of the angle {\small\texttt{A}}, where {\small\texttt{A}} is measured in 
 radians. 



   \index{cosh} {\small\texttt{cosh(A)}} The hyperbolic cosine of {\small\texttt{A}}. 



   \index{defined} {\small\texttt{ defined(}}\textit{IDENTIFIER}{\small\texttt{)}} Returns {\small\texttt{ true}} if the identifier is currently defined, {\small\texttt{ 
 false}} otherwise. This is especially useful for detecting end-\discretionary{}{}{}of-\discretionary{}{}{}file after a {\small\texttt{ \#read}} directive because the file identifier is automatically 
 undefined when end-\discretionary{}{}{}of-\discretionary{}{}{}file is reached. See "The \#read Directive" for details. 



   \index{degrees} {\small\texttt{degrees(A)}} Convert radians to degrees. Returns the angle measured in degrees whose value in radians is {\small\texttt{A}}. 
 Formula is \textit{ degrees=A/pi*180.0}. 



   \index{dimensions} {\small\texttt{ dimensions(}} \textit{ARRAY\_\-IDENTIFIER} {\small\texttt{)}} Returns the number of dimensions of a previously declared array 
 identifier. For example if you do {\small\texttt{\#declare MyArray=array[6][10]}} then {\small\texttt{ dimensions(MyArray)}} returns the value {\small\texttt{2}}. 
 



   \index{dimension\_\-size} {\small\texttt{ dimension\_\-size(}} \textit{ ARRAY\_\-IDENTIFIER, FLOAT} {\small\texttt{ )}} Returns the size of a given dimension of a 
 previously declared array identifier. Dimensions are numbered left-\discretionary{}{}{}to-\discretionary{}{}{}right starting with 1. For example if you do {\small\texttt{ \#declare 
 MyArray=array[6][10]}} then {\small\texttt{ dimension\_\-size(\discretionary{MyArray,}{}{MyArray,}2)}} returns the value {\small\texttt{10}}. 



   \index{div} {\small\texttt{ div(\discretionary{A,}{}{A,}B)}} Integer division. The integer part of {\small\texttt{ (A/B)}}. 



   \index{exp} {\small\texttt{exp(A)}} Exponential of {\small\texttt{A}}. Returns the value of \textit{ e} raised to the power {\small\texttt{ A}} where \textit{e} 
 is the base of the natural logarithm, \discretionary{i.}{}{i.}e. the non-\discretionary{}{}{}repeating value approximately equal to 2.71828182846. 



   \index{file\_\-exists} {\small\texttt{file\_\-exists(S)}} Attempts to open the file specified by the string {\small\texttt{S}}. The current directory and all 
 library directories specified by the {\small\texttt{Library\_\-Path}} or {\small\texttt{ +L}} options are also searched. See "Library Paths" for 
 details. Returns {\small\texttt{ 1}} if successful and {\small\texttt{0}} if unsuccessful. 



   \index{floor} {\small\texttt{ floor(A)}} Floor of {\small\texttt{A}}. Returns the largest integer less than {\small\texttt{A}}. Rounds down to the next lower 
 integer. 



   \index{inside} {\small\texttt{inside(\discretionary{O,}{}{O,}V)}} It returns either 0.0, when the vector {\small\texttt{V}} is outside the object, specified by the 
 object-\discretionary{}{}{}identifier {\small\texttt{O}}, or 1.0 if it is inside. 



   \textbf{Note:} {\small\texttt{inside}} does not accept object-\discretionary{}{}{}identifiers to non-\discretionary{}{}{}solid objects. 



   \index{int} {\small\texttt{ int(A)}} Integer part of {\small\texttt{A}}. Returns the truncated integer part of {\small\texttt{A}}. Rounds towards zero. 



   \index{log} {\small\texttt{ log(A)}} Logarithm of {\small\texttt{A}}. Returns the logarithm base \textit{10} of the value {\small\texttt{A}}. 



   \index{ln} {\small\texttt{ ln(A)}} Natural logarithm of {\small\texttt{A}}. Returns the natural logarithm base \textit{e} of the value {\small\texttt{A}}. 



   \index{max} {\small\texttt{ max(\discretionary{A,}{}{A,}B,...)}} Maximum of two or more float values. Returns {\small\texttt{A}} if {\small\texttt{A}} larger than {\small\texttt{B}}. 
 Otherwise returns {\small\texttt{B}}. 



   \index{min} {\small\texttt{min(\discretionary{A,}{}{A,}B,...)}} Minimum of two or more float values. Returns {\small\texttt{A}} if {\small\texttt{A}} smaller than {\small\texttt{ B}}. 
 Otherwise returns {\small\texttt{B}}. 



   \index{mod} {\small\texttt{mod(\discretionary{A,}{}{A,}B)}} Value of {\small\texttt{A}} modulo {\small\texttt{ B}}. Returns the remainder after the integer division of {\small\texttt{ 
 A}}/{\small\texttt{B}}. Formula is \textit{ mod=((A/B)-int(A/B))*B}. 



   \index{pow} {\small\texttt{ pow(\discretionary{A,}{}{A,}B)}} Exponentiation. Returns the value of {\small\texttt{A}} raised to the power {\small\texttt{B}}. 



   \textbf{Note:}For a negative A and a non-\discretionary{}{}{}integer B the function has no defined return value. The result then may depend on the platform POV-\discretionary{}{}{}Ray is compiled 
 on. 



   \index{radians} {\small\texttt{ radians(A)}} Convert degrees to radians. Returns the angle measured in radians whose value in degrees is {\small\texttt{A}}. 
 Formula is \textit{ radians=A*pi/180.0}. 



   \index{rand} {\small\texttt{rand(I)}} Returns the next pseudo-\discretionary{}{}{}random number from the stream specified by the positive integer {\small\texttt{I}}. You must 
 call {\small\texttt{ seed()}} to initialize a random stream before calling {\small\texttt{ rand()}}. The numbers are uniformly distributed, and have values 
 between {\small\texttt{0.0}} and {\small\texttt{1.0}}, inclusively. The numbers generated by separate streams are independent random variables. 



   \index{seed} {\small\texttt{ seed(I)}} Initializes a new pseudo-\discretionary{}{}{}random stream with the initial seed value {\small\texttt{A}}. The number corresponding to 
 this random stream is returned. Any number of pseudo-\discretionary{}{}{}random streams may be used as shown in the example below: 


{\small\begin{verbatim}
  #declare R1 = seed(0);
  #declare R2 = seed(12345);
  sphere { <rand(R1), rand(R1), rand(R1)>, rand(R2) }
\end{verbatim}}


   Multiple random generators are very useful in situations where you use {\small\texttt{rand()}} to place a group of objects, and then decide to use {\small\texttt{rand()}} 
 in another location earlier in the file to set some colors or place another group of objects. Without separate {\small\texttt{ rand()}} streams, all of your 
 objects would move when you added more calls to {\small\texttt{rand()}}. This is very annoying. 



   \index{select} {\small\texttt{select(A, B, C [,D])}}. It can be used with three or four parameters. {\small\texttt{Select}} compares the first argument with 
 zero, depending on the outcome it will return {\small\texttt{B}}, {\small\texttt{C}} or {\small\texttt{D}}. {\small\texttt{\discretionary{A,}{}{A,}B,\discretionary{C,}{}{C,}D}} can be floats or funtions.\newline  
 When used with three parameters, if {\small\texttt{A $<$ 0}} it will return {\small\texttt{B}}, else {\small\texttt{C}} ({\small\texttt{A $>$= 0}}).\newline  
 When used with four parameters, if {\small\texttt{A $<$ 0}} it will return B. If {\small\texttt{A = 0}} it will return {\small\texttt{C}}. Else it will 
 return {\small\texttt{D}} ({\small\texttt{A $>$ 0}}). 



   Example:\newline  If {\small\texttt{A}} has the consecutive values -2, -1, 0, 1, and 2 : 


{\small\begin{verbatim}
                           //    A =  -2 -1 0 1 2
  select (A, -1, 0, 1)     //returns  -1 -1 0 1 1 
  select (A, -1, 1)        //returns  -1 -1 1 1 1 
\end{verbatim}}


   \index{sin} {\small\texttt{sin(A)}} Sine of {\small\texttt{A}}. Returns the sine of the angle {\small\texttt{A}}, where {\small\texttt{ A}} is measured in 
 radians. 



   \index{sinh} {\small\texttt{sinh(A)}} The hyperbolic sine of {\small\texttt{A}}. 



   \index{strcmp} {\small\texttt{strcmp(\discretionary{S1,}{}{S1,}S2)}} Compare string {\small\texttt{S1}} to {\small\texttt{ S2}}. Returns a float value zero if the strings are 
 equal, a positive number if {\small\texttt{S1}} comes after {\small\texttt{S2}} in the ASCII collating sequence, else a negative number. 



   \index{strlen} {\small\texttt{ strlen(S)}} Length of {\small\texttt{S}}. Returns an integer value that is the number of characters in the string {\small\texttt{S}}. 
 



   \index{sqrt} {\small\texttt{ sqrt(A)}} Square root of {\small\texttt{A}}. Returns the value whose square is {\small\texttt{ A}}. 



   \index{tan} {\small\texttt{tan(A)}} Tangent of {\small\texttt{A}}. Returns the tangent of the angle {\small\texttt{A}}, where {\small\texttt{A}} is measured 
 in radians. 



   \index{tanh} {\small\texttt{tanh(A)}} The hyperbolic tangent of {\small\texttt{A}}. 



   \index{val} {\small\texttt{val(S)}} Convert string {\small\texttt{S}} to float. Returns a float value that is represented by the text in string {\small\texttt{S}}. 
 For example {\small\texttt{val("123.45")}} is 123.45 as a float. 



   \index{vdot} {\small\texttt{vdot(\discretionary{V1,}{}{V1,}V2)}} Dot product of {\small\texttt{V1}} and {\small\texttt{V2}}. Returns a float value that is the dot product 
 (sometimes called scalar product) of {\small\texttt{V1}} with {\small\texttt{V2}}. It is directly proportional to the length of the two vectors and the cosine 
 of the angle between them. Formula is \textit{vdot=\discretionary{V1.}{}{V1.}x*\discretionary{V2.}{}{V2.}x + \discretionary{V1.}{}{V1.}y*\discretionary{V2.}{}{V2.}y + \discretionary{V1.}{}{V1.}z*\discretionary{V2.}{}{V2.}z.} See the animated demo scene {\small\texttt{\discretionary{VECT2.}{}{VECT2.}POV}} for an 
 illustration. 



   \index{vlength} {\small\texttt{vlength(V)}} Length of {\small\texttt{V}}. Returns a float value that is the length of vector {\small\texttt{ V}}. Formula is \textit{ 
 vlength=sqrt(vdot(\discretionary{A,}{}{A,}A))}. Can be used to compute the distance between two points. {\small\texttt{ Dist=vlength(V2-V1)}}. 



   See section "Vector Functions" and section "String Functions" for other functions which are somewhat float-\discretionary{}{}{}related but which return 
 vectors and strings. In addition to the above built-\discretionary{}{}{}in functions, you may also define your own functions using the {\small\texttt{\#macro}} directive. See the 
 section "User Defined Macros" for more details. 


\subsubsection{Built-\discretionary{}{}{}in Constants}

% reference/000014.html

\index{boolean}\index{Float! boolean}\index{Float! built-\discretionary{}{}{}in constants}

   Constants are: 


{\small\begin{verbatim}
FLOAT_BUILT-IN_IDENT:
    false | no | off | on | pi | true | yes
\end{verbatim}}


   The built-\discretionary{}{}{}in constants never change value. They are defined as though the following lines were at the start of every scene. 


{\small\begin{verbatim}
  #declare pi = 3.1415926535897932384626;
  #declare true = 1;
  #declare yes = 1;
  #declare on = 1;
  #declare false = 0;
  #declare no = 0;
  #declare off = 0;
\end{verbatim}}
\index{true}\index{false}\index{yes}\index{no}\index{on}\index{off}\index{pi}

   The built-\discretionary{}{}{}in float identifier {\small\texttt{pi}} is obviously useful in math expressions involving circles. The built-\discretionary{}{}{}in float identifiers {\small\texttt{ on}}, 
 {\small\texttt{off}}, {\small\texttt{yes}}, {\small\texttt{no}}, {\small\texttt{ true}}, and {\small\texttt{false}} are designed for use as boolean constants. 



   The built-\discretionary{}{}{}in float constats {\small\texttt{on}}, {\small\texttt{off}}, {\small\texttt{ yes}}, {\small\texttt{no}}, {\small\texttt{true}}, and {\small\texttt{false}} 
 are most often used as boolean values with object modifiers or parameters such as {\small\texttt{sturm}}, {\small\texttt{hollow}}, {\small\texttt{hierarchy}}, {\small\texttt{smooth}}, 
 {\small\texttt{media\_\-attenuation}}, and {\small\texttt{media\_\-interaction}}. Whenever you see syntax of the form {\small\texttt{keyword}} \textit{{\small\texttt{[Bool]}}}, 
 if you simply specify the keyword without the optional boolean then it assumes {\small\texttt{keyword on}}. You need not use the boolean but for readability 
 it is a good idea. You must use one of the false booleans or an expression which evaluates to zero to turn it off. 



   \textbf{Note:} some of these keywords are {\small\texttt{on}} by default, if no keyword is specified. 



   For example: 


{\small\begin{verbatim}
  object { MyBlob }                // sturm defaults off, but
                                   // hierarchy defaults on
  object { MyBlob sturm }          // turn sturm on
  object { MyBlob sturm on }       // turn sturm on
  object { MyBlob sturm off }      // turn sturm off
  object { MyBlob hierarchy }      // does nothing, hierarchy was
                                   // already on
  object { MyBlob hierarchy off }  // turn hierarchy off
\end{verbatim}}

\subsubsection{Built-\discretionary{}{}{}in Variables}

% reference/000009.html

\index{Float! built-\discretionary{}{}{}in variables}

   There are several built-\discretionary{}{}{}in float variables. You can use them to specify values or to create expressions but you cannot re-\discretionary{}{}{}declare them to change their 
 values. 



   Clock-\discretionary{}{}{}related are: 


{\small\begin{verbatim}
FLOAT_BUILT-IN_IDENT:
   clock | clock_delta | clock_on | final_clock | final_frame
    frame_number | initial_clock | initial_frame
\end{verbatim}}


   These keywords allow to use the values of the clock which have been set in the command line switch options (or INI-\discretionary{}{}{}file). They represent float or integer 
 values, read from the animation options. You cannot re-\discretionary{}{}{}declare these identifiers.\index{clock} 



   {\small\texttt{\textbf{clock}}} \newline The built-\discretionary{}{}{}in float identifier {\small\texttt{clock}} is used to control animations in POV-\discretionary{}{}{}Ray. Unlike some animation 
 packages, the action in POV-\discretionary{}{}{}Ray animated scenes does not depend upon the integer frame numbers. Rather you should design your scenes based upon the float 
 identifier {\small\texttt{ clock}}. For non-\discretionary{}{}{}animated scenes its default value is 0 but you can set it to any float value using the INI file option {\small\texttt{Clock=}}\textit{\discretionary{n.}{}{n.}n} 
 or the command-\discretionary{}{}{}line switch {\small\texttt{+K}}\textit{\discretionary{n.}{}{n.}n} to pass a single float value your scene file. 



   Other INI options and switches may be used to animate scenes by automatically looping through the rendering of frames using various values for {\small\texttt{ 
 clock}}. By default, the clock value is 0 for the initial frame and 1 for the final frame. All other frames are interpolated between these values. \newline For 
 example if your object is supposed to rotate one full turn over the course of the animation you could specify {\small\texttt{rotate 360*clock*y}}. Then as 
 clock runs from 0 to 1, the object rotates about the y-\discretionary{}{}{}axis from 0 to 360 degrees. 



   Although the value of {\small\texttt{ clock}} will change from frame-\discretionary{}{}{}to-\discretionary{}{}{}frame, it will never change throughout the parsing of a scene.\index{clock\_\-delta} 



   {\small\texttt{\textbf{clock\_\-delta}}} \newline The built-\discretionary{}{}{}in float identifier {\small\texttt{clock\_\-delta}} returns the amount of time between clock values in 
 animations in POV-\discretionary{}{}{}Ray. While most animations only need the clock value itself, some animation calculations are easier if you know how long since the last 
 frame. Caution must be used when designing such scenes. If you render a scene with too few frames, the results may be different than if you render with more 
 frames in a given time period. On non-\discretionary{}{}{}animated scenes, {\small\texttt{clock\_\-delta}} defaults to 1.0. See section "Animation Options" for more 
 details.\index{clock\_\-on} 



   {\small\texttt{\textbf{clock\_\-on}}} \newline With this identifier the status of the clock can be checked: 1 is on, 0 is off. 


{\small\begin{verbatim}
  #if(clock_on=0)
    //stuff for still image
  #else
    //some animation
  #end
\end{verbatim}}
\index{frame\_\-number}

   {\small\texttt{\textbf{frame\_\-number}}} \newline If you rather want to define the action in POV-\discretionary{}{}{}Ray animated scenes depending upon the integer frame numbers, 
 this identifier can be used. \newline It reads the number of the frame currently being rendered. 


{\small\begin{verbatim}
  #if(frame_number=1)
    //stuff for first image or frame
  #end
  #if(frame_number=2)
    //stuff for second image or frame
  #end
  #if(frame_number=n)
    //stuff for n th image or frame
  #end
\end{verbatim}}
\index{initial\_\-clock}

   {\small\texttt{\textbf{initial\_\-clock}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Initial\_\-Clock=}}\textit{\discretionary{n.}{}{n.}n} 
 or the command-\discretionary{}{}{}line switch {\small\texttt{+KI}}\textit{\discretionary{n.}{}{n.}n}.\index{final\_\-clock} 



   {\small\texttt{\textbf{final\_\-clock}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Final\_\-Clock=}}\textit{\discretionary{n.}{}{n.}n} or 
 the command-\discretionary{}{}{}line switch {\small\texttt{+KF}}\textit{\discretionary{n.}{}{n.}n}.\index{initial\_\-frame} 



   {\small\texttt{\textbf{initial\_\-frame}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Initial\_\-Frame=}}\textit{n} or 
 the command-\discretionary{}{}{}line switch {\small\texttt{+KFI}}\textit{n}.\index{final\_\-frame} 



   {\small\texttt{\textbf{final\_\-frame}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Final\_\-Frame=}}\textit{n} or the 
 command-\discretionary{}{}{}line switch {\small\texttt{+KFF}}\textit{n}. 



   \textbf{Note:} that these values are the ones actually used. When the option 'cyclic animation' is set, they could be different from the ones originally set 
 in the options. 



   Image-\discretionary{}{}{}size are: 


{\small\begin{verbatim}
FLOAT_BUILT-IN_IDENT:
     image_width | image_height
\end{verbatim}}
\index{image\_\-width}

   {\small\texttt{\textbf{image\_\-width}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Width=}}\textit{n} or the 
 command-\discretionary{}{}{}line switch {\small\texttt{+W}}\textit{n}.\index{image\_\-height} 



   {\small\texttt{\textbf{image\_\-height}}} \newline This identifier reads the value set through the INI file option {\small\texttt{Height=}}\textit{n} or the 
 command-\discretionary{}{}{}line switch {\small\texttt{+H}}\textit{n}. 



   You could use these keywords to set the camera ratio (up and right vectors) correctly. The viewing angle of the camera covers the full width of the rendered 
 image. The camera ratio will always follow the ratio of the image width to height, regardless of the set image size. Use it like this: 


{\small\begin{verbatim}
  up y*image_height
  right x*image_width
\end{verbatim}}


   You could also make some items of the scene dependent on the image size: 


{\small\begin{verbatim}  
  #if (image_width < 300) crand 0.1 #else crand 0.5 #end

or:

  image_map {
    pattern image_width, image_width {  //make pattern resolution
      gradient x                        //dependent of render width
      color_map { [ 0.0 ... ] [ 1.0 ... ] }
    }
  }
\end{verbatim}}


   Version is: 


{\small\begin{verbatim}
FLOAT_BUILT-IN_IDENT:
     version
\end{verbatim}}


   The built-\discretionary{}{}{}in float variable {\small\texttt{ version}} contains the current setting of the version compatibility option. Although this value defaults to the 
 current POV-\discretionary{}{}{}Ray version number, the initial value of {\small\texttt{ version}} may be set by the INI file option {\small\texttt{ Version=}}\textit{\discretionary{n.}{}{n.}n} or by 
 the {\small\texttt{ +MV}}\textit{\discretionary{n.}{}{n.}n} command-\discretionary{}{}{}line switch. This tells POV-\discretionary{}{}{}Ray to parse the scene file using syntax from an earlier version of POV-\discretionary{}{}{}Ray. 



   The INI option or switch only affects the initial setting. Unlike other built-\discretionary{}{}{}in identifiers, you may change the value of {\small\texttt{version}} throughout 
 a scene file. You do not use {\small\texttt{\#declare}} to change it though. The {\small\texttt{ \#version}} language directive is used to change modes. Such 
 changes may occur several times within scene files. 



   Together with the built-\discretionary{}{}{}in {\small\texttt{ version}} identifier the {\small\texttt{ \#version}} directive allows you to save and restore the previous values 
 of this compatibility setting. The new {\small\texttt{\#local}} identifier option is especially useful here. For example suppose {\small\texttt{\discretionary{mystuff.}{}{mystuff.}inc}} 
 is in version 1 format. At the top of the file you could put: 


{\small\begin{verbatim}
 #local Temp_Vers = version;  // Save previous value
 #version 1.0;                // Change to 1.0 mode
 ...                          // Version 1.0 stuff goes here...
 #version Temp_Vers;          // Restore previous version
\end{verbatim}}


   \textbf{Note:} there should be a semi-\discretionary{}{}{}colon after the float expression in a {\small\texttt{\#version}} directive. If omitted, it generates a warning and some 
 macros may not work properly. 


\subsection{Vector Expressions}

% reference/000016.html

\index{Expressions! vector}\index{Vector! expressions}\index{Vector}

   POV-\discretionary{}{}{}Ray often requires you to specify a \textit{vector}. A vector is a set of related float values. Vectors may be specified using literals, identifiers or 
 functions which return vector values. You may also create very complex vector expressions from combinations of any of these using various familiar operators. 



   POV-\discretionary{}{}{}Ray vectors may have from two to five components but the vast majority of vectors have three components. Unless specified otherwise, you should assume 
 that the word "vector" means a three component vector. POV-\discretionary{}{}{}Ray operates in a 3D x, y, z coordinate system and you will use three component vectors 
 to specify x, y and z values. In some places POV-\discretionary{}{}{}Ray needs only two coordinates. These are often specified by a 2D vector called an \textit{ UV vector}. 
 Fractal objects use 4D vectors. Color expressions use 5D vectors but allow you to specify 3, 4 or 5 components and use default values for the unspecified 
 components. Unless otherwise noted, all 2, 4 or 5 component vectors work just like 3D vectors but they have a different number of components. 



   The syntax for combining vector literals into vector expressions is almost identical to the rules for float expressions. In the syntax for vector expressions 
 below, some of the syntax items are defined in the section for float expressions. See "Float Expressions" for those definitions. Detailed 
 explanations of vector-\discretionary{}{}{}specific issues are given in the following sub-\discretionary{}{}{}sections. 


{\small\begin{verbatim}
VECTOR:
    NUMERIC_TERM [SIGN NUMERIC_TERM]
NUMERIC_TERM:
    NUMERIC_FACTOR [MULT NUMERIC_FACTOR]
NUMERIC_FACTOR:
    VECTOR_LITERAL        | 
    VECTOR_IDENTIFIER     | 
    SIGN NUMERIC_FACTOR   | 
    VECTOR_FUNCTION       |
    VECTOR_BUILT-IN_IDENT | 
    ( FULL_EXPRESSION )   | 
    ! NUMERIC_FACTOR      | 
    FLOAT
VECTOR_LITERAL:
    < FLOAT , FLOAT , FLOAT >
VECTOR_FUNCTION:
    min_extent ( OBJECT_IDENTIFIER )         |
    max_extent ( OBJECT_IDENTIFIER )         |
    trace(OBJECT_IDENTIFIER, VECTOR, VECTOR, [VECTOR_IDENTIFIER] )|
    vaxis_rotate( VECTOR , VECTOR , FLOAT )  |
    vcross( VECTOR , VECTOR )                |
    vrotate( VECTOR , VECTOR )               | 
    vnormalize( VECTOR )                     |
    vturbulence(FLOAT, FLOAT, FLOAT, VECTOR)
VECTOR_BUILT-IN_IDENT:
     x | y | z | t | u | v
\end{verbatim}}


   Note: \textit{VECTOR\_\-IDENTIFIERS} are identifiers previously declared to have vector values. 


\subsubsection{Literals}

% reference/000017.html

\index{literals! vector}\index{Vector! literals}

   Vector literals consist of two to five float expressions that are bracketed by angle brackets {\small\texttt{$<$}} and {\small\texttt{$>$}}. The terms are 
 separated by commas. For example here is a typical three component vector: 


{\small\begin{verbatim}
 < 1.0, 3.2, -5.4578 >
\end{verbatim}}


   The commas between components are necessary to keep the program from thinking that the 2nd term is the single float expression {\small\texttt{ 3.2-5.4578}} 
 and that there is no 3rd term. If you see an error message such as "Float expected but '$>$' found instead" then you probably have missed a comma. 



   Sometimes POV-\discretionary{}{}{}Ray requires you to specify floats and vectors side-\discretionary{}{}{}by-\discretionary{}{}{}side. The rules for vector expressions allow for mixing of vectors with vectors or 
 vectors with floats so commas are required separators whenever an ambiguity might arise. For example {\small\texttt{ $<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$-4}} evaluates as a mixed 
 float and vector expression where 4 is subtracted from each component resulting in {\small\texttt{ $<$-3,-2,-1$>$}}. However the comma in {\small\texttt{ 
 $<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$,-4}} means this is a vector followed by a float. 



   Each component may be a full float expression. For example 


{\small\begin{verbatim}
 <This+3,That/3,5*Other_Thing>
\end{verbatim}}


   is a valid vector. 


\subsubsection{Identifiers}

% reference/000018.html

\index{Identifiers! vector}\index{Vector! identifiers}

   Vector identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
VECTOR_DECLARATION:
    #declare IDENTIFIER = EXPRESSION; |
    #local IDENTIFIER = EXPRESSION;
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{EXPRESSION} is any valid expression which evaluates to a vector 
 value. 



   \textbf{Note:} there should be a semi-\discretionary{}{}{}colon after the expression in a vector declaration. If omitted, it generates a warning and some macros may not work 
 properly. See " \#declare vs. \#local" for information on identifier scope. 



   Here are some examples.... 


{\small\begin{verbatim}
 #declare Here = <1,2,3>;
 #declare There = <3,4,5>;
 #declare Jump = <Foo*2,Bar-1,Bob/3>;
 #declare Route = There-Here;
 #declare Jump = Jump+<1,2,3>;
\end{verbatim}}


   \textbf{Note:} you invoke a vector identifier by using its name without any angle brackets. As the last example shows, you can re-\discretionary{}{}{}declare a vector identifier 
 and may use previously declared values in that re-\discretionary{}{}{}declaration. There are several built-\discretionary{}{}{}in identifiers which POV-\discretionary{}{}{}Ray declares for you. See section "Built-\discretionary{}{}{}in 
 Vector Identifiers" for details. 


\subsubsection{Operators}

% reference/000019.html

\index{Vector! operators}\index{Operators! vector}

   Vector literals, identifiers and functions may also be combined in expressions the same as float values. Operations are performed on a component-\discretionary{}{}{}by-\discretionary{}{}{}component 
 basis. For example {\small\texttt{$<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$ + $<$\discretionary{4,}{}{4,}\discretionary{5,}{}{5,}6$>$}} evaluates the same as {\small\texttt{$<$1+\discretionary{4,}{}{4,}2+\discretionary{5,}{}{5,}3+6$>$}} or {\small\texttt{$<$\discretionary{5,}{}{5,}\discretionary{7,}{}{7,}9$>$}}. 
 Other operations are done on a similar component-\discretionary{}{}{}by-\discretionary{}{}{}component basis. For example {\small\texttt{($<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$ = $<$\discretionary{3,}{}{3,}\discretionary{2,}{}{2,}1$>$)}} evaluates to {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{1,}{}{1,}0$>$}} 
 because the middle components are equal but the others are not. Admittedly this is not very useful but it is consistent with other vector operations. 



   Conditional expressions such as {\small\texttt{(C ? A : B)}} require that {\small\texttt{ C}} is a float expression but {\small\texttt{A}} and {\small\texttt{B}} 
 may be vector expressions. The result is that the entire conditional evaluates as a valid vector. For example if {\small\texttt{Foo}} and {\small\texttt{ Bar}} 
 are floats then {\small\texttt{(Foo $<$ Bar ? $<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$ : $<$\discretionary{5,}{}{5,}\discretionary{6,}{}{6,}7$>$)}} evaluates as the vector {\small\texttt{$<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$}} if {\small\texttt{Foo}} 
 is less than {\small\texttt{ Bar}} and evaluates as {\small\texttt{ $<$\discretionary{5,}{}{5,}\discretionary{6,}{}{6,}7$>$}} otherwise. 



   \index{t}\index{u}\index{v}\index{x}\index{y}\index{z} You may use the dot operator to extract a single float component from a vector. Suppose the identifier {\small\texttt{ 
 Spot}} was previously defined as a vector. Then {\small\texttt{\discretionary{Spot.}{}{Spot.}x}} is a float value that is the first component of this x, y, z vector. Similarly {\small\texttt{\discretionary{Spot.}{}{Spot.}y}} 
 and {\small\texttt{\discretionary{Spot.}{}{Spot.}z}} reference the 2nd and 3rd components. If {\small\texttt{Spot}} was a two component UV vector you could use {\small\texttt{\discretionary{Spot.}{}{Spot.}u}} 
 and {\small\texttt{\discretionary{Spot.}{}{Spot.}v}} to extract the first and second component. For a 4D vector use {\small\texttt{ .x}}, {\small\texttt{ .y}}, {\small\texttt{.z}}, 
 and {\small\texttt{.t}} to extract each float component. The dot operator is also used in color expressions which are covered later. 


\subsubsection{Operator Promotion}

% reference/000020.html

\index{Operators! promotion}

   You may use a lone float expression to define a vector whose components are all the same. POV-\discretionary{}{}{}Ray knows when it needs a vector of a particular type and will 
 promote a float into a vector if need be. For example the POV-\discretionary{}{}{}Ray {\small\texttt{scale}} statement requires a three component vector. If you specify {\small\texttt{scale 
 5}} then POV-\discretionary{}{}{}Ray interprets this as {\small\texttt{scale $<$\discretionary{5,}{}{5,}\discretionary{5,}{}{5,}5$>$}} which means you want to scale by 5 in every direction. 



   Versions of POV-\discretionary{}{}{}Ray prior to 3.0 only allowed such use of a float as a vector in various limited places such as {\small\texttt{scale}} and {\small\texttt{ 
 turbulence}}. However you may now use this trick anywhere. For example... 


{\small\begin{verbatim}
 box{0,1}  // Same as box{<0,0,0>,<1,1,1>}
 sphere{0,1} // Same as sphere{<0,0,0>,1}
\end{verbatim}}


   When promoting a float into a vector of 2, 3, 4 or 5 components, all components are set to the float value, however when promoting a vector of a lower number 
 of components into a higher order vector, all remaining components are set to zero. For example if POV-\discretionary{}{}{}Ray expects a 4D vector and you specify {\small\texttt{9}} 
 the result is {\small\texttt{$<$\discretionary{9,}{}{9,}9,\discretionary{9,}{}{9,}9$>$}} but if you specify {\small\texttt{$<$\discretionary{7,}{}{7,}6$>$}} the result is {\small\texttt{ $<$\discretionary{7,}{}{7,}6,\discretionary{0,}{}{0,}0$>$}}. 


\subsubsection{Functions}

% reference/000022.html

\index{Vector! functions}\index{Functions! vector}

   POV-\discretionary{}{}{}Ray defines a variety of built-\discretionary{}{}{}in functions for manipulating floats, vectors and strings. Function calls consist of a keyword which specifies the name of 
 the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example: 


{\small\begin{verbatim}
 keyword(param1,param2)
\end{verbatim}}


   The following are the functions which return vector values. They take one or more float, integer, vector, or string parameters. Assume that {\small\texttt{ A}} 
 and {\small\texttt{B}} are any valid expression that evaluates to a vector; and {\small\texttt{F}} is any float expression.\index{min\_\-extent}\index{max\_\-extent} 
 



   {\small\texttt{min\_\-extent(OBJECT\_\-IDENTIFIER), max\_\-extent(OBJECT\_\-IDENTIFIER)}}. The {\small\texttt{min\_\-extent}} and {\small\texttt{max\_\-extent}} return the 
 minimum and maximum coordinates of a \#declared object's bounding box (Corner1 and Corner2), in effect allowing you to find the dimensions and location of the 
 object. 



   \textbf{Note:} this is not perfect, in some cases (such as CSG intersections and differences or isosurfaces) the bounding box does not represent the actual 
 dimensions of the object. 



   Example: 


{\small\begin{verbatim}
#declare Sphere =
sphere {
  <0,0,0>, 1
  pigment { rgb <1,0,0> }
}
#declare Min = min_extent ( Sphere );
#declare Max = max_extent ( Sphere );
object { Sphere }
box {
    Min, Max
    pigment { rgbf <1,1,1,0.5> }
}
\end{verbatim}}
\index{trace}

   {\small\texttt{trace(OBJECT\_\-IDENTIFIER, A, B, [VECTOR\_\-IDENTIFIER])}}. {\small\texttt{trace}} helps you finding the exact location of a ray intersecting with 
 an object's surface. It traces a ray beginning at the point {\small\texttt{A}} in the direction specified by the vector {\small\texttt{B}}. If the ray hits 
 the specified object, this function returns the coordinate where the ray intersected the object. If not, it returns {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}. If a 
 fourth parameter in the form of a vector identifier is provided, the normal of the object at the intersection point (not including any normal perturbations 
 due to textures) is stored into that vector. If no intersection was found, the normal vector is reset to {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}. 



   \textbf{Note:} Checking the normal vector for {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}} is the only reliable way to determine whether an intersection has actually 
 occurred, intersections can and do occur anywhere, including at {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}. 



   Example: 


{\small\begin{verbatim}
#declare MySphere = sphere { <0, 0, 0>, 1 } 
#declare Norm = <0, 0, 0>; 
#declare Start = <1, 1, 1>; 
#declare Inter= 
  trace ( MySphere, Start, <0, 0, 0>-Start, Norm ); 
  object { 
    MySphere 
    texture { 
      pigment { rgb 1} 
    } 
  } 
  #if (vlength(Norm)!=0) 
  cylinder { 
    Inter, Inter+Norm, .1 
    texture { 
      pigment {color red 1} 
    } 
  } 
 #end
\end{verbatim}}
\index{vaxis\_\-rotate}

   {\small\texttt{vaxis\_\-rotate(\discretionary{A,}{}{A,}\discretionary{B,}{}{B,}F)}} Rotate {\small\texttt{A}} about {\small\texttt{ B}} by {\small\texttt{F}}. Given the \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z coordinates of a point in 
 space designated by the vector {\small\texttt{A}}, rotate that point about an arbitrary axis defined by the vector {\small\texttt{B}}. Rotate it through an 
 angle specified in degrees by the float value {\small\texttt{F}}. The result is a vector containing the new \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z coordinates of the point.\index{vcross} 



   {\small\texttt{vcross(\discretionary{A,}{}{A,}B)}} Cross product of {\small\texttt{A}} and {\small\texttt{B}}. Returns a vector that is the vector cross product of the two 
 vectors. The resulting vector is perpendicular to the two original vectors and its length is equal to the area of the parallelogram defined by them. Or to put 
 in an other way, the cross product can also be formulated as:\textit{{\small\texttt{ AxB = |A| * |B| * sin(angle(\discretionary{A,}{}{A,}B)) * perpendicular\_\-unit\_\-vector(\discretionary{A,}{}{A,}B) }}} So 
 the length of the resulting vector is proportional to the sine of the angle between {\small\texttt{A}} and {\small\texttt{B}}. See the animated demo scene {\small\texttt{\discretionary{VECT2.}{}{VECT2.}POV}} 
 for an illustration.\index{vnormalize} 



   {\small\texttt{vnormalize(A)}} Normalize vector {\small\texttt{ A}}. Returns a unit length vector that is the same direction as {\small\texttt{ A}}. Formula 
 is \textit{ vnormalize(A)=A/vlength(A)}. 



   \textbf{Note:}{\small\texttt{vnormalize($<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$)}} will result in an error.\index{vrotate} 



   {\small\texttt{vrotate(\discretionary{A,}{}{A,}B)}} Rotate {\small\texttt{ A}} about origin by {\small\texttt{ B}}. Given the \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z coordinates of a point in space designated by 
 the vector {\small\texttt{A}}, rotate that point about the origin by an amount specified by the vector {\small\texttt{B}}. Rotate it about the x-\discretionary{}{}{}axis by an 
 angle specified in degrees by the float value {\small\texttt{ \discretionary{B.}{}{B.}x}}. Similarly {\small\texttt{ \discretionary{B.}{}{B.}y}} and {\small\texttt{\discretionary{B.}{}{B.}z}} specify the amount to rotate in 
 degrees about the y-\discretionary{}{}{}axis and z-\discretionary{}{}{}axis. The result is a vector containing the new \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z coordinates of the point.\index{vturbulence} 



   {\small\texttt{vturbulence(Lambda, Omega, Octaves, A)}} Turbulence vector at A. Given the \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z coordinates of a point in space designated by the vector A, 
 return the turbulence vector for that point based on the numbers given for Lambda, Omega and Octaves. For the meaning of the parameters, check out the Lambda, 
 Omega and Octaves sections.\newline  The amount of turbulence can be controlled by multiplying the turbulence vector by a multiple. The frequency at which the 
 turbulence vector changes can be controlled by multiplying A with a multiple. The turbulence vector returned by the function can be added to the original 
 point A to obtain a turbulated version of the point A. Example :\newline  {\small\texttt{\#declare MyVector = MyVector + Amount * vturbulence(2, 0.5, 6, 
 MyVector * Frequency);}} 



   See section "Float Functions" for other functions which are somewhat vector-\discretionary{}{}{}related but which return floats. In addition to the above built-\discretionary{}{}{}in 
 functions, you may also define your own functions using the {\small\texttt{\#macro}} directive. See the section "User Defined Macros" for more 
 details. 


\subsubsection{Built-\discretionary{}{}{}in Constants}

% reference/000021.html

\index{Vector! built-\discretionary{}{}{}in identifiers}

   There are several built-\discretionary{}{}{}in vector identifiers. You can use them to specify values or to create expressions but you cannot re-\discretionary{}{}{}declare them to change their 
 values. They are: 


{\small\begin{verbatim}
VECTOR_BUILT-IN_IDENT:
    x | y | z | t | u | v
\end{verbatim}}


   All built-\discretionary{}{}{}in vector identifiers never change value. They are defined as though the following lines were at the start of every scene. 


{\small\begin{verbatim}
 #declare x = <1, 0, 0>;
 #declare y = <0, 1, 0>;
 #declare z = <0, 0, 1>;
 #declare t = <0, 0, 0, 1>;
 #declare u = <1, 0>;
 #declare v = <0, 1>;
\end{verbatim}}


   The built-\discretionary{}{}{}in vector identifiers {\small\texttt{x}}, {\small\texttt{y}}, and {\small\texttt{ z}} provide much greater readability for your scene files when 
 used in vector expressions. For example.... 


{\small\begin{verbatim}
 plane { y, 1}    // The normal vector is obviously "y".
 plane { <0,1,0>, 1} // This is harder to read.
 translate 5*x    // Move 5 units in the "x" direction.
 translate <5,0,0>  // This is less obvious.
\end{verbatim}}


   An expression like {\small\texttt{5*x}} evaluates to {\small\texttt{ 5*$<$\discretionary{1,}{}{1,}\discretionary{0,}{}{0,}0$>$}} or {\small\texttt{$<$\discretionary{5,}{}{5,}\discretionary{0,}{}{0,}0$>$}}. 



   Similarly {\small\texttt{ u}} and {\small\texttt{v}} may be used in 2D vectors. When using 4D vectors you should use {\small\texttt{x}}, {\small\texttt{y}}, {\small\texttt{ 
 z}}, and {\small\texttt{ t}} and POV-\discretionary{}{}{}Ray will promote {\small\texttt{x}}, {\small\texttt{ y}}, and {\small\texttt{ z}} to 4D when used where 4D is required. 


\subsection{Specifying Colors}

% reference/000023.html

\index{Color! specifying}
{\small\begin{verbatim}
COLOR:
    COLOR_BODY             |
    color COLOR_BODY       | (this means the keyword color or
    colour COLOR_BODY         colour may optionally precede
                              any color specification)
COLOR_BODY:
    COLOR_VECTOR           |
    COLOR_KEYWORD_GROUP    |
    COLOR_IDENTIFIER
COLOR_VECTOR:
    rgb <3_Term_Vector>  |
    rgbf <4_Term_Vector> |
    rgbt <4_Term_Vector> |
    [ rgbft ] <5_Term_Vector>
COLOR_KEYWORD_GROUP:
    [ COLOR_KEYWORD_ITEM ]...
COLOR_KEYWORD_ITEM:
    COLOR_IDENTIFIER       |
    red Red_Amount         |
    blue Blue_Amount       |
    green Green_Amount     |
    filter Filter_Amount   |
    transmit Transmit_Amount
\end{verbatim}}


   \textbf{Note:} \textit{COLOR\_\-IDENTIFIERS} are identifiers previously declared to have color values. The 3, 4, and 5 term vectors are usually vector literals 
 but may be vector expressions or floats promoted to vectors. See "Operator Promotion" and the sections below.\index{color}\index{colour}\index{filter}\index{transmit} 
 



   POV-\discretionary{}{}{}Ray often requires you to specify a color. Colors consist of five values or color components. The first three are called {\small\texttt{red}}, {\small\texttt{green}}, 
 and {\small\texttt{blue}}. They specify the intensity of the primary colors red, green and blue using an additive color system like the one used by the red, 
 green and blue color phosphors on a color monitor. 



   The 4th component, called {\small\texttt{filter}}, specifies the amount of filtered transparency of a substance. Some real-\discretionary{}{}{}world examples of filtered 
 transparency are stained glass windows or tinted cellophane. The light passing through such objects is tinted by the appropriate color as the material 
 selectively absorbs some frequencies of light while allowing others to pass through. The color of the object is subtracted from the light passing through so 
 this is called subtractive transparency. 



   The 5th component, called {\small\texttt{transmit}}, specifies the amount of non-\discretionary{}{}{}filtered light that is transmitted through a surface. Some real-\discretionary{}{}{}world 
 examples of non-\discretionary{}{}{}filtered transparency are thin see-\discretionary{}{}{}through cloth, fine mesh netting and dust on a surface. In these examples, all frequencies of light are 
 allowed to pass through tiny holes in the surface. Although the amount of light passing through is diminished, the color of the light passing through is 
 unchanged. 



   The color of the object and the color transmitted through the object together contribute 100\% of the final color. So if {\small\texttt{transmit}} is set to 
 0.9, the transmitted color contributes 90\% and the color of the object contributes only 10\%. This is also true outside of the 0-1 range, so for example if {\small\texttt{transmit}} 
 is set to 1.7, the transmitted color contributes with 170\% and the color of the object contributes with minus 70\%. Using {\small\texttt{transmit}} values 
 outside of the 0-1 range can be used to create interesting special effects, but does not correspond to any phenomena seen in the real world. An example: 


{\small\begin{verbatim}
#version 3.5;
global_settings {assumed_gamma 1.0}
camera {location -2.5*z look_at 0 orthographic}
box {
   0,1
   texture {
      pigment {
         gradient y
         colour_map {
            [0, red 1]
            [1, blue 1]
         }
      }
      finish{ambient 1}
   }
   texture {
      pigment {
         gradient x
         colour_map {
            [0, rgb 0.5 transmit -3]
            [1, rgb 0.5 transmit  3]
         }
      }
      finish{ambient 1}
   }
   translate <-0.5,-0.5,0>
   scale <3,2,1>
}
\end{verbatim}}


   When using the {\small\texttt{transmit}} value for special effects, you can visualize it this way: The {\small\texttt{transmit}} value means 
 "contrast". 1.0 is no change in contrast, 0.5 is half contrast, 2.0 is double contrast and so on. You could say that {\small\texttt{transmit}} 
 "scales" the colors. The color of the object is the "center value". All colors will get closer to the "center value" if {\small\texttt{transmit}} 
 is between 0 and 1, and all colors will spread away from the "center value" if {\small\texttt{transmit}} is greater than 1. If {\small\texttt{transmit}} 
 is negative the colors will be inverted around the "center value". Rgb 0.5 is common to use as "center value", but other values can be 
 used for other effects. The "center value" really is a color, and non-\discretionary{}{}{}gray colors can be used for interesting effects. The red, green and blue 
 components are handled separately. 



   \textbf{Note:} early versions of POV-\discretionary{}{}{}Ray used the keyword {\small\texttt{alpha}} to specify filtered transparency. However that word is often used to 
 describe non-\discretionary{}{}{}filtered transparency. For this reason {\small\texttt{alpha}} is no longer used. 



   Each of the five components of a color are float values which are normally in the range between 0.0 and 1.0. However any values, even negatives may be used. 



   Under most circumstances the keyword {\small\texttt{color}} is optional and may be omitted. We also support the British or Canadian spelling {\small\texttt{ 
 colour}}. Colors may be specified using vectors, keywords with floats or identifiers. You may also create very complex color expressions from combinations of 
 any of these using various familiar operators. The syntax for specifying a color has evolved since POV-\discretionary{}{}{}Ray was first released. We have maintained the original 
 keyword-\discretionary{}{}{}based syntax and added a short-\discretionary{}{}{}cut vector notation. Either the old or new syntax is acceptable however the vector syntax is easier 
 to use when creating color expressions. 



   The syntax for combining color literals into color expressions is almost identical to the rules for vector and float expressions. In the syntax for vector 
 expressions, some of the syntax items are defined in the section for float expressions. See "Float Expressions" for those definitions. Detailed 
 explanations of color-\discretionary{}{}{}specific issues are given in the following sub-\discretionary{}{}{}sections. 


\subsubsection{Color Vectors}

% reference/000024.html

\index{Vector! color}\index{Color! vectors}\index{rgb}

   The syntax for a color vector is... 


{\small\begin{verbatim}
COLOR_VECTOR:
    rgb <3_Term_Vector>   |
    rgbf <4_Term_Vector>  |
    rgbt <4_Term_Vector>  |
    [ rgbft ] <5_Term_Vector>
\end{verbatim}}


   ...where the vectors are any valid vector expressions of 3, 4 or 5 components. For example 


{\small\begin{verbatim}
 color rgb <1.0, 0.5, 0.2>
\end{verbatim}}


   This specifies a color whose red component is 1.0 or 100\% of full intensity. The green component is 0.5 or 50\% of full intensity and the blue component is 
 0.2 or 20\% of full intensity. Although the filter and transmit components are not explicitly specified, they exist and are set to their default values of 0 or 
 no transparency. 



   \index{rgbf}\index{rgbt}\index{rgbft} The {\small\texttt{rgbf}} keyword requires a four component vector. The 4th component is the filter component and the 
 transmit component defaults to zero. Similarly the {\small\texttt{ rgbt}} keyword requires four components where the 4th value is moved to the 5th component 
 which is transmit and then the filter component is set to zero. 



   The {\small\texttt{rgbft}} keyword allows you to specify all five components. Internally in expressions all five are always used. 



   Under some circumstances, if the vector expression is a 5 component expression or there is a color identifier in the expression then the {\small\texttt{ rgbtf}} 
 keyword is optional. 


\subsubsection{Color Keywords}

% reference/000025.html

\index{Keywords! color}\index{Color! keywords}\index{red}\index{green}\index{blue}

   The older keyword method of specifying a color is still useful and many users prefer it. 


{\small\begin{verbatim}
COLOR_KEYWORD_GROUP:
    [ COLOR_KEYWORD_ITEM ]...
COLOR_KEYWORD_ITEM:
    COLOR_IDENTIFIER |
    red Red_Amount | blue Blue_Amount | green Green_Amount | 
    filter Filter_Amount | transmit Transmit_Amount
\end{verbatim}}


   Although the {\small\texttt{color}} keyword at the beginning is optional, it is more common to see it in this usage. This is followed by any of five 
 additional keywords {\small\texttt{red}}, {\small\texttt{green}}, {\small\texttt{ blue}}, {\small\texttt{filter}}, or {\small\texttt{transmit}}. Each of these 
 component keywords is followed by a float expression. For example 


{\small\begin{verbatim}
 color red 1.0 green 0.5
\end{verbatim}}


   This specifies a color whose red component is 1.0 or 100\% of full intensity and the green component is 0.5 or 50\% of full intensity. Although the blue, 
 filter and transmit components are not explicitly specified, they exist and are set to their default values of 0. The component keywords may be given in any 
 order and if any component is unspecified its value defaults to zero. A \textit{COLOR\_\-IDENTIFIER} can also be specified but it should always be first in the 
 group. See "Common Color Pitfalls" for details. 


\subsubsection{Color Identifiers}

% reference/000026.html

\index{Color! identifiers}\index{Identifiers! color}

   Color identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
COLOR_DECLARATION:
    #declare IDENTIFIER = COLOR; |
    #local IDENTIFIER = COLOR;
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{COLOR} is any valid specification. 



   \textbf{Note:} there should be a semi-\discretionary{}{}{}colon at the end of the declaration. If omitted, it generates a warning and some macros may not work properly. See 
 " \#declare vs. \#local" for information on identifier scope. 



   Here are some examples.... 


{\small\begin{verbatim}
 #declare White = rgb <1,1,1>;
 #declare Cyan = color blue 1.0 green 1.0;
 #declare Weird = rgb <Foo*2,Bar-1,Bob/3>;
 #declare LightGray = White*0.8;
 #declare LightCyan = Cyan red 0.6;
\end{verbatim}}


   As the {\small\texttt{LightGray}} example shows you do not need any color keywords when creating color expressions based on previously declared colors. The 
 last example shows you may use a color identifier with the keyword style syntax. Make sure that the identifier comes first before any other component 
 keywords. 



   Like floats and vectors, you may re-\discretionary{}{}{}define colors throughout a scene but the need to do so is rare. 


\subsubsection{Color Operators}

% reference/000027.html

\index{Color! operators}\index{Operators! color}\index{gray}

   Color vectors may be combined in expressions the same as float or vector values. Operations are performed on a component by component basis. For example {\small\texttt{rgb 
 $<$1.\discretionary{0,}{}{0,}0.\discretionary{5,}{}{5,}0.2$>$*0.9}} evaluates the same as {\small\texttt{ rgb$<$1.\discretionary{0,}{}{0,}0.\discretionary{5,}{}{5,}0.2$>$*$<$0.\discretionary{9,}{}{9,}0.\discretionary{9,}{}{9,}0.9$>$}} or {\small\texttt{ 
 rgb$<$0.\discretionary{9,}{}{9,}0.\discretionary{45,}{}{45,}0.18$>$}}. Other operations are done on a similar component by component basis. 



   You may use the dot operator to extract a single component from a color. Suppose the identifier {\small\texttt{Shade}} was previously defined as a color. 
 Then {\small\texttt{\discretionary{Shade.}{}{Shade.}red}} is the float value of the red component of {\small\texttt{ Shade}}. Similarly {\small\texttt{ \discretionary{Shade.}{}{Shade.}green}}, {\small\texttt{\discretionary{Shade.}{}{Shade.}blue}}, 
 {\small\texttt{\discretionary{Shade.}{}{Shade.}filter}} and {\small\texttt{\discretionary{Shade.}{}{Shade.}transmit}} extract the float value of the other color components. {\small\texttt{\discretionary{shade.}{}{shade.}gray}} returns 
 the gray value of the color vector. 


\subsubsection{Common Color Pitfalls}

% reference/000028.html

\index{Color! common pitfalls}\index{Pitfalls! color}

   The variety and complexity of color specification methods can lead to some common mistakes. Here are some things to consider when specifying a color. 



   When using filter transparency, the colors which come through are multiplied by the primary color components. For example if gray light such as {\small\texttt{ 
 rgb$<$0.\discretionary{9,}{}{9,}0.\discretionary{9,}{}{9,}0.9$>$}} passes through a filter such as {\small\texttt{ rgbf$<$1.\discretionary{0,}{}{0,}0.\discretionary{5,}{}{5,}0.\discretionary{0,}{}{0,}1.0$>$}} the result is {\small\texttt{ 
 rgb$<$0.\discretionary{9,}{}{9,}0.\discretionary{45,}{}{45,}0.0$>$}} with the red let through 100\%, the green cut in half from 0.9 to 0.45 and the blue 
 totally blocked. Often users mistakenly specify a clear object by 


{\small\begin{verbatim}
 color filter 1.0
\end{verbatim}}


   but this has implied red, green and blue values of zero. You have just specified a totally black filter so no light passes through. The correct way is either 


{\small\begin{verbatim}
 color red 1.0  green 1.0  blue 1.0  filter 1.0
\end{verbatim}}


   or 


{\small\begin{verbatim}
 color transmit 1.0
\end{verbatim}}


   In the 2nd example it does not matter what the rgb values are. All of the light passes through untouched. Another pitfall is the use of color identifiers and 
 expressions with color keywords. For example... 


{\small\begin{verbatim}
 color My_Color red 0.5
\end{verbatim}}


   this substitutes whatever was the red component of {\small\texttt{My\_\-Color}} with a red component of 0.5 however... 


{\small\begin{verbatim}
 color My_Color + red 0.5
\end{verbatim}}


   adds 0.5 to the red component of {\small\texttt{My\_\-Color}} and even less obvious... 


{\small\begin{verbatim}
 color My_Color * red 0.5
\end{verbatim}}


   that cuts the red component in half as you would expect but it also multiplies the green, blue, filter and transmit components by zero! The part of the 
 expression after the multiply operator evaluates to {\small\texttt{ rgbft$<$0.\discretionary{5,}{}{5,}0,\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}} as a full 5 component color. 



   The following example results in no change to {\small\texttt{My\_\-Color}}. 


{\small\begin{verbatim}
 color red 0.5 My_Color
\end{verbatim}}


   This is because the identifier fully overwrites the previous value. When using identifiers with color keywords, the identifier should be first. Another issue 
 to consider: some POV-\discretionary{}{}{}Ray syntax allows full color specifications but only uses the rgb part. In these cases it is legal to use a float where a color is 
 needed. For example: 


{\small\begin{verbatim}
 finish { ambient 1 }
\end{verbatim}}


   The ambient keyword expects a color so the value {\small\texttt{1}} is promoted to {\small\texttt{$<$\discretionary{1,}{}{1,}1,\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$}} which is no problem. However 


{\small\begin{verbatim}
 pigment { color 0.4 }
\end{verbatim}}


   is legal but it may or may not be what you intended. The {\small\texttt{ 0.4}} is promoted to {\small\texttt{$<$0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.4$>$}} with the filter 
 and transmit set to 0.4 as well. It is more likely you wanted... 


{\small\begin{verbatim}
 pigment { color rgb 0.4 }
\end{verbatim}}


   in which case a 3 component vector is expected. Therefore the {\small\texttt{ 0.4}} is promoted to {\small\texttt{$<$0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.\discretionary{0,}{}{0,}0.0$>$}} with default 
 zero for filter and transmit. Finally there is another problem which arises when using color dot operators in {\small\texttt{\#declare}} or {\small\texttt{ 
 \#local}} directives. Consider the directive: 


{\small\begin{verbatim}
 #declare MyColor = rgb <0.75, 0.5, 0.75>;
 #declare RedAmt = MyColor.red;
\end{verbatim}}


   Now {\small\texttt{RedAmt}} should be a float but unfortunately it is a color. POV-\discretionary{}{}{}Ray looks at the first keyword after the equals to try to guess what type 
 of identifier you want. It sees the color identifier {\small\texttt{ MyColor}} and assumes you want to declare a color. It then computes the float value as 
 0.75 then promotes that into {\small\texttt{ rgbft$<$0.\discretionary{75,}{}{75,}0.\discretionary{75,}{}{75,}0.\discretionary{75,}{}{75,}0.\discretionary{75,}{}{75,}0.75$>$}}. It would take a major rewrite to fix this problem so we are just warning 
 you about it. Any of the following work-\discretionary{}{}{}arounds will work properly. 


{\small\begin{verbatim}
 #declare RedAmt = 0.0+MyColor.red;
 #declare RedAmt = 1.0*MyColor.red;
 #declare RedAmt = (MyColor.red);
\end{verbatim}}

\subsection{User-\discretionary{}{}{}Defined Functions}

% reference/000029.html

\index{Functions! user-\discretionary{}{}{}defined}\index{Functions}\index{function}

   Some objects allow you to specify functions that will be evaluated while rendering to determine the surface of these objects. In this respect functions are 
 quite different to macros, which are evaluated at parse time but do not otherwise affect rendering. Additionally you may call these functions anywhere a Float 
 Function is allowed, even during parsing. The syntax is identical to Float Expressions, however, only float functions that apply to float values may be used. 
 Excluded are for example {\small\texttt{strlen}} or {\small\texttt{vlength}}. You find a full list of supported float functions in the syntax definition 
 below. 


{\small\begin{verbatim}
FLOAT:
    LOGIC_AND [OR LOGIC_AND]
OR:
    |
LOGIC_AND:
    REL_TERM [AND REL_TERM]
AND:
    \&
REL_TERM:
    TERM [REL_OPERATOR TERM]
REL_OPERATOR:
    < | <= | >= | > | = | !=
TERM:
    FACTOR [SIGN FACTOR]
SIGN:
    + | -
FACTOR:
    MOD_EXPRESSION [MULT MOD_EXPRESSION]
MULT:
    * | /
EXPRESSION:
    FLOAT_LITERAL         |
    FLOAT_IDENTIFIER      |
    FLOAT_FUNCTION        |
    FLOAT_BUILT-IN_IDENT  |
    FUNCTION_IDENTIFIER   |
    ( FLOAT )             |
    IDENTIFIER            |
    SIGN EXPRESSION
FLOAT_FUNCTION:
    abs( FLOAT ) | acos( FLOAT ) | acosh( FLOAT ) | asin( FLOAT ) |
    asinh( FLOAT ) | atan( FLOAT) | atanh( FLOAT) |
    atan2( FLOAT , FLOAT ) | ceil( FLOAT ) | cos( FLOAT ) |
    cosh( FLOAT ) | degrees( FLOAT ) | exp( FLOAT ) |
    floor( FLOAT ) | int( FLOAT ) | ln (Float) | log( FLOAT ) |
    max( FLOAT , FLOAT, ... ) | min( FLOAT , FLOAT, ... ) |
    mod( FLOAT , FLOAT ) | pow( FLOAT , FLOAT ) |
    radians( FLOAT ) | sin( FLOAT ) | sinh( FLOAT ) |
    sqrt( FLOAT ) | tan( FLOAT ) | tanh( FLOAT ) |
    select( FLOAT , FLOAT , FLOAT [, FLOAT] )
FUNCTION_IDENTIFIER:
    #local FUNCTION_IDENTIFIER = function { FLOAT }               |
    #declare FUNCTION_IDENTIFIER = function { FLOAT }             |
    #local FUNCTION_IDENTIFIER = function(IDENT_LIST) { FLOAT }   |
    #declare FUNCTION_IDENTIFIER = function(IDENT_LIST) { FLOAT } |
    #local FUNCTION_IDENTIFIER = function{SPECIAL_FLOAT_FUNCTION} |
    #local VECTOR_IDENTIFIER = function{SPECIAL_VECTOR_FUNCTION}  |
    #local COLOR_IDENTIFIER = function { SPECIAL_COLOR_FUNCTION } |
IDENT_LIST:
    IDENT_ITEM [, IDENT_LIST]
IDENT_ITEM:
    x | y | z | u | v | IDENTIFIER
    (Note: x = u and y = v)
SPECIAL_FLOAT_FUNCTION:
    pattern { PATTERN_BLOCK }
SPECIAL_VECTOR_FUNCTION:
    TRANSFORMATION_BLOCK | SPLINE
SPECIAL_COLOR_FUNCTION:
    PIGMENT
PATTERN_BLOCK:
    PATTERN
\end{verbatim}}


   \textbf{Note:} Only the above mentioned items can be used in user-\discretionary{}{}{}defined functions. For example the rand() function is not available. 



   All of the above mentioned float functions are described in the section Float Functions. 


\subsubsection{Sum and Product functions}

% reference/000030.html

\index{prod}

   {\small\texttt{prod(i, b, n, a)}} The product function. 



   
\begin{mathequ}
% FILE: prod
% ----
\begin{displaymath}
  \prod_{i=b}^n a
\end{displaymath}

\caption{product function} \end{mathequ}
\index{sum} 



   {\small\texttt{sum(i, b, n, a)}} The sum function. 



   
\begin{mathequ}
% FILE: sum
% ---
\begin{displaymath}
  \sum_{i=b}^n a
\end{displaymath}

\caption{sum function} \end{mathequ}
 



   For both {\small\texttt{prod}} and {\small\texttt{sum}}: {\small\texttt{i}} is any variable name and {\small\texttt{a}} is any expression, usually depending 
 on {\small\texttt{i}}. {\small\texttt{b}} and {\small\texttt{n}} are also any expression. \newline Example: 


{\small\begin{verbatim}
  #declare factorial = function(C) { prod(i, 1, C, i) }
  #declare A = factorial(5);
\end{verbatim}}


   The first parameter is the name of the iteration variable. The second is the initial value expression and the third is the final value expression. Those may 
 not depend on the iteration variable but the iteration variable may still be used inside those two expressions (because it happens to already have been 
 defined) but its value is undefined. The last expression is the actual expression which will be iterated through. It may use any variable in scope. 



   The scope of an iteration variable is the sequence operation function. That is, a iteration variable is only defined when used inside the {\small\texttt{sum/prod}} 
 function. Of course {\small\texttt{sum/prod}} functions may be nested. However, there is one limit of a maximum of 56 local variable defined simultaneously, 
 which essentially means that in any combination {\small\texttt{sum/prod}} functions cannot be nested deeper than 56 levels. 



   The iteration variable is incremented by one for each step, but its initial and final value may be any value. The iteration will be continued as long as the 
 iteration value is less or equal to the final value. 



   \textbf{Note:} because the iteration value is a floating-\discretionary{}{}{}point variable, adding one will add a certain bias in a long iterations and thus the floating-\discretionary{}{}{}point 
 precision will be an issue in such a case and needs to be considered by allowing a reasonable error for the final value! 



   If the expression to be added has a negative sign it will of course in effect be substracted. Thus changing the sign will allow to generate negative values 
 in the sum function. Equally multiplying by {\small\texttt{1/expression}} effectively creates a division when used in the prod function. 



   Obviously to work in the first place the initial value of the result is the neutral element of the operation. That is, a sum calculation starts with {\small\texttt{0}} 
 and a product calculation starts with {\small\texttt{1}} just like it is assumed in the sum and product functions in 'regular' math. 



   It should be noted that mathematically either sum or product are redundant because: 


{\small\begin{verbatim}
    log10(prod(i, b, n, a)) = sum(i, b, n, log10(a))
\end{verbatim}}


   which implies a sum can be represented as a product and vice versa, observing the usual mathematical constraints of logarithms, of course. However, as 
 logarithms and their inverse (powers) are slow to compute both are provided... 


\subsubsection{Functions and Macros}

% reference/000031.html

\index{Functions! vs. macros}\index{Macros! vs. functions}

   You can use macros in functions, but the macros will be called only once when the function is defined, not every time the function is called. You cannot pass 
 function variables to the macros. 



   You can pass functions to macros, how to do this is best explained by an example: 


{\small\begin{verbatim}
  #macro Foo( Bar, X )
    #declare Y = Bar(X);
    #declare Z = Bar(Y);
  #end

  #declare FUNC=function(n){n+2}

  Foo(FUNC, 1)

  #debug str(Y,5,5)
  #debug "n"
  #debug str(Z,5,5)
  #debug "n"
\end{verbatim}}

\subsubsection{Declaring User-\discretionary{}{}{}Defined Float Functions}

% reference/000032.html

\index{Functions! user-\discretionary{}{}{}defined, float}\index{Float! functions, user-\discretionary{}{}{}defined}

   You declare a user defined function using the {\small\texttt{\#declare}} or {\small\texttt{\#local}} directives. By default a function takes three parameters 
 and you do not have to explicitly specify the parameter names. The default three parameters are {\small\texttt{x}}, {\small\texttt{y}} and {\small\texttt{z}}. 
 For example: 


{\small\begin{verbatim}
 #declare foo = function { x + y * z }
\end{verbatim}}


   If you need fewer or more parameters you have to explicitly specify the parameter list. 



   \textbf{Note:} {\small\texttt{x}} and {\small\texttt{u}} as well as {\small\texttt{y}} and {\small\texttt{v}} are equivalent so you may not specify both 
 parameter names. You may not specify two or more parameters with the same name either. Doing so may result in a parse error or undefined function results. 



   The following are valid functions with parameters: 


{\small\begin{verbatim}
 #declare foo2 = function(x, y, z) { x + y * z }
 #declare foo3 = function(k1, k2, z, y) { x + y * z + k1 * y + k2 }
 #declare foo4 = function(h) { h * h + h }
 #declare foo4 = function(u, v) { x + y * v } //=u + v*v
 #declare foo4 = function(x, v, z) { u + y * v + z } //=x + v*v + z
\end{verbatim}}


   \textbf{Limits:} 


\begin{itemize}
 
 \item 
   The minimum number of parameters per function is 1. 
 

 \item 
   The maximum number of allowed parameters per function is 56. 
 

 \item 
   The maximum number of {\small\texttt{function}} blocks per scene is 1048575. 
 

 \item 
   The maximum number of operators per function is about 200000. Individual limits will be different depending on the types of operators used in the 
  function. 
 

 \item 
   The maximum depth for nesting functions is 1024. 
 

 \item 
   The maximum number of constants in all functions 1048575. 
 

\end{itemize}


   \textbf{Note:} Redeclaring functions, directly, is not allowed. The way to do this is to {\small\texttt{undef}} it first.\index{pattern} 



   There is one special float function type. You may declare a {\small\texttt{pattern}} function. 



   \textbf{Note:} the syntax is identical to that of patterns, however, you may not specify colors. Its result is always a float and not a color vector, as 
 returned by a function containing a pigment. 


{\small\begin{verbatim}
 #declare foo = function {
   pattern {
     checker
   }
 }
\end{verbatim}}


   \textbf{Note:} the number of parameters of special function types is determined automatically, so you do not need to specify parameter names. 


\subsubsection{Declaring User-\discretionary{}{}{}Defined Vector Functions}

% reference/000033.html

\index{Functions! user-\discretionary{}{}{}defined, vector}\index{Vector! functions, user-\discretionary{}{}{}defined}

   Right now you may only declare vector functions using one of the special function types. Supported types are {\small\texttt{transform}} and {\small\texttt{spline}} 
 functions. For example: 


{\small\begin{verbatim}
 #declare foo = function {
   transform {
     rotate <90, 0, 0>
     scale 4
   }
 }
 
 #declare myvector = foo(4, 3, 7);

 #declare foo2 = function {
   spline {
     linear_spline
     0.0, <0,0,0>
     0.5, <1,0,0>
     1.0, <0,0,0>
   }
 }

 #declare myvector2 = foo2(0.7);
\end{verbatim}}


   Function splines take the vector size into account. That is, a function containing a spline with five components will also return a five component vector 
 (aka a color), a function containing a spline with two components will only return a two component vector and so on. 



   \textbf{Note:} the number of parameters of special function types is determined automatically, so you do not need to specify parameter names. 


\subsubsection{Declaring User-\discretionary{}{}{}Defined Color Functions}

% reference/000034.html

\index{Functions! user-\discretionary{}{}{}defined, color}\index{Color! functions, user-\discretionary{}{}{}defined}

   Right now you may only declare color functions using one of the special function types. The only supported type is the {\small\texttt{pigment}} function. You 
 may use every valid {\small\texttt{pigment}}. This is a very simple example: 


{\small\begin{verbatim}
 #declare foo = function {
   pigment {
     color red 1
   }
 }
 
 #declare Vec = foo(1,2,3)
\end{verbatim}}


   An example using a pattern: 


{\small\begin{verbatim}
 #declare foo = function {
   pigment {
     crackle
     color_map {
       [0.3, color Red]
       [1.0, color Blue]
     }
   }
 }

 #declare Val = foo(2,3,4).gray
\end{verbatim}}


   \textbf{Note:} the number of parameters of special function types is determined automatically, so you do not need to specify parameter names. 


\subsubsection{Internal Pre-\discretionary{}{}{}Defined Functions}

% reference/000035.html

\index{Functions! internal}\index{internal}

   Several functions are pre-\discretionary{}{}{}defined. These internal functions can be accessed through the "\discretionary{functions.}{}{functions.}inc", so it should be included in your scene. \newline The 
 number of required parameters and what they control are also given in the include file, but the "\discretionary{functions.}{}{functions.}inc" chapter in the "Standard 
 Include File" section gives more information. 


\subsection{Strings}

% reference/000036.html

\index{Strings}

   The POV-\discretionary{}{}{}Ray language requires you to specify a string of characters to be used as a file name, text for messages or text for a text object. Strings may be 
 specified using literals, identifiers or functions which return string values. See "String Functions" for details on string functions. Although you 
 cannot build string expressions from symbolic operators such as are used with floats, vectors or colors, you may perform various string operations using 
 string functions. Some applications of strings in POV-\discretionary{}{}{}Ray allow for non-\discretionary{}{}{}printing formatting characters such as newline or form-\discretionary{}{}{}feed. 


{\small\begin{verbatim}
STRING:
    STRING_FUNCTION   |
    STRING_IDENTIFIER |
STRING_LITERAL STRING_LITERAL:
    "up to 256 ASCII characters"
STRING_FUNCTION:
    str( FLOAT , INT , INT ) |
    concat( STRING , STRING , [STRING ,...]) | chr( INT ) |
    substr( STRING , INT , INT ) | strupr( STRING ) | 
    strlwr( STRING ) | vstr( INT, VECTOR, STRING, INT, INT )
\end{verbatim}}

\subsubsection{String Literals}

% reference/000037.html

\index{String Literals}\index{Literals! string}\index{String! literals}

   String literals begin with a double quote mark '"' which is followed by up to 256 characters and are terminated by another double quote mark. You can 
 change the character set of strings using the {\small\texttt{global\_\-settings}} {\small\texttt{charset}} option. The following are all valid string literals: 



   "Here" "There" "\discretionary{myfile.}{}{myfile.}gif" "\discretionary{textures.}{}{textures.}inc" 



   \textbf{Note:} if you need to specify a quote mark in a string literal you must precede it with a backslash. 



   Example 


{\small\begin{verbatim} "Joe said \"Hello\" as he walked in."\end{verbatim}}


   is converted to 


{\small\begin{verbatim} Joe said "Hello" as he walked in.\end{verbatim}}


   If you need to specify a backslash, you will have to specify two. For example: 


{\small\begin{verbatim} "This is a backslash \\ and this is two \\\\"\end{verbatim}}


   Is converted to: 


{\small\begin{verbatim}This is a backslash \ and this is two \\\end{verbatim}}


   Windows users need to be especially wary about this as the backslash is also the windows path separator. For example, the following code does not produce the 
 intended result: 


{\small\begin{verbatim}
  #declare DisplayFont = "c:\windows\fonts\lucon.ttf"
  text { ttf DisplayFont "Hello", 2,0 translate y*1.50 }
\end{verbatim}}


   New users might expect this to create a text object using the font "c:$\backslash$windows$\backslash$\discretionary{}{}{}fonts$\backslash$\discretionary{lucon.}{}{lucon.}ttf". Instead, it will give an error message saying that 
 it cannot find the font file "\discretionary{c:}{}{c:}\discretionary{windowsontslucon.}{}{windowsontslucon.}ttf". 



   The correct form of the above code is as follows: 


{\small\begin{verbatim}
  #declare DisplayFont = "c:\\windows\\fonts\\lucon.ttf"
  text { ttf DisplayFont "Hello", 2,0 translate y*1.50 }
\end{verbatim}}


   The escaping of backslashes occurs in all POV-\discretionary{}{}{}Ray string literals. There are also other formatting codes such as {\small\texttt{$\backslash$n}} for new line. See "Text 
 Formatting" for details. 


\subsubsection{String Identifiers}

% reference/000038.html

\index{Identifiers! string}\index{String! identifiers}

   String identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
STRING_DECLARATION:
    #declare IDENTIFIER = STRING |
    #local IDENTIFIER = STRING
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{STRING} is any valid string specification. 



   \textbf{Note:} unlike floats, vectors, or colors, there need not be a semi-\discretionary{}{}{}colon at the end of the declaration. See "\#declare vs. \#local" for 
 information on identifier scope. 



   Here are some examples... 


{\small\begin{verbatim}
 #declare Font_Name = "ariel.ttf"
 #declare Inc_File = "myfile.inc"
 #declare Name = "John"
 #declare Name = concat(Name," Doe")
\end{verbatim}}


   As the last example shows, you can re-\discretionary{}{}{}declare a string identifier and may use previously declared values in that re-\discretionary{}{}{}declaration. 


\subsubsection{String Functions}

% reference/000039.html

\index{String! functions}\index{Functions! string}

   POV-\discretionary{}{}{}Ray defines a variety of built-\discretionary{}{}{}in functions for manipulating floats, vectors and strings. Function calls consist of a keyword which specifies the name of 
 the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example: 


{\small\begin{verbatim}
 keyword(param1,param2)
\end{verbatim}}


   The following are the functions which return string values. They take one or more float, integer, vector, or string parameters. Assume that {\small\texttt{ A}} 
 is any valid expression that evaluates to a float; {\small\texttt{ B}}, {\small\texttt{L}}, and {\small\texttt{P}} are floats which are truncated to integers 
 internally, {\small\texttt{S}}, {\small\texttt{S1}}, {\small\texttt{S2}} etc are strings.\index{chr} 



   {\small\texttt{chr(B)}} Character whose character value is {\small\texttt{B}}. Returns a single character string. The character value of the character is 
 specified by an integer {\small\texttt{B}} which must be in the range 0 to 65535 if you specified {\small\texttt{charset utf8}} in the {\small\texttt{global\_\-settings}} 
 and 0 to 127 if you specified {\small\texttt{charset ascii}}. Refer to your platform specific documentation if you specified {\small\texttt{charset sys}}. For 
 example {\small\texttt{chr(70)}} is the string "F". When rendering text objects you should be aware that the characters rendered are dependent on 
 the (TTF) font being used. 



   \index{concat} {\small\texttt{ concat(\discretionary{S1,}{}{S1,}S2,...)}} Concatenate strings {\small\texttt{S1}} and {\small\texttt{ S2}}. Returns a string that is the 
 concatenation of all parameter strings. Must have at least 2 parameters but may have more. For example: 


{\small\begin{verbatim}
 concat("Value is ", str(A,3,1), " inches")
\end{verbatim}}


   If the float value {\small\texttt{A}} was {\small\texttt{12.34321}} the result is {\small\texttt{"Value is 12.3 inches"}} which is a string.\index{str} 
 



   {\small\texttt{ str(\discretionary{A,}{}{A,}\discretionary{L,}{}{L,}P):}} Convert float A to a formatted string. Returns a formatted string representation of float value {\small\texttt{A}}. The integer 
 parameter {\small\texttt{L}} specifies the minimum length of the string and the type of left padding used if the string's representation is shorter than the 
 minimum. If {\small\texttt{L}} is positive then the padding is with blanks. If {\small\texttt{L}} is negative then the padding is with zeros. The overall 
 minimum length of the formatted string is \textit{abs(L)}. If the string needs to be longer, it will be made as long as necessary to represent the value. 



   The integer parameter {\small\texttt{P}} specifies the number of digits after the decimal point. If {\small\texttt{P}} is negative then a compiler-\discretionary{}{}{}specific 
 default precision is use. Here are some examples: 


{\small\begin{verbatim}
 str(123.456, 0, 3) "123.456"
 str(123.456, 4, 3) "123.456"
 str(123.456, 9, 3) "  123.456"
 str(123.456,-9, 3) "00123.456"

 str(123.456, 0, 2) "123.46"
 str(123.456, 0, 0) "123"
 str(123.456, 5, 0) "  123"
 str(123.000, 7, 2) " 123.00"

 str(123.456, 0,-1) "123.456000" (platform specific)
\end{verbatim}}
\index{strlwr}

   {\small\texttt{strlwr(S)}} Lower case of {\small\texttt{S}}. Returns a new string in which all upper case letters in the string S1 are converted to lower 
 case. The original string is not affected. For example {\small\texttt{ strlwr("Hello There!")}} results in "hello there!". 



   \index{substr} {\small\texttt{ substr(\discretionary{S,}{}{S,}\discretionary{P,}{}{P,}L)}} Sub-\discretionary{}{}{}string from {\small\texttt{S}}. Returns a string that is a subset of the characters in parameter {\small\texttt{ 
 S}} starting at the position specified by the integer value {\small\texttt{ P}} for a length specified by the integer value {\small\texttt{L}}. For example {\small\texttt{ 
 substr("ABCDEFGHI",\discretionary{4,}{}{4,}2)}} evaluates to the string "DE". If \textit{P+L-1$>$strlen(S)} an error occurs. 



   \index{strupr} {\small\texttt{ strupr(S)}} Upper case of {\small\texttt{S}}. Returns a new string in which all lower case letters in the string {\small\texttt{S}} 
 are converted to upper case. The original string is not affected. For example {\small\texttt{ strupr("Hello There!")}} results in "HELLO 
 THERE!".\index{vstr} 



   {\small\texttt{vstr(\discretionary{N,}{}{N,}A,\discretionary{S,}{}{S,}\discretionary{L,}{}{L,}P)}} Convert vector A to a formatted string. Returns a formatted string representation of vector {\small\texttt{A}} where the 
 elements of the vector are separated by the string parameter {\small\texttt{S}}. The integer parameter {\small\texttt{N}} specifies the amount of dimensions 
 in vector {\small\texttt{A}}. {\small\texttt{N}} is autoclipped to the range of 2 to 5, without warning. Specifying a vector {\small\texttt{A}} with more 
 dimensions than given by {\small\texttt{N}} will result in an error.\newline  The integer parameter {\small\texttt{L}} specifies the minimum length of the 
 string and the type of left padding used if the string's representation is shorter than the minimum. The integer parameter {\small\texttt{P}} specifies the 
 number of digits after the decimal point. If {\small\texttt{P}} is negative then a compiler-\discretionary{}{}{}specific default precision is use. The function of {\small\texttt{L}} 
 and {\small\texttt{P}} is the same as in {\small\texttt{str}}. Here are some examples: 


{\small\begin{verbatim}
 vstr(2, <1,2>, ", ", 0,1)         "1.0, 2.0"
 vstr(5, <1,2,3,4,5>, ", ", 0,1)   "1.0, 2.0, 3.0, 4.0, 5.0"
 vstr(1, 1, ", ", 0,1)             "1.0, 1.0"
 vstr(2, 1, ", ", 0,1)             "1.0, 1.0"
 vstr(5, 1, ", ", 0,1)             "1.0, 1.0, 1.0, 1.0, 1.0"
 vstr(7, 1, ", ", 0,1)             "1.0, 1.0, 1.0, 1.0, 1.0"
 vstr(3, <1,2>, ", ", 0,1)         "1.0, 2.0, 0.0"
 vstr(5, <1,2,3>, ", ", 0,1)       "1.0, 2.0, 3.0, 0.0, 0.0"
 vstr(3, <1,2,3,4>, ", ", 0,1)     error
\end{verbatim}}


   See section "Float Functions" for other functions which are somewhat string-\discretionary{}{}{}related but which return floats. In addition to the above built-\discretionary{}{}{}in 
 functions, you may also define your own functions using the {\small\texttt{\#macro}} directive. See the section "User Defined Macros" for more 
 details. 


\subsection{Array Identifiers}

% reference/000040.html

\index{Identifiers! array}\index{Array! identifiers}\index{array}

   You may declare arrays of identifiers of up to five dimensions. Any item that can be declared as an identifier can be declared in an array. 


\subsubsection{Declaring Arrays}

% reference/000041.html

\index{Array! declaring}\index{Declaring! arrays}

   The syntax for declaring an array is as follows: 


{\small\begin{verbatim}
ARRAY_DECLARATION:
  #declare IDENTIFIER = array[ INT ][[ INT ]]..[ARRAY_INITIALIZER] |
  #local IDENTIFIER = array[ INT ][[ INT ]]..[ARRAY_INITIALIZER]
ARRAY_INITIALIZER:
  {ARRAY_ITEM, [ARRAY_ITEM, ]... }
ARRAY_ITEM:
  RVALUE | ARRAY_INITIALIZER
\end{verbatim}}


   Where IDENTIFIER is the name of the identifier up to 40 characters long and INT is a valid float expression which is internally truncated to an integer which 
 specifies the size of the array. The optional \textit{ ARRAY\_\-INITIALIZER} is discussed in the next section "Array Initializers". Here is an example 
 of a one-\discretionary{}{}{}dimensional, uninitialized array. 


{\small\begin{verbatim}
 #declare MyArray = array[10]
\end{verbatim}}


   This declares an uninitialized array of ten elements. The elements are referenced as {\small\texttt{MyArray[0]}} through {\small\texttt{MyArray[9]}}. As yet, 
 the type of the elements are undetermined. Once you have initialized any element of the array, all other elements can only be defined as that type. An attempt 
 to reference an uninitialized element results in an error. For example: 


{\small\begin{verbatim}
 #declare MyArray = array[10]
 #declare MyArray[5] = pigment{White}     //all other elements must 
                                          //be pigments too.
 #declare MyArray[2] = normal{bumps 0.2}  //generates an error
 #declare Thing = MyArray[4]   //error: uninitialized array element
\end{verbatim}}


   Multi-\discretionary{}{}{}dimensional arrays up to five dimensions may be declared. For example: 


{\small\begin{verbatim}
 #declare MyGrid = array[4][5]
\end{verbatim}}


   declares a 20 element array of 4 rows and 5 columns. Elements are referenced from {\small\texttt{MyGrid[0][0]}} to {\small\texttt{MyGrid[3][4]}}. Although it 
 is permissible to reference an entire array as a whole, you may not reference just one dimension of a multi-\discretionary{}{}{}dimensional array. For example: 


{\small\begin{verbatim}
 #declare MyArray = array[10]
 #declare MyGrid = array[4][5]
 #declare YourArray = MyArray  //this is ok
 #declare YourGrid = MyGrid   //so is this
 #declare OneRow  = MyGrid[2] //this is illegal
\end{verbatim}}


   The {\small\texttt{\#ifdef}} and {\small\texttt{\#ifndef}} directives can be used to check whether a specific element of an array has been declared. For 
 methods to determine the size of an array look in the float section for {\small\texttt{dimensions}} and {\small\texttt{dimension\_\-size}} 



   Large uninitialized arrays do not take much memory. Internally they are arrays of pointers so they probably use just 4 bytes per element. Once initialized 
 with values, they consume memory depending on what you put in them. 



   The rules for local vs. global arrays are the same as any other identifier. 



   \textbf{Note:} this applies to the entire array. You cannot mix local and global elements in the same array. See "\#declare vs. \#local" for 
 information on identifier scope. 


\subsubsection{Array Initializers}

% reference/000042.html

\index{Array! initialization}\index{Initialization! arrays}

   Because it is cumbersome to individually initialize the elements of an array, you may initialize it as it is created using array initializer syntax. For 
 example: 


{\small\begin{verbatim}
 #include "colors.inc"
 #declare FlagColors = array[3] {Red,White,Blue}
\end{verbatim}}


   Multi-\discretionary{}{}{}dimensional arrays may also be initialized this way. For example: 


{\small\begin{verbatim}
 #declare Digits =
 array[4][10]
 {
  {7,6,7,0,2,1,6,5,5,0},
  {1,2,3,4,5,6,7,8,9,0},
  {0,9,8,7,6,5,4,3,2,1},
  {1,1,2,2,3,3,4,4,5,5}
 }
\end{verbatim}}


   The commas are required between elements and between dimensions as shown in the example. 


\subsection{Spline Identifiers}

% reference/000043.html

\index{spline}

   Splines give you a way to define 'pathways' through your scenes. You specify a series of points, and POV-\discretionary{}{}{}Ray interpolates to make a curve connecting them. 
 Every point along the spline has a numerical value. A good example of a spline is the path of a moving object: the spline itself would be the path traced out 
 by the object and the 'parameter' would be time; as time changes the object's position moves along the spline. \newline Therefore, given a time reference you 
 could use this spline to find the position of the object. In fact, splines are very well suited to animation. 



   The syntax is: 


{\small\begin{verbatim}
SPLINE_DECLARATION:
  #declare IDENTIFIER =
    spline {
      [SPLINE_IDENTIFIER] |
      [SPLINE_TYPE] |
      [Val_1, <Point_1>[,]
       Val_2, <Point_2>[,]
       ...
       Val_n, <Point_n>]
    }

SPLINE_TYPE:
  linear_spline | quadratic_spline | cubic_spline | natural_spline

SPLINE_USAGE:
  MySpline(Val) | MySpline(Val, SPLINE_TYPE)
\end{verbatim}}


   The first item gives the type of interpolation. \newline In a {\small\texttt{linear\_\-spline}}, straight lines connect each point. \newline In a {\small\texttt{quadratic\_\-spline}}, 
 a smooth curve defined by a second-\discretionary{}{}{}order polynomial connects each point. \index{natural\_\-spline} \newline In {\small\texttt{cubic\_\-spline}} and {\small\texttt{natural\_\-spline}}, 
 a smooth curve defined by a third-\discretionary{}{}{}order polynomial connects each point. \newline The default is {\small\texttt{linear\_\-spline}}. 



   Following this are a number of float values each followed by a position vector, all separated by commas. {\small\texttt{Val\_\-1}}, {\small\texttt{Val\_\-2}}, etc, 
 are the value of the spline parameter at each specific point. The points need not be in order of their parameter values. If two points have the same parameter 
 value, the second point will replace the first. Beyond the range of the lowest and highest parameter values, the spline position is fixed at the endpoints. 



   \textbf{Note:} Because of the way cubic\_\-splines are defined: the first and last points are tangents rather than points on the spline, cubic\_\-spline 
 interpolation is only valid between the second and next-\discretionary{}{}{}to-\discretionary{}{}{}last points. For all other spline types, interpolation is valid from the first point to the last 
 point. For t-\discretionary{}{}{}values outside the valid range, POV-\discretionary{}{}{}Ray returns the value of the nearest valid point. 



   To use a spline, you place the spline identifier followed by the parameter (in parentheses) wherever you would normally put a vector, similar to a macro. 
 Splines behave mostly like three-\discretionary{}{}{}dimensional vectors. \newline Here is an example: 


{\small\begin{verbatim}
camera { location <0,2,-2> look_at 0 }
light_source { <-5,30,-10> 1 }
#declare MySpline =
  spline {
    cubic_spline
    -.25, <0,0,-1>
    0.00, <1,0,0>
    0.25, <0,0,1>
    0.50, <-1,0,0>
    0.75, <0,0,-1>
    1.00, <1,0,0>
    1.25, <0,0,1>
  }

#declare ctr = 0;
#while (ctr < 1)
  sphere {
    MySpline(ctr),.25
    pigment { rgb <1-ctr,ctr,0> }
  }
  #declare ctr = ctr + 0.01;
#end
\end{verbatim}}


   You can also have POV-\discretionary{}{}{}Ray evaluate a spline as if it were a different type of spline by specifying the type of spline after the value to interpolate at, for 
 example:\newline  


{\small\begin{verbatim}
sphere{ <2,0,2>, .25 pigment{rgb MySpline(clock, linear_spline)}}
\end{verbatim}}


   Splines are 'intelligent' when it comes to returning vectors. The vector with the most components in the spline determines the size of the returned vector. 
 This allows vectors from two to five components to be returned by splines. 



   Also, function splines take the vector size into account. That is, a function containing a spline with five components will also return a five component 
 vector (aka a color), a function containing a spline with two components will only return a two component vector and so on. 


\subsubsection{Splines and Macros}

% reference/000044.html

\index{Splines! vs. macros}\index{Macros! vs. splines}

   You can pass functions to macros, how to do this is best explained by an example 


{\small\begin{verbatim}
  #macro Foo( Bar, Val )
    #declare Y = Bar(Val).y;
  #end

  #declare myspline = spline { 
      1, <4,5> 
      3, <5,5> 
      5, <6,5>
  }

  Foo(myspline, 2)

  #debug str(Y,5,5)
  #debug "\n"
\end{verbatim}}

\section{Language Directives}

% reference/000045.html

\index{Directives! language}\index{Language! directives}

   The POV Scene Language contains several statements called \textit{language directives} which tell the file parser how to do its job. These directives can 
 appear in almost any place in the scene file - even in the middle of some other statements. They are used to include other text files in the stream of 
 commands, to declare identifiers, to define macros, conditional, or looped parsing and to control other important aspects of scene file processing. 



   Each directive begins with the hash character {\small\texttt{\#}} (often called a number sign or pound sign). It is followed by a keyword and optionally other 
 parameters. 



   In versions of POV-\discretionary{}{}{}Ray prior to 3.0, the use of this {\small\texttt{\#}} character was optional. Language directives could only be used between objects, 
 camera or light\_\-source statements and could not appear within those statements. The exception was the {\small\texttt{ \#include}} which could appear anywhere. 
 Now that all language directives can be used almost anywhere, the {\small\texttt{\#}} character is mandatory. The following keywords introduce language 
 directives. 


\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{ \#break\newline  \#case\newline  \#debug\newline  \#declare\newline  \#default\newline  \#else\newline  \#end\newline  \#error\newline  \#fclose\newline  
   }} 
  } & 

  {\raggedleft 
    {\small\texttt{ \#fopen\newline  \#if\newline  \#ifdef\newline  \#ifndef\newline  \#include\newline  \#local\newline  \#macro\newline  \#range\newline  \#read\newline  
   }} 
  } & 
{\raggedleft  {\small\texttt{ \#render\newline  \#statistics\newline  \#switch\newline  \#undef\newline  \#version\newline  \#warning\newline  \#while\newline  \#write\newline  
  }} } \\ 
 

\end{tabular*} \caption{All language directives} \end{table}


   Earlier versions of POV-\discretionary{}{}{}Ray considered the keyword {\small\texttt{\#max\_\-intersections}} and the keyword {\small\texttt{\#max\_\-trace\_\-level}} to be language 
 directives but they have been moved to the {\small\texttt{global\_\-settings}} statement and should be placed there without the {\small\texttt{\#}} sign. Their 
 use as a directive still works but it generates a warning and may be discontinued in the future. 


\subsection{Include Files and the \#include Directive}

% reference/000046.html

\index{\#include}\index{include}\index{Directives! language, \#include}

   The language allows include files to be specified by placing the line 


{\small\begin{verbatim}
 #include "filename.inc"
\end{verbatim}}


   at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It 
 may be up to 40 characters long (or your computer's limit), including the two double-\discretionary{}{}{}quote characters. 



   The include file is read in as if it were inserted at that point in the file. Using include is almost the same as cutting and pasting the entire contents of 
 this file into your scene. 



   Include files may be nested. You may have at most 10 nested include files. There is no limit on un-\discretionary{}{}{}nested include files. 



   Generally, include files have data for scenes but are not scenes in themselves. By convention scene files end in {\small\texttt{.pov}} and include files end 
 with {\small\texttt{.inc}}. 



   It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between 
 various platforms. Use of full lower case is also recommended but not required. 



   \textbf{Note:} if you ever intend to distribute any source files you make for POV-\discretionary{}{}{}Ray, remember that some operating systems have case-\discretionary{}{}{}sensitive file names). 



   It is typical to put standard include files in a special sub-\discretionary{}{}{}directory. POV-\discretionary{}{}{}Ray can only read files in the current directory or one referenced by the {\small\texttt{Library\_\-Path}} 
 option or {\small\texttt{+L}} switch. See section "Library Paths". 



   You may use the {\small\texttt{\#local}} directive to declare identifiers which are temporary in duration and local to the include file in scope. For details 
 see "\#declare vs. \#local". 


\subsection{The \#declare and \#local Directives}

% reference/000047.html

\index{Directives! language, \#declare}\index{Directives! language, \#local}\index{\#local}\index{local}

   Identifiers may be declared and later referenced to make scene files more readable and to parameterize scenes so that changing a single declaration changes 
 many values. There are several built-\discretionary{}{}{}in identifiers which POV-\discretionary{}{}{}Ray declares for you. See section "Float Expressions: Built-\discretionary{}{}{}in Variables" and "Built-\discretionary{}{}{}in 
 Vector Identifiers" for details. 


\subsubsection{Declaring identifiers}

% reference/000048.html

\index{Identifiers! declaring}\index{Directives! language, identifiers}\index{\#declare}\index{declare}

   An identifier is declared as follows. 


{\small\begin{verbatim}
DECLARATION:
    #declare IDENTIFIER = RVALUE |
    #local IDENTIFIER = RVALUE
RVALUE:
    FLOAT; | VECTOR; | COLOR; | STRING | OBJECT | TEXTURE |
    PIGMENT | NORMAL | FINISH | INTERIOR | MEDIA | DENSITY |
    COLOR_MAP | PIGMENT_MAP | SLOPE_MAP | NORMAL_MAP |
    DENSITY_MAP | CAMERA | LIGHT_SOURCE | FOG | RAINBOW |
    SKY_SPHERE | TRANSFORM
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{RVALUE} is any of the listed items. They are called that because 
 they are values that can appear to the \textit{right} of the equals sign. The syntax for each is in the corresponding section of this language reference. Here 
 are some examples. 


{\small\begin{verbatim}
 #declare Rows = 5;
 #declare Count = Count+1;
 #local  Here = <1,2,3>;
 #declare White = rgb <1,1,1>;
 #declare Cyan = color blue 1.0 green 1.0;
 #declare Font_Name = "ariel.ttf"
 #declare Rod = cylinder {-5*x,5*x,1}
 #declare Ring = torus {5,1}
 #local  Checks = pigment { checker White, Cyan }
 object{ Rod scale y*5 }     // not "cylinder { Rod }"
 object {
  Ring
  pigment { Checks scale 0.5 }
  transform Skew
 }
\end{verbatim}}


   \textbf{Note:} that there should be a semi-\discretionary{}{}{}colon after the expression in all float, vector and color identifier declarations. This semi-\discretionary{}{}{}colon is introduced 
 in POV-\discretionary{}{}{}Ray version 3.1. If omitted, it generates a warning and some macros may not work properly. Semicolons after other declarations are optional. 



   Declarations, like most language directives, can appear almost anywhere in the file - even within other statements. For example: 


{\small\begin{verbatim}
 #declare Here=<1,2,3>;
 #declare Count=0;         // initialize Count
 union {
  object { Rod translate Here*Count }
  #declare Count=Count+1;     // re-declare inside union
  object { Rod translate Here*Count }
  #declare Count=Count+1;     // re-declare inside union
  object { Rod translate Here*Count }
 }
\end{verbatim}}


   As this example shows, you can re-\discretionary{}{}{}declare an identifier and may use previously declared values in that re-\discretionary{}{}{}declaration. 



   \textbf{Note:} object identifiers use the generic wrapper statement {\small\texttt{ object\{}} ... {\small\texttt{\}}}. You do not need to know what kind of 
 object it is. 



   Declarations may be nested inside each other within limits. In the example in the previous section you could declare the entire union as a object. However 
 for technical reasons there are instances where you may not use any language directive inside the declaration of floats, vectors or color expressions. 
 Although these limits have been loosened somewhat since POV-\discretionary{}{}{}Ray 3.1, they still exist. 



   Identifiers declared within {\small\texttt{\#macro}} ... {\small\texttt{\#end}} blocks are not created at the time the macro is defined. They are only created 
 at the time the macro is actually invoked. Like all other items inside such a \#macro definition, they are ignored when the macro is defined. 


\subsubsection{\#declare vs. \#local}

% reference/000049.html

\index{Directives! \#language, \#declare vs. \#local}

   Identifiers may be declared either global using {\small\texttt{\#declare}} or local using the {\small\texttt{\#local}} directive. 



   Those created by the {\small\texttt{\#declare}} directive are permanent in duration and global in scope. Once created, they are available throughout the scene 
 and they are not released until all parsing is complete or until they are specifically released using {\small\texttt{\#undef}}. See "Destroying Identifiers". 
 



   Those created by the {\small\texttt{\#local}} directive are temporary in duration and local in scope. They temporarily override any identifiers with the same 
 name. See "Identifier Name Collisions". 



   If {\small\texttt{\#local}} is used inside a {\small\texttt{ \#macro}} then the identifier is local to that macro. When the macro is invoked and the {\small\texttt{\#local}} 
 directive is parsed, the identifier is created. It persists until the {\small\texttt{\#end}} directive of the macro is reached. At the {\small\texttt{\#end}} 
 directive, the identifier is destroyed. Subsequent invocations of the macro create totally new identifiers. 



   Use of {\small\texttt{\#local}} within an include file but not in a macro, also creates a temporary identifier that is local to that include file. When the 
 include file is included and the {\small\texttt{\#local}} directive is parsed, the identifier is created. It persists until the end of the include file is 
 reached. At the end of file the identifier is destroyed. Subsequent inclusions of the file create totally new identifiers. 



   Use of {\small\texttt{\#local}} in the main scene file (not in an include file and not in a macro) is identical to {\small\texttt{\#declare}}. For clarity sake 
 you should not use {\small\texttt{\#local}} in a main file except in a macro. 



   There is currently no way to create permanent, yet local identifiers in POV-\discretionary{}{}{}Ray. 



   Local identifiers may be specifically released early using {\small\texttt{\#undef}} but in general there is no need to do so. See "Destroying Identifiers". 
 


\subsubsection{Identifier Name Collisions}

% reference/000050.html

\index{Directives! name collisions}

   Local identifiers may have the same names as previously declared identifiers. In this instance, the most recent, most local identifier takes precedence. Upon 
 entering an include file or invoking a macro, a new symbol table is created. When referencing identifiers, the most recently created symbol table is searched 
 first, then the next most recent and so on back to the global table of the main scene file. As each macro or include file is exited, its table and identifiers 
 are destroyed. Parameters passed by value reside in the same symbol table as the one used for identifiers local to the macro. 



   The rules for duplicate identifiers may seem complicated when multiple-\discretionary{}{}{}nested includes and macros are involved, but in actual practice the results are 
 generally what you intended. 



   Consider this example: You have a main scene file called {\small\texttt{\discretionary{myscene.}{}{myscene.}pov}} and it contains 


{\small\begin{verbatim}
 #declare A = 123;
 #declare B = rgb<1,2,3>;
 #declare C = 0;
 #include "myinc.inc"
\end{verbatim}}


   Inside the include file you invoke a macro called {\small\texttt{MyMacro(\discretionary{J,}{}{J,}\discretionary{K,}{}{K,}L)}}. It is not important where {\small\texttt{ MyMacro}} is defined as long as 
 it is defined before it is invoked. In this example, it is important that the macro is invoked from within {\small\texttt{ \discretionary{myinc.}{}{myinc.}inc}}. 



   The identifiers {\small\texttt{A}}, {\small\texttt{B}}, and {\small\texttt{ C}} are generally available at all levels. If either {\small\texttt{ \discretionary{myinc.}{}{myinc.}inc}} 
 or {\small\texttt{ MyMacro}} contain a line such as {\small\texttt{ \#declare C=C+1;}} then the value {\small\texttt{C}} is changed everywhere as you might 
 expect. 



   Now suppose inside {\small\texttt{\discretionary{myinc.}{}{myinc.}inc}} you do... 


{\small\begin{verbatim}
 #local A = 546;
\end{verbatim}}


   The main version of {\small\texttt{A}} is hidden and a new {\small\texttt{A}} is created. This new {\small\texttt{A}} is also available inside {\small\texttt{ 
 MyMacro}} because {\small\texttt{MyMacro}} is nested inside {\small\texttt{ \discretionary{myinc.}{}{myinc.}inc}}. Once you exit {\small\texttt{\discretionary{myinc.}{}{myinc.}inc}}, the local {\small\texttt{ A}} 
 is destroyed and the original {\small\texttt{A}} with its value of {\small\texttt{123}} is now in effect. Once you have created the local {\small\texttt{ A}} 
 inside {\small\texttt{\discretionary{myinc.}{}{myinc.}inc}}, there is no way to reference the original global {\small\texttt{A}} unless you {\small\texttt{\#undef A}} or exit the 
 include file. Using {\small\texttt{\#undef}} always undefines the most local version of an identifier. 



   Similarly if {\small\texttt{MyMacro}} contained... 


{\small\begin{verbatim}
 #local B = box{0,1}
\end{verbatim}}


   then a new identifier {\small\texttt{B}} is created local to the macro only. The original value of {\small\texttt{B}} remains hidden but is restored when the 
 macro is finished. The local {\small\texttt{B}} need not have the same type as the original. 



   The complication comes when trying to assign a new value to an identifier at one level that was declared local at an earlier level. Suppose inside {\small\texttt{ 
 \discretionary{myinc.}{}{myinc.}inc}} you do... 


{\small\begin{verbatim}
 #local D = 789;
\end{verbatim}}


   If you are inside {\small\texttt{\discretionary{myinc.}{}{myinc.}inc}} and you want to increment {\small\texttt{ D}} by one, you might try to do... 


{\small\begin{verbatim}
 #local D = D + 1;
\end{verbatim}}


   but if you try to do that inside {\small\texttt{MyMacro}} you will create a new {\small\texttt{D}} which is local to {\small\texttt{MyMacro}} and not the {\small\texttt{ 
 D}} which is external to {\small\texttt{MyMacro}} but local to {\small\texttt{ \discretionary{myinc.}{}{myinc.}inc}}. Therefore you've said "create a {\small\texttt{ MyMacro D}} 
 from the value of {\small\texttt{\discretionary{myinc.}{}{myinc.}inc}}'s {\small\texttt{ D}} plus one". That's probably not what you wanted. Instead you should do... 


{\small\begin{verbatim}
 #declare D = D + 1;
\end{verbatim}}


   You might think this creates a new {\small\texttt{D}} that is global but it actually increments the \discretionary{myinc.}{}{myinc.}inc version of {\small\texttt{D}}. Confusing isn't 
 it? Here are the rules: 


\begin{enumerate}
 
 \item 
   When referencing an identifier, you always get the most recent, most local version. By "referencing" we mean using the value of the 
  identifier in a POV-\discretionary{}{}{}Ray statement or using it on the right of an equals sign in either a {\small\texttt{\#declare}} or {\small\texttt{ \#local}}. 
 

 \item 
   When declaring an identifier using the {\small\texttt{\#local}} keyword, the identifier which is created or has a new value assigned, is ALWAYS created 
  at the current nesting level of macros or include files. 
 

 \item 
   When declaring a NEW, NON-\discretionary{}{}{}EXISTANT identifier using {\small\texttt{\#declare}}, it is created as fully global. It is put in the symbol table of the main 
  scene file. 
 

 \item 
   When ASSIGNING A VALUE TO AN EXISTING identifier using {\small\texttt{\#declare}}, it assigns it to the most recent, most local version at the time. 
 

\end{enumerate}


   In summary, {\small\texttt{\#local}} always means "the current level", and {\small\texttt{\#declare}} means "global" for new identifiers 
 and "most recent" for existing identifiers. 


\subsubsection{Destroying Identifiers with \#undef}

% reference/000051.html

\index{Identifiers! destroying}\index{Directives! language, identifiers, destroying}\index{Directives! language, \#undef}\index{\#undef}\index{undef}

   Identifiers created with {\small\texttt{\#declare}} will generally persist until parsing is complete. Identifiers created with {\small\texttt{\#local}} will 
 persist until the end of the macro or include file in which they were created. You may however un-\discretionary{}{}{}define an identifier using the {\small\texttt{ \#undef}} 
 directive. For example: 


{\small\begin{verbatim}
 #undef MyValue
\end{verbatim}}


   If multiple local nested versions of the identifier exist, the most local most recent version is deleted and any identically named identifiers which were 
 created at higher levels will still exist. 



   See also "The \#ifdef and \#ifndef Directives". 


\subsection{File I/O Directives}

% reference/000052.html

\index{Directives! language, file I/O}

   You may open, read, write, append, and close plain ASCII text files while parsing POV-\discretionary{}{}{}Ray scenes. This feature is primarily intended to help pass information 
 between frames of an animation. Values such as an object's position can be written while parsing the current frame and read back during the next frame. Clever 
 use of this feature could allow a POV-\discretionary{}{}{}Ray scene to generate its own include files or write self-\discretionary{}{}{}modifying scripts. We trust that users will come up with other 
 interesting uses for this feature. 



   \textbf{Note:} some platform versions of POV-\discretionary{}{}{}Ray (\discretionary{e.}{}{e.}g. Windows) provide means to restrict the ability of scene files to read \& write files. 


\subsubsection{The \#fopen Directive}

% reference/000053.html

\index{\#fopen}\index{fopen}\index{append}\index{Directives! language, \#fopen}

   Users may open a text file using the {\small\texttt{\#fopen}} directive. The syntax is as follows: 


{\small\begin{verbatim}
FOPEN_DIRECTIVE:
    #fopen IDENTIFIER "filename" OPEN_TYPE
OPEN_TYPE:
    read | write | append
\end{verbatim}}


   Where \textit{IDENTIFIER} is an undefined identifier used to reference this file as a file handle, \textit{"filename"} is any string literal or 
 string expression which specifies the file name. Files opened with the {\small\texttt{read}} are open for read only. Those opened with {\small\texttt{ write}} 
 create a new file with the specified name and it overwrites any existing file with that name. Those opened with {\small\texttt{append}} opens a file for 
 writing but appends the text to the end of any existing file. 



   The file handle identifier created by {\small\texttt{\#fopen}} is always global and remains in effect (and the file remains open) until the scene parsing is 
 complete or until you {\small\texttt{\#fclose}} the file. You may use {\small\texttt{ \#ifdef}} \textit{FILE\_\-HANDLE\_\-IDENTIFIER} to see if a file is open. 


\subsubsection{The \#fclose Directive}

% reference/000054.html

\index{\#fclose}\index{fclose}\index{Directives! language, \#fclose}

   Files opened with the {\small\texttt{\#fopen}} directive are automatically closed when scene parsing completes however you may close a file using the {\small\texttt{\#fclose}} 
 directive. The syntax is as follows: 


{\small\begin{verbatim}
FCLOSE_DIRECTIVE:
    #fclose FILE_HANDLE_IDENTIFIER
\end{verbatim}}


   Where \textit{FILE\_\-HANDLE\_\-IDENTIFIER} is previously opened file opened with the {\small\texttt{\#fopen}} directive. See "The \#fopen Directive". 


\subsubsection{The \#read Directive}

% reference/000055.html

\index{\#read}\index{read}\index{Directives! language, \#read}

   You may read string, float or vector values from a plain ASCII text file directly into POV-\discretionary{}{}{}Ray variables using the \#read directive. The file must first be 
 opened in "read" mode using the \#fopen directive. The syntax for \#read is as follows: 


{\small\begin{verbatim}
READ_DIRECTIVE:
  #read (FILE_HANDLE_IDENTIFIER, DATA_IDENTIFIER[,DATA_IDENTIFIER]..)
DATA_IDENTIFIER:
  UNDECLARED_IDENTIFIER | FLOAT_IDENTIFIER | VECTOR_IDENTIFIER | 
  STRING_IDENTIFIER
\end{verbatim}}


   Where \textit{FILE\_\-HANDLE\_\-IDENTIFIER} is the previously opened file. It is followed by one or more \textit{DATA\_\-IDENTIFIER}s separated by commas. The 
 parentheses around the identifier list are required. A \textit{ DATA\_\-IDENTIFIER} is any undeclared identifier or any previously declared string identifier, 
 float identifier, or vector identifier. Undefined identifiers will be turned into global identifiers of the type determined by the data which is read. 
 Previously defined identifiers remain at whatever global/local status they had when originally created. Type checking is performed to insure that the proper 
 type data is read into these identifiers. 



   The format of the data to be read must be a series of valid string literals, float literals, or vector literals separated by commas. Expressions or 
 identifiers are not permitted in the data file however unary minus signs and exponential notation are permitted on float values. 



   If you attempt to read past end-\discretionary{}{}{}of-\discretionary{}{}{}file, the file is automatically closed and the \textit{ FILE\_\-HANDLE\_\-IDENTIFIER} is deleted from the symbol table. This 
 means that the boolean function {\small\texttt{ defined(}}\textit{IDENTIFIER}{\small\texttt{)}} can be used to detect end-\discretionary{}{}{}of-\discretionary{}{}{}file. For example: 


{\small\begin{verbatim}
  #fopen MyFile "mydata.txt" read
  #while (defined(MyFile))
    #read (MyFile,Var1,Var2,Var3)
    ...
  #end
\end{verbatim}}

\subsubsection{The \#write Directive}

% reference/000056.html

\index{\#write}\index{write}\index{Directives! language, \#write}

   You may write string, float or vector values to a plain ASCII text file from POV-\discretionary{}{}{}Ray variables using the {\small\texttt{\#write}} directive. The file must 
 first be opened in either {\small\texttt{write}} or {\small\texttt{append}} mode using the {\small\texttt{\#fopen}} directive. The syntax for {\small\texttt{ 
 \#write}} is as follows: 


{\small\begin{verbatim}
WRITE_DIRECTIVE:
    #write( FILE_HANDLE_IDENTIFIER, DATA_ITEM[,DATA_ITEM]...)
DATA_ITEM:
    FLOAT | VECTOR | STRING
\end{verbatim}}


   Where \textit{FILE\_\-HANDLE\_\-IDENTIFIER} is the previously opened file. It is followed by one or more \textit{DATA\_\-ITEM}s separated by commas. The parentheses 
 around the identifier list are required. A \textit{DATA\_\-ITEM} is any valid string expression, float expression, or vector expression. Float expressions are 
 evaluated and written as signed float literals. If you require format control, you should use the {\small\texttt{str(\discretionary{VALUE,}{}{VALUE,}\discretionary{L,}{}{L,}P)}} function to convert it to a 
 formatted string. See "String Functions" for details on the {\small\texttt{str}} function. Vector expressions are evaluated into three signed float 
 constants and are written with angle brackets and commas in standard POV-\discretionary{}{}{}Ray vector notation. String expressions are evaluated and written as specified. 



   \textbf{Note:} data read by the {\small\texttt{\#read}} directive must have comma delimiters between values and quotes around string data but the {\small\texttt{ 
 \#write}} directive does not automatically output commas or quotes. 



   For example the following {\small\texttt{ \#read}} directive reads a string, float and vector. 


{\small\begin{verbatim}
 #read (MyFile,MyString,MyFloat,MyVect)
\end{verbatim}}


   It expects to read something like: 


{\small\begin{verbatim}
 "A quote delimited string", -123.45, <1,2,-3>
\end{verbatim}}


   The POV-\discretionary{}{}{}Ray code to write this might be: 


{\small\begin{verbatim}
 #declare Val1 = -123.45;
 #declare Vect1 = <1,2,-3>;
 #write(MyFile,"\"A quote delimited string\",",Val1,",",Vect1,"\n")
\end{verbatim}}


   See "String Literals" and "Text Formatting" for details on writing special characters such as quotes, newline, etc. 


\subsection{The \#default Directive}

% reference/000057.html

\index{Directives! language, default texture}\index{Textures! default}\index{\#default}\index{default}\index{Directives! language, \#default}

   POV-\discretionary{}{}{}Ray creates a default texture when it begins processing. You may change those defaults as described below. Every time you specify a {\small\texttt{texture}} 
 statement, POV-\discretionary{}{}{}Ray creates a copy of the default texture. Anything you put in the texture statement overrides the default settings. If you attach a {\small\texttt{pigment}}, 
 {\small\texttt{normal}}, or {\small\texttt{ finish}} to an object without any texture statement then POV-\discretionary{}{}{}Ray checks to see if a texture has already been 
 attached. If it has a texture then the pigment, normal or finish will modify the existing texture. If no texture has yet been attached to the object then the 
 default texture is copied and the pigment, normal or finish will modify that texture. 



   You may change the default texture, pigment, normal or finish using the language directive {\small\texttt{\#default}} as follows: 


{\small\begin{verbatim}
DEFAULT_DIRECTIVE:
    #default {DEFAULT_ITEM }
DEFAULT_ITEM:
    TEXTURE | PIGMENT | NORMAL | FINISH
\end{verbatim}}


   For example: 


{\small\begin{verbatim}
 #default {
   texture {
     pigment { rgb <1,0,0> }
     normal { bumps 0.3 }
     finish { ambient 0.4 }
   }
 }
\end{verbatim}}


   This means objects will default to red bumps and slightly high ambient finish. Also you may change just part of it like this: 


{\small\begin{verbatim}
 #default {
  pigment {rgb <1,0,0>}
 }
\end{verbatim}}


   This still changes the pigment of the default texture. At any time there is only one default texture made from the default pigment, normal and finish. The 
 example above does not make a separate default for pigments alone. 



   \textbf{Note:} the special textures {\small\texttt{tiles}} and {\small\texttt{ material\_\-map}} or a texture with a {\small\texttt{texture\_\-map}} may not be 
 used as defaults. 



   You may change the defaults several times throughout a scene as you wish. Subsequent {\small\texttt{\#default}} statements begin with the defaults that were 
 in effect at the time. If you wish to reset to the original POV-\discretionary{}{}{}Ray defaults then you should first save them as follows: 


{\small\begin{verbatim}
 //At top of file
 #declare Original_Default = texture {}
\end{verbatim}}


   later after changing defaults you may restore it with... 


{\small\begin{verbatim}
 #default {texture {Original_Default}}
\end{verbatim}}


   If you do not specify a texture for an object then the default texture is attached when the object appears in the scene. It is not attached when an object is 
 declared. For example: 


{\small\begin{verbatim}
 #declare My_Object =
  sphere{ <0,0,0>, 1 } // Default texture not applied
  object{ My_Object }  // Default texture added here
\end{verbatim}}


   You may force a default texture to be added by using an empty texture statement as follows: 


{\small\begin{verbatim}
 #declare My_Thing =
  sphere { <0,0,0>, 1 texture {} } // Default texture applied
\end{verbatim}}


   The original POV-\discretionary{}{}{}Ray defaults for all items are given throughout the documentation under each appropriate section. 


\subsection{The \#version Directive}

% reference/000058.html

\index{Directives! language, \#version}\index{\#version}\index{version}

   As POV-\discretionary{}{}{}Ray has evolved from version 1.0 through 3.6 we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some 
 old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. 
 However \textit{some} old features can still be used if you warn POV-\discretionary{}{}{}Ray that this is an older scene. The {\small\texttt{ \#version}} directive can be used to 
 switch version compatibility to different setting several times throughout a scene file. The syntax is: 


{\small\begin{verbatim}
VERSION_DIRECTIVE: 
    #version FLOAT;
\end{verbatim}}


   \textbf{Note:} there should be a semi-\discretionary{}{}{}colon after the float expression in a {\small\texttt{\#version}} directive. This semi-\discretionary{}{}{}colon is introduced in POV-\discretionary{}{}{}Ray 
 version 3.1. If omitted, it generates a warning and some macros may not work properly. 



   Additionally you may use the {\small\texttt{ Version=}}\textit{\discretionary{n.}{}{n.}n} option or the {\small\texttt{+MV}}\textit{\discretionary{n.}{}{n.}n} switch to establish the \textit{initial} 
 setting. See "Language Version" for details. For example one feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing 
 of float expressions. Using {\small\texttt{\#version 1.0}} turns off expression parsing as well as many warning messages so that nearly all 1.0 files will 
 still work. Naturally the default setting for this option is {\small\texttt{\#version 3.5}}. 



   \textbf{Note:} Some obsolete or re-\discretionary{}{}{}designed features \textit{are totally unavailable in the current version of POV-\discretionary{}{}{}Ray REGARDLES OF THE VERSION SETTING.} 
 Details on these features are noted throughout this documentation. 



   The built-\discretionary{}{}{}in float identifier {\small\texttt{version}} contains the current setting of the version compatibility option. See "Float Expressions: Built-\discretionary{}{}{}in 
 Variables". Together with the built-\discretionary{}{}{}in {\small\texttt{version}} identifier the {\small\texttt{\#version}} directive allows you to save and restore the 
 previous values of this compatibility setting. The new {\small\texttt{ \#local}} identifier option is especially useful here. For example suppose {\small\texttt{ 
 \discretionary{mystuff.}{}{mystuff.}inc}} is in version 1 format. At the top of the file you could put: 


{\small\begin{verbatim}
 #local Temp_Vers = version;  // Save previous value
 #version 1.0;         // Change to 1.0 mode
 ... // Version 1.0 stuff goes here...
 #version Temp_Vers;      // Restore previous version
\end{verbatim}}


   Future versions of POV-\discretionary{}{}{}Ray may not continue to maintain full backward compatibility even with the {\small\texttt{\#version}} directive. We strongly encourage 
 you to phase in current version syntax as much as possible. 


\subsection{Conditional Directives}

% reference/000059.html

\index{Directives! language, conditional}

   POV-\discretionary{}{}{}Ray allows a variety of language directives to implement conditional parsing of various sections of your scene file. This is especially useful in 
 describing the motion for animations but it has other uses as well. Also available is a {\small\texttt{\#while}} loop directive. You may nest conditional 
 directives 200 levels deep. 


\subsubsection{The \#if...\#else...\#end Directives}

% reference/000060.html

\index{if}\index{else}\index{end}\index{\#if}\index{\#else}\index{\#end}\index{Directives! language, \#if}\index{Directives! language, \#else}\index{Directives! language, \#end}

   The simplest conditional directive is a traditional {\small\texttt{\#if}} directive. It is of the form... 


{\small\begin{verbatim}
IF_DIRECTIVE:
    #if ( Cond ) TOKENS... [#else TOKENS...] #end
\end{verbatim}}


   The \textit{TOKENS} are any number of POV-\discretionary{}{}{}Ray keyword, identifiers, or punctuation and {\small\texttt{(}}\textit{ Cond} {\small\texttt{)}} is a float 
 expression that is interpreted as a boolean value. The parentheses are required. The {\small\texttt{\#end}} directive is required. A value of 0.0 is false and 
 any non-\discretionary{}{}{}zero value is true. 



   \textbf{Note:} extremely small values of about 1e-10 are considered zero in case of round off errors. 



   If \textit{ Cond} is true, the first group of tokens is parsed normally and the second set is skipped. If false, the first set is skipped and the second set 
 is parsed. For example: 


{\small\begin{verbatim}
 #declare Which=1;
 #if (Which)
   box { 0, 1 }
 #else
   sphere { 0, 1 }
 #end
\end{verbatim}}


   The box is parsed and the sphere is skipped. Changing the value of {\small\texttt{ Which}} to {\small\texttt{0}} means the box is skipped and the sphere is 
 used. The {\small\texttt{\#else}} directive and second token group is optional. For example: 


{\small\begin{verbatim}
 #declare Which=1;
 #if (Which)
   box { 0, 1 }
 #end
\end{verbatim}}


   Changing the value of {\small\texttt{Which}} to {\small\texttt{0}} means the box is removed. 



   At the beginning of the chapter "Language Directives" it was stated that "These directives can appear in almost any place in the scene 
 file....". The following is an example where it will not work, it will confuse the parser: 


{\small\begin{verbatim}
   #if( #if(yes) yes #end ) #end
\end{verbatim}}

\subsubsection{The \#ifdef and \#ifndef Directives}

% reference/000061.html

\index{ifdef}\index{ifndef}\index{\#ifdef}\index{\#ifndef}\index{Directives! language, \#ifdef}\index{Directives! language, \#ifndef}

   The {\small\texttt{\#ifdef}} and {\small\texttt{\#ifndef}} directive are similar to the {\small\texttt{\#if}} directive however they are used to determine if an 
 identifier has been previously declared. 


{\small\begin{verbatim}
IFDEF_DIRECTIVE:
    #ifdef ( IDENTIFIER ) TOKENS... [#else TOKENS...] #end
IFNDEF_DIRECTIVE:
    #ifndef ( IDENTIFIER ) TOKENS... [#else TOKENS...] #end
\end{verbatim}}


   If the \textit{IDENTIFIER} exists then the first group of tokens is parsed normally and the second set is skipped. If false, the first set is skipped and the 
 second set is parsed. This is especially useful for replacing an undefined item with a default. For example: 


{\small\begin{verbatim}
  #ifdef (User_Thing)
  // This section is parsed if the
  // identifier "User_Thing" was
  // previously declared
  object{User_Thing} // invoke identifier
 #else
  // This section is parsed if the
  // identifier "User_Thing" was not
  // previously declared
  box{<0,0,0>,<1,1,1>} // use a default
 #end
  // End of conditional part
\end{verbatim}}


   The {\small\texttt{\#ifndef}} directive works the opposite. The first group is parsed if the identifier is \textit{not} defined. As with the {\small\texttt{ 
 \#if}} directive, the {\small\texttt{\#else}} clause is optional and the {\small\texttt{\#end}} directive is required. 



   The {\small\texttt{\#ifdef}} and {\small\texttt{\#ifndef}} directives can be used to determine whether a specific element of an array has been assigned. 


{\small\begin{verbatim}
 #declare MyArray=array[10]
 //#declare MyArray[0]=7;
 #ifdef(MyArray[0])
    #debug "first element is assigned\n"
 #else 
    #debug "first element is not assigned\n"
 #end
\end{verbatim}}

\subsubsection{The \#switch, \#case, \#range and \#break Directives}

% reference/000062.html

\index{switch}\index{case}\index{range}\index{break}\index{\#switch}\index{\#case}\index{\#range}\index{\#break}\index{Directives! language, \#switch}\index{Directives! language, \#case}\index{Directives! language, \#range}\index{Directives! language, \#break}

   A more powerful conditional is the {\small\texttt{\#switch}} directive. The syntax is as follows... 


{\small\begin{verbatim}
SWITCH_DIRECTIVE:
   #switch ( Switch_Value ) SWITCH_CLAUSE... [#else TOKENS...] #end
SWITCH_CLAUSE:
   #case( Case_Value ) TOKENS... [#break] |
   #range( Low_Value , High_Value ) TOKENS... [#break]
\end{verbatim}}


   The \textit{TOKENS} are any number of POV-\discretionary{}{}{}Ray keyword, identifiers, or punctuation and {\small\texttt{(}}\textit{ Switch\_\-Value} {\small\texttt{)}} is a float 
 expression. The parentheses are required. The {\small\texttt{\#end}} directive is required. The \textit{SWITCH\_\-CLAUSE} comes in two varieties. In the {\small\texttt{\#case}} 
 variety, the float \textit{Switch\_\-Value} is compared to the float \textit{Case\_\-Value}. If they are equal, the condition is true. 



   \textbf{Note:} that values whose difference is less than 1e-10 are considered equal in case of round off errors. 



   In the {\small\texttt{\#range}} variety, \textit{Low\_\-Value} and \textit{High\_\-Value} are floats separated by a comma and enclosed in parentheses. If \textit{Low\_\-Value 
 $<$= Switch\_\-Value} and \textit{ Switch\_\-Value$<$=High\_\-Value} then the condition is true. 



   In either variety, if the clause's condition is true, that clause's tokens are parsed normally and parsing continues until a {\small\texttt{\#break}}, {\small\texttt{ 
 \#else}} or {\small\texttt{\#end}} directive is reached. If the condition is false, POV-\discretionary{}{}{}Ray skips until another {\small\texttt{\#case}} or {\small\texttt{ \#range}} 
 is found. 



   There may be any number of {\small\texttt{\#case}} or {\small\texttt{ \#range}} clauses in any order you want. If a clause evaluates true but no {\small\texttt{ 
 \#break}} is specified, the parsing will fall through to the next {\small\texttt{ \#case}} or {\small\texttt{\#range}} and that clause conditional is evaluated. 
 Hitting {\small\texttt{\#break}} while parsing a successful section causes an immediate jump to the {\small\texttt{\#end}} without processing subsequent 
 sections, even if a subsequent condition would also have been satisfied. 



   An optional {\small\texttt{\#else}} clause may be the last clause. It is only executed if the clause before it was a false clause. 



   Here is an example: 


{\small\begin{verbatim}
 #switch (VALUE)
  #case (TEST_1)
   // This section is parsed if VALUE=TEST_1
  #break //First case ends
  #case (TEST_2)
   // This section is parsed if VALUE=TEST_2
  #break //Second case ends
  #range (LOW_1,HIGH_1)
   // This section is parsed if (VALUE>=LOW_1)\&(VALUE<=HIGH_1)
  #break //Third case ends
  #range (LOW_2,HIGH_2)
   // This section is parsed if (VALUE>=LOW_2)\&(VALUE<=HIGH_2)
  #break //Fourth case ends
  #else
   // This section is parsed if no other case or
   // range is true.
 #end // End of conditional part
\end{verbatim}}

\subsubsection{The \#while...\#end Directive}

% reference/000063.html

\index{while}\index{\#while}\index{Directives! language, \#while}\index{Directives! language, \#end}

   The {\small\texttt{\#while}} directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses. 


{\small\begin{verbatim}
WHILE_DIRECTIVE:
    #while ( Cond ) TOKENS... #end
\end{verbatim}}


   The \textit{TOKENS} are any number of POV-\discretionary{}{}{}Ray keyword, identifiers, or punctuation marks which are the \textit{body} of the loop. The {\small\texttt{ \#while}} 
 directive is followed by a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-\discretionary{}{}{}zero value is true. 



   \textbf{Note:} extremely small values of about 1e-10 are considered zero in case of round off errors. 



   The parentheses around the expression are required. If the condition is true parsing continues normally until an {\small\texttt{\#end}} directive is reached. 
 At the end, POV-\discretionary{}{}{}Ray loops back to the {\small\texttt{ \#while}} directive and the condition is re-\discretionary{}{}{}evaluated. Looping continues until the condition fails. When 
 it fails, parsing continues after the {\small\texttt{ \#end}} directive. 



   \textbf{Note:} it is possible for the condition to fail the first time and the loop is totally skipped. It is up to the user to insure that something inside 
 the loop changes so that it eventually terminates. 



   Here is a properly constructed loop example: 


{\small\begin{verbatim}
 #declare Count=0;
 #while (Count < 5)
  object { MyObject translate x*3*Count }
  #declare Count=Count+1;
 #end
\end{verbatim}}


   This example places five copies of {\small\texttt{MyObject}} in a row spaced three units apart in the x-\discretionary{}{}{}direction. 


\subsection{User Message Directives}

% reference/000064.html

\index{Directives! language, user messages}

   With the addition of conditional and loop directives, the POV-\discretionary{}{}{}Ray language has the potential to be more like an actual programming language. This means that 
 it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to 
 print text messages to the screen. You have a choice of five different text streams to use including the ability to generate a fatal error if you find it 
 necessary. Limited formatting is available for strings output by this method. 


\subsubsection{Text Message Streams}

% reference/000065.html

\index{\#debug}\index{\#error}\index{\#warning}\index{\#render}\index{\#statistics}\index{statistics}\index{debug}\index{error}\index{warning}\index{render}\index{Directives! language, \#debug}\index{Directives! language, \#error}\index{Directives! language, \#warning}

   The syntax for a text message is any of the following: 


{\small\begin{verbatim}
TEXT_STREAM_DIRECTIVE:
    #debug STRING | #error STRING | #warning STRING
\end{verbatim}}


   Where \textit{STRING} is any valid string of text including string identifiers or functions which return strings. For example: 


{\small\begin{verbatim}
 #switch (clock*360)
  #range (0,180)
   #debug "Clock in 0 to 180 range\n"
  #break
  #range (180,360)
   #debug "Clock in 180 to 360 range\n"
  #break
  #else
   #warning "Clock outside expected range\n"
   #warning concat("Value is:",str(clock*360,5,0),"\n")
 #end
\end{verbatim}}


   There are seven distinct text streams that POV-\discretionary{}{}{}Ray uses for output. You may output only to three of them. On some versions of POV-\discretionary{}{}{}Ray, each stream is 
 designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The 
 distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to 
 review the streams separately in their own scroll-\discretionary{}{}{}back buffer. See "Directing Text Streams to Files" for details on re-\discretionary{}{}{}directing the streams to a 
 text file. 



   Here is a description of how POV-\discretionary{}{}{}Ray uses each stream. You may use them for whatever purpose you want except note that use of the {\small\texttt{\#error}} 
 stream causes a fatal error after the text is displayed. 



   \textbf{Debug:} This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to 
 display messages from within their scene files. 



   \textbf{Error:} This stream displays fatal error messages. After displaying this text, POV-\discretionary{}{}{}Ray will terminate. When the error is a scene parsing error, you 
 may be shown several lines of scene text that leads up to the error. 



   \textbf{Warning:} This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-\discretionary{}{}{}Ray can continue to 
 render the scene.\index{Directives! language, \#render}\index{Directives! language, \#statistics}\index{Directives! language, \#debug}\index{Directives! language, \#status}\index{Directives! language, \#banner} 
 



   The {\small\texttt{\#render}} and {\small\texttt{\#statistsics}} could be accessed in previous versions. Their output is now redirected to the {\small\texttt{\#debug}} 
 stream. The {\small\texttt{\#banner}} and {\small\texttt{\#status}} streams can not be accessed by the user. 


\subsubsection{Text Formatting}

% reference/000066.html



   Some escape sequences are available to include non-\discretionary{}{}{}printing control characters in your text. These sequences are similar to those used in string literals in 
 the C programming language. The sequences are: 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{102pt}@{} p{266pt}@{} p{41pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$a"}} 
  } & 

  {\raggedleft 
    Bell or alarm, 
  } & 
{\raggedleft  0x07 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$b"}} 
  } & 

  {\raggedleft 
    Backspace, 
  } & 
{\raggedleft  0x08 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$f"}} 
  } & 

  {\raggedleft 
    Form feed, 
  } & 
{\raggedleft  0x0C } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$n"}} 
  } & 

  {\raggedleft 
    New line (line feed) 
  } & 
{\raggedleft  0x0A } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$r"}} 
  } & 

  {\raggedleft 
    Carriage return 
  } & 
{\raggedleft  0x0D } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$t"}} 
  } & 

  {\raggedleft 
    Horizontal tab 
  } & 
{\raggedleft  0x09 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$uNNNN"}} 
  } & 

  {\raggedleft 
    Unicode character code NNNN 
  } & 
{\raggedleft  0xNNNN } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$v"}} 
  } & 

  {\raggedleft 
    Vertical tab 
  } & 
{\raggedleft  0x0B } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$0"}} 
  } & 

  {\raggedleft 
    Null 
  } & 
{\raggedleft  0x00 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$$\backslash$"}} 
  } & 

  {\raggedleft 
    Backslash 
  } & 
{\raggedleft  0x5C } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$'"}} 
  } & 

  {\raggedleft 
    Single quote 
  } & 
{\raggedleft  0x27 } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{"$\backslash$""}} 
  } & 

  {\raggedleft 
    Double quote 
  } & 
{\raggedleft  0x22 } \\ 
 

\end{tabular*} \caption{All character escape sequences} \end{table}


   For example: 


{\small\begin{verbatim}
 #debug "This is one line.\nBut this is another"\n
\end{verbatim}}


   Depending on what platform you are using, they may not be fully supported for console output. However they will appear in any text file if you re-\discretionary{}{}{}direct a 
 stream to a file. 


\subsection{User Defined Macros}

% reference/000067.html

\index{Macros}\index{\#macro}\index{macro}\index{Directives! language, \#macro}

   POV-\discretionary{}{}{}Ray 3.1 introduced user defined macros with parameters. This feature, along with the ability to declare {\small\texttt{\#local}} variables, turned the 
 POV-\discretionary{}{}{}Ray Language into a fully functional programming language. Consequently, it is now possible to write scene generation tools in 
 POV-\discretionary{}{}{}Ray's own language that previously required external utilities. 


\subsubsection{The \#macro Directive}

% reference/000068.html

\index{Directives! language, \#macro}\index{Macros! declaring}

   The syntax for declaring a macro is: 


{\small\begin{verbatim}
MACRO_DEFINITION:
#macro IDENTIFIER ([PARAM_IDENT] [, PARAM_IDENT]... ) TOKENS... #end
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the macro and \textit{ PARAM\_\-IDENT}s are a list of zero or more formal parameter identifiers separated by commas and 
 enclosed by parentheses. The parentheses are required even if no parameters are specified. 



   The \textit{TOKENS} are any number of POV-\discretionary{}{}{}Ray keyword, identifiers, or punctuation marks which are the \textit{ body} of the macro. The body of the macro may 
 contain almost any POV-\discretionary{}{}{}Ray syntax items you desire. It is terminated by the {\small\texttt{\#end}} directive. 



   \textbf{Note:} any conditional directives such as {\small\texttt{ \#if}}...{\small\texttt{\#end}}, {\small\texttt{ \#while}}...{\small\texttt{\#end}}, etc. must 
 be fully nested inside or outside the macro so that the corresponding {\small\texttt{\#end}} directives pair-\discretionary{}{}{}up properly. 



   A macro must be declared before it is invoked. All macro names are global in scope and permanent in duration. You may redefine a macro by another {\small\texttt{ 
 \#macro}} directive with the same name. The previous definition is lost. Macro names respond to {\small\texttt{ \#ifdef}}, {\small\texttt{ \#ifndef}}, and {\small\texttt{\#undef}} 
 directives. See "The \#ifdef and \#ifndef Directives" and "Destroying Identifiers with \#undef". 


\subsubsection{Invoking Macros}

% reference/000069.html

\index{Macros! invoking}

   You invoke the macro by specifying the macro name followed by a list of zero or more actual parameters enclosed in parentheses and separated by commas. The 
 number of actual parameters must match the number of formal parameters in the definition. The parentheses are required even if no parameters are specified. 
 The syntax is: 


{\small\begin{verbatim}
MACRO_INVOCATION:
    MACRO_IDENTIFIER ( [ACTUAL_PARAM] [, ACTUAL_PARAM]... )
ACTUAL_PARAM:
    IDENTIFIER | RVALUE
\end{verbatim}}


   An \textit{RVALUE} is any value that can legally appear to the right of an equals sign in a {\small\texttt{\#declare}} or {\small\texttt{\#local}} declaration. 
 See "Declaring identifiers" for information on \textit{ RVALUE}s. When the macro is invoked, a new local symbol table is created. The actual 
 parameters are assigned to formal parameter identifiers as local, temporary variables. POV-\discretionary{}{}{}Ray jumps to the body of the macro and continues parsing until the 
 matching {\small\texttt{\#end}} directive is reached. There, the local variables created by the parameters are destroyed as well as any local identifiers 
 expressly created in the body of the macro. It then resumes parsing at the point where the macro was invoked. It is as though the body of the macro was cut 
 and pasted into the scene at the point where the macro was invoked. 



   \textbf{Note:} it is possible to invoke a macro that was declared in another file. This is quite normal and in fact is how many "plug-\discretionary{}{}{}ins" work 
 (such as the popular Lens Flare macro). However, be aware that calling a macro that was declared in a file different from the one that it is being called from 
 involves more overhead than calling one in the same file. 



   This is because POV-\discretionary{}{}{}Ray does not tokenize and store its language. Calling a macro in another file therefore requires that the other file be opened and closed 
 for each call. Normally, this overhead is inconsequential; however, if you are calling the macro many thousands of times, it can cause significant delays. A 
 future version of the POV-\discretionary{}{}{}Ray language will remove this problem. 



   Here is a simple macro that creates a window frame object when you specify the inner and outer dimensions. 


{\small\begin{verbatim}
#macro Make_Frame(OuterWidth,OuterHeight,InnerWidth,
                  InnerHeight,Depth)
  #local Horz = (OuterHeight-InnerHeight)/2;
  #local Vert = (OuterWidth-InnerWidth)/2;
  difference {
    box{
	  <0,0,0>,<OuterWidth,OuterHeight,Depth>
	}
    box{
	  <Vert,Horz,-0.1>,
      <OuterWidth-Vert,OuterHeight-Horz,Depth+0.1>
	}
  }
#end
Make_Frame(8,10,7,9,1) //invoke the macro
\end{verbatim}}


   In this example, the macro has five float parameters. The actual parameters (the values 8, 10, 7, 9, and 1) are assigned to the five identifiers in the {\small\texttt{\#macro}} 
 formal parameter list. It is as though you had used the following five lines of code. 


{\small\begin{verbatim}
 #local OuterWidth = 8;
 #local OuterHeight = 10;
 #local InnerWidth, = 7;
 #local InnerHeight = 9;
 #local Depth = 1;
\end{verbatim}}


   These five identifiers are stored in the same symbol table as any other local identifier such as {\small\texttt{Horz}} or {\small\texttt{Vert}} in this 
 example. The parameters and local variables are all destroyed when the {\small\texttt{ \#end}} statement is reached. See "Identifier Name Collisions" 
 for a detailed discussion of how local identifiers, parameters, and global identifiers work when a local identifier has the same name as a previously declared 
 identifier. 


\subsubsection{Are POV-\discretionary{}{}{}Ray Macros a Function or a Macro?}

% reference/000070.html



   POV-\discretionary{}{}{}Ray macros are a strange mix of macros and functions. In traditional computer programming languages, a macro works entirely by token substitution. The 
 body of the routine is inserted into the invocation point by simply copying the tokens and parsing them as if they had been cut and pasted in place. Such 
 cut-\discretionary{}{}{}and-\discretionary{}{}{}paste substitution is often called \textit{macro substitution} because it is what macros are all about. In 
 this respect, POV-\discretionary{}{}{}Ray macros are exactly like traditional macros in that they use macro substitution for the body of the macro. However traditional macros 
 also use this cut-\discretionary{}{}{}and-\discretionary{}{}{}paste substitution strategy for parameters but POV-\discretionary{}{}{}Ray does not. 



   Suppose you have a macro in the C programming language {\small\texttt{ Typical\_\-Cmac(Param)}} and you invoke it as {\small\texttt{Typical\_\-Cmac(else A=B)}}. 
 Anywhere that {\small\texttt{Param}} appears in the macro body, the four tokens {\small\texttt{else}}, {\small\texttt{A}}, {\small\texttt{=}}, and {\small\texttt{ 
 B}} are substituted into the program code using a cut-\discretionary{}{}{}and-\discretionary{}{}{}paste operation. No type checking is performed because anything is legal. The ability to pass an 
 arbitrary group of tokens via a macro parameter is a powerful (and sadly often abused) feature of traditional macros. 



   After careful deliberation, we have decided against this type of parameters for our macros. The reason is that POV-\discretionary{}{}{}Ray uses commas more frequently in its 
 syntax than do most programming languages. Suppose you create a macro that is designed to operate on one vector and two floats. It might be defined {\small\texttt{ 
 OurMac(\discretionary{V,}{}{V,}\discretionary{F1,}{}{F1,}F2)}}. If you allow arbitrary strings of tokens and invoke a macro such as {\small\texttt{OurMac($<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$,\discretionary{4,}{}{4,}5)}} 
 then it is impossible to tell if this is a vector and two floats or if its 5 parameters with the two tokens {\small\texttt{$<$}} and {\small\texttt{1}} as 
 the first parameter. If we design the macro to accept 5 parameters then we cannot invoke it like this... {\small\texttt{OurMac(\discretionary{MyVector,}{}{MyVector,}\discretionary{4,}{}{4,}5)}}. 



   Function parameters in traditional programming languages do not use token substitution to pass values. They create temporary, local variables to store 
 parameters that are either constant values or identifier references which are in effect a pointer to a variable. POV-\discretionary{}{}{}Ray macros use this function-\discretionary{}{}{}like system 
 for passing parameters to its macros. In our example {\small\texttt{ OurMac($<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$,\discretionary{4,}{}{4,}5)}}, POV-\discretionary{}{}{}Ray sees the {\small\texttt{$<$}} and knows it must be 
 the start of a vector. It parses the whole vector expression and assigns it to the first parameter exactly as though you had used the statement {\small\texttt{\#local 
 V=$<$\discretionary{1,}{}{1,}\discretionary{2,}{}{2,}3$>$;}}. 



   Although we say that POV-\discretionary{}{}{}Ray parameters are more like traditional function parameters than macro parameters, there still is one difference. Most languages 
 require you to declare the type of each parameter in the definition before you use it but POV-\discretionary{}{}{}Ray does not. This should be no surprise because most languages 
 require you to declare the type of any identifier before you use it but POV-\discretionary{}{}{}Ray does not. This means that if you pass the wrong type value in a POV-\discretionary{}{}{}Ray macro 
 parameter, it may not generate an error until you reference the identifier in the macro body. No type checking is performed as the parameter is passed. So in 
 this very limited respect, POV-\discretionary{}{}{}Ray parameters are somewhat macro-\discretionary{}{}{}like but are mostly function-\discretionary{}{}{}like. 


\subsubsection{Returning a Value Like a Function}

% reference/000071.html

\index{Macros! returning values from}

   POV-\discretionary{}{}{}Ray macros have a variety of uses. Like most macros, they provide a parameterized way to insert arbitrary code into a scene file. However most POV-\discretionary{}{}{}Ray 
 macros will be used like functions or procedures in a traditional programming language. Macros are designed to fill all of these roles. 



   When the body of a macro consists of statements that create an entire item such as an object, texture, etc. then the macro acts like a function which returns 
 a single value. The {\small\texttt{Make\_\-Frame}} macro example in the section "Invoking Macros" above is such a macro which returns a value that is 
 an object. Here are some examples of how you might invoke it. 


{\small\begin{verbatim}
 union {  //make a union of two objects
   object{ Make_Frame(8,10,7,9,1) translate  20*x}
   object{ Make_Frame(8,10,7,9,1) translate -20*x}
 }
 #declare BigFrame = object{ Make_Frame(8,10,7,9,1)}
 #declare SmallFrame = object{ Make_Frame(5,4,4,3,0.5)}
\end{verbatim}}


   Because no type checking is performed on parameters and because the expression syntax for floats, vectors, and colors is identical, you can create clever 
 macros which work on all three. See the sample scene {\small\texttt{ \discretionary{MACRO3.}{}{MACRO3.}POV}} which includes this macro to interpolate values. 


{\small\begin{verbatim}
// Define the macro.  Parameters are:
//   T:  Middle value of time
//   T1: Initial time
//   T2: Final time
//   P1: Initial position (may be float, vector or color)
//   P2: Final position (may be float, vector or color)
//   Result is a value between P1 and P2 in the same proportion
//    as T is between T1 and T2.
#macro Interpolate(T,T1,T2,P1,P2)
   (P1+(T1+T/(T2-T1))*(P2-P1))
#end
\end{verbatim}}


   You might invoke it with {\small\texttt{P1}} and {\small\texttt{P2}} as floats, vectors, or colors as follows. 


{\small\begin{verbatim}
sphere{
  Interpolate(I,0,15,<2,3,4>,<9,8,7>), //center location is vector
  Interpolate(I,0,15,3.0,5.5)          //radius is float
  pigment {
    color Interpolate(I,0,15,rgb<1,1,0>,rgb<0,1,1>)
  }
}
\end{verbatim}}


   As the float value {\small\texttt{I}} varies from 0 to 15, the location, radius, and color of the sphere vary accordingly. 



   There is a danger in using macros as functions. In a traditional programming language function, the result to be returned is actually assigned to a temporary 
 variable and the invoking code treats it as a variable of a given type. However macro substitution may result in invalid or undesired syntax. The definition 
 of the macro {\small\texttt{Interpolate}} above has an outermost set of parentheses. If those parentheses are omitted, it will not matter in the examples 
 above, but what if you do this... 


{\small\begin{verbatim}
 #declare Value = Interpolate(I,0,15,3.0,5.5)*15;
\end{verbatim}}


   The end result is as if you had done... 


{\small\begin{verbatim}
 #declare Value = P1+(T1+T/(T2-T1))*(P2-P1) * 15;
\end{verbatim}}


   which is syntactically legal but not mathematically correct because the {\small\texttt{P1}} term is not multiplied. The parentheses in the original example 
 solves this problem. The end result is as if you had done... 


{\small\begin{verbatim}
 #declare Value = (P1+(T1+T/(T2-T1))*(P2-P1)) * 15;
\end{verbatim}}


   which is correct. 


\subsubsection{Returning Values Via Parameters}

% reference/000072.html

\index{Macros! return values in parameters}

   Sometimes it is necessary to have a macro return more than one value or you may simply prefer to return a value via a parameter as is typical in traditional 
 programming language procedures. POV-\discretionary{}{}{}Ray macros are capable of returning values this way. The syntax for POV-\discretionary{}{}{}Ray macro parameters says that the actual 
 parameter may be an \textit{IDENTIFIER} or an \textit{ RVALUE}. Values may only be returned via a parameter if the parameter is an \textit{ IDENTIFIER}. 
 Parameters that are \textit{RVALUES} are constant values that cannot return information. An \textit{RVALUE} is anything that legally may appear to the right 
 of an equals sign in a {\small\texttt{ \#declare}} or {\small\texttt{\#local}} directive. For example consider the following trivial macro which rotates an 
 object about the x-\discretionary{}{}{}axis. 


{\small\begin{verbatim}
 #macro Turn_Me(Stuff,Degrees)
   #declare Stuff = object{Stuff rotate x*Degrees}
 #end
\end{verbatim}}


   This attempts to re-\discretionary{}{}{}declare the identifier {\small\texttt{Stuff}} as the rotated version of the object. However the macro might be invoked with {\small\texttt{ 
 Turn\_\-Me(box\{\discretionary{0,}{}{0,}1\},30)}} which uses a box object as an \textit{ RVALUE} parameter. This will not work because the box is not an 
 identifier. You can however do this 


{\small\begin{verbatim}
   #declare MyObject=box{0,1}
   Turn_Me(MyObject,30)
\end{verbatim}}


   The identifier {\small\texttt{MyObject}} now contains the rotated box. 



   See "Identifier Name Collisions" for a detailed discussion of how local identifiers, parameters, and global identifiers work when a local 
 identifier has the same name as a previously declared identifier. 



   While it is obvious that {\small\texttt{MyObject}} is an identifier and {\small\texttt{ box\{\discretionary{0,}{}{0,}1\}}} is not, it should be noted that {\small\texttt{ 
 Turn\_\-Me(object\{MyObject\},30)}} will not work because {\small\texttt{ object\{MyObject\}}} is considered an object statement and is not a \textit{ pure} 
 identifier. This mistake is more likely to be made with float identifiers versus float expressions. Consider these examples. 


{\small\begin{verbatim}
  #declare Value=5.0;
  MyMacro(Value)     //MyMacro can change the value of Value but...
  MyMacro(+Value)    //This version and the rest are not lone
  MyMacro(Value+0.0) // identifiers. They are float expressions
  MyMacro(Value*1.0) // which cannot be changed.
\end{verbatim}}


   Although all four invocations of {\small\texttt{MyMacro}} are passed the value 5.0, only the first may modify the value of the identifier. 


\clearpage \chapter{Scene Settings}

% reference/000073.html


\section{Camera}

% reference/000074.html

\index{camera}\index{camera! keyword}\index{Keyword! camera}\index{perspective! camera}\index{Keyword! perspective}\index{orthographic! camera}\index{Keyword! orthographic}\index{fisheye! camera}\index{Keyword! fisheye}\index{ultra\_\-wide\_\-angle! camera}\index{Keyword! ultra\_\-wide\_\-angle}\index{omnimax! camera}\index{Keyword! omnimax}\index{panoramic! camera}\index{Keyword! panoramic}\index{cylinder! camera}\index{Keyword! cylinder}\index{spherical! camera}\index{Keyword! spherical}\index{location! camera}\index{Keyword! location}\index{right! camera}\index{Keyword! right}\index{up! camera}\index{Keyword! up}\index{direction! camera}\index{Keyword! direction}\index{sky! camera}\index{Keyword! sky}\index{angle! camera}\index{Keyword! angle}\index{look\_\-at! camera}\index{Keyword! look\_\-at}\index{blur\_\-samples! camera}\index{Keyword! blur\_\-samples}\index{aperture! camera}\index{Keyword! aperture}\index{focal\_\-point! camera}\index{Keyword! focal\_\-point}\index{confidence! camera}\index{Keyword! confidence}\index{variance! camera}\index{Keyword! variance}

   The camera definition describes the position, projection type and properties of the camera viewing the scene. Its syntax is: 


{\small\begin{verbatim}
CAMERA:
    camera{ [CAMERA_ITEMS...] }
CAMERA_ITEM:
    CAMERA_TYPE | CAMERA_VECTOR | CAMERA_MODIFIER |
    CAMERA_IDENTIFIER
CAMERA_TYPE:
    perspective | orthographic | fisheye | ultra_wide_angle |
    omnimax | panoramic | cylinder CylinderType | spherical
CAMERA_VECTOR:
    location <Location> | right <Right> | up <Up> | 
    direction <Direction> | sky <Sky>
CAMERA_MODIFIER:
    angle HORIZONTAL [VERTICAL] | look_at <Look_At> |
    blur_samples Num_of_Samples | aperture Size |
    focal_point <Point> | confidence Blur_Confidence |
    variance Blur_Variance | NORMAL | TRANSFORMATION
\end{verbatim}}


   Camera default values: \index{Default values! camera} 


{\small\begin{verbatim}
DEFAULT CAMERA:
  camera {
    perspective
    location <0,0,0>
    direction <0,0,1>
    right 1.33*x
    up y
    sky <0,1,0>
  }

CAMERA TYPE: perspective
angle      : \~{}67.380 ( direction_length=0.5*
                       right_length/tan(angle/2) )
confidence : 0.9 (90\%)
direction  : <0,0,1>
focal_point: <0,0,0>
location   : <0,0,0>
look_at    : z
right      : 1.33*x
sky        : <0,1,0>
up         : y
variance   : 1/128
\end{verbatim}}


   Depending on the projection type zero or more of the parameters are required: 


\begin{itemize}
 
 \item 
   If no camera is specified the default camera is used. 
 

 \item 
   If no projection type is given the perspective camera will be used (pinhole camera). 
 

 \item 
   The \textit{CAMERA\_\-TYPE} has to be the first item in the camera statement. 
 

 \item 
   Other \textit{CAMERA\_\-ITEMs} may legally appear in any order. 
 

 \item 
   For other than the perspective camera, the minimum that has to be specified is the CAMERA\_\-TYPE, the cylindrical camera also requires the \textit{CAMERA\_\-TYPE} 
  to be followed by a float. 
 

 \item 
   The Orthographic camera has two 'modes'. For the pure orthographic projection up or right have to be specified. For an orthographic camera, with the 
  same area of view as a perspective camera at the plane which goes through the look\_\-at point, the angle keyword has to be use. A value for the angle is 
  optional. 
 

 \item 
   All other \textit{CAMERA\_\-ITEM}s are taken from the default camera, unless they are specified differently. 
 

\end{itemize}

\subsection{Placing the Camera}

% reference/000075.html

\index{Camera! placing}\index{Moving! camera}

   The POV-\discretionary{}{}{}Ray camera has ten different models, each of which uses a different projection method to project the scene onto your screen. Regardless of the 
 projection type all cameras use the {\small\texttt{location}}, {\small\texttt{ right}}, {\small\texttt{up}}, {\small\texttt{direction}}, and keywords to 
 determine the location and orientation of the camera. The type keywords and these four vectors fully define the camera. All other camera modifiers adjust how 
 the camera does its job. The meaning of these vectors and other modifiers differ with the projection type used. A more detailed explanation of the camera 
 types follows later. In the sub-\discretionary{}{}{}sections which follows, we explain how to place and orient the camera by the use of these four vectors and the {\small\texttt{sky}} 
 and {\small\texttt{ look\_\-at}} modifiers. You may wish to refer to the illustration of the perspective camera below as you read about these vectors.\begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/perspcam} \caption{The perspective camera.} \end{figure} 
 


\subsubsection{Location and Look\_\-At}

% reference/000076.html

\index{location}\index{look\_\-at}

   Under many circumstances just two vectors in the camera statement are all you need to position the camera: {\small\texttt{location}} and {\small\texttt{look\_\-at}} 
 vectors. For example: 


{\small\begin{verbatim}
 camera {
  location <3,5,-10>
  look_at <0,2,1>
 }
\end{verbatim}}


   The location is simply the x, y, z coordinates of the camera. The camera can be located anywhere in the ray-\discretionary{}{}{}tracing universe. The default location is {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}. 
 The {\small\texttt{look\_\-at}} vector tells POV-\discretionary{}{}{}Ray to pan and tilt the camera until it is looking at the specified x, y, z coordinates. By default the camera 
 looks at a point one unit in the z-\discretionary{}{}{}direction from the location. 



   The {\small\texttt{look\_\-at}} modifier should almost always be the last item in the camera statement. If other camera items are placed after the {\small\texttt{ 
 look\_\-at}} vector then the camera may not continue to look at the specified point. 


\subsubsection{The Sky Vector}

% reference/000077.html

\index{Vectors! sky}\index{sky}

   Normally POV-\discretionary{}{}{}Ray pans left or right by rotating about the y-\discretionary{}{}{}axis until it lines up with the {\small\texttt{look\_\-at}} point and then tilts straight up or down 
 until the point is met exactly. However you may want to slant the camera sideways like an airplane making a banked turn. You may change the tilt of the camera 
 using the {\small\texttt{sky}} vector. For example: 


{\small\begin{verbatim}
 camera {
  location <3,5,-10>
  sky   <1,1,0>
  look_at <0,2,1>
 }
\end{verbatim}}


   This tells POV-\discretionary{}{}{}Ray to roll the camera until the top of the camera is in line with the sky vector. Imagine that the sky vector is an antenna pointing out of 
 the top of the camera. Then it uses the {\small\texttt{sky}} vector as the axis of rotation left or right and then to tilt up or down in line with the {\small\texttt{sky}} 
 until pointing at the {\small\texttt{look\_\-at}} point. In effect you are telling POV-\discretionary{}{}{}Ray to assume that the sky isn't straight up. 



   The {\small\texttt{sky}} vector does nothing on its own. It only modifies the way the {\small\texttt{look\_\-at}} vector turns the camera. The default value is {\small\texttt{ 
 sky$<$\discretionary{0,}{}{0,}\discretionary{1,}{}{1,}0$>$}}. 


\subsubsection{Angles}

% reference/000078.html

\index{angle}\index{angle! camera}

   The {\small\texttt{angle}} keyword followed by a float expression specifies the (horizontal) viewing angle in degrees of the camera used. Even though it is 
 possible to use the {\small\texttt{direction}} vector to determine the viewing angle for the perspective camera it is much easier to use the {\small\texttt{ 
 angle}} keyword. 



   When you specify the {\small\texttt{angle}}, POV-\discretionary{}{}{}Ray adjusts the length of the {\small\texttt{direction}} vector accordingly. The formula used is \textit{ 
 direction\_\-length = 0.5 * right\_\-length / tan(angle / 2)} where \textit{ right\_\-length} is the length of the {\small\texttt{right}} vector. You should 
 therefore specify the {\small\texttt{ direction}} and {\small\texttt{ right}} vectors before the {\small\texttt{ angle}} keyword. The {\small\texttt{ right}} 
 vector is explained in the next section. 



   There is no limitation to the viewing angle except for the perspective projection. If you choose viewing angles larger than 360 degrees you will see repeated 
 images of the scene (the way the repetition takes place depends on the camera). This might be useful for special effects. 



   The {\small\texttt{spherical}} camera has the option to also specify a vertical angle. If not specified it defaults to the horizontal angle/2 



   For example if you render an image with a \discretionary{2:}{}{2:}1 aspect ratio and map it to a sphere using spherical mapping, it will recreate the scene. Another use is to map 
 it onto an object and if you specify transformations for the object before the texture, say in an animation, it will look like reflections of the environment 
 (sometimes called environment mapping). 


\subsubsection{The Direction Vector}

% reference/000079.html

\index{Vectors! direction}\index{direction}

   You will probably not need to explicitly specify or change the camera {\small\texttt{direction}} vector but it is described here in case you do. It tells 
 POV-\discretionary{}{}{}Ray the initial direction to point the camera before moving it with the {\small\texttt{look\_\-at}} or {\small\texttt{rotate}} vectors 
 (the default value is {\small\texttt{direction$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}1$>$}}). It may also be used to control the (horizontal) field of view with some types of projection. 
 The length of the vector determines the distance of the viewing plane from the camera's location. A shorter {\small\texttt{direction}} vector gives a wider 
 view while a longer vector zooms in for close-\discretionary{}{}{}ups. In early versions of POV-\discretionary{}{}{}Ray, this was the only way to adjust field of view. However zooming should now be 
 done using the easier to use {\small\texttt{angle}} keyword. 



   If you are using the {\small\texttt{ultra\_\-wide\_\-angle}}, {\small\texttt{panoramic}}, or {\small\texttt{ cylindrical}} projection you should use a unit length {\small\texttt{ 
 direction}} vector to avoid strange results. The length of the {\small\texttt{ direction}} vector does not matter when using the {\small\texttt{ orthographic}}, 
 {\small\texttt{fisheye}}, or {\small\texttt{omnimax}} projection types. 


\subsubsection{Up and Right Vectors}

% reference/000080.html

\index{up}\index{right}

   The primary purpose of the {\small\texttt{up}} and {\small\texttt{right}} vectors is to tell POV-\discretionary{}{}{}Ray the relative height and width of the view screen. The 
 default values are: 


{\small\begin{verbatim}
 right 4/3*x
 up y
\end{verbatim}}


   In the default {\small\texttt{perspective}} camera, these two vectors also define the initial plane of the view screen before moving it with the {\small\texttt{ 
 look\_\-at}} or {\small\texttt{rotate}} vectors. The length of the {\small\texttt{ right}} vector (together with the {\small\texttt{direction}} vector) may 
 also be used to control the (horizontal) field of view with some types of projection. The {\small\texttt{look\_\-at}} modifier changes both the {\small\texttt{up}} 
 and {\small\texttt{right}} vectors. The {\small\texttt{angle}} calculation depends on the {\small\texttt{ right}} vector. 



   Most camera types treat the {\small\texttt{up}} and {\small\texttt{ right}} vectors the same as the {\small\texttt{perspective}} type. However several make 
 special use of them. In the {\small\texttt{orthographic}} projection: The lengths of the {\small\texttt{ up}} and {\small\texttt{right}} vectors set the size 
 of the viewing window regardless of the {\small\texttt{ direction}} vector length, which is not used by the orthographic camera. 



   When using {\small\texttt{cylindrical}} projection: types 1 and 3, the axis of the cylinder lies along the {\small\texttt{up}} vector and the width is 
 determined by the length of {\small\texttt{right}} vector or it may be overridden with the {\small\texttt{angle}} vector. In type 3 the {\small\texttt{ up}} 
 vector determines how many units high the image is. For example if you have {\small\texttt{up 4*y}} on a camera at the origin. Only points from y=2 to y=-2 
 are visible. All viewing rays are perpendicular to the y-\discretionary{}{}{}axis. For type 2 and 4, the cylinder lies along the {\small\texttt{right}} vector. Viewing rays for 
 type 4 are perpendicular to the {\small\texttt{right}} vector. 



   \textbf{Note:} that the {\small\texttt{up}}, {\small\texttt{right}}, and {\small\texttt{ direction}} vectors should always remain perpendicular to each other 
 or the image will be distorted. If this is not the case a warning message will be printed. The vista buffer will not work for non-\discretionary{}{}{}perpendicular camera 
 vectors. 


\subsubsection{Aspect Ratio}

% reference/000081.html



   Together the {\small\texttt{up}} and {\small\texttt{right}} vectors define the \textit{aspect ratio} (height to width ratio) of the resulting image. The 
 default values {\small\texttt{up$<$\discretionary{0,}{}{0,}\discretionary{1,}{}{1,}0$>$}} and {\small\texttt{ right$<$1.\discretionary{33,}{}{33,}\discretionary{0,}{}{0,}0$>$}} result in an aspect ratio of 4 to 3. This is the aspect ratio of a 
 typical computer monitor. If you wanted a tall skinny image or a short wide panoramic image or a perfectly square image you should adjust the {\small\texttt{up}} 
 and {\small\texttt{right}} vectors to the appropriate proportions. 



   Most computer video modes and graphics printers use perfectly square pixels. For example Macintosh displays and IBM SVGA modes 640x480, 800x600 and 1024x768 
 all use square pixels. When your intended viewing method uses square pixels then the width and height you set with the {\small\texttt{ Width}} and {\small\texttt{Height}} 
 options or {\small\texttt{+W}} or {\small\texttt{+H}} switches should also have the same ratio as the {\small\texttt{up}} and {\small\texttt{right}} vectors. 



   \textbf{Note:} 640/480 = 4/3 so the ratio is proper for this square pixel mode. 



   Not all display modes use square pixels however. For example IBM VGA mode 320x200 and Amiga 320x400 modes do not use square pixels. These two modes still 
 produce a 4/3 aspect ratio image. Therefore images intended to be viewed on such hardware should still use 4/3 ratio on their {\small\texttt{up}} and {\small\texttt{right}} 
 vectors but the pixel settings will not be 4/3. 



   For example: 


{\small\begin{verbatim}
 camera {
  location <3,5,-10>
  up    <0,1,0>
  right  <1,0,0>
  look_at <0,2,1>
 }
\end{verbatim}}


   This specifies a perfectly square image. On a square pixel display like SVGA you would use pixel settings such as {\small\texttt{+W480 +H480}} or {\small\texttt{ 
 +W600 +H600}}. However on the non-\discretionary{}{}{}square pixel Amiga 320x400 mode you would want to use values of {\small\texttt{+W240 +H400}} to render a square image. 



   The bottom line issue is this: the {\small\texttt{up}} and {\small\texttt{ right}} vectors should specify the artist's intended aspect ratio for the image 
 and the pixel settings should be adjusted to that same ratio for square pixels and to an adjusted pixel resolution for non-\discretionary{}{}{}square pixels. The {\small\texttt{ 
 up}} and {\small\texttt{right}} vectors should \textit{ not} be adjusted based on non-\discretionary{}{}{}square pixels. 


\subsubsection{Handedness}

% reference/000082.html

\index{Camera! coordinate system}\index{Coordinate system! camera}

   The {\small\texttt{right}} vector also describes the direction to the right of the camera. It tells POV-\discretionary{}{}{}Ray where the right side of your screen is. The sign 
 of the {\small\texttt{right}} vector can be used to determine the handedness of the coordinate system in use. The default value is: {\small\texttt{ 
 right$<$1.\discretionary{33,}{}{33,}\discretionary{0,}{}{0,}0$>$}}. This means that the +x-\discretionary{}{}{}direction is to the right. It is called a \textit{left-\discretionary{}{}{}handed} 
 system because you can use your left hand to keep track of the axes. Hold out your left hand with your palm facing to your right. Stick your thumb up. Point 
 straight ahead with your index finger. Point your other fingers to the right. Your bent fingers are pointing to the +x-\discretionary{}{}{}direction. Your thumb now points into 
 +y-\discretionary{}{}{}direction. Your index finger points into the +z-\discretionary{}{}{}direction. 



   To use a right-\discretionary{}{}{}handed coordinate system, as is popular in some CAD programs and other ray-\discretionary{}{}{}tracers, make the same shape using your right hand. Your thumb 
 still points up in the +y-\discretionary{}{}{}direction and your index finger still points forward in the +z-\discretionary{}{}{}direction but your other fingers now say the +x-\discretionary{}{}{}direction is to the 
 left. That means that the right side of your screen is now in the -x-\discretionary{}{}{}direction. To tell POV-\discretionary{}{}{}Ray to act like this you can use a negative x value in the {\small\texttt{ 
 right}} vector such as: {\small\texttt{ right$<$-1.\discretionary{33,}{}{33,}\discretionary{0,}{}{0,}0$>$}}. Since having x values increasing to the left does not make much sense on a 2D screen you now 
 rotate the whole thing 180 degrees around by using a positive z value in your camera's location. You end up with something like this. 


{\small\begin{verbatim}
 camera {
  location <0,0,10>
  up    <0,1,0>
  right  <-1.33,0,0>
  look_at <0,0,0>
 }
\end{verbatim}}


   Now when you do your ray-\discretionary{}{}{}tracer's aerobics, as explained in the section "Understanding POV-\discretionary{}{}{}Ray's Coordinate System", you use your right hand to 
 determine the direction of rotations. 



   In a two dimensional grid, x is always to the right and y is up. The two versions of handedness arise from the question of whether z points into the screen 
 or out of it and which axis in your computer model relates to up in the real world. 



   Architectural CAD systems, like AutoCAD, tend to use the \textit{ God's Eye} orientation that the z-\discretionary{}{}{}axis is the elevation and is the model's up direction. 
 This approach makes sense if you are an architect looking at a building blueprint on a computer screen. z means up, and it increases towards you, with x and y 
 still across and up the screen. This is the basic right handed system. 



   Stand alone rendering systems, like POV-\discretionary{}{}{}Ray, tend to consider you as a participant. You are looking at the screen as if you were a photographer standing in 
 the scene. The up direction in the model is now y, the same as up in the real world and x is still to the right, so z must be depth, which increases away from 
 you into the screen. This is the basic left handed system. 


\subsubsection{Transforming the Camera}

% reference/000083.html



   The various transformations such as {\small\texttt{translate}} and {\small\texttt{ rotate}} modifiers can re-\discretionary{}{}{}position the camera once you have defined it. 
 For example: 


{\small\begin{verbatim}
 camera {
  location < 0, 0, 0>
  direction < 0, 0, 1>
  up    < 0, 1, 0>
  right   < 1, 0, 0>
  rotate  <30, 60, 30>
  translate < 5, 3, 4>
 }
\end{verbatim}}


   In this example, the camera is created, then rotated by 30 degrees about the x-\discretionary{}{}{}axis, 60 degrees about the y-\discretionary{}{}{}axis and 30 degrees about the z-\discretionary{}{}{}axis, then 
 translated to another point in space. 


\subsection{Types of Projection}

% reference/000084.html

\index{Camera! types of}

   The following list explains the different projection types that can be used with the camera. The most common types are the perspective and orthographic 
 projections. The \textit{CAMERA\_\-TYPE} should be the \textit{first} item in a {\small\texttt{camera}} statement. If none is specified, the {\small\texttt{perspective}} 
 camera is the default. 



   You should note that the vista buffer can only be used with the perspective and orthographic camera. 


\subsubsection{Perspective projection}

% reference/000085.html

\index{perspective}\index{projection! perspective}

   The {\small\texttt{perspective}} keyword specifies the default perspective camera which simulates the classic pinhole camera. The (horizontal) viewing angle 
 is either determined by the ratio between the length of the {\small\texttt{direction}} vector and the length of the {\small\texttt{ right}} vector or by the 
 optional keyword {\small\texttt{angle}}, which is the preferred way. The viewing angle has to be larger than 0 degrees and smaller than 180 degrees. See the 
 figure in "Placing the Camera" for the geometry of the perspective camera. 


\subsubsection{Orthographic projection}

% reference/000086.html

\index{orthographic}\index{projection! orthographic}

   The orthographic camera offers two modes of operation: 



   The pure {\small\texttt{orthographic}} projection. This projection uses parallel camera rays to create an image of the scene. The area of view is determined 
 by the lengths of the {\small\texttt{right}} and {\small\texttt{up}} vectors. One of these has to be specified, they are not taken from the default camera. If 
 omitted the second method of the camera is used. 



   If, in a perspective camera, you replace the {\small\texttt{perspective}} keyword by {\small\texttt{orthographic}} and leave all other parameters the same, 
 you will get an orthographic view with the same image area, \discretionary{i.}{}{i.}e. the size of the image is the same. The same can be achieved by adding the {\small\texttt{angle}} 
 keyword to an orthographic camera. A value for the angle is optional. So this second mode is active if no up and right are within the camera statement, or 
 when the angle keyword is within the camera statement. 



   You should be aware though that the visible parts of the scene change when switching from perspective to orthographic view. As long as all objects of 
 interest are near the look\_\-at point they will be still visible if the orthographic camera is used. Objects farther away may get out of view while nearer 
 objects will stay in view. 



   If objects are too close to the camera location they may disappear. Too close here means, behind the orthographic camera projection plane (the plane that 
 goes through the {\small\texttt{look\_\-at}} point). 


\subsubsection{Fisheye projection}

% reference/000087.html

\index{fisheye}\index{projection! fisheye}

   This is a spherical projection. The viewing angle is specified by the {\small\texttt{angle}} keyword. An angle of 180 degrees creates the 
 "standard" fisheye while an angle of 360 degrees creates a super-\discretionary{}{}{}fisheye ("I-\discretionary{}{}{}see-\discretionary{}{}{}everything-\discretionary{}{}{}view"). If you use this projection you should get a 
 circular image. If this is not the case, \discretionary{i.}{}{i.}e. you get an elliptical image, you should read "Aspect Ratio". 


\subsubsection{Ultra wide angle projection}

% reference/000088.html

\index{ultra\_\-wide\_\-angle}\index{projection! ultra\_\-wide\_\-angle}

   This projection is somewhat similar to the fisheye but it projects the image onto a rectangle instead of a circle. The viewing angle can be specified using 
 the {\small\texttt{angle}} keyword. 


\subsubsection{Omnimax projection}

% reference/000089.html

\index{omnimax}\index{projection! omnimax}

   The omnimax projection is a 180 degrees fisheye that has a reduced viewing angle in the vertical direction. In reality this projection is used to make movies 
 that can be viewed in the dome-\discretionary{}{}{}like Omnimax theaters. The image will look somewhat elliptical. The {\small\texttt{angle}} keyword is not used with this 
 projection. 


\subsubsection{Panoramic projection}

% reference/000090.html

\index{panoramic}\index{projection! panoramic}

   This projection is called "cylindrical equirectangular projection". It overcomes the degeneration problem of the perspective projection if the 
 viewing angle approaches 180 degrees. It uses a type of cylindrical projection to be able to use viewing angles larger than 180 degrees with a tolerable 
 lateral-\discretionary{}{}{}stretching distortion. The {\small\texttt{angle}} keyword is used to determine the viewing angle. 


\subsubsection{Cylindrical projection}

% reference/000091.html

\index{cylindrical! projection}\index{projection! cylindrical}

   Using this projection the scene is projected onto a cylinder. There are four different types of cylindrical projections depending on the orientation of the 
 cylinder and the position of the viewpoint. A float value in the range 1 to 4 must follow the {\small\texttt{ cylinder}} keyword. The viewing angle and the 
 length of the {\small\texttt{ up}} or {\small\texttt{right}} vector determine the dimensions of the camera and the visible image. The camera to use is 
 specified by a number. The types are: 


\begin{enumerate}
 
 \item 
   vertical cylinder, fixed viewpoint 
 

 \item 
   horizontal cylinder, fixed viewpoint 
 

 \item 
   vertical cylinder, viewpoint moves along the cylinder's axis 
 

 \item 
   horizontal cylinder, viewpoint moves along the cylinder's axis 
 

\end{enumerate}

\subsubsection{Spherical projection}

% reference/000092.html

\index{spherical! projection}\index{projection! spherical}

   Using this projection the scene is projected onto a sphere. \newline Syntax: 


{\small\begin{verbatim}
  camera {
    spherical
    [angle HORIZONTAL [VERTICAL]]
    [CAMERA_ITEMS...]
  }
\end{verbatim}}


   The first value after {\small\texttt{angle}} sets the horizontal viewing angle of the camera. With the optional second value, the vertical viewing angle is 
 set: both in degrees. If the vertical angle is not specified, it defaults to half the horizontal angle. 



   The spherical projection is similar to the fisheye projection, in that the scene is projected on a sphere. But unlike the fisheye camera, it uses rectangular 
 coordinates instead of polar coordinates; in this it works the same way as spherical mapping (map\_\-type 1). 



   This has a number of uses. Firstly, it allows an image rendered with the spherical camera to be mapped on a sphere without distortion (with the fisheye 
 camera, you first have to convert the image from polar to rectangular coordinates in some image editor). Also, it allows effects such as "environment 
 mapping", often used for simulating reflections in scanline renderers. 


\subsection{Focal Blur}

% reference/000093.html

\index{Blur}\index{Camera! focal blur}\index{Depth of field}\index{aperture}

   POV-\discretionary{}{}{}Ray can simulate focal depth-\discretionary{}{}{}of-\discretionary{}{}{}field by shooting a number of sample rays from jittered points within each pixel and averaging the results. 



   To turn on focal blur, you must specify the {\small\texttt{aperture}} keyword followed by a float value which determines the depth of the sharpness zone. 
 Large apertures give a lot of blurring, while narrow apertures will give a wide zone of sharpness. 



   \textbf{Note:} while this behaves as a real camera does, the values for aperture are purely arbitrary and are not related to \textit{f}-stops. 



   You must also specify the {\small\texttt{blur\_\-samples}} keyword followed by an integer value specifying the maximum number of rays to use for each pixel. 
 More rays give a smoother appearance but is slower. By default no focal blur is used, i. e. the default aperture is 0 and the default number of samples is 0.\index{focal\_\-point} 
 



   The center of the \textit{zone of sharpness} is specified by the {\small\texttt{ focal\_\-point}} vector. The \textit{zone of sharpness} is a plane through the {\small\texttt{focal\_\-point}} 
 and is parallel to the camera. Objects close to this plane of focus are in focus and those farther from that plane are more blurred. The default value is {\small\texttt{ 
 focal\_\-point$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}.\index{blur\_\-samples} 



   Although {\small\texttt{blur\_\-samples}} specifies the maximum number of samples, there is an adaptive mechanism that stops shooting rays when a certain degree 
 of confidence has been reached. At that point, shooting more rays would not result in a significant change.\index{variance}\index{confidence}\index{variance! focal blur}\index{confidence! focal blur} 
 



   The {\small\texttt{confidence}} and {\small\texttt{ variance}} keywords are followed by float values to control the adaptive function. The {\small\texttt{confidence}} 
 value is used to determine when the samples seem to be \textit{close enough} to the correct color. The {\small\texttt{ variance}} value specifies an 
 acceptable tolerance on the variance of the samples taken so far. In other words, the process of shooting sample rays is terminated when the estimated color 
 value is very likely (as controlled by the confidence probability) near the real color value. 



   Since the {\small\texttt{confidence}} is a probability its values can range from 0 to $<$1 (the default is 0.9, i. e. 90\%). The value for the {\small\texttt{ 
 variance}} should be in the range of the smallest displayable color difference (the default is 1/128). If 1 is used POV-\discretionary{}{}{}Ray will issue a warning and then use 
 the default instead. 



   Rendering with the default settings can result in quite grainy images. This can be improved by using a lower {\small\texttt{variance}}. A value of 1/10000 
 gives a fairly good result (with default confidence and blur\_\-samples set to something like 100) without being unacceptably slow. 



   Larger {\small\texttt{confidence}} values will lead to more samples, slower traces and better images. The same holds for smaller {\small\texttt{variance}} 
 thresholds. 


\subsection{Camera Ray Perturbation}

% reference/000094.html

\index{Perturbation! camera ray}

   The optional {\small\texttt{normal}} may be used to assign a normal pattern to the camera. For example: 


{\small\begin{verbatim}
 camera{
   location Here
   look_at There
   normal { bumps 0.5 }
 }
\end{verbatim}}


   All camera rays will be perturbed using this pattern. The image will be distorted as though you were looking through bumpy glass or seeing a reflection off 
 of a bumpy surface. This lets you create special effects. See the animated scene {\small\texttt{\discretionary{camera2.}{}{camera2.}pov}} for an example. See "Normal" for 
 information on normal patterns. 


\subsection{Camera Identifiers}

% reference/000095.html

\index{Language! identifiers, camera}

   Camera identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. 
 You may declare several camera identifiers if you wish. This makes it easy to quickly change cameras. An identifier is declared as follows. 


{\small\begin{verbatim}
CAMERA_DECLARATION:
    #declare IDENTIFIER = CAMERA |
    #local IDENTIFIER = CAMERA
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{CAMERA} is any valid camera statement. See "\#declare vs. 
 \#local" for information on identifier scope. Here is an example... 


{\small\begin{verbatim}
 #declare Long_Lens = camera {
    location -z*100
    look_at <0,0,0>
    angle 3
 }
 
 #declare Short_Lens = camera {
    location -z*50
    look_at <0,0,0>
    angle 15
 }
    
 camera {
    Long_Lens  // edit this line to change lenses
    translate <33,2,0>
 }
\end{verbatim}}


   \textbf{Note:} only camera transformations can be added to an already declared camera. Camera behaviour changing keywords are not allowed, as they are needed 
 in an earlier stage for resolving the keyword order dependencies. 


\section{Atmospheric Effects}

% reference/000096.html



   Atmospheric effects are a loosely-\discretionary{}{}{}knit group of features that affect the background and/or the atmosphere enclosing the scene. POV-\discretionary{}{}{}Ray includes the ability 
 to render a number of atmospheric effects, such as fog, haze, mist, rainbows and skies. 


\subsection{Atmospheric Media}

% reference/000097.html

\index{media! atmospheric}

   Atmospheric effects such as fog, dust, haze, or visible gas may be simulated by a {\small\texttt{media}} statement specified in the scene but not attached to 
 any object. All areas not inside a non-\discretionary{}{}{}hollow object in the entire scene. A very simple approach to add fog to a scene is explained in section "Fog" 
 however this kind of fog does not interact with any light sources like {\small\texttt{media}} does. It will not show light beams or other effects and is 
 therefore not very realistic. 



   The atmosphere media effect overcomes some of the fog's limitations by calculating the interaction between light and the particles in the atmosphere using 
 volume sampling. Thus shafts of light beams will become visible and objects will cast shadows onto smoke or fog. 



   \textbf{Note:} POV-\discretionary{}{}{}Ray cannot sample media along an infinitely long ray. The ray must be finite in order to be possible to sample. This means that sampling 
 media is only possible for rays that hit an object. So no atmospheric media will show up against {\small\texttt{background}} or {\small\texttt{sky\_\-sphere}}. \newline Another 
 way of being able to sample media is using spotlights because also in this case the ray is not infinite (it is sampled only inside the spotlight cone). 



   With spotlights you will be able to create the best results because their cone of light will become visible. Pointlights can be used to create effects like 
 street lights in fog. Lights can be made to not interact with the atmosphere by adding {\small\texttt{media\_\-interaction off}} to the light source. They can be 
 used to increase the overall light level of the scene to make it look more realistic. 



   Complete details on {\small\texttt{media}} are given in the section "Media". Earlier versions of POV-\discretionary{}{}{}Ray used an {\small\texttt{atmosphere}} 
 statement for atmospheric effects but that system was incompatible with the old object {\small\texttt{halo}} system. So {\small\texttt{ atmosphere}} has been 
 eliminated and replaced with a simpler and more powerful media feature. The user now only has to learn one {\small\texttt{ media}} system for either 
 atmospheric or object use. 



   If you only want media effects in a particular area, you should use object media rather than only relying upon the media pattern. In general it will be 
 faster and more accurate because it only calculates inside the constraining object. 



   \textbf{Note:} the atmosphere feature will not work if the camera is inside a non-\discretionary{}{}{}hollow object (see section "Empty and Solid Objects" for a 
 detailed explanation). 


\subsection{Background}

% reference/000098.html

\index{background}\index{background! keyword}\index{Keyword! background}

   A background color can be specified if desired. Any ray that does not hit an object will be colored with this color. The default background is black. The 
 syntax for {\small\texttt{background}} is: 


{\small\begin{verbatim}
  BACKGROUND: 
       background {COLOR}
  \end{verbatim}}

\subsection{Fog}

% reference/000099.html

\index{fog}\index{fog! keyword}\index{Keyword! fog}\index{fog\_\-type! fog}\index{Keyword! fog\_\-type}\index{distance! fog}\index{Keyword! distance}\index{turbulence! fog}\index{Keyword! turbulence}\index{turb\_\-depth! fog}\index{Keyword! turb\_\-depth}\index{omega! fog}\index{Keyword! omega}\index{lambda! fog}\index{Keyword! lambda}\index{octaves! fog}\index{Keyword! octaves}\index{fog\_\-offset! fog}\index{Keyword! fog\_\-offset}\index{fog\_\-alt! fog}\index{Keyword! fog\_\-alt}\index{up! fog}\index{Keyword! up}

   If it is not necessary for light beams to interact with atmospheric media, then {\small\texttt{fog}} may be a faster way to simulate haze or fog. This 
 feature artificially adds color to every pixel based on the distance the ray has traveled. The syntax for fog is: 


{\small\begin{verbatim}
FOG:
    fog { [FOG_IDENTIFIER] [FOG_ITEMS...] }
FOG_ITEMS:
    fog_type Fog_Type | distance Distance | COLOR | 
    turbulence <Turbulence> | turb_depth Turb_Depth |
    omega Omega | lambda Lambda | octaves Octaves |
    fog_offset Fog_Offset | fog_alt Fog_Alt | 
    up <Fog_Up> | TRANSFORMATION
\end{verbatim}}


   Fog default values: \index{Default values! fog} 


{\small\begin{verbatim}
lambda     : 2.0
fog_type   : 1
fog_offset : 0.0
fog_alt    : 0.0
octaves    : 6
omega      : 0.5 
turbulence : <0,0,0>
turb_depth : 0.5
up         : <0,1,0>
\end{verbatim}}
\index{fog\_\-type}\index{ground fog}\index{constant fog}

   Currently there are two fog types, the default {\small\texttt{fog\_\-type 1}} is a constant fog and {\small\texttt{fog\_\-type 2}} is ground fog. The constant fog 
 has a constant density everywhere while the ground fog has a constant density for all heights below a given point on the up axis and thins out along this 
 axis. 



   The color of a pixel with an intersection depth \textit{d} is calculated by 



   \textit{ PIXEL\_\-COLOR = exp(-d/D) * OBJECT\_\-COLOR + (1-exp(-d/D)) * FOG\_\-COLOR} 



   \index{distance} \index{distance! fog} where \textit{D} is the specified value of the required fog {\small\texttt{distance}} keyword. At depth 0 the final 
 color is the object's color. If the intersection depth equals the fog distance the final color consists of 64\% of the object's color and 36\% of the fog's 
 color. 



   \textbf{Note:} for this equation, a distance of zero is undefined. In practice, povray will treat this value as "fog is off". To use an extremely 
 thick fog, use a small nonzero number such as 1e-6 or 1e-10. 



   \index{fog\_\-offset}\index{fog\_\-alt} For ground fog, the height below which the fog has constant density is specified by the {\small\texttt{fog\_\-offset}} 
 keyword. The {\small\texttt{fog\_\-alt}} keyword is used to specify the rate by which the fog fades away. The default values for both are 0.0 so be sure to 
 specify them if ground fog is used. At an altitude of \textit{{\small\texttt{ Fog\_\-Offset+Fog\_\-Alt}}} the fog has a density of 25\%. The density of the fog at 
 height less than or equal to \textit{Fog\_\-Offset} is 1.0 and for height larger than than \textit{Fog\_\-Offset} is calculated by: 



   \textit{ {\small\texttt{ 1/(1 + (y - Fog\_\-Offset) / Fog\_\-Alt) \^{}2}}} 



   The total density along a ray is calculated by integrating from the height of the starting point to the height of the end point. 



   The optional {\small\texttt{up}} vector specifies a direction pointing up, generally the same as the camera's up vector. All calculations done during the 
 ground fog evaluation are done relative to this up vector, i. e. the actual heights are calculated along this vector. The up vector can also be modified using 
 any of the known transformations described in "Transformations". Though it may not be a good idea to scale the up vector - the results are hardly 
 predictable - it is quite useful to be able to rotate it. You should also note that translations do not affect the up direction (and thus do not affect the 
 fog). 



   The required fog color has three purposes. First it defines the color to be used in blending the fog and the background. Second it is used to specify a 
 translucency threshold. By using a transmittance larger than zero one can make sure that at least that amount of light will be seen through the fog. With a 
 transmittance of 0.3 you will see at least 30\% of the background. Third it can be used to make a filtering fog. With a filter value larger than zero the 
 amount of background light given by the filter value will be multiplied with the fog color. A filter value of 0.7 will lead to a fog that filters 70\% of the 
 background light and leaves 30\% unfiltered. 



   Fogs may be layered. That is, you can apply as many layers of fog as you like. Generally this is most effective if each layer is a ground fog of different 
 color, altitude and with different turbulence values. To use multiple layers of fogs, just add all of them to the scene. 



   \index{turbulence! fog} You may optionally stir up the fog by adding turbulence. The {\small\texttt{turbulence}} keyword may be followed by a float or vector 
 to specify an amount of turbulence to be used. The {\small\texttt{omega}}, {\small\texttt{lambda}} and {\small\texttt{ octaves}} turbulence parameters may 
 also be specified. See section "Pattern Modifiers" for details on all of these turbulence parameters. 



   \index{turb\_\-depth} Additionally the fog turbulence may be scaled along the direction of the viewing ray using the {\small\texttt{turb\_\-depth}} amount. 
 Typical values are from 0.0 to 1.0 or more. The default value is 0.5 but any float value may be used. 



   \textbf{Note:} the fog feature will not work if the camera is inside a non-\discretionary{}{}{}hollow object (see section "Empty and Solid Objects" for a detailed 
 explanation). 


\subsection{Sky Sphere}

% reference/000100.html

\index{sky\_\-sphere}\index{sky\_\-sphere! keyword}\index{Keyword! sky\_\-sphere}

   The sky sphere is used create a realistic sky background without the need of an additional sphere to simulate the sky. Its syntax is: 


{\small\begin{verbatim}
SKY_SPHERE:
    sky_sphere { [SKY_SPHERE_IDENTIFIER] [SKY_SPHERE_ITEMS...] }
SKY_SPHERE_ITEM:
    PIGMENT | TRANSFORMATION
\end{verbatim}}


   The sky sphere can contain several pigment layers with the last pigment being at the top, i. e. it is evaluated last, and the first pigment being at the 
 bottom, i. e. it is evaluated first. If the upper layers contain filtering and/or transmitting components lower layers will shine through. If not lower layers 
 will be invisible. 



   The sky sphere is calculated by using the direction vector as the parameter for evaluating the pigment patterns. This leads to results independent from the 
 view point which pretty good models a real sky where the distance to the sky is much larger than the distances between visible objects. 



   If you want to add a nice color blend to your background you can easily do this by using the following example. 


{\small\begin{verbatim}
  sky_sphere {
    pigment {
      gradient y
      color_map {
        [ 0.5  color CornflowerBlue ]
        [ 1.0  color MidnightBlue ]
      }
      scale 2
      translate -1
    }
  }
\end{verbatim}}


   This gives a soft blend from {\small\texttt{CornflowerBlue}} at the horizon to {\small\texttt{MidnightBlue}} at the zenith. The scale and translate 
 operations are used to map the direction vector values, which lie in the range from $<$-1, -1, -1$>$ to $<$1, 1, 1$>$, onto the range from $<$0, 0, 0$>$ 
 to $<$1, 1, 1$>$. Thus a repetition of the color blend is avoided for parts of the sky below the horizon. 



   In order to easily animate a sky sphere you can transform it using the usual transformations described in "Transformations". Though it may not be a 
 good idea to translate or scale a sky sphere - the results are hardly predictable - it is quite useful to be able to rotate it. In an animation the color 
 blendings of the sky can be made to follow the rising sun for example. 



   \textbf{Note:} only one sky sphere can be used in any scene. It also will not work as you might expect if you use camera types like the orthographic or cylindrical 
 camera. The orthographic camera uses parallel rays and thus you will only see a very small part of the sky sphere (you will get one color skies in most 
 cases). Reflections in curved surface will work though, e. g. you will clearly see the sky in a mirrored ball. 


\subsection{Rainbow}

% reference/000101.html

\index{rainbow}\index{rainbow! keyword}\index{Keyword! rainbow}\index{direction! rainbow}\index{Keyword! direction}\index{angle! rainbow}\index{Keyword! angle}\index{width! rainbow}\index{Keyword! width}\index{distance! rainbow}\index{Keyword! distance}\index{jitter! rainbow}\index{Keyword! jitter}\index{up! rainbow}\index{Keyword! up}\index{arc\_\-angle! rainbow}\index{Keyword! arc\_\-angle}\index{falloff\_\-angle! rainbow}\index{Keyword! falloff\_\-angle}

   Rainbows are implemented using fog-\discretionary{}{}{}like, circular arcs. Their syntax is: 


{\small\begin{verbatim}
RAINBOW:
    rainbow { [RAINBOW_IDENTIFIER] [RAINBOW_ITEMS...] }
RAINBOW_ITEM:
    direction <Dir> | angle Angle | width Width |
    distance Distance | COLOR_MAP | jitter Jitter | up <Up> |
    arc_angle Arc_Angle | falloff_angle Falloff_Angle
\end{verbatim}}


   Rainbow default values: \index{Default values! rainbow} 


{\small\begin{verbatim}
arc_angle     : 180.0
falloff_angle : 180.0
jitter        : 0.0
up            : y
\end{verbatim}}
\index{width}\index{arc\_\-angle}\index{falloff\_\-angle}\index{direction! rainbow}\index{width! rainbow}\index{angle! rainbow}

   The required {\small\texttt{direction}} vector determines the direction of the (virtual) light that is responsible for the rainbow. Ideally this is an 
 infinitely far away light source like the sun that emits parallel light rays. The position and size of the rainbow are specified by the required {\small\texttt{angle}} 
 and {\small\texttt{width}} keywords. To understand how they work you should first know how the rainbow is calculated. 



   For each ray the angle between the rainbow's direction vector and the ray's direction vector is calculated. If this angle lies in the interval from \textit{{\small\texttt{ 
 Angle-\discretionary{}{}{}Width/2}}} to \textit{{\small\texttt{ Angle+Width/2}}} the rainbow is hit by the ray. The color is then determined by using the 
 angle as an index into the rainbow's color\_\-map. After the color has been determined it will be mixed with the background color in the same way like it is done 
 for fogs. 



   \index{jitter! rainbow} Thus the angle and width parameters determine the angles under which the rainbow will be seen. The optional {\small\texttt{ jitter}} 
 keyword can be used to add random noise to the index. This adds some irregularity to the rainbow that makes it look more realistic. 



   \index{distance! rainbow} The required {\small\texttt{distance}} keyword is the same like the one used with fogs. Since the rainbow is a fog-\discretionary{}{}{}like effect it 
 is possible that the rainbow is noticeable on objects. If this effect is not wanted it can be avoided by using a large distance value. By default a 
 sufficiently large value is used to make sure that this effect does not occur. 



   \index{color\_\-map! rainbow} The {\small\texttt{color\_\-map}} statement is used to assign a color map that will be mapped onto the rainbow. To be able to 
 create realistic rainbows it is important to know that the index into the color map increases with the angle between the ray's and rainbow's direction vector. 
 The index is zero at the innermost ring and one at the outermost ring. The filter and transmittance values of the colors in the color map have the same 
 meaning as the ones used with fogs (see section "Fog"). 



   The default rainbow is a 360 degree arc that looks like a circle. This is no problem as long as you have a ground plane that hides the lower, non-\discretionary{}{}{}visible 
 part of the rainbow. If this is not the case or if you do not want the full arc to be visible you can use the optional keywords {\small\texttt{up}}, {\small\texttt{ 
 arc\_\-angle}} and {\small\texttt{falloff\_\-angle}} to specify a smaller arc. 



   \index{arc\_\-angle! rainbow} \index{falloff\_\-angle! rainbow} The {\small\texttt{arc\_\-angle}} keyword determines the size of the arc in degrees (from 0 to 
 360 degrees). A value smaller than 360 degrees results in an arc that abruptly vanishes. Since this does not look nice you can use the {\small\texttt{falloff\_\-angle}} 
 keyword to specify a region in which the rainbow will smoothly blend into the background making it vanish softly. The falloff angle has to be smaller or equal 
 to the arc angle. 



   \index{up! rainbow} The {\small\texttt{ up}} keyword determines were the zero angle position is. By changing this vector you can rotate the rainbow about its 
 direction. You should note that the arc goes from \textit{-Arc\_\-Angle/2} to \textit{ +Arc\_\-Angle/2}. The soft regions go from \textit{-Arc\_\-Angle/2} to \textit{ 
 -Falloff\_\-Angle/2} and from \textit{+Falloff\_\-Angle/2} to \textit{ +Arc\_\-Angle/2}. 



   The following example generates a 120 degrees rainbow arc that has a falloff region of 30 degrees at both ends: 


{\small\begin{verbatim}
  rainbow {
    direction <0, 0, 1>
    angle 42.5
    width 5
    distance 1000
    jitter 0.01
    color_map { Rainbow_Color_Map }
    up <0, 1, 0>
    arc_angle 120
    falloff_angle 30
  }
\end{verbatim}}


   It is possible to use any number of rainbows and to combine them with other atmospheric effects. 


\section{Global Settings}

% reference/000102.html

\index{Settings! global}\index{global\_\-settings}\index{global\_\-settings! keyword}\index{Keyword! global\_\-settings}\index{adc\_\-bailout! global\_\-settings}\index{Keyword! adc\_\-bailout}\index{ambient\_\-light! global\_\-settings}\index{Keyword! ambient\_\-light}\index{assumed\_\-gamma! global\_\-settings}\index{Keyword! assumed\_\-gamma}\index{hf\_\-gray\_\-16! global\_\-settings}\index{Keyword! hf\_\-gray\_\-16}\index{irid\_\-wavelength! global\_\-settings}\index{Keyword! irid\_\-wavelength}\index{charset! global\_\-settings}\index{Keyword! charset}\index{max\_\-intersections! global\_\-settings}\index{Keyword! max\_\-intersections}\index{max\_\-trace\_\-level! global\_\-settings}\index{Keyword! max\_\-trace\_\-level}\index{number\_\-of\_\-waves! global\_\-settings}\index{Keyword! number\_\-of\_\-waves}\index{noise\_\-generator! global\_\-settings}\index{Keyword! noise\_\-generator}\index{radiosity! global\_\-settings}\index{Keyword! radiosity}\index{photon! global\_\-settings}\index{Keyword! photon}\index{ascii! global\_\-settings}\index{Keyword! ascii}\index{utf8! global\_\-settings}\index{Keyword! utf8}\index{sys! global\_\-settings}\index{Keyword! sys}

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



   \textbf{Note:} some items which were language directives in earlier versions of POV-\discretionary{}{}{}Ray have been moved inside the {\small\texttt{global\_\-settings}} statement 
 so that it is more obvious to the user that their effect is global. The old syntax is permitted but generates a warning. 



   The new syntax is: 


{\small\begin{verbatim}
GLOBAL_SETTINGS:
    global_settings { [GLOBAL_SETTINGS_ITEMS...] }
GLOBAL_SETTINGS_ITEM:
    adc_bailout Value | ambient_light COLOR | assumed_gamma Value | 
    hf_gray_16 [Bool] | irid_wavelength COLOR |
    charset GLOBAL_CHARSET | max_intersections Number |
    max_trace_level Number | number_of_waves Number |
    noise_generator Number | radiosity { RADIOSITY_ITEMS... } |
    photon { PHOTON_ITEMS... }
GLOBAL_CHARSET:
    ascii | utf8 | sys
\end{verbatim}}


   Global setting default values: \index{Default values! global settings} 


{\small\begin{verbatim}
charset            : ascii
adc_bailout        : 1/255
ambient_light      : <1,1,1>
assumed_gamma      : No gamma correction
hf_gray_16         : off
irid_wavelength    : <0.25,0.18,0.14>
max_trace_level    : 5
max_intersections  : 64
number_of_waves    : 10
noise_generator    : 2

Radiosity:
  adc_bailout      : 0.01
  always_sample    : on
  brightness       : 1.0
  count            : 35  (max = 1600)
  error_bound      : 1.8
  gray_threshold   : 0.0
  low_error_factor : 0.5
  max_sample       : non-positive value
  minimum_reuse    : 0.015
  nearest_count    : 5   (max = 20)
  normal           : off 
  pretrace_start   : 0.08
  pretrace_end     : 0.04
  recursion_limit  : 3
\end{verbatim}}


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


\subsection{ADC\_\-Bailout}

% reference/000103.html

\index{adc\_\-bailout! global\_\-settings}\index{adc\_\-bailout}

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



   You may use the global setting {\small\texttt{adc\_\-bailout}} keyword followed by float value to specify the point at which a ray's contribution is considered 
 insignificant. For example: 


{\small\begin{verbatim}
  global_settings { adc_bailout 0.01 }
\end{verbatim}}


   The default value is 1/255, or approximately 0.0039, since a change smaller than that could not be visible in a 24 bit image. Generally this setting is 
 perfectly adequate and should be left alone. Setting {\small\texttt{adc\_\-bailout}} to 0 will disable ADC, relying completely on {\small\texttt{max\_\-trace\_\-level}} 
 to set an upper limit on the number of rays spawned. 



   See section "Max\_\-Trace\_\-Level" for details on how ADC and {\small\texttt{max\_\-trace\_\-level}} interact. 


\subsection{Ambient\_\-Light}

% reference/000104.html

\index{ambient\_\-light! global\_\-settings}\index{ambient\_\-light}

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


{\small\begin{verbatim}
 global_settings { ambient_light COLOR }
\end{verbatim}}


   The default is a white ambient light source set at {\small\texttt{rgb $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$}}. Only the rgb components are used. The actual ambient used is: \textit{Ambient 
 = Finish\_\-Ambient * Global\_\-Ambient}. 



   See section "Ambient" for more information. 


\subsection{Assumed\_\-Gamma}

% reference/000105.html

\index{assumed\_\-gamma! global\_\-settings}\index{assumed\_\-gamma}

   Many people may have noticed at one time or another that some images are too bright or dim when displayed on their system. As a rule, Macintosh users find 
 that images created on a PC are too bright, while PC users find that images created on a Macintosh are too dim. 



   The {\small\texttt{assumed\_\-gamma}} global setting works in conjunction with the {\small\texttt{Display\_\-Gamma}} INI setting (see section "Display 
 Hardware Settings") to ensure that scene files render the same way across the wide variety of hardware platforms that POV-\discretionary{}{}{}Ray is used on. The assumed 
 gamma setting is used in a scene file by adding 


{\small\begin{verbatim}
 global_settings { assumed_gamma Value }
\end{verbatim}}


   where the assumed gamma value is the correction factor to be applied before the pixels are displayed and/or saved to disk. For scenes created in older 
 versions of POV-\discretionary{}{}{}Ray, the assumed gamma value will be the same as the display gamma value of the system the scene was created on. For PC systems, the most 
 common display gamma is 2.2, while for scenes created on Macintosh systems should use a scene gamma of 1.8. Another gamma value that sometimes occurs in 
 scenes is 1.0. 



   Scenes that do not have an {\small\texttt{assumed\_\-gamma}} global setting will not have any gamma correction performed on them, for compatibility reasons. If 
 you are creating new scenes or rendering old scenes, it is strongly recommended that you put in an appropriate {\small\texttt{assumed\_\-gamma}} global setting. 
 For new scenes, you should use an assumed gamma value of 1.0 as this models how light appears in the real world more realistically. 



   Before we go to the following sections, that explain more thoroughly what gamma is and why it is important, a short overview of how gamma works in POV-\discretionary{}{}{}Ray: 


\begin{description}
 
 \item 
   no {\small\texttt{assumed\_\-gamma}} in scene : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   No gamma correction is applied to output file. 
 \end{list}

 \item 
   {\small\texttt{assumed\_\-gamma 1}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gamma {\small\texttt{Display\_\-Gamma}} is applied to output file. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   If {\small\texttt{Display\_\-Gamma}} is not specified, 2.2 is used. 
 \end{list}

 \item 
   {\small\texttt{assumed\_\-gamma G}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gamma {\small\texttt{Display\_\-Gamma/G}} is applied to output file. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   If {\small\texttt{Display\_\-Gamma}} is not specified, 2.2/G is used. 
 \end{list}

 \item 
   Recommended value for {\small\texttt{assumed\_\-gamma}} is 1. 
 

\end{description}

\subsubsection{Monitor Gamma}

% reference/000106.html

\index{Gamma! monitor}

   The differences in how images are displayed is a result of how a computer actually takes an image and displays it on the monitor. In the process of rendering 
 an image and displaying it on the screen, several gamma values are important, including the POV scene file or image file gamma and the monitor gamma. 



   Most image files generated by POV-\discretionary{}{}{}Ray store numbers in the range from 0 to 255 for each of the red, green and blue components of a pixel. These numbers 
 represent the intensity of each color component, with 0 being black and 255 being the brightest color (either 100\% red, 100\% green or 100\% blue). When an 
 image is displayed, the graphics card converts each color component into a voltage which is sent to the monitor to light up the red, green and blue phosphors 
 on the screen. The voltage is usually proportional to the value of each color component. 



   Gamma becomes important when displaying intensities that are not the maximum or minimum possible values. For example, 127 should represent 50\% of the maximum 
 intensity for pixels stored as numbers between 0 and 255. On systems that do not do gamma correction, 127 will be converted to 50\% of the maximum voltage, but 
 because of the way the phosphors and the electron guns in a monitor work, this may be only 22\% of the maximum color intensity on a monitor with a gamma of 
 2.2. To display a pixel which is 50\% of the maximum intensity on this monitor, we would need a voltage of 73\% of the maximum voltage, which translates to 
 storing a pixel value of 186. 



   The relationship between the input pixel value and the displayed intensity can be approximated by an exponential function\textit{{\small\texttt{ obright = 
 ibright \^{} display\_\-gamma}}} where obright is the output intensity and ibright is the input pixel intensity. Both values are in the range from 0 to 1 (0\% to 
 100\%). Most monitors have a fixed gamma value in the range from 1.8 to 2.6. Using the above formula with display\_\-gamma values greater than 1 means that the 
 output brightness will be less than the input brightness. In order to have the output and input brightness be equal an overall system gamma of 1 is needed. To 
 do this, we need to gamma correct the input brightness in the same manner as above but with a gamma value of 1/display\_\-gamma before it is sent to the monitor. 
 To correct for a display gamma of 2.2, this pre-\discretionary{}{}{}monitor gamma correction uses a gamma value of 1.0/2.2 or approximately 0.45. 



   How the pre-\discretionary{}{}{}monitor gamma correction is done depends on what hardware and software is being used. On Macintosh systems, the operating system has taken it 
 upon itself to insulate applications from the differences in display hardware. Through a gamma control panel the user may be able to set the actual monitor 
 gamma and Mac will then convert all pixel intensities so that the monitor will appear to have the specified gamma value. On Silicon Graphics machines, the 
 display adapter has built-\discretionary{}{}{}in gamma correction calibrated to the monitor which gives the desired overall gamma (the default is 1.7). Unfortunately, on PCs and 
 most UNIX systems, it is up to the application to do any gamma correction needed. 


\subsubsection{Image File Gamma}

% reference/000107.html

\index{Gamma! image file}

   Since most PC and UNIX applications and image file formats do not understand display gamma, they do not do anything to correct for it. As a result, users 
 creating images on these systems adjust the image in such a way that it has the correct brightness when displayed. This means that the data values stored in 
 the files are made brighter to compensate for the darkening effect of the monitor. In essence, the 0.45 gamma correction is built in to the image files 
 created and stored on these systems. When these files are displayed on a Macintosh system, the gamma correction built in to the file, in addition to gamma 
 correction built into MacOS, means that the image will be too bright. Similarly, files that look correct on Macintosh or SGI systems because of the built-\discretionary{}{}{}in 
 gamma correction will be too dark when displayed on a PC. 



   The PNG format files generated by POV-\discretionary{}{}{}Ray overcome the problem of too much or not enough gamma correction by storing the image file gamma (which is 
 1.0/display\_\-gamma) inside the PNG file when it is generated by POV-\discretionary{}{}{}Ray. When the PNG file is later displayed by a program that has been set up correctly, 
 it uses this gamma value as well as the current display gamma to correct for the potentially different display gamma used when originally creating the image. 



   Unfortunately, of all the image file formats POV-\discretionary{}{}{}Ray supports, PNG is the only one that has any gamma correction features and is therefore preferred for 
 images that will be displayed on a wide variety of platforms. 


\subsubsection{Scene File Gamma}

% reference/000108.html

\index{Gamma! scene file}

   The image file gamma problem itself is just a result of how scenes themselves are generated in POV-\discretionary{}{}{}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. 



   This means that as the artist you are doing gamma correction in the POV-\discretionary{}{}{}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 (heaven forbid!), POV-\discretionary{}{}{}Ray allows you to specify in the scene file the display gamma of the system that the scene was created on. 



   The {\small\texttt{assumed\_\-gamma}} global setting, in conjunction with the {\small\texttt{Display\_\-Gamma}} INI setting lets POV-\discretionary{}{}{}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-\discretionary{}{}{}Ray, it will produce output image files that are the correct brightness for the current display, regardless of what output format is used. 
 As well, since the gamma correction is performed in the high-\discretionary{}{}{}precision data format that POV-\discretionary{}{}{}Ray uses internally, it produces better results than gamma 
 correction done after the file is written to disk. 



   Although you may not notice any difference in the output on your system with and without an {\small\texttt{assumed\_\-gamma}} setting, the assumed gamma is 
 important if the scene is ever rendered on another platform. 


\subsection{HF\_\-Gray\_\-16}

% reference/000109.html

\index{hf\_\-gray\_\-16! global\_\-settings}\index{hf\_\-gray\_\-16}

   The {\small\texttt{hf\_\-gray\_\-16}} setting is useful when using POV-\discretionary{}{}{}Ray to generate heightfields for use in other POV-\discretionary{}{}{}Ray scenes. The syntax is... 
 global\_\-settings \{ hf\_\-gray\_\-16 [Bool] \} 



   The boolean value turns the option on or off. If the keyword is specified without the boolean value then the option is turned on. If {\small\texttt{ 
 hf\_\-gray\_\-16}} is not specified in any {\small\texttt{global\_\-settings}} statement in the entire scene then the default is off. 



   When {\small\texttt{ hf\_\-gray\_\-16}} is on, 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:\textit{{\small\texttt{ height = 0.3 
 * red + 0.59 * green + 0.11 * blue}}}. 



   Setting the {\small\texttt{ hf\_\-gray\_\-16}} 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 "Height Field" 
 for a description of how POV-\discretionary{}{}{}Ray heightfields are stored for each file type. 


\subsection{Irid\_\-Wavelength}

% reference/000110.html

\index{irid\_\-wavelength! global\_\-settings}\index{irid\_\-wavelength}

   Iridescence calculations depend upon the dominant wavelengths of the primary colors of red, green and blue light. You may adjust the values using the global 
 setting {\small\texttt{irid\_\-wavelength}} as follows... 


{\small\begin{verbatim}
 global_settings { irid_wavelength COLOR }
\end{verbatim}}


   The default value is {\small\texttt{rgb $<$0.\discretionary{25,}{}{25,}0.\discretionary{18,}{}{18,}0.14$>$}} and any filter or transmit values are ignored. These values are proportional to the 
 wavelength of light but they represent no real world units. 



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


\subsection{Charset}

% reference/000111.html

\index{charset! global\_\-settings}\index{ascii}\index{utf8}\index{sys}

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


\subsection{Max\_\-Trace\_\-Level}

% reference/000112.html

\index{max\_\-trace\_\-level! global\_\-settings}\index{max\_\-trace\_\-level}

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


{\small\begin{verbatim}
 global_settings { max_trace_level Level }
\end{verbatim}}


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



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



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



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



   If {\small\texttt{max\_\-trace\_\-level}} is reached before a non-\discretionary{}{}{}reflecting surface is found and if ADC has not allowed an early exit from the ray tree the color 
 is returned as black. Raise {\small\texttt{max\_\-trace\_\-level}} if you see black areas in a reflective surface where there should be a color. 



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



   \textbf{Note:} that raising {\small\texttt{max\_\-trace\_\-level}} will use more memory and time and it could cause the program to crash with a stack overflow 
 error, although ADC will alleviate this to a large extent. 



   Values for {\small\texttt{max\_\-trace\_\-level}} can be set up to a maximum of 256. If there is no {\small\texttt{max\_\-trace\_\-level}} set and during rendering the 
 default value is reached, a warning is issued. 


\subsection{Max\_\-Intersections}

% reference/000113.html

\index{max\_\-intersections! global\_\-settings}\index{max\_\-intersections}

   POV-\discretionary{}{}{}Ray uses a set of internal stacks to collect ray/object intersection points. The usual maximum number of entries in these \textit{I-\discretionary{}{}{}Stacks} is 64. 
 Complex scenes may cause these stacks to overflow. POV-\discretionary{}{}{}Ray does not stop but it may incorrectly render your scene. When POV-\discretionary{}{}{}Ray finishes rendering, a number 
 of statistics are displayed. If you see {\small\texttt{I-\discretionary{}{}{}Stack Overflows}} reported in the statistics you should increase the stack size. Add a global setting 
 to your scene as follows: 


{\small\begin{verbatim}
 global_settings { max_intersections Integer }
\end{verbatim}}


   If the {\small\texttt{I-\discretionary{}{}{}Stack Overflows}} remain increase this value until they stop. 


\subsection{Number\_\-Of\_\-Waves}

% reference/000114.html

\index{number\_\-of\_\-waves! global\_\-settings}\index{number\_\-of\_\-waves}

   The {\small\texttt{waves}} and {\small\texttt{ripples}} patterns are generated by summing a series of waves, each with a slightly different center and size. 
 By default, ten waves are summed but this amount can be globally controlled by changing the {\small\texttt{number\_\-of\_\-waves}} setting. 


{\small\begin{verbatim}
 global_settings { number_of_waves Integer }
\end{verbatim}}


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


\subsection{Noise\_\-generator}

% reference/000115.html

\index{noise\_\-generator! global\_\-settings}

   There are three noise generators implemented. 


\begin{itemize}
 
 \item 
   {\small\texttt{noise\_\-generator 1}} the noise that was used in POV\_\-Ray 3.1 
 

 \item 
   {\small\texttt{noise\_\-generator 2}} 'range corrected' version of the old noise, it does not show the plateaus seen with {\small\texttt{noise\_\-generator 1}} 
  
 

 \item 
   {\small\texttt{noise\_\-generator 3}} generates Perlin noise 
 

\end{itemize}


   The default is {\small\texttt{noise\_\-generator 2}} 



   \textbf{Note:} The noise\_\-generators can also be used within the pigment/normal/etc. statement. 


\subsection{Radiosity Basics}

% reference/000116.html



   \textit{Important notice:} The radiosity features in POV-\discretionary{}{}{}Ray are somewhat experimental. There is a high probability that the design and implementation of 
 these features will be changed in future versions. We cannot guarantee that scenes using these features in this version will render identically in future 
 releases or that full backwards compatibility of language syntax can be maintained. 



   Radiosity is an extra calculation that more realistically computes the diffuse interreflection of light. This diffuse interreflection can be seen if you 
 place a white chair in a room full of blue carpet, blue walls and blue curtains. The chair will pick up a blue tint from light reflecting off of other parts 
 of the room. Also notice that the shadowed areas of your surroundings are not totally dark even if no light source shines directly on the surface. Diffuse 
 light reflecting off of other objects fills in the shadows. Typically ray-\discretionary{}{}{}tracing uses a trick called \textit{ ambient} light to simulate such effects but it 
 is not very accurate. 



   Radiosity calculations are only made when a {\small\texttt{radiosity\{\}}} block is used inside the {\small\texttt{global\_\-settings\{\}}} block. 



   The following sections describes how radiosity works, how to control it with various global settings and tips on trading quality vs. speed. 


\section{Radiosity}

% reference/000117.html

\index{Radiosity! reference}\index{radiosity}
\subsection{How Radiosity Works}

% reference/000118.html

\index{Radiosity! how it works}

   The problem of ray-\discretionary{}{}{}tracing is to figure out what the light level is at each point that you can see in a scene. Traditionally, in ray tracing, this is broken 
 into the sum of these components: 


\begin{description}
 
 \item 
   Diffuse 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   the effect that makes the side of things facing the light brighter; 
 \end{list}

 \item 
   Specular 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   the effect that makes shiny things have dings or sparkles on them; 
 \end{list}

 \item 
   Reflection 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   the effect that mirrors give; and 
 \end{list}

 \item 
   Ambient 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   the general all-\discretionary{}{}{}over light level that any scene has, which keeps things in shadow 
  from being pure black. 
 \end{list}

\end{description}


   POV-\discretionary{}{}{}Ray's radiosity system, based on a method by Greg Ward, provides a way to replace the last term - the constant ambient light value - with a light level 
 which is based on what surfaces are nearby and how bright in turn they are. 



   The first thing you might notice about this definition is that it is circular: the brightness and color of everything is dependent on everything else and 
 vice versa. This is true in real life but in the world of ray-\discretionary{}{}{}tracing, we can make an approximation. The approximation that is used is: the objects you are 
 looking at have their {\small\texttt{ambient}} values calculated for you by checking the other objects nearby. When those objects are checked during this 
 process, however, their {\small\texttt{diffuse}} term is used. The brightness of radiosity in POV-\discretionary{}{}{}Ray is based on two things: 


\begin{enumerate}
 
 \item 
   the amount of light "gathered" 
 

 \item 
   the 'diffuse' property of the surface finish 
 

\end{enumerate}


   An object can have both radiosity and an ambient term. However, it is suggested that if you use radiosity in a scene, you either set {\small\texttt{ambient\_\-light}} 
 to 0 in {\small\texttt{global\_\-settings}}, or use {\small\texttt{ambient 0}} in each object's finish. This lighting model is much more realistic, and POV-\discretionary{}{}{}Ray 
 will not try to adjust the overall brightness of the radiosity to match the ambient level specified by the user. 



   How does POV-\discretionary{}{}{}Ray calculate the ambient term for each point? By sending out more rays, in many different directions, and averaging the results. A typical 
 point might use 200 or more rays to calculate its ambient light level correctly. 



   Now this sounds like it would make the ray-\discretionary{}{}{}tracer 200 times slower. This is true, except that the software takes advantage of the fact that ambient light 
 levels change quite slowly (remember, shadows are calculated separately, so sharp shadow edges are not a problem). Therefore, these extra rays are sent out 
 only \textit{once in a while} (about 1 time in 50), then these calculated values are saved and reused for nearby pixels in the image when possible. 



   This process of saving and reusing values is what causes the need for a variety of tuning parameters, so you can get the scene to look just the way you want. 


\subsection{Adjusting Radiosity}

% reference/000119.html

\index{Radiosity! adjusting}

   As described earlier, radiosity is turned on by using the {\small\texttt{radiosity\{\}}} block in {\small\texttt{global\_\-setting}}. Radiosity has many 
 parameters that are specified as follows: 


{\small\begin{verbatim}
    global_settings { radiosity { [RADIOSITY_ITEMS...] } }
RADIOSITY_ITEMS:
    adc_bailout Float | always_sample Bool | brightness Float | 
    count Integer | error_bound Float | gray_threshold Float |
    load_file Filename | low_error_factor Float | max_sample Float |
    media Bool | minimum_reuse Float | nearest_count Integer |
    normal Bool | pretrace_end Float | pretrace_start Float |
    recursion_limit Integer | save_file Filename
\end{verbatim}}


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



   \textbf{Note:} Considerable changes have been made to the way radiosity works in POV-\discretionary{}{}{}Ray 3.5 compared to POV-\discretionary{}{}{}Ray 3.1. Old scene will not render to the same 
 result, if they render at all. It is not possible to use the {\small\texttt{\#version}} directive to get backward compatibility for radiosity. 


\subsubsection{radiosity adc\_\-bailout}

% reference/000120.html

\index{adc\_\-bailout! radiosity}

   You can specify an adc\_\-bailout for radiosity rays. Use {\small\texttt{adc\_\-bailout = 0.01 / brightest\_\-ambient\_\-object}} for good results. Default is 0.01. 


\subsubsection{always\_\-sample}

% reference/000121.html

\index{always\_\-sample}

   You can force POV-\discretionary{}{}{}Ray to only use the data from the pretrace step and not gather any new samples during the final radiosity pass. This may reduce 
 splotchiness. To do this, use {\small\texttt{always\_\-sample off}}, by default it is {\small\texttt{on}}. It can also be usefully when reusing previously saved 
 radiosity data. 


\subsubsection{brightness}

% reference/000122.html

\index{brightness}

   The {\small\texttt{brightness}} keyword specifies a float value that is the degree to which objects are brightened before being returned upwards to the rest 
 of the system. The default value is 1.0. In cases where you would raise the {\small\texttt{global\_\-settings\{ambient\_\-light value\}}} to increase the over all 
 brightness in a non-\discretionary{}{}{}radiosity scene, you can use {\small\texttt{brightness}} in a radiosity scene. 


\subsubsection{count}

% reference/000123.html

\index{count}

   The integer number of rays that are sent out whenever a new radiosity value has to be calculated is given by {\small\texttt{count}}. A value of 35 is the 
 default, the maximum is 1600. When this value is too low, the light level will tend to look a little bit blotchy, as if the surfaces you are looking at were 
 slightly warped. If this is not important to your scene (as in the case that you have a bump map or if you have a strong texture) then by all means use a 
 lower number. 


\subsubsection{error\_\-bound}

% reference/000124.html



   The {\small\texttt{error\_\-bound}} float value is one of the two main speed/quality tuning values (the other is of course the number of rays shot). In an ideal 
 world, this would be the {\small\texttt{only}} value needed. It is intended to mean the fraction of error tolerated. For example, if it were set to 1 the 
 algorithm would not calculate a new value until the error on the last one was estimated at as high as 100\%. Ignoring the error introduced by rotation for the 
 moment, on flat surfaces this is equal to the fraction of the reuse distance, which in turn is the distance to the closest item hit. If you have an old sample 
 on the floor 10 inches from a wall, an error bound of 0.5 will get you a new sample at a distance of about 5 inches from the wall. 



   The default value of 1.8 is good for a smooth general lighting effect. Using lower values is more accurate, but it will strongly increase the danger of 
 artifacts and therefore require higher {\small\texttt{count}}. You can use values even lower than 0.1 but both render time and memory use can become extremely 
 high then. 


\subsubsection{gray\_\-threshold}

% reference/000125.html

\index{gray\_\-threshold}

   Diffusely interreflected light is a function of the objects around the point in question. Since this is recursively defined to millions of levels of 
 recursion, in any real life scene, every point is illuminated at least in part by every other part of the scene. Since we cannot afford to compute this, if we 
 only do one bounce, the calculated ambient light is very strongly affected by the colors of the objects near it. This is known as color bleed and it really 
 happens but not as much as this calculation method would have you believe. The {\small\texttt{gray\_\-threshold}} float value grays it down a little, to make 
 your scene more believable. A value of .6 means to calculate the ambient value as 60\% of the equivalent gray value calculated, plus 40\% of the actual value 
 calculated. At 0\%, this feature does nothing. At 100\%, you always get white/gray ambient light, with no hue. 



   \textbf{Note:} this does not change the lightness/darkness, only the strength of hue/grayness (in HLS terms, it changes S only). The default value is 0.0 


\subsubsection{low\_\-error\_\-factor}

% reference/000126.html

\index{low\_\-error\_\-factor}

   If you calculate just enough samples, but no more, you will get an image which has slightly blotchy lighting. What you want is just a few extra interspersed, 
 so that the blending will be nice and smooth. The solution to this is the mosaic preview, controlled by {\small\texttt{pretrace}}: it goes over the image one 
 or more times beforehand, calculating radiosity values. To ensure that you get a few extra, the radiosity algorithm lowers the error bound during the 
 pre-\discretionary{}{}{}final passes, then sets it back just before the final pass. The {\small\texttt{ low\_\-error\_\-factor}} is a float tuning value which sets 
 the amount that the error bound is dropped during the preliminary image passes. If your low error factor is 0.8 and your error bound is set to 0.4 it will 
 really use an error bound of 0.32 during the first passes and 0.4 on the final pass. The default value is 0.5. 


\subsubsection{max\_\-sample}

% reference/000127.html

\index{max\_\-sample}

   Sometimes there can be problems with splotchiness that is caused by objects that are very bright. This can be sometimes avoided by using the {\small\texttt{max\_\-sample}} 
 keyword. {\small\texttt{max\_\-sample}} takes a float parameter which specifies the brightest that any gathered sample is allowed to be. Any samples brighter 
 than this will have their brightness decreased (without affecting color). Specifying a non-\discretionary{}{}{}positive value for {\small\texttt{max\_\-sample}} will allow any 
 brightness of samples (which is the default). 


\subsubsection{Media and Radiosity}

% reference/000128.html



   Radiosity estimation can be affected by media. To enable this feature, add {\small\texttt{media on}} to the {\small\texttt{radiosity\{\}}} block. The default 
 is {\small\texttt{off}} 


\subsubsection{minimum\_\-reuse}

% reference/000129.html

\index{minimum\_\-reuse}

   The minimum effective radius ratio is set by {\small\texttt{minimum\_\-reuse}} float value. This is the fraction of the screen width which sets the minimum 
 radius of reuse for each sample point (actually, it is the fraction of the distance from the eye but the two are roughly equal). For example, if the value is 
 0.02, the radius of maximum reuse for every sample is set to whatever ground distance corresponds to 2\% of the width of the screen. Imagine you sent a ray off 
 to the horizon and it hits the ground at a distance of 100 miles from your eye point. The reuse distance for that sample will be set to 2 miles. At a 
 resolution of 300*400 this will correspond to (very roughly) 8 pixels. The theory is that you do not want to calculate values for every pixel into every 
 crevice everywhere in the scene, it will take too long. This sets a minimum bound for the reuse. If this value is too low, (which it should be in theory) 
 rendering gets slow, and inside corners can get a little grainy. If it is set too high, you do not get the natural darkening of illumination near inside 
 edges, since it reuses. At values higher than 2\% you start getting more just plain errors, like reusing the illumination of the open table underneath the 
 apple. Remember that this is a unit less ratio. The default value is 0.015. 


\subsubsection{nearest\_\-count}

% reference/000130.html

\index{error\_\-bound}\index{nearest\_\-count}

   The {\small\texttt{nearest\_\-count}} integer value is the minimum number of old ambient values blended together to create a new interpolated value. The total 
 number blended will vary depending on {\small\texttt{error\_\-bound}}. All previous values that fit within the specified error\_\-bound will be used in the average. 



   It will always be the n geometrically closest reusable points that get used. If you go lower than 4, things can get pretty patchy. This can be good for 
 debugging, though. Must be no more than 20, since that is the size of the array allocated. The default value is 5. 


\subsubsection{Normal and Radiosity}

% reference/000131.html



   Radiosity estimation can be affected by normals. To enable this feature, add {\small\texttt{normal on}} to the {\small\texttt{radiosity\{\}}} block. The 
 default is {\small\texttt{off}} 


\subsubsection{Pretrace}

% reference/000132.html

\index{pretrace\_\-start}\index{pretrace\_\-end}

   To control the radiosity pre-\discretionary{}{}{}trace gathering step, use the keywords {\small\texttt{pretrace\_\-start}} and {\small\texttt{pretrace\_\-end}} within the {\small\texttt{radiosity\{\}}} 
 block. Each of these is followed by a decimal value between 0.0 and 1.0 which specifies the size of the blocks in the mosaic preview as a percentage of the 
 image size. The defaults are 0.08 for {\small\texttt{pretrace\_\-start}} and 0.04 for {\small\texttt{pretrace\_\-end}} 


\subsubsection{recursion\_\-limit}

% reference/000133.html

\index{recursion\_\-limit}

   The {\small\texttt{recursion\_\-limit}} is an integer value which determines how many recursion levels are used to calculate the diffuse inter-\discretionary{}{}{}reflection. The 
 default value is 3, the upper limit is 20. 


\subsubsection{Save and load radiosity data}

% reference/000134.html

\index{load\_\-file}\index{save\_\-file}\index{load\_\-file! radiosity}\index{save\_\-file! radiosity}

   You can save the radiosity data using {\small\texttt{save\_\-file "file\_\-name"}} and load the same data later using {\small\texttt{load\_\-file 
 "file\_\-name"}}. In general, it is not a good idea to save and load radiosity data if scene objects are moving. Even if data are loaded, more samples may be 
 taken during rendering (which produces a better approximation). You can disable samples from being taken during the final rendering phase by specifying {\small\texttt{always\_\-sample 
 off}}. 


\subsection{Tips on Radiosity}

% reference/000135.html

\index{Radiosity! tips}

   Have a look at the "Radiosity Tutorial" in the "Advanced Tutorial" section, to get a feel for what the visual result of changing 
 radiosity parameters is. 



   If you want to see where your values are being calculated set radiosity {\small\texttt{count}} down to about 20, set radiosity {\small\texttt{ nearest\_\-count}} 
 to 1 and set {\small\texttt{gray\_\-threshold}} to 0. This will make everything maximally patchy, so you will be able to see the borders between patches. There 
 will have been a radiosity calculation at the center of most patches. As a bonus, this is quick to run. You can then change the {\small\texttt{ error\_\-bound}} 
 up and down to see how it changes things. Likewise modify {\small\texttt{minimum\_\-reuse}}. 



   One way to get extra smooth results: crank up the sample count (we have gone as high as 1300) and drop the {\small\texttt{ low\_\-error\_\-factor}} to something 
 small like 0.6. Bump up the {\small\texttt{ nearest\_\-count}} to 7 or 8. This will get better values, and more of them, then interpolate among more of them on 
 the last pass. This is not for people with a lack of patience since it is like a squared function. If your blotchiness is only in certain corners or near 
 certain objects try tuning the error bound instead. Never drop it by more than a little at a time, since the run time will get very long. 



   Sometimes extra samples are taken during the final rendering pass. These newer samples can cause discontinuities in the radiosity in some scenes. To decrease 
 these artefacts, use a pretrace\_\-end of 0.04 (or even 0.02 if you are really patient and picky). This will cause the majority of the samples to be taken during 
 the preview passes, and decrease the artefacts created during the final rendering pass. You can force POV-\discretionary{}{}{}Ray to only use the data from the pretrace step and 
 not gather any new samples during the final radiosity pass. To do this, use "always\_\-sample no" within the radiosity block inside global\_\-settings. 



   If your scene uses ambient objects (especially small ambient objects) as light sources, you should probably use a higher count (100-150 and higher). For such 
 scenes, an error\_\-bound of 1.0 is usually good. Higher causes too much error, but lower causes very slow rendering. And it is important to adapt adc\_\-bailout. 


\clearpage \chapter{Objects}

% reference/000136.html

\index{objects}

   Objects are the building blocks of your scene. There are a lot of different types of objects supported by POV-\discretionary{}{}{}Ray. In the sections which follows, we describe 
 "Finite Solid Primitives", "Finite Patch Primitives", "Infinite Solid Primitives", "Isosurface Object", "Parametric 
 Object", and "Light Sources". These primitive shapes may be combined into complex shapes using "Constructive Solid Geometry" (also 
 known as CSG). 



   The basic syntax of an object is a keyword describing its type, some floats, vectors or other parameters which further define its location and/or shape and 
 some optional object modifiers such as texture, interior\_\-texture, pigment, normal, finish, interior, bounding, clipping or transformations. Specifically the 
 syntax is: 


{\small\begin{verbatim}
OBJECT:
    FINITE_SOLID_OBJECT | FINITE_PATCH_OBJECT | 
    INFINITE_SOLID_OBJECT | ISOSURFACE_OBJECT | PARAMETRIC_OBJECT |
    CSG_OBJECT | LIGHT_SOURCE |
    object { OBJECT_IDENTIFIER [OBJECT_MODIFIERS...] }
FINITE_SOLID_OBJECT:
    BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | JULIA_FRACTAL |
    LATHE | PRISM | SPHERE | SPHERESWEEP | SUPERELLIPSOID | SOR |
    TEXT | TORUS
FINITE_PATCH_OBJECT:
    BICUBIC_PATCH | DISC | MESH | MESH2 | POLYGON | TRIANGLE |
    SMOOTH_TRIANGLE
INFINITE_SOLID_OBJECT:
    PLANE | POLY | CUBIC | QUARTIC | QUADRIC
ISOSURFACE_OBJECT:
	ISOSURFACE
PARAMETRIC_OBJECT:
	PARAMETRIC	
CSG_OBJECT:
    UNION | INTERSECTION | DIFFERENCE | MERGE
\end{verbatim}}


   Object identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
OBJECT_DECLARATION:
    #declare IDENTIFIER = OBJECT |
    #local IDENTIFIER = OBJECT
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{OBJECT} is any valid object. To invoke an object identifier, you 
 wrap it in an {\small\texttt{object\{...\}}} statement. You use the {\small\texttt{object}} statement regardless of what type of object it originally was. 
 Although early versions of POV-\discretionary{}{}{}Ray required this {\small\texttt{ object}} wrapper all of the time, now it is only used with \textit{ OBJECT\_\-IDENTIFIERS}. 



   Object modifiers are covered in detail later. However here is a brief overview. 



   The texture describes the surface properties of the object. Complete details are in "Textures". Textures are combinations of pigments, normals, and 
 finishes. In the section "Pigment" you will learn how to specify the color or pattern of colors inherent in the material. In "Normal" we 
 describe a method of simulating various patterns of bumps, dents, ripples or waves by modifying the surface normal vector. The section on "Finish" 
 describes the reflective properties of the surface. The "Interior" is a feature introduced in POV-\discretionary{}{}{}Ray 3.1. It contains information about the 
 interior of the object which was formerly contained in the finish and halo parts of a texture. Interior items are no longer part of the texture. Instead, they 
 attach directly to the objects. The halo feature has been discontinued and replaced with a new feature called "Media" which replaces both halo and 
 atmosphere. 



   Bounding shapes are finite, invisible shapes which wrap around complex, slow rendering shapes in order to speed up rendering time. Clipping shapes are used 
 to cut away parts of shapes to expose a hollow interior. Transformations tell the ray-\discretionary{}{}{}tracer how to move, size or rotate the shape and/or the texture in the 
 scene. 


\section{Finite Solid Primitives}

% reference/000137.html



   There are fourteen different solid finite primitive shapes: blob, box, cone, cylinder, height field, Julia fractal, lathe, prism, sphere, spheresweep, 
 superellipsoid, surface of revolution, text object and torus. These have a well-\discretionary{}{}{}defined \textit{inside} and can be used in CSG (see section "Constructive 
 Solid Geometry"). They are finite and respond to automatic bounding. You may specify an interior for these objects. 


\subsection{Blob}

% reference/000138.html

\index{Blobs}\index{blob}\index{blob! keyword}\index{Keyword! blob}\index{sphere! blob}\index{Keyword! sphere}\index{strength! blob}\index{Keyword! strength}\index{cylinder! blob}\index{Keyword! cylinder}\index{component! blob}\index{Keyword! component}\index{threshold! blob}\index{Keyword! threshold}\index{hierarchy! blob}\index{Keyword! hierarchy}\index{sturm! blob}\index{Keyword! sturm}

   Blobs are an interesting and flexible object type. Mathematically they are iso-\discretionary{}{}{}surfaces of scalar fields, \discretionary{i.}{}{i.}e. their surface is defined by the strength of 
 the field in each point. If this strength is equal to a threshold value you are on the surface otherwise you are not. 



   Picture each blob component as an object floating in space. This object is \textit{ filled} with a field that has its maximum at the center of the object and 
 drops off to zero at the object's surface. The field strength of all those components are added together to form the field of the blob. Now POV-\discretionary{}{}{}Ray looks for 
 points where this field has a given value, the threshold value. All these points form the surface of the blob object. Points with a greater field value than 
 the threshold value are considered to be inside while points with a smaller field value are outside. 



   There's another, simpler way of looking at blobs. They can be seen as a union of flexible components that attract or repel each other to form a blobby 
 organic looking shape. The components' surfaces actually stretch out smoothly and connect as if they were made of honey or something similar. 



   The syntax for {\small\texttt{blob}} is defined as follows: 


{\small\begin{verbatim}
BLOB:
    blob { BLOB_ITEM... [BLOB_MODIFIERS...]}
BLOB_ITEM:
    sphere{<Center>, Radius,
           [ strength ] Strength[COMPONENT_MODIFIER...] } |
    cylinder{<End1>, <End2>, Radius,
             [ strength ] Strength [COMPONENT_MODIFIER...] } |
    component Strength, Radius, <Center> |
    threshold Amount
COMPONENT_MODIFIER:
    TEXTURE | PIGMENT | NORMAL | FINISH | TRANSFORMATION
BLOB_MODIFIER:
    hierarchy [Boolean] | sturm [Boolean] | OBJECT_MODIFIER
\end{verbatim}}


   Blob default values: \index{Default values! blob} 


{\small\begin{verbatim}
hierarchy : on
sturm     : off
threshold : 1.0
\end{verbatim}}
\index{threshold}

   The {\small\texttt{threshold}} keyword is followed by a float value which determines the total field strength value that POV-\discretionary{}{}{}Ray is looking for. The default 
 value if none is specified is {\small\texttt{threshold 1.0}}. By following the ray out into space and looking at how each blob component affects the ray, 
 POV-\discretionary{}{}{}Ray will find the points in space where the field strength is equal to the threshold value. The following list shows some things you 
 should know about the threshold value. 


\begin{enumerate}
 
 \item 
   The threshold value must be positive. 
 

 \item 
   A component disappears if the threshold value is greater than its strength. 
 

 \item 
   As the threshold value gets larger, the surface you see gets closer to the centers of the components. 
 

 \item 
   As the threshold value gets smaller, the surface you see gets closer to the surface of the components. 
 

\end{enumerate}
\index{cylinder! blob component}\index{blob! component, cylinder}

   Cylindrical components are specified by a {\small\texttt{cylinder}} statement. The center of the end-\discretionary{}{}{}caps of the cylinder is defined by the vectors \textit{ {\small\texttt{$<$End1$>$}}} 
 and \textit{{\small\texttt{ $<$End2$>$}}}. Next is the float value of the \textit{Radius} followed by the float \textit{ Strength}. These vectors and floats 
 are required and should be separated by commas. The keyword {\small\texttt{ strength}} may optionally precede the strength value. The cylinder has 
 hemispherical caps at each end.\index{sphere! blob component}\index{blob! component, sphere} 



   Spherical components are specified by a {\small\texttt{sphere}} statement. The location is defined by the vector \textit{ {\small\texttt{$<$Center$>$}}}. 
 Next is the float value of the \textit{ Radius} followed by the float \textit{ Strength}. These vector and float values are required and should be separated 
 by commas. The keyword {\small\texttt{ strength}} may optionally precede the strength value. 



   You usually will apply a single texture to the entire blob object, and you typically use transformations to change its size, location, and orientation. 
 However both the {\small\texttt{cylinder}} and {\small\texttt{sphere}} statements may have individual texture, pigment, normal, finish, and transformations 
 applied to them. You may not apply separate {\small\texttt{interior}} statements to the components but you may specify one for the entire blob. 



   \textbf{Note:} by unevenly scaling a spherical component you can create ellipsoidal components. The tutorial section on "Blob Object" illustrates 
 individually textured blob components and many other blob examples. 



   \index{component} \index{blob! component} The {\small\texttt{component}} keyword is an obsolete method for specifying a spherical component and is only used 
 for compatibility with earlier POV-\discretionary{}{}{}Ray versions. It may not have textures or transformations individually applied to it. 



   \index{strength} \index{strength! blob} The {\small\texttt{strength}} parameter of either type of blob component is a float value specifying the field 
 strength at the center of the object. The strength may be positive or negative. A positive value will make that component attract other components while a 
 negative value will make it repel other components. Components in different, separate blob shapes do not affect each other. 



   You should keep the following things in mind. 


\begin{enumerate}
 
 \item 
   The strength value may be positive or negative. Zero is a bad value, as the net result is that no field was added -- you might just as well have not 
  used this component. 
 

 \item 
   If strength is positive, then POV-\discretionary{}{}{}Ray will add the component's field to the space around the center of the component. If this adds enough field 
  strength to be greater than the threshold value you will see a surface. 
 

 \item 
   If the strength value is negative, then POV-\discretionary{}{}{}Ray will subtract the component's field from the space around the center of the component. This will only 
  do something if there happen to be positive components nearby. The surface around any nearby positive components will be dented away from the center of the 
  negative component. 
 

\end{enumerate}
\index{hierarchy}\index{hierarchy! blob}

   After all components and the optional {\small\texttt{threshold}} value have been specified you may specify zero or more blob modifiers. A blob modifier is 
 any regular object modifier or the {\small\texttt{hierarchy}} or {\small\texttt{ sturm}} keywords. 



   The components of each blob object are internally bounded by a spherical bounding hierarchy to speed up blob intersection tests and other operations. Using 
 the optional keyword {\small\texttt{ hierarchy}} followed by an optional boolean float value will turn it off or on. By default it is on. 



   The calculations for blobs must be very accurate. If this shape renders improperly you may add the keyword {\small\texttt{ sturm}} followed by an optional 
 boolean float value to turn off or on POV-\discretionary{}{}{}Ray's slower-\discretionary{}{}{}yet-\discretionary{}{}{}more-\discretionary{}{}{}accurate Sturmian root solver. By default it is off. 



   An example of a three component blob is: 


{\small\begin{verbatim}
BLOB:
 blob {
  threshold 0.6
  sphere { <.75, 0, 0>, 1, 1 }
  sphere { <-.375, .64952, 0>, 1, 1 }
  sphere { <-.375, -.64952, 0>, 1, 1 }
  scale 2
 }
\end{verbatim}}


   If you have a single blob component then the surface you see will just look like the object used, \discretionary{i.}{}{i.}e. a sphere or a cylinder, with the surface being 
 somewhere inside the surface specified for the component. The exact surface location can be determined from the blob equation listed below (you will probably 
 never need to know this, blobs are more for visual appeal than for exact modeling). 



   For the more mathematically minded, here's the formula used internally by POV-\discretionary{}{}{}Ray to create blobs. You do not need to understand this to use blobs. The 
 density of the blob field of a single component is: 



   
\begin{mathequ}
% FILE: blobdens
% --------
\begin{displaymath}
  \mathit{density} =
  \mathit{strength}\cdot
  \left(1-\left(\frac{\mathit{distance}}{\mathit{radius}}\right)^2\right)^2
\end{displaymath}

\caption{Density of a blob field.} \end{mathequ}
 



   where \textit{distance} is the distance of a given point from the spherical blob's center or cylinder blob's axis. This formula has the nice property that it 
 is exactly equal to the strength parameter at the center of the component and drops off to exactly 0 at a distance from the center of the component that is 
 equal to the radius value. The density formula for more than one blob component is just the sum of the individual component densities. 


\subsection{Box}

% reference/000139.html

\index{box}\index{box! keyword}\index{Keyword! box}

   A simple box can be defined by listing two corners of the box using the following syntax for a {\small\texttt{box}} statement: 


{\small\begin{verbatim}
BOX:
    box
    {
        <Corner_1>, <Corner_2>
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/boxgeom} \caption{The geometry of a box.} \end{figure} 



   Where \textit{{\small\texttt{$<$Corner\_\-1$>$}}} and \textit{{\small\texttt{ $<$Corner\_\-2$>$}}} are vectors defining the x, y, z coordinates of the opposite 
 corners of the box. 



   \textbf{Note:} that all boxes are defined with their faces parallel to the coordinate axes. They may later be rotated to any orientation using the {\small\texttt{ 
 rotate}} keyword. 



   Boxes are calculated efficiently and make good bounding shapes (if manually bounding seems to be necessary). 


\subsection{Cone}

% reference/000140.html

\index{cone}\index{cone! keyword}\index{Keyword! cone}\index{open! cone}\index{Keyword! open}

   The {\small\texttt{cone}} statement creates a finite length cone or a \textit{ frustum} (a cone with the point cut off). The syntax is: 


{\small\begin{verbatim}
CONE:
    cone
    {
        <Base_Point>, Base_Radius, <Cap_Point>, Cap_Radius
        [ open ][OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/conegeom} \caption{The geometry of a cone.} \end{figure} 



   Where \textit{{\small\texttt{$<$Base\_\-Point$>$}}} and \textit{{\small\texttt{$<$ Cap\_\-Point$>$}}} are vectors defining the x, y, z coordinates of the 
 center of the cone's base and cap and \textit{{\small\texttt{ Base\_\-Radius}}} and \textit{{\small\texttt{Cap\_\-Radius}}} are float values for the corresponding 
 radii. 



   Normally the ends of a cone are closed by flat discs that are parallel to each other and perpendicular to the length of the cone. Adding the optional keyword {\small\texttt{open}} 
 after \textit{{\small\texttt{Cap\_\-Radius}}} will remove the end caps and results in a tapered hollow tube like a megaphone or funnel. 


\subsection{Cylinder}

% reference/000141.html

\index{cylinder}\index{cylinder! keyword}\index{Keyword! cylinder}\index{open! cylinder}\index{Keyword! open}

   The {\small\texttt{cylinder}} statement creates a finite length cylinder with parallel end caps The syntax is: 


{\small\begin{verbatim}
CYLINDER:
    cylinder
    {
        <Base_Point>, <Cap_Point>, Radius
        [ open ][OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/cylgeom} \caption{The geometry of a cylinder.} \end{figure} 



   Where \textit{{\small\texttt{$<$Base\_\-Point$>$}}} and \textit{{\small\texttt{ $<$Cap\_\-Point$>$}}} are vectors defining the x, y, z coordinates of the 
 cylinder's base and cap and \textit{{\small\texttt{Radius}}} is a float value for the radius. 



   Normally the ends of a cylinder are closed by flat discs that are parallel to each other and perpendicular to the length of the cylinder. Adding the optional 
 keyword {\small\texttt{open}} after the radius will remove the end caps and results in a hollow tube. 


\subsection{Height Field}

% reference/000142.html

\index{height\_\-field}\index{height\_\-field! keyword}\index{Keyword! height\_\-field}\index{hierarchy! height\_\-field}\index{Keyword! hierarchy}\index{smooth! height\_\-field}\index{Keyword! smooth}\index{water\_\-level! height\_\-field}\index{Keyword! water\_\-level}\index{gif! height\_\-field}\index{Keyword! gif}\index{tga! height\_\-field}\index{Keyword! tga}\index{pot! height\_\-field}\index{Keyword! pot}\index{png! height\_\-field}\index{Keyword! png}\index{pgm! height\_\-field}\index{Keyword! pgm}\index{jpeg! height\_\-field}\index{Keyword! jpeg}\index{tiff! height\_\-field}\index{Keyword! tiff}\index{sys! height\_\-field}\index{Keyword! sys}\index{function! height\_\-field}\index{Keyword! function}\index{Mountains! generating with a height field}

   Height fields are fast, efficient objects that are generally used to create mountains or other raised surfaces out of hundreds of triangles in a mesh. The {\small\texttt{height\_\-field}} 
 statement syntax is: 


{\small\begin{verbatim}
HEIGHT_FIELD:
    height_field{
      [HF_TYPE]
      "filename"
      [HF_MODIFIER...]
      [OBJECT_MODIFIER...]
    }
HF_TYPE:
    gif | tga | pot | png | pgm | ppm | jpeg | tiff | sys | function
HF_MODIFIER:
    hierarchy [Boolean]  |
    smooth               |
    water_level Level
\end{verbatim}}


   Height\_\-field default values: \index{Default values! height\_\-field} 


{\small\begin{verbatim}
hierarchy   : on
smooth      : off
water_level : 0.0
\end{verbatim}}


   A height field is essentially a one unit wide by one unit long square with a mountainous surface on top. The height of the mountain at each point is taken 
 from the color number or palette index of the pixels in a graphic image file. The maximum height is one, which corresponds to the maximum possible color or 
 palette index value in the image file. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/unhfield} \caption{The size and orientation of an un-\discretionary{}{}{}scaled height field.} \end{figure} 
 



   The mesh of triangles corresponds directly to the pixels in the image file. Each square formed by four neighboring pixels is divided into two triangles. An 
 image with a resolution of \textit{{\small\texttt{N*M}}} pixels has \textit{{\small\texttt{(N-1)*(M-1)}}} squares that are divided into \textit{ {\small\texttt{ 
 2*(N-1)*(M-1)}}} triangles. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/pixhfld} \caption{Relationship of pixels and triangles in a height field.} \end{figure} 
 



   The resolution of the height field is influenced by two factors: the resolution of the image and the resolution of the color/index values. The size of the 
 image determines the resolution in the x- and z-\discretionary{}{}{}direction. A larger image uses more triangles and looks smoother. The resolution of the color/index value 
 determines the resolution along the y-\discretionary{}{}{}axis. A height field made from an 8-bit image can have 256 different height levels while one made from a 16-bit image 
 can have up to 65536 different height levels. Thus the second height field will look much smoother in the y-\discretionary{}{}{}direction if the height field is created 
 appropriately. 



   The size/resolution of the image does not affect the size of the height field. The un-\discretionary{}{}{}scaled height field size will always be 1 by 1 by 1. Higher resolution 
 image files will create smaller triangles, not larger height fields. 



   \index{pot} There are eight or possibly nine types of files which can define a height field. The image file type used to create a height field is specified 
 by one of the keywords {\small\texttt{gif}}, {\small\texttt{tga}}, {\small\texttt{pot}}, {\small\texttt{png}}, {\small\texttt{ pgm}}, {\small\texttt{ ppm}},{\small\texttt{ 
 tiff}}, {\small\texttt{jpeg}} and possibly {\small\texttt{ sys}} which is a system specific (e. g. Windows BMP or Macintosh Pict) format file. Specifying the 
 file type is optional. If it is not defined the same file type will be assumed as the one that is set as the output file type. This is useful when the source 
 for the {\small\texttt{height\_\-field}} is also generated with POV-\discretionary{}{}{}Ray. 



   The GIF, PNG, PGM, TIFF and possibly SYS format files are the only ones that can be created using a standard paint program. Though there are paint programs 
 for creating TGA image files they will not be of much use for creating the special 16 bit TGA files used by POV-\discretionary{}{}{}Ray (see below and "HF\_\-Gray\_\-16" for 
 more details). 



   In an image file that uses a color palette, like GIF, the color number is the palette index at a given pixel. Use a paint program to look at the palette of a 
 GIF image. The first color is palette index zero, the second is index one, the third is index two and so on. The last palette entry is index 255. Portions of 
 the image that use low palette entries will result in lower parts of the height field. Portions of the image that use higher palette entries will result in 
 higher parts of the height field. 



   Height fields created from GIF files can only have 256 different height levels because the maximum number of colors in a GIF file is 256. 



   The color of the palette entry does not affect the height of the pixel. Color entry 0 could be red, blue, black or orange but the height of any pixel that 
 uses color entry 0 will always be 0. Color entry 255 could be indigo, hot pink, white or sky blue but the height of any pixel that uses color entry 255 will 
 always be 1. 



   You can create height field GIF images with a paint program or a fractal program like {\small\texttt{ Fractint}}. You can usually get {\small\texttt{ Fractint}} 
 from most of the same sources as POV-\discretionary{}{}{}Ray. 



   A POT file is essentially a GIF file with a 16 bit palette. The maximum number of colors in a POT file is 65536. This means a POT height field can have up to 
 65536 possible height values. This makes it possible to have much smoother height fields. 



   \textbf{Note:} the maximum height of the field is still 1 even though more intermediate values are possible. 



   At the time of this writing the only program that created POT files was a freeware MS-\discretionary{}{}{}Dos/Windows program called {\small\texttt{Fractint}}. POT files 
 generated with this fractal program create fantastic landscapes. 



   The TGA and PPM file formats may be used as a storage device for 16 bit numbers rather than an image file. These formats use the red and green bytes of each 
 pixel to store the high and low bytes of a height value. These files are as smooth as POT files but they must be generated with special custom-\discretionary{}{}{}made programs. 
 Several programs can create TGA heightfields in the format POV uses, such as {\small\texttt{Gforge}} and {\small\texttt{Terrain Maker}}. 



   PNG format heightfields are usually stored in the form of a grayscale image with black corresponding to lower and white to higher parts of the height field. 
 Because PNG files can store up to 16 bits in grayscale images they will be as smooth as TGA and PPM images. Since they are grayscale images you will be able 
 to view them with a regular image viewer. {\small\texttt{ gforge}} can create 16-bit heightfields in PNG format. Color PNG images will be used in the same way 
 as TGA and PPM images. 



   SYS format is a platform specific file format. See your platform specific documentation for details. 



   In addition to all the usual object modifiers, there are three additional height field modifiers available. 



   \index{water\_\-level} The optional {\small\texttt{water\_\-level}} parameter may be added after the file name. It consists of the keyword {\small\texttt{water\_\-level}} 
 followed by a float value telling the program to ignore parts of the height field below that value. The default value is zero and legal values are between 
 zero and one. For example {\small\texttt{water\_\-level 0.5}} tells POV-\discretionary{}{}{}Ray to only render the top half of the height field. The other half is \textit{below the 
 water} and could not be seen anyway. Using {\small\texttt{water\_\-level}} renders faster than cutting off the lower part using CSG or clipping. This term comes 
 from the popular use of height fields to render landscapes. A height field would be used to create islands and another shape would be used to simulate water 
 around the islands. A large portion of the height field would be obscured by the water so the {\small\texttt{ water\_\-level}} parameter was introduced to allow 
 the ray-\discretionary{}{}{}tracer to ignore the unseen parts of the height field. {\small\texttt{water\_\-level}} is also used to cut away unwanted lower values in a height field. 
 For example if you have an image of a fractal on a solid colored background, where the background color is palette entry 0, you can remove the background in 
 the height field by specifying, {\small\texttt{ water\_\-level 0.001}}. 



   \index{smooth} Normally height fields have a rough, jagged look because they are made of lots of flat triangles. Adding the keyword {\small\texttt{ smooth}} 
 causes POV-\discretionary{}{}{}Ray to modify the surface normal vectors of the triangles in such a way that the lighting and shading of the triangles will give a smooth look. 
 This may allow you to use a lower resolution file for your height field than would otherwise be needed. However, smooth triangles will take longer to render. 
 The default value is off. 



   \index{hierarchy! height\_\-field} In order to speed up the intersection tests a one-\discretionary{}{}{}level bounding hierarchy is available. By default it is always used but 
 it can be switched off using {\small\texttt{hierarchy off}} to improve the rendering speed for small height fields (\discretionary{i.}{}{i.}e. low resolution images). You may 
 optionally use a boolean value such as {\small\texttt{ hierarchy on}} or {\small\texttt{ hierarchy off}}. 


\subsection{Julia Fractal}

% reference/000143.html

\index{Fractal Object}\index{fractal}\index{julia\_\-fractal}\index{julia\_\-fractal! keyword}\index{Keyword! julia\_\-fractal}\index{max\_\-iteration! julia\_\-fractal}\index{Keyword! max\_\-iteration}\index{precision! julia\_\-fractal}\index{Keyword! precision}\index{quaternion! julia\_\-fractal}\index{Keyword! quaternion}\index{hypercomplex! julia\_\-fractal}\index{Keyword! hypercomplex}\index{sqr! julia\_\-fractal}\index{Keyword! sqr}\index{cube! julia\_\-fractal}\index{Keyword! cube}\index{exp! julia\_\-fractal}\index{Keyword! exp}\index{reciprocal! julia\_\-fractal}\index{Keyword! reciprocal}\index{sin! julia\_\-fractal}\index{Keyword! sin}\index{asin! julia\_\-fractal}\index{Keyword! asin}\index{sinh! julia\_\-fractal}\index{Keyword! sinh}\index{asinh! julia\_\-fractal}\index{Keyword! asinh}\index{cos! julia\_\-fractal}\index{Keyword! cos}\index{acos! julia\_\-fractal}\index{Keyword! acos}\index{cosh! julia\_\-fractal}\index{Keyword! cosh}\index{acosh! julia\_\-fractal}\index{Keyword! acosh}\index{tan! julia\_\-fractal}\index{Keyword! tan}\index{atan! julia\_\-fractal}\index{Keyword! atan}\index{tanh! julia\_\-fractal}\index{Keyword! tanh}\index{atanh! julia\_\-fractal}\index{Keyword! atanh}\index{ln! julia\_\-fractal}\index{Keyword! ln}\index{pwr! julia\_\-fractal}\index{Keyword! pwr}

   A \textit{julia fractal} object is a 3-D \textit{slice} of a 4-D object created by generalizing the process used to create the classic Julia sets. You can 
 make a wide variety of strange objects using the {\small\texttt{ julia\_\-fractal}} statement including some that look like bizarre blobs of twisted taffy. The {\small\texttt{julia\_\-fractal}} 
 syntax is: 


{\small\begin{verbatim}
JULIA_FRACTAL:
    julia_fractal
    {
        <4D_Julia_Parameter>
        [JF_ITEM...] [OBJECT_MODIFIER...]
    }
JF_ITEM:
    ALGEBRA_TYPE | FUNCTION_TYPE | max_iteration Count |
    precision Amt | slice <4D_Normal>, Distance
ALGEBRA_TYPE:
    quaternion | hypercomplex
FUNCTION_TYPE:
    QUATERNATION: 
         sqr | cube
    HYPERCOMPLEX:
         sqr | cube | exp | reciprocal | sin | asin | sinh |
         asinh | cos | acos | cosh | acosh | tan | atan |tanh |
         atanh | ln | pwr( X_Val, Y_Val )
\end{verbatim}}


   Julia Fractal default values: \index{Default values! julia fractal} 


{\small\begin{verbatim}
ALGEBRA_TYPE    : quaternion
FUNCTION_TYPE   : sqr
max_iteration   : 20
precision       : 20
slice, DISTANCE : <0,0,0,1>, 0.0
\end{verbatim}}
\index{max\_\-iteration}

   The required 4-D vector \textit{{\small\texttt{$<$4D\_\-Julia\_\-Parameter$>$}}} is the classic Julia parameter \textit{{\small\texttt{p}}} in the iterated 
 formula \textit{{\small\texttt{f(h) + p}}}. The julia fractal object is calculated by using an algorithm that determines whether an arbitrary point \textit{{\small\texttt{h(0)}}} 
 in 4-D space is inside or outside the object. The algorithm requires generating the sequence of vectors \textit{{\small\texttt{h(0), h(1), ...}}} by iterating 
 the formula \textit{{\small\texttt{h(n+1) = f(h(n)) + p (n = 0, 1, ..., max\_\-iteration-1)}}} where \textit{{\small\texttt{ p}}} is the fixed 4-D vector 
 parameter of the julia fractal and \textit{{\small\texttt{f()}}} is one of the functions {\small\texttt{sqr}}, {\small\texttt{ cube}}, ... specified by the 
 presence of the corresponding keyword. The point \textit{{\small\texttt{ h(0)}}} that begins the sequence is considered inside the julia fractal object if 
 none of the vectors in the sequence escapes a hypersphere of radius 4 about the origin before the iteration number reaches the integer {\small\texttt{max\_\-iteration}} 
 value. As you increase {\small\texttt{max\_\-iteration}}, some points escape that did not previously escape, forming the julia fractal. Depending on the \textit{{\small\texttt{ 
 $<$4D\_\-Julia\_\-Parameter$>$}}}, the julia fractal object is not necessarily connected; it may be scattered fractal dust. Using a low {\small\texttt{ 
 max\_\-iteration}} can fuse together the dust to make a solid object. A high {\small\texttt{max\_\-iteration}} is more accurate but slows rendering. Even though 
 it is not accurate, the solid shapes you get with a low {\small\texttt{max\_\-iteration}} value can be quite interesting. If none is specified, the default is {\small\texttt{max\_\-iteration 
 20}}. 



   \index{slice} Since the mathematical object described by this algorithm is four-\discretionary{}{}{}dimensional and POV-\discretionary{}{}{}Ray renders three dimensional objects, there must be a 
 way to reduce the number of dimensions of the object from four dimensions to three. This is accomplished by intersecting the 4-D fractal with a 3-D 
 "plane" defined by the {\small\texttt{slice}} modifier and then projecting the intersection to 3-D space. The keyword is followed by 4-D vector and a float 
 separated by a comma. The slice plane is the 3-D space that is perpendicular to \textit{{\small\texttt{ $<$4D\_\-Normal$>$}}} and is \textit{{\small\texttt{ 
 Distance}}} units from the origin. Zero length \textit{{\small\texttt{ $<$4D\_\-Normal$>$}}} vectors or a \textit{{\small\texttt{ $<$4D\_\-Normal$>$}}} vector 
 with a zero fourth component are illegal. If none is specified, the default is {\small\texttt{ slice $<$\discretionary{0,}{}{0,}0,\discretionary{0,}{}{0,}1$>$,0}}. 



   You can get a good feel for the four dimensional nature of a julia fractal by using POV-\discretionary{}{}{}Ray's animation feature to vary a slice's \textit{{\small\texttt{ 
 Distance}}} parameter. You can make the julia fractal appear from nothing, grow, then shrink to nothing as \textit{{\small\texttt{ Distance}}} changes, much 
 as the cross section of a 3-D object changes as it passes through a plane. 



   \index{precision} The {\small\texttt{ precision}} parameter is a tolerance used in the determination of whether points are inside or outside the fractal 
 object. Larger values give more accurate results but slower rendering. Use as low a value as you can without visibly degrading the fractal object's appearance 
 but note values less than 1.0 are clipped at 1.0. The default if none is specified is {\small\texttt{precision 20}}. 



   \index{quaternion}\index{hypercomplex} The presence of the keywords {\small\texttt{ quaternion}} or {\small\texttt{ hypercomplex}} determine which 4-D 
 algebra is used to calculate the fractal. The default is {\small\texttt{quaternion}}. Both are 4-D generalizations of the complex numbers but neither 
 satisfies all the field properties (all the properties of real and complex numbers that many of us slept through in high school). Quaternions have 
 non-\discretionary{}{}{}commutative multiplication and hypercomplex numbers can fail to have a multiplicative inverse for some non-\discretionary{}{}{}zero elements (it has been 
 proved that you cannot successfully generalize complex numbers to four dimensions with all the field properties intact, so something has to break). Both of 
 these algebras were discovered in the 19th century. Of the two, the quaternions are much better known, but one can argue that hypercomplex numbers are more 
 useful for our purposes, since complex valued functions such as sin, cos, etc. can be generalized to work for hypercomplex numbers in a uniform way. 



   For the mathematically curious, the algebraic properties of these two algebras can be derived from the multiplication properties of the unit basis vectors 1 
 = $<$\discretionary{1,}{}{1,}0,\discretionary{0,}{}{0,}0$>$, i=$<$ \discretionary{0,}{}{0,}1,\discretionary{0,}{}{0,}0$>$, j=$<$\discretionary{0,}{}{0,}0,\discretionary{1,}{}{1,}0$>$ and k=$<$ \discretionary{0,}{}{0,}0,\discretionary{0,}{}{0,}1$>$. In both algebras 1 x = x 1 = x for any x (1 is the multiplicative identity). 
 The basis vectors 1 and i behave exactly like the familiar complex numbers 1 and i in both algebras. 


\begin{table} \centering\begin{tabular*}{302pt}[t]{@{} p{100pt}@{} p{100pt}@{} p{100pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{ij = k}} 
  } & 

  {\raggedleft 
    {\small\texttt{jk = i}} 
  } & 
{\raggedleft  {\small\texttt{ki = j}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ji = -k}} 
  } & 

  {\raggedleft 
    {\small\texttt{kj = -i}} 
  } & 
{\raggedleft  {\small\texttt{ik = -j}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ii = jj = kk = -1}} 
  } & 

  {\raggedleft 
    {\small\texttt{ijk = -1}} 
  } & 
{\raggedleft      } \\ 
 

\end{tabular*} \caption{Quaternion basis vector multiplication rules} \end{table}

\begin{table} \centering\begin{tabular*}{302pt}[t]{@{} p{100pt}@{} p{100pt}@{} p{100pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{ij = k}} 
  } & 

  {\raggedleft 
    {\small\texttt{jk = -i}} 
  } & 
{\raggedleft  {\small\texttt{ki = -j}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ji = k}} 
  } & 

  {\raggedleft 
    {\small\texttt{kj = -i}} 
  } & 
{\raggedleft  {\small\texttt{ik = -j}} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ii = jj = kk = -1}} 
  } & 

  {\raggedleft 
    {\small\texttt{ijk = 1}} 
  } & 
{\raggedleft      } \\ 
 

\end{tabular*} \caption{Hypercomplex basis vector multiplication rules} \end{table}


   A distance estimation calculation is used with the quaternion calculations to speed them up. The proof that this distance estimation formula works does not 
 generalize from two to four dimensions but the formula seems to work well anyway, the absence of proof notwithstanding! 



   \index{sqr} \index{cube} The presence of one of the function keywords {\small\texttt{sqr}}, {\small\texttt{ cube}}, etc. determines which function is used 
 for \textit{{\small\texttt{ f(h)}}} in the iteration formula \textit{ {\small\texttt{h(n+1) = f(h(n)) + p}}}. The default is {\small\texttt{sqr.}} Most of the 
 function keywords work only if the {\small\texttt{hypercomplex}} keyword is present. Only {\small\texttt{ sqr}} and {\small\texttt{cube}} work with {\small\texttt{ 
 quaternion}}. The functions are all familiar complex functions generalized to four dimensions. Function Keyword Maps 4-D value h to: 


\begin{table} \centering\begin{tabular*}{308pt}[t]{@{} p{92pt}@{} p{215pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{sqr}} 
  } & 
{\raggedleft  h*h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{cube}} 
  } & 
{\raggedleft  h*h*h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{exp}}\index{exp! julia} 
  } & 
{\raggedleft  e raised to the power h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{reciprocal}}\index{reciprocal} 
  } & 
{\raggedleft  1/h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{sin}}\index{sin! julia} 
  } & 
{\raggedleft  sine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{asin}}\index{asin! julia} 
  } & 
{\raggedleft  arcsine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{sinh}}\index{sinh! julia} 
  } & 
{\raggedleft  hyperbolic sine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{asinh}}\index{asinh! julia} 
  } & 
{\raggedleft  inverse hyperbolic sine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{cos}}\index{cos! julia} 
  } & 
{\raggedleft  cosine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{acos}}\index{acos! julia} 
  } & 
{\raggedleft  arccosine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{cosh}}\index{cosh! julia} 
  } & 
{\raggedleft  hyperbolic cos of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{acosh}}\index{acosh! julia} 
  } & 
{\raggedleft  inverse hyperbolic cosine of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{tan}}\index{tan! julia} 
  } & 
{\raggedleft  tangent of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{atan}}\index{atan} 
  } & 
{\raggedleft  arctangent of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{tanh}}\index{tanh! julia} 
  } & 
{\raggedleft  hyperbolic tangent of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{atanh}}\index{atanh! julia} 
  } & 
{\raggedleft  inverse hyperbolic tangent of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ln}}\index{ln! julia} 
  } & 
{\raggedleft  natural logarithm of h } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{pwr(\discretionary{x,}{}{x,}y)}}\index{pwr} 
  } & 
{\raggedleft  h raised to the complex power x+iy } \\ 
 

\end{tabular*} \caption{Function Keyword Maps 4-D value of h} \end{table}


   A simple example of a julia fractal object is: 


{\small\begin{verbatim}
 julia_fractal {
  <-0.083,0.0,-0.83,-0.025>
  quaternion
  sqr
  max_iteration 8
  precision 15
 }
\end{verbatim}}


   The first renderings of julia fractals using quaternions were done by Alan Norton and later by John Hart in the '80's. This POV-\discretionary{}{}{}Ray implementation follows {\small\texttt{Fractint}} 
 in pushing beyond what is known in the literature by using hypercomplex numbers and by generalizing the iterating formula to use a variety of transcendental 
 functions instead of just the classic Mandelbrot \textit{z2 + c} formula. With an extra two dimensions and eighteen functions to work with, intrepid explorers 
 should be able to locate some new fractal beasts in hyperspace, so have at it! 


\subsection{Lathe}

% reference/000144.html

\index{lathe}\index{lathe! keyword}\index{Keyword! lathe}\index{linear\_\-spline! lathe}\index{Keyword! linear\_\-spline}\index{quadratic\_\-spline! lathe}\index{Keyword! quadratic\_\-spline}\index{cubic\_\-spline! lathe}\index{Keyword! cubic\_\-spline}\index{bezier\_\-spline! lathe}\index{Keyword! bezier\_\-spline}\index{sturm! lathe}\index{Keyword! sturm}

   The {\small\texttt{lathe}} is an object generated from rotating a two-\discretionary{}{}{}dimensional curve about an axis. This curve is defined by a set of points which are 
 connected by linear, quadratic, cubic or bezier spline curves. The syntax is: 


{\small\begin{verbatim}
LATHE:
    lathe
    {
        [SPLINE_TYPE] Number_Of_Points, <Point_1>
        <Point_2>... <Point_n>
        [LATHE_MODIFIER...]
    }
SPLINE_TYPE:
    linear_spline | quadratic_spline | cubic_spline | bezier_spline
LATHE_MODIFIER:
    sturm | OBJECT_MODIFIER
\end{verbatim}}


   Lathe default values: \index{Default values! lathe} 


{\small\begin{verbatim}
SPLINE_TYPE   : linear_spline
sturm         : off
\end{verbatim}}
\index{linear\_\-spline}

   The first item is a keyword specifying the type of spline. The default if none is specified is {\small\texttt{linear\_\-spline}}. The required integer value \textit{{\small\texttt{Number\_\-Of\_\-Points}}} 
 specifies how many two-\discretionary{}{}{}dimensional points are used to define the curve. The points follow and are specified by 2-D vectors. The curve is not automatically 
 closed, \discretionary{i.}{}{i.}e. the first and last points are not automatically connected. You will have to do this yourself if you want a closed curve. The curve thus defined 
 is rotated about the y-\discretionary{}{}{}axis to form the lathe object, centered at the origin. 



   The following examples creates a simple lathe object that looks like a thick cylinder, \discretionary{i.}{}{i.}e. a cylinder with a thick wall: 


{\small\begin{verbatim}
 lathe {
  linear_spline
  5,
  <2, 0>, <3, 0>, <3, 5>, <2, 5>, <2, 0>
  pigment {Red}
 }
\end{verbatim}}


   The cylinder has an inner radius of 2 and an outer radius of 3, giving a wall width of 1. It's height is 5 and it's located at the origin pointing up, \discretionary{i.}{}{i.}e. 
 the rotation axis is the y-\discretionary{}{}{}axis. 



   \textbf{Note:} the first and last point are equal to get a closed curve. 



   The splines that are used by the lathe and prism objects are a little bit difficult to understand. The basic concept of splines is to draw a curve through a 
 given set of points in a determined way. The default {\small\texttt{ linear\_\-spline}} is the simplest spline because it's nothing more than connecting 
 consecutive points with a line. This means the curve that is drawn between two points only depends on those two points. No additional information is taken 
 into account. The other splines are different in that they do take other points into account when connecting two points. This creates a smooth curve and, in 
 the case of the cubic spline, produces smoother transitions at each point. 



   \index{quadratic\_\-spline} The {\small\texttt{quadratic\_\-spline}} keyword creates splines that are made of quadratic curves. Each of them connects two 
 consecutive points. Since those two points (call them second and third point) are not sufficient to describe a quadratic curve, the predecessor of the second 
 point is taken into account when the curve is drawn. Mathematically, the relationship (their relative locations on the 2-D plane) between the first and second 
 point determines the slope of the curve at the second point. The slope of the curve at the third point is out of control. Thus quadratic splines look much 
 smoother than linear splines but the transitions at each point are generally not smooth because the slopes on both sides of the point are different. 



   \index{cubic\_\-spline} The {\small\texttt{cubic\_\-spline}} keyword creates splines which overcome the transition problem of quadratic splines because they 
 also take a fourth point into account when drawing the curve between the second and third point. The slope at the fourth point is under control now and allows 
 a smooth transition at each point. Thus cubic splines produce the most flexible and smooth curves. 



   \index{bezier\_\-spline} The {\small\texttt{bezier\_\-spline}} is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and 
 points 2 and 3 are control points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the 
 spline. If you draw an imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the 
 distance between 1 and 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you 
 want the spline to be smooth between segments, points 3 and 4 on one segment and points 1 and 2 on the next segment must form a straight line and point 4 of 
 one segment must be the same as point 1 on the next segment. 



   You should note that the number of spline segments, i. e. curves between two points, depends on the spline type used. For linear splines you get n-1 segments 
 connecting the points P[i], i=1,...,n. A quadratic spline gives you n-2 segments because the last point is only used for determining the slope, as explained 
 above (thus you will need at least three points to define a quadratic spline). The same holds for cubic splines where you get n-3 segments with the first and 
 last point used only for slope calculations (thus needing at least four points). The bezier spline requires 4 points per segment, creating n/4 segments. 



   If you want to get a closed quadratic and cubic spline with smooth transitions at the end points you have to make sure that in the cubic case P[n-1] = P[2] 
 (to get a closed curve), P[n] = P[3] and P[n-2] = P[1] (to smooth the transition). In the quadratic case P[n-1] = P[1] (to close the curve) and P[n] = P[2]. 



   \index{sturm! lathe} The {\small\texttt{sturm}} keyword can be used to specify that the slower, but more accurate, Sturmian root solver should be used. Use 
 it, if the shape does not render properly. Since a quadratic polynomial has to be solved for the linear spline lathe, the Sturmian root solver is not needed. 


\subsection{Prism}

% reference/000145.html

\index{prism}\index{prism! keyword}\index{Keyword! prism}\index{open! prism}\index{Keyword! open}\index{linear\_\-spline! prism}\index{Keyword! linear\_\-spline}\index{quadratic\_\-spline! prism}\index{Keyword! quadratic\_\-spline}\index{cubic\_\-spline! prism}\index{Keyword! cubic\_\-spline}\index{bezier\_\-spline! prism}\index{Keyword! bezier\_\-spline}\index{linear\_\-sweep! prism}\index{Keyword! linear\_\-sweep}\index{conic\_\-sweep! prism}\index{Keyword! conic\_\-sweep}\index{sturm! prism}\index{Keyword! sturm}

   The {\small\texttt{prism}} is an object generated specifying one or more two-\discretionary{}{}{}dimensional, closed curves in the x-\discretionary{}{}{}z plane and sweeping them along y axis. 
 These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines. The syntax for the prism is: 


{\small\begin{verbatim}
PRISM:
    prism
    {
        [PRISM_ITEMS...] Height_1, Height_2, Number_Of_Points,
        <Point_1>, <Point_2>, ... <Point_n>
        [ open ] [PRISM_MODIFIERS...]
    }
PRISM_ITEM:
    linear_spline | quadratic_spline | cubic_spline |
    bezier_spline | linear_sweep | conic_sweep
PRISM_MODIFIER:
    sturm | OBJECT_MODIFIER
\end{verbatim}}


   Prism default values: \index{Default values! prism} 


{\small\begin{verbatim}
SPLINE_TYPE   : linear_spline
SWEEP_TYPE    : linear_sweep
sturm         : off
\end{verbatim}}
\index{linear\_\-sweep}

   The first items specify the spline type and sweep type. The defaults if none is specified is {\small\texttt{linear\_\-spline}} and {\small\texttt{ linear\_\-sweep}}. 
 This is followed by two float values \textit{{\small\texttt{ Height\_\-1}}} and \textit{ {\small\texttt{Height\_\-2}}} which are the y coordinates of the top and 
 bottom of the prism. This is followed by a float value specifying the number of 2-D points you will use to define the prism. (This includes all control points 
 needed for quadratic, cubic and bezier splines). This is followed by the specified number of 2-D vectors which define the shape in the x-\discretionary{}{}{}z plane. 



   The interpretation of the points depends on the spline type. The prism object allows you to use any number of sub-\discretionary{}{}{}prisms inside one prism statement (they are 
 of the same spline and sweep type). Wherever an even number of sub-\discretionary{}{}{}prisms overlaps a hole appears. 



   \textbf{Note:} you need not have multiple sub-\discretionary{}{}{}prisms and they need not overlap as these examples do. 



   In the {\small\texttt{linear\_\-spline}} the first point specified is the start of the first sub-\discretionary{}{}{}prism. The following points are connected by straight lines. If 
 you specify a value identical to the first point, this closes the sub-\discretionary{}{}{}prism and next point starts a new one. When you specify the value of that sub-\discretionary{}{}{}prism's 
 start, then it is closed. Each of the sub-\discretionary{}{}{}prisms has to be closed by repeating the first point of a sub-\discretionary{}{}{}prism at the end of the sub-\discretionary{}{}{}prism's point sequence. In 
 this example, there are two rectangular sub-\discretionary{}{}{}prisms nested inside each other to create a frame. 


{\small\begin{verbatim}
 prism {
  linear_spline
  0, 1, 10,
  <0,0>, <6,0>, <6,8>, <0,8>, <0,0>,  //outer rim
  <1,1>, <5,1>, <5,7>, <1,7>, <1,1>   //inner rim
 }
\end{verbatim}}


   The last sub-\discretionary{}{}{}prism of a linear spline prism is automatically closed - just like the last sub-\discretionary{}{}{}polygon in the polygon statement - if the first and last point 
 of the sub-\discretionary{}{}{}polygon's point sequence are not the same. This make it very easy to convert between polygons and prisms. Quadratic, cubic and bezier splines are 
 never automatically closed. 



   In the {\small\texttt{ quadratic\_\-spline}}, each sub-\discretionary{}{}{}prism needs an additional control point at the beginning of each sub-\discretionary{}{}{}prisms' point sequence to determine 
 the slope at the start of the curve. The first point specified is the control point which is not actually part of the spline. The second point is the start of 
 the spline. The sub-\discretionary{}{}{}prism ends when this second point is duplicated. The next point is the control point of the next sub-\discretionary{}{}{}prism. The point after that is the 
 first point of the second sub-\discretionary{}{}{}prism. Here is an example: 


{\small\begin{verbatim}
 prism {
   quadratic_spline
   0, 1, 12,
   <1,-1>, <0,0>, <6,0>, //outer rim; <1,-1> is control point and 
   <6,8>, <0,8>, <0,0>,  //<0,0> is first \& last point

   <2,0>, <1,1>, <5,1>,  //inner rim; <2,0> is control point and 
   <5,7>, <1,7>, <1,1>   //<1,1> is first \& last point
 }
\end{verbatim}}


   In the {\small\texttt{cubic\_\-spline}}, each sub-\discretionary{}{}{}prism needs two additional control points -- one at the beginning of each sub-\discretionary{}{}{}prisms' point sequence to 
 determine the slope at the start of the curve and one at the end. The first point specified is the control point which is not actually part of the spline. The 
 second point is the start of the spline. The sub-\discretionary{}{}{}prism ends when this second point is duplicated. The next point is the control point of the end of the first 
 sub-\discretionary{}{}{}prism. Next is the beginning control point of the next sub-\discretionary{}{}{}prism. The point after that is the first point of the second sub-\discretionary{}{}{}prism. 



   Here is an example: 


{\small\begin{verbatim}
 prism {
   cubic_spline
   0, 1, 14,
   <1,-1>, <0,0>, <6,0>, //outer rim; First control is <1,-1> and
   <6,8>, <0,8>, <0,0>,  //<0,0> is first \& last point.
   <-1,1>,               //Last control of first spline is <-1,1>

   <2,0>, <1,1>, <5,1>,  //inner rim; First control is <2,0> and 
   <5,7>, <1,7>, <1,1>,  //<1,1> is first \& last point
   <0,2>                 //Last control of first spline is <0,2>
 }
\end{verbatim}}
\index{conic\_\-sweep}

   The {\small\texttt{bezier\_\-spline}} is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and points 2 and 3 are control 
 points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the spline. If you draw an 
 imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the distance between 1 and 
 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you want the spline to be 
 smooth between segments, point 3 and 4 on one segment and point 1 and 2 on the next segment must form a straight line and point 4 of one segment must be the 
 same as point one on the next segment. 



   By default linear sweeping is used to create the prism, \discretionary{i.}{}{i.}e. the prism's walls are perpendicular to the x-\discretionary{}{}{}z-\discretionary{}{}{}plane (the size of the curve does not change 
 during the sweep). You can also use {\small\texttt{conic\_\-sweep}} that leads to a prism with cone-\discretionary{}{}{}like walls by scaling the curve down during the sweep. 



   Like cylinders the prism is normally closed. You can remove the caps on the prism by using the {\small\texttt{open}} keyword. If you do so you should not use 
 it with CSG because the results may get wrong. 



   For an explanation of the spline concept read the description of the "Lathe" object. Also see the tutorials on "Lathe Object" and 
 "Prism Object".\index{sturm! prism} 



   The {\small\texttt{ sturm}} keyword specifies the slower but more accurate Sturmian root solver which may be used with the cubic or bezier spline prisms if 
 the shape does not render properly. The linear and quadratic spline prisms do not need the Sturmian root solver. 


\subsection{Sphere}

% reference/000146.html

\index{sphere}\index{sphere! keyword}\index{Keyword! sphere}

   The syntax of the {\small\texttt{sphere}} object is: 


{\small\begin{verbatim}
SPHERE:
    sphere
    {
        <Center>, Radius
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/sphgeom} \caption{The geometry of a sphere.} \end{figure} 



   Where \textit{{\small\texttt{$<$Center$>$}}} is a vector specifying the x, y, z coordinates of the center of the sphere and \textit{{\small\texttt{ Radius}}} 
 is a float value specifying the radius. Spheres may be scaled unevenly giving an ellipsoid shape. 



   Because spheres are highly optimized they make good bounding shapes (if manual bounding seems to be necessary). 


\subsection{Sphere Sweep}

% reference/000147.html

\index{b\_\-spline}\index{tolerance}\index{sphere\_\-sweep}\index{sphere\_\-sweep! keyword}\index{Keyword! sphere\_\-sweep}\index{linear\_\-spline! sphere\_\-sweep}\index{Keyword! linear\_\-spline}\index{b\_\-spline! sphere\_\-sweep}\index{Keyword! b\_\-spline}\index{cubic\_\-spline! sphere\_\-sweep}\index{Keyword! cubic\_\-spline}\index{tolerance! sphere\_\-sweep}\index{Keyword! tolerance}

   The syntax of the {\small\texttt{sphere\_\-sweep}} object is: 


{\small\begin{verbatim}
SPHERE_SWEEP:
sphere_sweep {
  linear_spline | b_spline | cubic_spline
  NUM_OF_SPHERES,

  CENTER, RADIUS,
  CENTER, RADIUS,
  ...
  CENTER, RADIUS
  [tolerance DEPTH_TOLERANCE]
  [OBJECT_MODIFIERS]
}
\end{verbatim}}


   Sphere\_\-sweep default values: \index{Default values! sphere\_\-sweep} 


{\small\begin{verbatim}
tolerance : 1.0e-6 (0.000001) 
\end{verbatim}}


   A Sphere Sweep is the envelope of a moving sphere with varying radius, or, in other words, the space a sphere occupies during its movement along a spline. \newline Sphere 
 Sweeps are modeled by specifying a list of single spheres which are then interpolated. \newline Three kinds of interpolation are supported: 


\begin{itemize}
 
 \item 
   {\small\texttt{linear\_\-spline}} : Interpolating the input data with a linear function, which means that the single spheres are connected by straight 
  tubes. 
 

 \item 
   {\small\texttt{b\_\-spline}} : Approximating the input data using a cubic b-\discretionary{}{}{}spline function, which results in a curved object. 
 

 \item 
   {\small\texttt{cubic\_\-spline}} : Approximating the input data using a cubic spline, which results in a curved object. 
 

\end{itemize}


   The sphere list (center and radius of each sphere) can take as many spheres as you like to describe the object, but you will need at least two spheres for a {\small\texttt{linear\_\-spline}}, 
 and four spheres for {\small\texttt{b\_\-spline}} or {\small\texttt{cubic\_\-spline}}. 



   Optional: The depth tolerance that should be used for the intersection calculations. This is done by adding the {\small\texttt{tolerance}} keyword and the 
 desired value: the default distance is 1.0e-6 (0.000001) and should do for most sphere sweep objects. \newline You should change this when you see dark spots 
 on the surface of the object. These are probably caused by an effect called "Self-\discretionary{}{}{}Shading". This means that the object casts shadows onto itself at 
 some points because of calculation errors. A ray tracing program usually defines the minimal distance a ray must travel before it actually hits another (or 
 the same) object to avoid this effect. If this distance is chosen too small, Self-\discretionary{}{}{}Shading may occur. \newline If so, specify {\small\texttt{tolerance 1.0e-4}} 
 or higher. 



   \textbf{Note:} if these dark spots remain after raising the tolerance, you might get rid of these spots by using Adaptive Supersampling (Method 2) for 
 antialiasing. Images look better with antialiasing anyway. 



   \textbf{Note:} the merge CSG operation is not recommended with Sphere Sweeps: there could be a small gap between the merged objects! 


\subsection{Superquadric Ellipsoid}

% reference/000148.html

\index{superquadric}\index{superellipsoid}\index{superellipsoid! keyword}\index{Keyword! superellipsoid}

   The {\small\texttt{superellipsoid}} object creates a shape known as a \textit{ superquadric ellipsoid} object. It is an extension of the quadric ellipsoid. 
 It can be used to create boxes and cylinders with round edges and other interesting shapes. Mathematically it is given by the equation: 



   
\begin{mathequ}
% FILE: sqemath
% -------
\begin{displaymath}
  f(x,y,z) =
  \left(|x|^{\left(\frac{2}{e}\right)} + |y|^{\left(\frac{2}{e}\right)}
  \right)^{\left(\frac{e}{n}\right)} + |z|^{\left(\frac{2}{n}\right)} - 1 = 0
\end{displaymath}

\caption{} \end{mathequ}
 



   The values of \textit{{\small\texttt{e}}} and \textit{{\small\texttt{n}}}, called the \textit{east-\discretionary{}{}{}west} and \textit{north-\discretionary{}{}{}south} exponent, determine the 
 shape of the superquadric ellipsoid. Both have to be greater than zero. The sphere is given by \textit{e = 1} and \textit{n = 1}. 



   The syntax of the superquadric ellipsoid is: 


{\small\begin{verbatim}
SUPERELLIPSOID:
    superellipsoid
    {
        <Value_E, Value_N>
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   The 2-D vector specifies the \textit{{\small\texttt{e}}} and \textit{{\small\texttt{ n}}} values in the equation above. The object sits at the origin and 
 occupies a space about the size of a {\small\texttt{ box\{$<$-1,-1,-1$>$,$<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$\}}}. 



   Two useful objects are the rounded box and the rounded cylinder. These are declared in the following way. 


{\small\begin{verbatim}
 #declare Rounded_Box = superellipsoid { <Round, Round> }
 #declare Rounded_Cylinder = superellipsoid { <1, Round> }
\end{verbatim}}


   The roundedness value {\small\texttt{Round}} determines the roundedness of the edges and has to be greater than zero and smaller than one. The smaller you 
 choose the values, the smaller and sharper the edges will get. 



   Very small values of \textit{{\small\texttt{e}}} and \textit{{\small\texttt{n}}} might cause problems with the root solver (the Sturmian root solver cannot 
 be used). 


\subsection{Surface of Revolution}

% reference/000149.html

\index{sor}\index{sor! keyword}\index{Keyword! sor}\index{open! sor}\index{Keyword! open}\index{sturm! sor}\index{Keyword! sturm}

   The {\small\texttt{sor}} object is a \textit{surface of revolution} generated by rotating the graph of a function about the y-\discretionary{}{}{}axis. This function describes 
 the dependence of the radius from the position on the rotation axis. The syntax is: 


{\small\begin{verbatim}
SOR:
    sor
    {
        Number_Of_Points, <Point_1>, <Point_2>, ... <Point_n>
        [ open ] [SOR_MODIFIERS...]
    }
SOR_MODIFIER:
    sturm | OBJECT_MODIFIER
\end{verbatim}}


   SOR default values: \index{Default values! sor} 


{\small\begin{verbatim}
sturm : off
\end{verbatim}}


   The float value \textit{{\small\texttt{Number\_\-Of\_\-Points}}} specifies the number of 2-D vectors which follow. The points \textit{{\small\texttt{ 
 $<$Point\_\-1$>$}}} through \textit{{\small\texttt{$<$Point\_\-n$>$}}} are two-\discretionary{}{}{}dimensional vectors consisting of the radius and the corresponding height, \discretionary{i.}{}{i.}e. 
 the position on the rotation axis. These points are smoothly connected (the curve is passing through the specified points) and rotated about the y-\discretionary{}{}{}axis to 
 form the SOR object. The first and last points are only used to determine the slopes of the function at the start and end point. They do not actually lie on 
 the curve. The function used for the SOR object is similar to the splines used for the lathe object. The difference is that the SOR object is less flexible 
 because it underlies the restrictions of any mathematical function, \discretionary{i.}{}{i.}e. to any given point y on the rotation axis belongs at most one function value, \discretionary{i.}{}{i.}e. 
 one radius value. You cannot rotate closed curves with the SOR object. Also, make sure that the curve does not cross zero (y-\discretionary{}{}{}axis) as this can result in 'less 
 than perfect' bounding cylinders. POV-\discretionary{}{}{}Ray will very likely fail to render large chunks of the part of the spline contained in such an interval. 



   The optional keyword {\small\texttt{ open}} allows you to remove the caps on the SOR object. If you do this you should not use it with CSG because the 
 results may be wrong. 



   The SOR object is useful for creating bottles, vases, and things like that. A simple vase could look like this: 


{\small\begin{verbatim}
 #declare Vase = sor {
  7,
  <0.000000, 0.000000>
  <0.118143, 0.000000>
  <0.620253, 0.540084>
  <0.210970, 0.827004>
  <0.194093, 0.962025>
  <0.286920, 1.000000>
  <0.468354, 1.033755>
  open
 }
\end{verbatim}}


   One might ask why there is any need for a SOR object if there is already a lathe object which is much more flexible. The reason is quite simple. The 
 intersection test with a SOR object involves solving a cubic polynomial while the test with a lathe object requires to solve a 6th order polynomial (you need 
 a cubic spline for the same smoothness). Since most SOR and lathe objects will have several segments this will make a great difference in speed. The roots of 
 the 3rd order polynomial will also be more accurate and easier to find. 



   \index{sturm! sor} The {\small\texttt{sturm}} keyword may be added to specify the slower but more accurate Sturmian root solver. It may be used with the 
 surface of revolution object if the shape does not render properly. 



   The following explanations are for the mathematically interested reader who wants to know how the surface of revolution is calculated. Though it is not 
 necessary to read on it might help in understanding the SOR object. 



   The function that is rotated about the y-\discretionary{}{}{}axis to get the final SOR object is given by 



   
\begin{mathequ}
% sormath
% -------
\begin{displaymath}
  r^2 = f(h) = A\cdot h^3 + B\cdot h^2 + C\cdot h + D
\end{displaymath}

\caption{} \end{mathequ}
 



   with radius \textit{{\small\texttt{r}}} and height \textit{{\small\texttt{h}}}. Since this is a cubic function in h it has enough flexibility to allow smooth 
 curves. 



   The curve itself is defined by a set of n points P(i), i=0...n-1, which are interpolated using one function for every segment of the curve. A segment j, 
 j=1...n-3, goes from point P(j) to point P(j+1) and uses points P(j-1) and P(j+2) to determine the slopes at the endpoints. If there are n points we will have 
 n-3 segments. This means that we need at least four points to get a proper curve. The coefficients A(j), B(j), C(j) and D(j) are calculated for every segment 
 using the equation 



   
\begin{mathequ}
% FILE: curvmath
% --------
\begin{displaymath}
  \begin{array}{l}
    b = M \cdot x, \mathrm{with:}
    \\ \\
    b = \left[
      \begin{array}{c}
        r(j)^2 \\
        r(j+1)^2 \\
        2 \cdot r(j) \cdot (r(j+1)-r(j-1)) \\
        \hline
        h(j+1)-h(j-1) \\
        2 \cdot r(j+1) \cdot (r(j+2)-r(j)) \\
        \hline
        h(j+2)-h(j)
      \end{array}
    \right]
    \\ \\
    M = \left[
      \begin{array}{c c c c}
        h(j)^3 & h(j)^2 & h(j) & 1 \\
        h(j+1)^3 & h(j+1)^2 & h(j+1) & 1 \\
        3\cdot h(j)^2 & 2\cdot h(j) & 1 & 0 \\
        3\cdot h(j+1)^2 & 2\cdot h(j+1) & 1 & 0
      \end{array}
    \right]
    \\ \\
    x = \left[
      \begin{array}{c}
        A(j)\\ B(j)\\ C(j)\\ D(j)
      \end{array}
    \right]
  \end{array}
\end{displaymath}

\caption{} \end{mathequ}
 



   where r(j) is the radius and h(j) is the height of point P(j). 



   The figure below shows the configuration of the points P(i), the location of segment j, and the curve that is defined by this segment. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/segmpts} \caption{Points on a surface of revolution.} \end{figure} 


\subsection{Text}

% reference/000150.html

\index{text}\index{text! keyword}\index{Keyword! text}\index{ttf! text}\index{Keyword! ttf}\index{ttf}

   A {\small\texttt{text}} object creates 3-D text as an extruded block letter. Currently only TrueType fonts (ttf) and TrueType Collections (ttc) are supported 
 but the syntax allows for other font types to be added in the future. If TrueType Collections are used, the first font found in the collection will be used. 
 The syntax is: 


{\small\begin{verbatim}
TEXT_OBECT:
  text {
    ttf "fontname.ttf/ttc" "String_of_Text"
	Thickness, <Offset>
    [OBJECT_MODIFIERS...]
  }
\end{verbatim}}


   Where {\small\texttt{\discretionary{fontname.}{}{fontname.}ttf}} or {\small\texttt{\discretionary{fontname.}{}{fontname.}ttc}} is the name of the TrueType font file. It is a quoted string literal or string 
 expression. The string expression which follows is the actual text of the string object. It too may be a quoted string literal or string expression. See 
 section "Strings" for more on string expressions. 



   The text will start with the origin at the lower left, front of the first character and will extend in the +x-\discretionary{}{}{}direction. The baseline of the text follows the 
 x-\discretionary{}{}{}axis and descender drop into the -y-\discretionary{}{}{}direction. The front of the character sits in the x-\discretionary{}{}{}y-\discretionary{}{}{}plane and the text is extruded in the 
 +z-\discretionary{}{}{}direction. The front-\discretionary{}{}{}to-\discretionary{}{}{}back thickness is specified by the required value \textit{{\small\texttt{ Thickness}}}. 



   Characters are generally sized so that 1 unit of vertical spacing is correct. The characters are about 0.5 to 0.75 units tall. 



   The horizontal spacing is handled by POV-\discretionary{}{}{}Ray internally including any kerning information stored in the font. The required vector \textit{{\small\texttt{ 
 $<$Offset$>$}}} defines any extra translation between each character. Normally you should specify a zero for this value. Specifying {\small\texttt{0.1*x}} 
 would put additional 0.1 units of space between each character. Here is an example: 


{\small\begin{verbatim}
  text {
    ttf "timrom.ttf" "POV-Ray" 1, 0
    pigment { Red }
  }
\end{verbatim}}


   Only printable characters are allowed in text objects. Characters such as return, line feed, tabs, backspace etc. are not supported. 



   For easy access to your fonts, set the Library\_\-Path to the directory that contains your font collection. 


\subsection{Torus}

% reference/000151.html

\index{torus}\index{torus! keyword}\index{Keyword! torus}\index{sturm! torus}\index{Keyword! sturm}

   A {\small\texttt{torus}} is a 4th order quartic polynomial shape that looks like a donut or inner tube. Because this shape is so useful and quartics are 
 difficult to define, POV-\discretionary{}{}{}Ray lets you take a short-\discretionary{}{}{}cut and define a torus by: 


{\small\begin{verbatim}
TORUS:
    torus
    {
        Major, Minor
        [TORUS_MODIFIER...]
    }
TORUS_MODIFIER:
    sturm | OBJECT_MODIFIER
\end{verbatim}}


   Torus default values: \index{Default values! torus} 


{\small\begin{verbatim}
sturm : off
\end{verbatim}}


   where \textit{{\small\texttt{Major}}} is a float value giving the major radius and \textit{{\small\texttt{Minor}}} is a float specifying the minor radius. 
 The major radius extends from the center of the hole to the mid-\discretionary{}{}{}line of the rim while the minor radius is the radius of the cross-\discretionary{}{}{}section of the rim. The 
 torus is centered at the origin and lies in the x-\discretionary{}{}{}z-\discretionary{}{}{}plane with the y-\discretionary{}{}{}axis sticking through the hole. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/mimxrtor} \caption{Major and minor radius of a torus.} \end{figure} 



   The torus is internally bounded by two cylinders and two rings forming a thick cylinder. With this bounding cylinder the performance of the torus 
 intersection test is vastly increased. The test for a valid torus intersection, \discretionary{i.}{}{i.}e. solving a 4th order polynomial, is only performed if the bounding 
 cylinder is hit. Thus a lot of slow root solving calculations are avoided. 



   \index{sturm! torus} Calculations for all higher order polynomials must be very accurate. If the torus renders improperly you may add the keyword {\small\texttt{ 
 sturm}} to use POV-\discretionary{}{}{}Ray's slower-\discretionary{}{}{}yet-\discretionary{}{}{}more-\discretionary{}{}{}accurate Sturmian root solver. 


\section{Finite Patch Primitives}

% reference/000152.html



   There are six totally thin, finite objects which have no well-\discretionary{}{}{}defined inside. They are bicubic patch, disc, smooth triangle, triangle, polygon and mesh / 
 mesh2. They may be combined in CSG union but cannot be used in other types of CSG (or inside a {\small\texttt{clipped\_\-by}} statement). Because these types are 
 finite POV-\discretionary{}{}{}Ray can use automatic bounding on them to speed up rendering time. As with all shapes they can be translated, rotated and scaled. 


\subsection{Bicubic Patch}

% reference/000153.html

\index{bezier}\index{Bezier Patch}\index{bicubic\_\-patch}\index{bicubic\_\-patch! keyword}\index{Keyword! bicubic\_\-patch}\index{type! bicubic\_\-patch}\index{Keyword! type}\index{u\_\-steps! bicubic\_\-patch}\index{Keyword! u\_\-steps}\index{v\_\-steps! bicubic\_\-patch}\index{Keyword! v\_\-steps}\index{flatness! bicubic\_\-patch}\index{Keyword! flatness}

   A {\small\texttt{bicubic\_\-patch}} is a 3D curved surface created from a mesh of triangles. POV-\discretionary{}{}{}Ray supports a type of bicubic patch called a \textit{Bezier 
 patch}. A bicubic patch is defined as follows: 


{\small\begin{verbatim}
BICUBIC_PATCH:
    bicubic_patch
    {
        PATCH_ITEMS...
        <Point_1>,<Point_2>,<Point_3>,<Point_4>,
        <Point_5>,<Point_6>,<Point_7>,<Point_8>,
        <Point_9>,<Point_10>,<Point_11>,<Point_12>,
        <Point_13>,<Point_14>,<Point_15>,<Point_16>
        [OBJECT_MODIFIERS...]
    }
PATCH_ITEMS:
    type Patch_Type | u_steps Num_U_Steps | v_steps Num_V_Steps |
    flatness Flatness
\end{verbatim}}


   Bicubic patch default values: \index{Default values! bicubic\_\-patch} 


{\small\begin{verbatim}
flatness : 0.0
u_steps  : 0
v_steps  : 0
\end{verbatim}}
\index{type}

   The keyword {\small\texttt{type}} is followed by a float \textit{{\small\texttt{ Patch\_\-Type}}} which currently must be either 0 or 1. For type 0 only the 
 control points are retained within POV-\discretionary{}{}{}Ray. This means that a minimal amount of memory is needed but POV-\discretionary{}{}{}Ray will need to perform many extra calculations when 
 trying to render the patch. Type 1 preprocesses the patch into many subpatches. This results in a significant speedup in rendering at the cost of memory. 



   \index{flatness}\index{u\_\-steps}\index{v\_\-steps} The four parameters {\small\texttt{type}}, {\small\texttt{ flatness}}, {\small\texttt{ u\_\-steps}} and {\small\texttt{v\_\-steps}} 
 may appear in any order. Only {\small\texttt{type}} is required. They are followed by 16 vectors (4 rows of 4) that define the x, y, z coordinates of the 16 
 control points which define the patch. The patch touches the four corner points \textit{{\small\texttt{ $<$Point\_\-1$>$}}}, \textit{{\small\texttt{ 
 $<$Point\_\-4$>$}}}, \textit{ {\small\texttt{$<$Point\_\-13$>$}}} and \textit{ {\small\texttt{ $<$Point\_\-16$>$}}} while the other 12 points pull and stretch 
 the patch into shape. The Bezier surface is enclosed by the convex hull formed by the 16 control points, this is known as the \textit{convex hull property}. 



   The keywords {\small\texttt{u\_\-steps}} and {\small\texttt{v\_\-steps}} are each followed by integer values which tell how many rows and columns of triangles are 
 the minimum to use to create the surface, both default to 0. The maximum number of individual pieces of the patch that are tested by POV-\discretionary{}{}{}Ray can be calculated 
 from the following: \textit{pieces = 2\^{}u\_\-steps * 2\^{}v\_\-steps}. 



   This means that you really should keep {\small\texttt{u\_\-steps}} and {\small\texttt{ v\_\-steps}} under 4. Most patches look just fine with {\small\texttt{u\_\-steps 
 3}} and {\small\texttt{v\_\-steps 3}}, which translates to 64 subpatches (128 smooth triangles). 



   As POV-\discretionary{}{}{}Ray processes the Bezier patch it makes a test of the current piece of the patch to see if it is flat enough to just pretend it is a rectangle. The 
 statement that controls this test is specified with the {\small\texttt{ flatness}} keyword followed by a float. Typical flatness values range from 0 to 1 (the 
 lower the slower). The default if none is specified is 0.0. 



   If the value for flatness is 0 POV-\discretionary{}{}{}Ray will always subdivide the patch to the extend specified by {\small\texttt{u\_\-steps}} and {\small\texttt{v\_\-steps}}. If 
 flatness is greater than 0 then every time the patch is split, POV-\discretionary{}{}{}Ray will check to see if there is any need to split further. 



   There are both advantages and disadvantages to using a non-\discretionary{}{}{}zero flatness. The advantages include: 



   - If the patch is not very curved, then this will be detected and POV-\discretionary{}{}{}Ray will not waste a lot of time looking at the wrong pieces. 



   - If the patch is only highly curved in a couple of places, POV-\discretionary{}{}{}Ray will keep subdividing there and concentrate its efforts on the hard part. 



   The biggest disadvantage is that if POV-\discretionary{}{}{}Ray stops subdividing at a particular level on one part of the patch and at a different level on an adjacent part of 
 the patch there is the potential for cracking. This is typically visible as spots within the patch where you can see through. How bad this appears depends 
 very highly on the angle at which you are viewing the patch. 



   Like triangles, the bicubic patch is not meant to be generated by hand. These shapes should be created by a special utility. You may be able to acquire 
 utilities to generate these shapes from the same source from which you obtained POV-\discretionary{}{}{}Ray. Here is an example: 


{\small\begin{verbatim}
  bicubic_patch {
    type 0
    flatness 0.01
    u_steps 4
    v_steps 4
    <0, 0, 2>, <1, 0, 0>, <2, 0, 0>, <3, 0,-2>,
    <0, 1  0>, <1, 1, 0>, <2, 1, 0>, <3, 1, 0>,
    <0, 2, 0>, <1, 2, 0>, <2, 2, 0>, <3, 2, 0>,
    <0, 3, 2>, <1, 3, 0>, <2, 3, 0>, <3, 3, -2>
  }
\end{verbatim}}


   The triangles in a POV-\discretionary{}{}{}Ray {\small\texttt{bicubic\_\-patch}} are automatically smoothed using normal interpolation but it is up to the user (or the user's 
 utility program) to create control points which smoothly stitch together groups of patches. 


\subsection{Disc}

% reference/000154.html

\index{disc}\index{disc! keyword}\index{Keyword! disc}

   Another flat, finite object available with POV-\discretionary{}{}{}Ray is the {\small\texttt{ disc}}. The disc is infinitely thin, it has no thickness. If you want a disc with 
 true thickness you should use a very short cylinder. A disc shape may be defined by: 


{\small\begin{verbatim}
DISC:
    disc
    {
        <Center>, <Normal>, Radius [, Hole_Radius]
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   Disc default values: \index{Default values! disc} 


{\small\begin{verbatim}
HOLE RADIUS : 0.0
\end{verbatim}}


   The vector \textit{{\small\texttt{$<$Center$>$}}} defines the x, y, z coordinates of the center of the disc. The \textit{{\small\texttt{ $<$Normal$>$}}} 
 vector describes its orientation by describing its surface normal vector. This is followed by a float specifying the \textit{ {\small\texttt{ Radius}}}. This 
 may be optionally followed by another float specifying the radius of a hole to be cut from the center of the disc. 



   \textbf{Note:} The inside of a disc is the inside of the plane that contains the disc. Also note that it is not constrained by the radius of the disc. 


\subsection{Mesh}

% reference/000155.html

\index{mesh}\index{mesh! keyword}\index{Keyword! mesh}\index{uv\_\-vectors! mesh}\index{Keyword! uv\_\-vectors}\index{texture\_\-list! mesh}\index{Keyword! texture\_\-list}\index{inside\_\-vector! mesh}\index{Keyword! inside\_\-vector}\index{triangle! mesh}\index{Keyword! triangle}\index{smooth\_\-triangle! mesh}\index{Keyword! smooth\_\-triangle}\index{hierarchy! mesh}\index{Keyword! hierarchy}

   The {\small\texttt{mesh}} object can be used to efficiently store large numbers of triangles. Its syntax is: 


{\small\begin{verbatim}
MESH:
    mesh
    {
        MESH_TRIANGLE...
        [MESH_MODIFIER...]
    }
MESH_TRIANGLE:
    triangle
    {
        <Corner_1>, <Corner_2>, <Corner_3>
        [uv_vectors <uv_Corner_1>, <uv_Corner_2>, <uv_Corner_3>]
        [MESH_TEXTURE]
    } |
    smooth_triangle
    {
        <Corner_1>, <Normal_1>,
        <Corner_2>, <Normal_2>,
        <Corner_3>, <Normal_3>
        [uv_vectors <uv_Corner_1>, <uv_Corner_2>, <uv_Corner_3>]
        [MESH_TEXTURE]
    }
MESH_TEXTURE:
  texture { TEXTURE_IDENTIFIER }
  texture_list {
    TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER
  }

MESH_MODIFIER:
    inside_vector <direction> | hierarchy [ Boolean ] |
    OBJECT_MODIFIER
\end{verbatim}}


   Mesh default values: \index{Default values! mesh} 


{\small\begin{verbatim}
hierarchy : on
\end{verbatim}}


   Any number of {\small\texttt{triangle}} and/or {\small\texttt{smooth\_\-triangle}} statements can be used and each of those triangles can be individually 
 textured by assigning a texture identifier to it. The texture has to be declared before the mesh is parsed. It is not possible to use texture definitions 
 inside the triangle or smooth triangle statements. This is a restriction that is necessary for an efficient storage of the assigned textures. See "Triangle 
 and Smooth Triangle" for more information on triangles. 



   The {\small\texttt{mesh}} object can support {\small\texttt{uv\_\-mapping}}. For this, per triangle the keyword {\small\texttt{uv\_\-vectors}} has to be given, 
 together with three 2D uv-\discretionary{}{}{}vectors. Each vector specifies a location in the xy-\discretionary{}{}{}plane from which the texture has to be mapped to the matching points of the 
 triangle. Also see the section uv\_\-mapping. 



   \index{hierarchy! mesh} The mesh's components are internally bounded by a bounding box hierarchy to speed up intersection testing. The bounding hierarchy can 
 be turned off with the {\small\texttt{hierarchy off}} keyword. This should only be done if memory is short or the mesh consists of only a few triangles. The 
 default is {\small\texttt{hierarchy on}}. 



   Copies of a mesh object refer to the same triangle data and thus consume very little memory. You can easily trace a hundred copies of a 10000 triangle mesh 
 without running out of memory (assuming the first mesh fits into memory). The mesh object has two advantages over a union of triangles: it needs less memory 
 and it is transformed faster. The memory requirements are reduced by efficiently storing the triangles vertices and normals. The parsing time for transformed 
 meshes is reduced because only the mesh object has to be transformed and not every single triangle as it is necessary for unions. 



   The mesh object can currently only include triangle and smooth triangle components. That restriction may change, allowing polygonal components, at some point 
 in the future. 


\subsubsection{Solid Mesh}

% reference/000156.html

\index{inside\_\-vector}\index{solid triangle mesh}

   Triangle mesh objects ({\small\texttt{mesh}} and {\small\texttt{mesh2}}) can now be used in CSG objects such as difference and intersect, because, after 
 adding {\small\texttt{inside\_\-vector}}, they do have a defined 'inside'. This will only work for well-\discretionary{}{}{}behaved meshes, which are completely closed volumes. If 
 meshes have any holes in them, this might work, but the results are not guaranteed. 



   To determine if a point is inside a triangle mesh, POV-\discretionary{}{}{}Ray shoots a ray from the point in some arbitrary direction. If this vector intersects an odd number 
 of triangles, the point is inside the mesh. If it intersects an even number of triangles, the point is outside of the mesh. You can specify the direction of 
 this vector. For example, to use {\small\texttt{+z}} as the direction, you would add the following line to the triangle mesh description (following all other 
 mesh data, but before the object modifiers). 


{\small\begin{verbatim}
  inside_vector <0, 0, 1>
\end{verbatim}}


   This change does not have any effect on unions of triangles... these will still be always hollow. 


\subsection{Mesh2}

% reference/000157.html

\index{vertex\_\-vectors}\index{normal\_\-vectors}\index{uv\_\-vectors}\index{face\_\-indices}\index{normal\_\-indices}\index{uv\_\-indices}\index{texture-\discretionary{}{}{}list}\index{mesh2}\index{mesh2! keyword}\index{Keyword! mesh2}\index{vertex\_\-vectors! mesh2}\index{Keyword! vertex\_\-vectors}\index{normal\_\-vectors! mesh2}\index{Keyword! normal\_\-vectors}\index{uv\_\-vectors! mesh2}\index{Keyword! uv\_\-vectors}\index{texture\_\-list! mesh2}\index{Keyword! texture\_\-list}\index{face\_\-indices! mesh2}\index{Keyword! face\_\-indices}\index{normal\_\-indices! mesh2}\index{Keyword! normal\_\-indices}\index{uv\_\-indices! mesh2}\index{Keyword! uv\_\-indices}\index{inside\_\-vector! mesh2}\index{Keyword! inside\_\-vector}

   The new mesh syntax is designed for use in conversion from other file formats. 


{\small\begin{verbatim}
  MESH2 :
      mesh2{
        VECTORS...
        LISTS...   |
        INDICES... |
        MESH_MODIFIERS
      }
  VECTORS :
      vertex_vectors 
      {
        number_of_vertices,
        <vertex1>, <vertex2>, ...
      }|
      normal_vectors 
      {
        number_of_normals,
        <normal1>, <normal2>, ...
      }|
      uv_vectors 
      {
        number_of_uv_vectors,
        <uv_vect1>, <uv_vect2>, ...
      }
  LISTS :
      texture_list 
      {
        number_of_textures,
        texture { Texture1 },
        texture { Texture2 }, ...
      }|
  INDICES :
      face_indices 
      {
        number_of_faces,
        <index_a, index_b, index_c> [,texture_index [,
                                    texture_index, texture_index]],
        <index_d, index_e, index_f> [,texture_index [,
                                    texture_index, texture_index]],
        ...
      }|
      normal_indices 
      {
        number_of_faces,
        <index_a, index_b, index_c>,
        <index_d, index_e, index_f>,
        ...
      }|
      uv_indices {
        number_of_faces,
        <index_a, index_b, index_c>,
        <index_d, index_e, index_f>,
        ...
      }
  MESH_MODIFIER :
      inside_vector <direction> | OBJECT_MODIFIERS
\end{verbatim}}


   {\small\texttt{mesh2}} has to be specified in the order \textit{VECTORS...}, \textit{LISTS...}, \textit{INDICES...}. The {\small\texttt{normal\_\-vectors}}, {\small\texttt{uv\_\-vectors}}, 
 and {\small\texttt{texture\_\-list}} sections are optional. If the number of normals equals the number of vertices then the normal\_\-indices section is optional 
 and the indexes from the {\small\texttt{face\_\-indices}} section are used instead. Likewise for the {\small\texttt{uv\_\-indices}} section. 



   \textbf{Note:} that the numbers of uv\_\-indices must equal number of faces. 



   The indexes are ZERO-\discretionary{}{}{}BASED! So the first item in each list has an index of zero. 


\subsubsection{Smooth and Flat triangles in the same mesh}

% reference/000158.html



   You can specify both flat and smooth triangles in the same mesh. To do this, specify the smooth triangles first in the {\small\texttt{face\_\-indices}} section, 
 followed by the flat triangles. Then, specify normal indices (in the {\small\texttt{normal\_\-indices}} section) for only the smooth triangles. Any remaining 
 triangles that do not have normal indices associated with them will be assumed to be flat triangles. 


\subsubsection{Mesh Triangle Textures}

% reference/000159.html



   To specify a texture for an individual mesh triangle, specify a single integer texture index following the face-\discretionary{}{}{}index vector for that triangle. 



   To specify three textures for vertex-\discretionary{}{}{}texture interpolation, specify three integer texture indices (separated by commas) following the face-\discretionary{}{}{}index vector for 
 that triangle. 



   Vertex-\discretionary{}{}{}texture interpolation and textures for an individual triangle can be mixed in the same mesh 


\subsection{Polygon}

% reference/000160.html

\index{polygon}\index{polygon! keyword}\index{Keyword! polygon}

   The {\small\texttt{polygon}} object is useful for creating rectangles, squares and other planar shapes with more than three edges. Their syntax is: 


{\small\begin{verbatim}
POLYGON:
    polygon
    {
        Number_Of_Points, <Point_1> <Point_2>... <Point_n>
        [OBJECT_MODIFIER...]
    }
\end{verbatim}}


   The float \textit{{\small\texttt{Number\_\-Of\_\-Points}}} tells how many points are used to define the polygon. The points \textit{{\small\texttt{ $<$Point\_\-1$>$}}} 
 through \textit{{\small\texttt{$<$Point\_\-n$>$}}} describe the polygon or polygons. A polygon can contain any number of sub-\discretionary{}{}{}polygons, either overlapping or 
 not. In places where an even number of polygons overlaps a hole appears. When you repeat the first point of a sub-\discretionary{}{}{}polygon, it closes it and starts a new 
 sub-\discretionary{}{}{}polygon's point sequence. This means that all points of a sub-\discretionary{}{}{}polygon are different. 



   If the last sub-\discretionary{}{}{}polygon is not closed a warning is issued and the program automatically closes the polygon. This is useful because polygons imported from 
 other programs may not be closed, \discretionary{i.}{}{i.}e. their first and last point are not the same. 



   All points of a polygon are three-\discretionary{}{}{}dimensional vectors that have to lay on the same plane. If this is not the case an error occurs. It is common to use 
 two-\discretionary{}{}{}dimensional vectors to describe the polygon. POV-\discretionary{}{}{}Ray assumes that the z value is zero in this case. 



   A square polygon that matches the default planar image map is simply: 


{\small\begin{verbatim}
  polygon {
    4,
    <0, 0>, <0, 1>, <1, 1>, <1, 0>
    texture {
      finish { ambient 1 diffuse 0 }
      pigment { image_map { gif "test.gif"  } }
    }
    //scale and rotate as needed here
  }
\end{verbatim}}


   The sub-\discretionary{}{}{}polygon feature can be used to generate complex shapes like the letter "P", where a hole is cut into another polygon: 


{\small\begin{verbatim}
  #declare P = polygon {
    12,
    <0, 0>, <0, 6>, <4, 6>, <4, 3>, <1, 3>, <1,0>, <0, 0>, 
    <1, 4>, <1, 5>, <3, 5>, <3, 4>, <1, 4>
  }
\end{verbatim}}


   The first sub-\discretionary{}{}{}polygon (on the first line) describes the outer shape of the letter "P". The second sub-\discretionary{}{}{}polygon (on the second line) describes the 
 rectangular hole that is cut in the top of the letter "P". Both rectangles are closed, \discretionary{i.}{}{i.}e. their first and last points are the same. 



   The feature of cutting holes into a polygon is based on the polygon inside/outside test used. A point is considered to be inside a polygon if a straight line 
 drawn from this point in an arbitrary direction crosses an odd number of edges (this is known as \textit{Jordan's curve theorem}). 



   Another very complex example showing one large triangle with three small holes and three separate, small triangles is given below: 


{\small\begin{verbatim}
  polygon {
    28,
    <0, 0> <1, 0> <0, 1> <0, 0>          // large outer triangle
    <.3, .7> <.4, .7> <.3, .8> <.3, .7>  // small outer triangle #1
    <.5, .5> <.6, .5> <.5, .6> <.5, .5>  // small outer triangle #2
    <.7, .3> <.8, .3> <.7, .4> <.7, .3>  // small outer triangle #3
    <.5, .2> <.6, .2> <.5, .3> <.5, .2>  // inner triangle #1
    <.2, .5> <.3, .5> <.2, .6> <.2, .5>  // inner triangle #2
    <.1, .1> <.2, .1> <.1, .2> <.1, .1>  // inner triangle #3
  }
\end{verbatim}}

\subsection{Triangle and Smooth Triangle}

% reference/000161.html

\index{triangle}\index{triangle! keyword}\index{Keyword! triangle}

   The {\small\texttt{triangle}} primitive is available in order to make more complex objects than the built-\discretionary{}{}{}in shapes will permit. Triangles are usually not 
 created by hand but are converted from other files or generated by utilities. A triangle is defined by 


{\small\begin{verbatim}
TRIANGLE:
    triangle
    {
        <Corner_1>, <Corner_2>, <Corner_3>
        [OBJECT_MODIFIER...]
    }
\end{verbatim}}


   where \textit{{\small\texttt{$<$Corner\_\-n$>$}}} is a vector defining the x, y, z coordinates of each corner of the triangle. 



   Because triangles are perfectly flat surfaces it would require extremely large numbers of very small triangles to approximate a smooth, curved surface. 
 However much of our perception of smooth surfaces is dependent upon the way light and shading is done. By artificially modifying the surface normals we can 
 simulate a smooth surface and hide the sharp-\discretionary{}{}{}edged seams between individual triangles. 



   \index{smooth\_\-triangle}\index{smooth\_\-triangle! keyword} \index{Keyword! smooth\_\-triangle} The {\small\texttt{smooth\_\-triangle}} primitive is used for 
 just such purposes. The smooth triangles use a formula called Phong normal interpolation to calculate the surface normal for any point on the triangle based 
 on normal vectors which you define for the three corners. This makes the triangle appear to be a smooth curved surface. A smooth triangle is defined by 


{\small\begin{verbatim}
SMOOTH_TRIANGLE:
    smooth_triangle
    {
        <Corner_1>, <Normal_1>, <Corner_2>,
        <Normal_2>, <Corner_3>, <Normal_3>
        [OBJECT_MODIFIER...]
    }
\end{verbatim}}


   where the corners are defined as in regular triangles and \textit{{\small\texttt{ $<$Normal\_\-n$>$}}} is a vector describing the direction of the surface 
 normal at each corner. 



   These normal vectors are prohibitively difficult to compute by hand. Therefore smooth triangles are almost always generated by utility programs. To achieve 
 smooth results, any triangles which share a common vertex should have the same normal vector at that vertex. Generally the smoothed normal should be the 
 average of all the actual normals of the triangles which share that point. 



   The {\small\texttt{ mesh}} object is a way to combine many {\small\texttt{triangle}} and {\small\texttt{smooth\_\-triangle}} objects together in a very 
 efficient way. See "Mesh" for details. 


\section{Infinite Solid Primitives}

% reference/000162.html



   There are five polynomial primitive shapes that are possibly infinite and do not respond to automatic bounding. They are plane, cubic, poly, quadric and 
 quartic. They do have a well defined inside and may be used in CSG and inside a {\small\texttt{clipped\_\-by}} statement. As with all shapes they can be 
 translated, rotated and scaled. 


\subsection{Plane}

% reference/000163.html

\index{plane}\index{plane! keyword}\index{Keyword! plane}

   The {\small\texttt{plane}} primitive is a simple way to define an infinite flat surface. The plane is not a thin boundary or can be compared to a sheet of 
 paper. A plane is a solid object of infinite size that divides POV-\discretionary{}{}{}space in two parts, inside and outside the plane. The plane is specified as follows: 


{\small\begin{verbatim}
PLANE:
    plane
    {
        <Normal>, Distance
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   The \textit{{\small\texttt{$<$Normal$>$}}} vector defines the surface normal of the plane. A surface normal is a vector which points up from the surface at 
 a 90 degree angle. This is followed by a float value that gives the distance along the normal that the plane is from the origin (that is only true if the 
 normal vector has unit length; see below). For example: 


{\small\begin{verbatim}
  plane { <0, 1, 0>, 4 }
\end{verbatim}}


   This is a plane where straight up is defined in the positive y-\discretionary{}{}{}direction. The plane is 4 units in that direction away from the origin. Because most planes 
 are defined with surface normals in the direction of an axis you will often see planes defined using the {\small\texttt{x}}, {\small\texttt{ y}} or {\small\texttt{ 
 z}} built-\discretionary{}{}{}in vector identifiers. The example above could be specified as: 


{\small\begin{verbatim}
  plane { y, 4 }
\end{verbatim}}


   The plane extends infinitely in the x- and z-\discretionary{}{}{}directions. It effectively divides the world into two pieces. By definition the normal vector points to the 
 outside of the plane while any points away from the vector are defined as inside. This inside/outside distinction is important when using planes in CSG and {\small\texttt{clipped\_\-by}}. 
 It is also important when using fog or atmospheric media. If you place a camera on the "inside" half of the world, then the fog or media will not 
 appear. Such issues arise in any solid object but it is more common with planes. Users typically know when they have accidentally placed a camera inside a 
 sphere or box but "inside a plane" is an unusual concept. In general you can reverse the inside/outside properties of an object by adding the object 
 modifier {\small\texttt{ inverse}}. See "Inverse" and "Empty and Solid Objects" for details. 



   A plane is called a \textit{polynomial} shape because it is defined by a first order polynomial equation. Given a plane: 


{\small\begin{verbatim}
  plane { <A, B, C>, D }
\end{verbatim}}


   it can be represented by the equation\textit{{\small\texttt{ A*x + B*y + C*z - D*sqrt(A\^{}2 + B\^{}2 + C\^{}2) = 0}}}. 



   Therefore our example {\small\texttt{ plane\{\discretionary{y,}{}{y,}4\}}} is actually the polynomial equation y=4. You can think of this as a set of all x, y, z points where all 
 have y values equal to 4, regardless of the x or z values. 



   This equation is a first order polynomial because each term contains only single powers of x, y or z. A second order equation has terms like x\^{}2, y\^{}2, z\^{}2, 
 xy, xz and yz. Another name for a 2nd order equation is a quadric equation. Third order polys are called cubics. A 4th order equation is a quartic. Such 
 shapes are described in the sections below. 


\subsection{Poly, Cubic and Quartic}

% reference/000164.html

\index{poly}\index{poly! keyword}\index{Keyword! poly}\index{sturm! poly}\index{Keyword! sturm}

   Higher order polynomial surfaces may be defined by the use of a {\small\texttt{ poly}} shape. The syntax is 


{\small\begin{verbatim}
POLY:
    poly
    {
        Order, <A1, A2, A3,... An>
        [POLY_MODIFIERS...]
    }
POLY_MODIFIERS:
    sturm | OBJECT_MODIFIER
\end{verbatim}}


   Poly default values: \index{Default values! poly} 


{\small\begin{verbatim}
sturm : off
\end{verbatim}}


   where \textit{{\small\texttt{Order}}} is an integer number from 2 to 15 inclusively that specifies the order of the equation. \textit{{\small\texttt{A1, A2, 
 ... An}}} are float values for the coefficients of the equation. There are \textit{{\small\texttt{n}}} such terms where \textit{{\small\texttt{ n = 
 ((Order+1)*(Order+2)*(Order+3))/6.}}}\index{cubic}\index{cubic! keyword}\index{Keyword! cubic} 



   The {\small\texttt{cubic}} object is an alternate way to specify 3rd order polys. Its syntax is: 


{\small\begin{verbatim}
CUBIC:
    cubic
    {
        <A1, A2, A3,... A20>
        [POLY_MODIFIERS...]
    }
\end{verbatim}}
\index{quartic}\index{quartic! keyword}\index{Keyword! quartic}

   Also 4th order equations may be specified with the {\small\texttt{quartic}} object. Its syntax is: 


{\small\begin{verbatim}
QUARTIC:
    quartic
    {
        <A1, A2, A3,... A35>
        [POLY_MODIFIERS...]
    }
\end{verbatim}}


   The following table shows which polynomial terms correspond to which \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z factors for the orders 2 to 7. Remember {\small\texttt{cubic}} is actually a 3rd 
 order polynomial and {\small\texttt{quartic}} is 4th order. 


\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{20pt}@{} p{20pt}@{} p{24pt}@{} p{28pt}@{} p{32pt}@{} p{36pt}@{} p{40pt}@{} p{24pt}@{} p{32pt}@{} p{36pt}@{} p{40pt}@{} p{24pt}@{} p{20pt}@{} p{20pt}@{} }
 
 
  {\raggedleft  } & {\raggedleft 2$^{nd}$} & {\raggedleft 3$^{rd}$} & {\raggedleft 4$^{th}$} & {\raggedleft 5$^{th}$} & {\raggedleft 6$^{th}$} & {\raggedleft 7$^{th}$} & {\raggedleft  
  } & {\raggedleft 5$^{th}$} & {\raggedleft 6$^{th}$} & {\raggedleft 7$^{th}$} & {\raggedleft  } & {\raggedleft 6$^{th}$} & 7$^{th}$ \\ \hline 
 

 
  
  {\raggedleft 
    A$_{1}$ 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$ 
  } & 

  {\raggedleft 
    x$^{5}$ 
  } & 

  {\raggedleft 
    x$^{6}$ 
  } & 

  {\raggedleft 
    x$^{7}$ 
  } & 

  {\raggedleft 
    A$_{41}$ 
  } & 

  {\raggedleft 
    y$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$ 
  } & 

  {\raggedleft 
    A$_{81}$ 
  } & 

  {\raggedleft 
    z$^{3}$ 
  } & 
{\raggedleft  xz$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{2}$ 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    x$^{2}$y 
  } & 

  {\raggedleft 
    x$^{3}$y 
  } & 

  {\raggedleft 
    x$^{4}$y 
  } & 

  {\raggedleft 
    x$^{5}$y 
  } & 

  {\raggedleft 
    x$^{6}$y 
  } & 

  {\raggedleft 
    A$_{42}$ 
  } & 

  {\raggedleft 
    y$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{82}$ 
  } & 

  {\raggedleft 
    z$^{2}$ 
  } & 
{\raggedleft  xz$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{3}$ 
  } & 

  {\raggedleft 
    xz 
  } & 

  {\raggedleft 
    x$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$z 
  } & 

  {\raggedleft 
    x$^{4}$z 
  } & 

  {\raggedleft 
    x$^{5}$z 
  } & 

  {\raggedleft 
    x$^{6}$z 
  } & 

  {\raggedleft 
    A$_{43}$ 
  } & 

  {\raggedleft 
    y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{83}$ 
  } & 

  {\raggedleft 
    z 
  } & 
{\raggedleft  xz } \\ 
 

 
  
  {\raggedleft 
    A$_{4}$ 
  } & 

  {\raggedleft 
    x 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$ 
  } & 

  {\raggedleft 
    x$^{5}$ 
  } & 

  {\raggedleft 
    x$^{6}$ 
  } & 

  {\raggedleft 
    A$_{44}$ 
  } & 

  {\raggedleft 
    y$^{2}$z 
  } & 

  {\raggedleft 
    xy$^{2}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z 
  } & 

  {\raggedleft 
    A$_{84}$ 
  } & 

  {\raggedleft 
    1 
  } & 
{\raggedleft  x } \\ 
 

 
  
  {\raggedleft 
    A$_{5}$ 
  } & 

  {\raggedleft 
    y$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{4}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{5}$y$^{2}$ 
  } & 

  {\raggedleft 
    A$_{45}$ 
  } & 

  {\raggedleft 
    y$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$ 
  } & 

  {\raggedleft 
    A$_{85}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{7}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{6}$ 
  } & 

  {\raggedleft 
    yz 
  } & 

  {\raggedleft 
    xyz 
  } & 

  {\raggedleft 
    x$^{2}$yz 
  } & 

  {\raggedleft 
    x$^{3}$yz 
  } & 

  {\raggedleft 
    x$^{4}$yz 
  } & 

  {\raggedleft 
    x$^{5}$yz 
  } & 

  {\raggedleft 
    A$_{46}$ 
  } & 

  {\raggedleft 
    yz$^{4}$ 
  } & 

  {\raggedleft 
    xyz$^{4}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{4}$ 
  } & 

  {\raggedleft 
    A$_{86}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{6}$z } \\ 
 

 
  
  {\raggedleft 
    A$_{7}$ 
  } & 

  {\raggedleft 
    y 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    x$^{2}$y 
  } & 

  {\raggedleft 
    x$^{3}$y 
  } & 

  {\raggedleft 
    x$^{4}$y 
  } & 

  {\raggedleft 
    x$^{5}$y 
  } & 

  {\raggedleft 
    A$_{47}$ 
  } & 

  {\raggedleft 
    yz$^{3}$ 
  } & 

  {\raggedleft 
    xyz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{3}$ 
  } & 

  {\raggedleft 
    A$_{87}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{6}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{8}$ 
  } & 

  {\raggedleft 
    z$^{2}$ 
  } & 

  {\raggedleft 
    xz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{4}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{5}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{48}$ 
  } & 

  {\raggedleft 
    yz$^{2}$ 
  } & 

  {\raggedleft 
    xyz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{2}$ 
  } & 

  {\raggedleft 
    A$_{88}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{5}$z$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{9}$ 
  } & 

  {\raggedleft 
    z 
  } & 

  {\raggedleft 
    xz 
  } & 

  {\raggedleft 
    x$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$z 
  } & 

  {\raggedleft 
    x$^{4}$z 
  } & 

  {\raggedleft 
    x$^{5}$z 
  } & 

  {\raggedleft 
    A$_{49}$ 
  } & 

  {\raggedleft 
    yz 
  } & 

  {\raggedleft 
    xyz 
  } & 

  {\raggedleft 
    x$^{2}$yz 
  } & 

  {\raggedleft 
    A$_{89}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{5}$z } \\ 
 

 
  
  {\raggedleft 
    A$_{10}$ 
  } & 

  {\raggedleft 
    1 
  } & 

  {\raggedleft 
    x 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$ 
  } & 

  {\raggedleft 
    x$^{5}$ 
  } & 

  {\raggedleft 
    A$_{50}$ 
  } & 

  {\raggedleft 
    y 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    x$^{2}$y 
  } & 

  {\raggedleft 
    A$_{90}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{5}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{11}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$y$^{3}$ 
  } & 

  {\raggedleft 
    A$_{51}$ 
  } & 

  {\raggedleft 
    z$^{5}$ 
  } & 

  {\raggedleft 
    xz$^{5}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{5}$ 
  } & 

  {\raggedleft 
    A$_{91}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{4}$z$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{12}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z 
  } & 

  {\raggedleft 
    xy$^{2}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$z 
  } & 

  {\raggedleft 
    x$^{4}$y$^{2}$z 
  } & 

  {\raggedleft 
    A$_{52}$ 
  } & 

  {\raggedleft 
    z$^{4}$ 
  } & 

  {\raggedleft 
    xz$^{4}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{4}$ 
  } & 

  {\raggedleft 
    A$_{92}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{4}$z$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{13}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{4}$y$^{2}$ 
  } & 

  {\raggedleft 
    A$_{53}$ 
  } & 

  {\raggedleft 
    z$^{3}$ 
  } & 

  {\raggedleft 
    xz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{93}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{4}$z } \\ 
 

 
  
  {\raggedleft 
    A$_{14}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{2}$ 
  } & 

  {\raggedleft 
    xyz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$yz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{4}$yz$^{2}$ 
  } & 

  {\raggedleft 
    A$_{54}$ 
  } & 

  {\raggedleft 
    z$^{2}$ 
  } & 

  {\raggedleft 
    xz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{94}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{4}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{15}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz 
  } & 

  {\raggedleft 
    xyz 
  } & 

  {\raggedleft 
    x$^{2}$yz 
  } & 

  {\raggedleft 
    x$^{3}$yz 
  } & 

  {\raggedleft 
    x$^{4}$yz 
  } & 

  {\raggedleft 
    A$_{55}$ 
  } & 

  {\raggedleft 
    z 
  } & 

  {\raggedleft 
    xz 
  } & 

  {\raggedleft 
    x$^{2}$z 
  } & 

  {\raggedleft 
    A$_{95}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{3}$z$^{4}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{16}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    x$^{2}$y 
  } & 

  {\raggedleft 
    x$^{3}$y 
  } & 

  {\raggedleft 
    x$^{4}$y 
  } & 

  {\raggedleft 
    A$_{56}$ 
  } & 

  {\raggedleft 
    1 
  } & 

  {\raggedleft 
    x 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    A$_{96}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{3}$z$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{17}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{3}$ 
  } & 

  {\raggedleft 
    xz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{57}$ 
  } & 

  {\raggedleft 
      
  } & 

  {\raggedleft 
    y$^{6}$ 
  } & 

  {\raggedleft 
    xy$^{6}$ 
  } & 

  {\raggedleft 
    A$_{97}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{3}$z$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{18}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{2}$ 
  } & 

  {\raggedleft 
    xz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{4}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{58}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{5}$z 
  } & 

  {\raggedleft 
    xy$^{5}$z 
  } & 

  {\raggedleft 
    A$_{98}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{3}$z } \\ 
 

 
  
  {\raggedleft 
    A$_{19}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z 
  } & 

  {\raggedleft 
    xz 
  } & 

  {\raggedleft 
    x$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$z 
  } & 

  {\raggedleft 
    x$^{4}$z 
  } & 

  {\raggedleft 
    A$_{59}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{5}$ 
  } & 

  {\raggedleft 
    xy$^{5}$ 
  } & 

  {\raggedleft 
    A$_{99}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{20}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    1 
  } & 

  {\raggedleft 
    x 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$ 
  } & 

  {\raggedleft 
    x$^{4}$ 
  } & 

  {\raggedleft 
    A$_{60}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{4}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{100}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$z$^{5}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{21}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$ 
  } & 

  {\raggedleft 
    xy$^{4}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{4}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{4}$ 
  } & 

  {\raggedleft 
    A$_{61}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$z 
  } & 

  {\raggedleft 
    xy$^{4}$z 
  } & 

  {\raggedleft 
    A$_{101}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$z$^{4}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{22}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z 
  } & 

  {\raggedleft 
    xy$^{3}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$z 
  } & 

  {\raggedleft 
    x$^{3}$y$^{3}$z 
  } & 

  {\raggedleft 
    A$_{62}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$ 
  } & 

  {\raggedleft 
    xy$^{4}$ 
  } & 

  {\raggedleft 
    A$_{102}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$z$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{23}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{3}$ 
  } & 

  {\raggedleft 
    A$_{63}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{3}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{103}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$z$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{24}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{64}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{104}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$z } \\ 
 

 
  
  {\raggedleft 
    A$_{25}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z 
  } & 

  {\raggedleft 
    xy$^{2}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$z 
  } & 

  {\raggedleft 
    A$_{65}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z 
  } & 

  {\raggedleft 
    xy$^{3}$z 
  } & 

  {\raggedleft 
    A$_{105}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{26}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$y$^{2}$ 
  } & 

  {\raggedleft 
    A$_{66}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{3}$ 
  } & 

  {\raggedleft 
    A$_{106}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz$^{6}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{27}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{3}$ 
  } & 

  {\raggedleft 
    xyz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{3}$yz$^{3}$ 
  } & 

  {\raggedleft 
    A$_{67}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z$^{4}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{4}$ 
  } & 

  {\raggedleft 
    A$_{107}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz$^{5}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{28}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{2}$ 
  } & 

  {\raggedleft 
    xyz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$yz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$yz$^{2}$ 
  } & 

  {\raggedleft 
    A$_{68}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{108}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz$^{4}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{29}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz 
  } & 

  {\raggedleft 
    xyz 
  } & 

  {\raggedleft 
    x$^{2}$yz 
  } & 

  {\raggedleft 
    x$^{3}$yz 
  } & 

  {\raggedleft 
    A$_{69}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{109}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{30}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    x$^{2}$y 
  } & 

  {\raggedleft 
    x$^{3}$y 
  } & 

  {\raggedleft 
    A$_{70}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$z 
  } & 

  {\raggedleft 
    xy$^{2}$z 
  } & 

  {\raggedleft 
    A$_{110}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{31}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{4}$ 
  } & 

  {\raggedleft 
    xz$^{4}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{4}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{4}$ 
  } & 

  {\raggedleft 
    A$_{71}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{2}$ 
  } & 

  {\raggedleft 
    A$_{111}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  yz } \\ 
 

 
  
  {\raggedleft 
    A$_{32}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{3}$ 
  } & 

  {\raggedleft 
    xz$^{3}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{3}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{3}$ 
  } & 

  {\raggedleft 
    A$_{72}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{5}$ 
  } & 

  {\raggedleft 
    xyz$^{5}$ 
  } & 

  {\raggedleft 
    A$_{112}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  y } \\ 
 

 
  
  {\raggedleft 
    A$_{33}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{2}$ 
  } & 

  {\raggedleft 
    xz$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{73}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{4}$ 
  } & 

  {\raggedleft 
    xyz$^{4}$ 
  } & 

  {\raggedleft 
    A$_{113}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{7}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{34}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z 
  } & 

  {\raggedleft 
    xz 
  } & 

  {\raggedleft 
    x$^{2}$z 
  } & 

  {\raggedleft 
    x$^{3}$z 
  } & 

  {\raggedleft 
    A$_{74}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{3}$ 
  } & 

  {\raggedleft 
    xyz$^{3}$ 
  } & 

  {\raggedleft 
    A$_{114}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{6}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{35}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    1 
  } & 

  {\raggedleft 
    x 
  } & 

  {\raggedleft 
    x$^{2}$ 
  } & 

  {\raggedleft 
    x$^{3}$ 
  } & 

  {\raggedleft 
    A$_{75}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz$^{2}$ 
  } & 

  {\raggedleft 
    xyz$^{2}$ 
  } & 

  {\raggedleft 
    A$_{115}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{5}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{36}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{5}$ 
  } & 

  {\raggedleft 
    xy$^{5}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{5}$ 
  } & 

  {\raggedleft 
    A$_{76}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    yz 
  } & 

  {\raggedleft 
    xyz 
  } & 

  {\raggedleft 
    A$_{116}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{4}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{37}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$z 
  } & 

  {\raggedleft 
    xy$^{4}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{4}$z 
  } & 

  {\raggedleft 
    A$_{77}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y 
  } & 

  {\raggedleft 
    xy 
  } & 

  {\raggedleft 
    A$_{117}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{3}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{38}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{4}$ 
  } & 

  {\raggedleft 
    xy$^{4}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{4}$ 
  } & 

  {\raggedleft 
    A$_{78}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{6}$ 
  } & 

  {\raggedleft 
    xz$^{6}$ 
  } & 

  {\raggedleft 
    A$_{118}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z$^{2}$ } \\ 
 

 
  
  {\raggedleft 
    A$_{39}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    xy$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$z$^{2}$ 
  } & 

  {\raggedleft 
    A$_{79}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{5}$ 
  } & 

  {\raggedleft 
    xz$^{5}$ 
  } & 

  {\raggedleft 
    A$_{119}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  z } \\ 
 

 
  
  {\raggedleft 
    A$_{40}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    y$^{3}$z 
  } & 

  {\raggedleft 
    xy$^{3}$z 
  } & 

  {\raggedleft 
    x$^{2}$y$^{3}$z 
  } & 

  {\raggedleft 
    A$_{80}$ 
  } & 

  {\raggedleft 
    
  } & 

  {\raggedleft 
    z$^{4}$ 
  } & 

  {\raggedleft 
    xz$^{4}$ 
  } & 

  {\raggedleft 
    A$_{120}$ 
  } & 

  {\raggedleft 
    
  } & 
{\raggedleft  1 } \\ 
 

\end{tabular*} \caption{Cubic and quartic polynomial terms} \end{table}


   Polynomial shapes can be used to describe a large class of shapes including the torus, the lemniscate, etc. For example, to declare a quartic surface 
 requires that each of the coefficients (\textit{{\small\texttt{A1 ... A35}}}) be placed in order into a single long vector of 35 terms. As an example let's 
 define a torus the hard way. A Torus can be represented by the equation: {\small\texttt{x$^{4}$ + y$^{4}$ + z$^{4}$ + 2 x$^{2}$ y$^{2}$ + 2 x$^{2}$ z$^{2}$ + 
 2 y$^{2}$ z$^{2}$ - 2 (r\_\-02 + r\_\-12) x$^{2}$ + 2 (r\_\-02 - r\_\-12) y$^{2}$ - 2 (r\_\-02 + r\_\-12) z$^{2}$ + (r\_\-02 - r\_\-12)$^{2}$ = 0}} 



   Where r\_\-0 is the major radius of the torus, the distance from the hole of the donut to the middle of the ring of the donut, and r\_\-1 is the minor radius of 
 the torus, the distance from the middle of the ring of the donut to the outer surface. The following object declaration is for a torus having major radius 6.3 
 minor radius 3.5 (Making the maximum width just under 20). 


{\small\begin{verbatim}
  // Torus having major radius sqrt(40), minor radius sqrt(12)
  quartic {
    < 1,   0,   0,   0,   2,   0,   0,   2,   0,
   -104,   0,   0,   0,   0,   0,   0,   0,   0,
      0,   0,   1,   0,   0,   2,   0,  56,   0,
      0,   0,   0,   1,   0, -104,  0, 784 >
    sturm
  }
\end{verbatim}}


   Poly, cubic and quartics are just like quadrics in that you do not have to understand one to use one. The file {\small\texttt{ \discretionary{shapesq.}{}{shapesq.}inc}} has plenty of 
 pre-\discretionary{}{}{}defined quartics for you to play with. 



   Polys use highly complex computations and will not always render perfectly. If the surface is not smooth, has dropouts, or extra random pixels, try using the 
 optional keyword {\small\texttt{sturm}} in the definition. This will cause a slower but more accurate calculation method to be used. Usually, but not always, 
 this will solve the problem. If sturm does not work, try rotating or translating the shape by some small amount. 



   There are really so many different polynomial shapes, we cannot even begin to list or describe them all. We suggest you find a good reference or text book if 
 you want to investigate the subject further. 


\subsection{Quadric}

% reference/000165.html

\index{quadric}\index{quadric! keyword}\index{Keyword! quadric}

   The {\small\texttt{quadric}} object can produce shapes like paraboloids (dish shapes) and hyperboloids (saddle or hourglass shapes). It can also produce 
 ellipsoids, spheres, cones, and cylinders but you should use the {\small\texttt{ sphere}}, {\small\texttt{cone}}, and {\small\texttt{cylinder}} objects built 
 into POV-\discretionary{}{}{}Ray because they are faster than the quadric version. 



   \textbf{Note:} do not confuse "quaDRic" with "quaRTic". A quadric is a 2nd order polynomial while a quartic is 4th order. 



   Quadrics render much faster and are less error-\discretionary{}{}{}prone but produce less complex objects. The syntax is: 


{\small\begin{verbatim}
QUADRIC:
    quadric
    {
        <A,B,C>,<D,E,F>,<G,H,I>,J
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   Although the syntax actually will parse 3 vector expressions followed by a float, we traditionally have written the syntax as above where \textit{{\small\texttt{ 
 A}}} through \textit{{\small\texttt{J}}} are float expressions. These 10 float that define a surface of x, y, z points which satisfy the equation A x$^{2}$ + 
 B y$^{2}$ + C z$^{2}$ + D xy + E xz + F yz + G x + H y + I z + J = 0 



   Different values of \textit{{\small\texttt{A, B, C, ... J}}} will give different shapes. If you take any three dimensional point and use its x, y and z 
 coordinates in the above equation the answer will be 0 if the point is on the surface of the object. The answer will be negative if the point is inside the 
 object and positive if the point is outside the object. Here are some examples: 


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{123pt}@{} p{287pt}@{} }
 
 
  
  {\raggedleft 
    X$^{2}$ + Y$^{2}$ + Z$^{2}$ - 1 = 0 
  } & 
{\raggedleft  Sphere } \\ 
 

 
  
  {\raggedleft 
    X$^{2}$ + Y$^{2}$ - 1 = 0 
  } & 
{\raggedleft  Infinite cylinder along the Z axis } \\ 
 

 
  
  {\raggedleft 
    X$^{2}$ + Y$^{2}$ - Z$^{2}$ = 0 
  } & 
{\raggedleft  Infinite cone along the Z axis } \\ 
 

\end{tabular*} \caption{Some quartic shapes} \end{table}


   The easiest way to use these shapes is to include the standard file {\small\texttt{ \discretionary{shapes.}{}{shapes.}inc}} into your program. It contains several pre-\discretionary{}{}{}defined quadrics 
 and you can transform these pre-\discretionary{}{}{}defined shapes (using translate, rotate and scale) into the ones you want. For a complete list, see the file {\small\texttt{ 
 \discretionary{shapes.}{}{shapes.}inc}}. 


\section{Isosurface Object}

% reference/000166.html

\index{isosurface}\index{isosurface! keyword}\index{Keyword! isosurface}\index{function! isosurface}\index{Keyword! function}\index{contained\_\-by! isosurface}\index{Keyword! contained\_\-by}\index{threshold! isosurface}\index{Keyword! threshold}\index{accuracy! isosurface}\index{Keyword! accuracy}\index{max\_\-gradient! isosurface}\index{Keyword! max\_\-gradient}\index{evaluate! isosurface}\index{Keyword! evaluate}\index{open! isosurface}\index{Keyword! open}\index{max\_\-trace! isosurface}\index{Keyword! max\_\-trace}\index{all\_\-intersections! isosurface}\index{Keyword! all\_\-intersections}

   Details about many of the things that can be done with the isosurface object are discussed in the isosurface tutorial section. Below you will only find the 
 syntax basics: 


{\small\begin{verbatim}
isosurface {
  function { FUNCTION_ITEMS }
  [contained_by { SPHERE | BOX }]
  [threshold FLOAT_VALUE]
  [accuracy FLOAT_VALUE]
  [max_gradient FLOAT_VALUE]
  [evaluate P0, P1, P2]
  [open]
  [max_trace INTEGER] | [all_intersections]
  [OBJECT_MODIFIERS...]
}
\end{verbatim}}


   Isosurface default values:\index{Default values! isosurface}\index{isosurface! default values} 


{\small\begin{verbatim}
contained_by : box{-1,1}
threshold    : 0.0
accuracy     : 0.001
max_gradient : 1.1
\end{verbatim}}


   {\small\texttt{function \{ ... \}}} This must be specified and be the first item of the {\small\texttt{isosurface}} statement. Here you place all the 
 mathematical functions that will describe the surface.\index{contained\_\-by}\index{contained\_\-by! isosurface} 



   {\small\texttt{contained\_\-by \{ ... \}}} The {\small\texttt{contained\_\-by}} 'object' limits the area where POV-\discretionary{}{}{}Ray samples for the surface of the function. This 
 container can either be a sphere or a box, both of which use the standard POV-\discretionary{}{}{}Ray syntax. If not specified a {\small\texttt{box \{$<$-1,-1,-1$>$, 
 $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$\}}} will be used as default. 


{\small\begin{verbatim}
contained_by { sphere { CENTER, RADIUS } }
contained_by { box { CORNER1, CORNER2 } }
\end{verbatim}}
\index{threshold! isosurface}

   {\small\texttt{threshold}} This specifies how much strength, or substance to give the {\small\texttt{isosurface}}. The surface appears where the {\small\texttt{function}} 
 value equals the {\small\texttt{threshold}} value. The default threshold is 0. 


{\small\begin{verbatim}function = threshold\end{verbatim}}
\index{accuracy}

   {\small\texttt{accuracy}} The isosurface finding method is a recursive subdivision method. This subdivision goes on until the length of the interval where 
 POV-\discretionary{}{}{}Ray finds a surface point is less than the specified {\small\texttt{accuracy}}. The default value is 0.001. \newline Smaller values 
 produces more accurate surfaces, but it takes longer to render.\index{max\_\-gradient}\index{max\_\-gradient! isosurface} 



   {\small\texttt{max\_\-gradient}} POV-\discretionary{}{}{}Ray can find the first intersecting point between a ray and the {\small\texttt{isosurface}} of any continuous function if 
 the maximum gradient of the function is known. Therefore you can specify a {\small\texttt{max\_\-gradient}} for the function. The default value is 1.1. When the {\small\texttt{max\_\-gradient}} 
 used to find the intersecting point is too high, the render slows down considerably. When it is too low, artefacts or holes may appear on the isosurface. When 
 it is way too low, the surface does not show at all. While rendering the isosurface POV-\discretionary{}{}{}Ray records the found gradient values and prints a warning if these 
 values are higher or much lower than the specified {\small\texttt{max\_\-gradient}}: 


{\small\begin{verbatim}
Warning: The maximum gradient found was 5.257, but max_gradient of
the isosurface was set to 5.000. The isosurface may contain holes!
Adjust max_gradient to get a proper rendering of the isosurface.
\end{verbatim}}

{\small\begin{verbatim}
Warning: The maximum gradient found was 5.257, but max_gradient of
the isosurface was set to 7.000. Adjust max_gradient to
get a faster rendering of the isosurface.
\end{verbatim}}


   For best performance you should specify a value close to the real maximum gradient.\index{evaluate}\index{dynamic max\_\-gradient} 



   {\small\texttt{evaluate}} POV-\discretionary{}{}{}Ray can also dynamically adapt the used max\_\-gradient. To activate this technique you have to specify the {\small\texttt{evaluate}} 
 keyword followed by three parameters: 


\begin{itemize}
 
 \item 
     P0: the minimum max\_\-gradient in the estimation process, 
 

 \item 
     P1: an over-\discretionary{}{}{}estimating factor. This means that the max\_\-gradient is multiplied by the P1 parameter. 
 

 \item 
     P2: an attenuation parameter (1 or less) 
 

\end{itemize}


   In this case POV-\discretionary{}{}{}Ray starts with the {\small\texttt{max\_\-gradient}} value {\small\texttt{P0}} and dynamically changes it during the render using {\small\texttt{P1}} 
 and {\small\texttt{P2}}. In the evaluation process, the P1 and P2 parameters are used in quadratic functions. This means that over-\discretionary{}{}{}estimation increases more 
 rapidly with higher values and attenuation more rapidly with lower values. Also with dynamic {\small\texttt{max\_\-gradient}}, there can be artefacts and holes. 



   If you are unsure what values to use, start a render without {\small\texttt{evaluate}} to get a value for {\small\texttt{max\_\-gradient}}. Now you can use it 
 with {\small\texttt{evaluate}} like this: 


\begin{itemize}
 
 \item 
   P0 : found max\_\-gradient * min\_\-factor\newline  'min\_\-factor' being a float between 0 and 1 to reduce the {\small\texttt{max\_\-gradient}} to a 'minimum 
  max\_\-gradient'. The ideal value for P0 would be the average of the found max\_\-gradients, but we do not have access to that information.\newline  A good 
  starting point is 0.6 for the min\_\-factor 
 

 \item 
   P1 : sqrt(found max\_\-gradient/(found max\_\-gradient * min\_\-factor))\newline  'min\_\-factor' being the same as used in P0 this will give an over-\discretionary{}{}{}estimation 
  factor of more than 1, based on your minimum max\_\-gradient and the found max\_\-gradient. 
 

 \item 
   P2 : 1 or less\newline  0.7 is a good starting point. 
 

\end{itemize}


   When there are artifacts / holes in the isosurface, increase the min\_\-factor and / or P2 a bit. Example: when the first run gives a found max\_\-gradient of 356, 
 start with 


{\small\begin{verbatim}
  #declare Min_factor= 0.6;
  isosurface {
     ...
     evaluate 356*Min_factor,  sqrt(356/(356*Min_factor)),  0.7
     //evaluate 213.6, 1.29, 0.7
     ...
   }
\end{verbatim}}


   This method is only an approximation of what happens internally, but it gives faster rendering speeds with the majority of isosurfaces.\index{open! isosurface} 
 



   {\small\texttt{open}} When the isosurface is not fully contained within the contained\_\-by object, there will be a cross section. Where this happens, you will 
 see the surface of the container. With the {\small\texttt{open}} keyword, these cross section surfaces are removed. The inside of the isosurface becomes 
 visible. 



   \textbf{Note:} that {\small\texttt{open}} slows down the render speed. Also, it is not recommended to use it with CSG operations.\index{max\_\-trace}\index{all\_\-intersections} 
 



   {\small\texttt{max\_\-trace}} Isosurfaces can be used in CSG shapes since they are solid finite objects - if not finite by themselves, they are through the 
 cross section with the container. \newline By default POV-\discretionary{}{}{}Ray searches only for the first surface which the ray intersects. But when using an {\small\texttt{isosurface}} 
 in CSG operations, the other surfaces must also be found. Therefore, the keyword {\small\texttt{max\_\-trace}} must be added to the {\small\texttt{isosurface}} 
 statement. It must be followed by an integer value. To check for all surfaces, use the keyword {\small\texttt{all\_\-intersections}} instead. \newline With {\small\texttt{all\_\-intersections}} 
 POV-\discretionary{}{}{}Ray keeps looking until all surfaces are found. With a {\small\texttt{max\_\-trace}} it only checks until that number is reached. 


\section{Parametric Object}

% reference/000167.html

\index{parametric}\index{parametric! keyword}\index{Keyword! parametric}\index{function! parametric}\index{Keyword! function}\index{contained\_\-by! parametric}\index{Keyword! contained\_\-by}\index{max\_\-gradient! parametric}\index{Keyword! max\_\-gradient}\index{accuracy! parametric}\index{Keyword! accuracy}\index{precompute! parametric}\index{Keyword! precompute}

   Where the isosurface object uses implicit surface functions, F(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z)=0, the parametric object is a set of equations for a surface expressed in the form of 
 the parameters that locate points on the surface, x(\discretionary{u,}{}{u,}v), y(\discretionary{u,}{}{u,}v), z(\discretionary{u,}{}{u,}v). Each pair of values for u and v gives a single point {\small\texttt{$<$\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z$>$}} 
 in 3d space 



   The parametric object is not a solid object it is "hollow", like a thin shell. 



   Syntax: 


{\small\begin{verbatim}
  parametric {
    function { FUNCTION_ITEMS },
    function { FUNCTION_ITEMS },
    function { FUNCTION_ITEMS }
    <u1,v1>, <u2,v2>
    [contained_by { SPHERE | BOX }]
    [max_gradient FLOAT_VALUE]
    [accuracy FLOAT_VALUE]
    [precompute DEPTH, VarList]
  }
\end{verbatim}}


   Parametric default values: \index{Default values! parametric} 


{\small\begin{verbatim}
accuracy     : 0.001 
\end{verbatim}}


   The first function calculates the {\small\texttt{x}} value of the surface, the second {\small\texttt{y}} and the third the {\small\texttt{z}} value. Allowed 
 is any function that results in a float. 



   {\small\texttt{$<$\discretionary{u1,}{}{u1,}v1$>$,$<$\discretionary{u2,}{}{u2,}v2$>$}} boundaries of the {\small\texttt{(\discretionary{u,}{}{u,}v)}} space, in which the surface has to be calculated\index{contained\_\-by! parametric} 
 



   {\small\texttt{contained\_\-by \{ ... \}}} The contained\_\-by 'object' limits the area where POV-\discretionary{}{}{}Ray samples for the surface of the function. This container can 
 either be a sphere or a box, both of which use the standard POV-\discretionary{}{}{}Ray syntax. If not specified a {\small\texttt{box \{$<$-1,-1,-1$>$, $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$\}}} will be 
 used as default.\index{max\_\-gradient! parametric} 



   {\small\texttt{max\_\-gradient}}, It is not really the maximum gradient. It's the maximum magnitude of all six partial derivatives over the specified ranges of 
 u and v. That is, if you take {\small\texttt{dx/du}}, {\small\texttt{dx/dv}}, {\small\texttt{dy/du}}, {\small\texttt{dy/dv}}, {\small\texttt{dz/du}}, and {\small\texttt{dz/dv}} 
 and calculate them over the entire range, the {\small\texttt{max\_\-gradient}} is the maximum of the absolute values of all of those values. \index{accuracy! parametric} 
 



   {\small\texttt{accuracy}} The default value is 0.001. Smaller values produces more accurate surfaces, but take longer to render.\index{precompute} 



   {\small\texttt{precompute}} can speedup rendering of parametric surfaces. It simply divides parametric surfaces into small ones (2\^{}depth) and precomputes 
 ranges of the variables(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z) which you specify after depth. The maximum depth is 20. High values of depth can produce arrays that use a lot of memory, take 
 longer to parse and render faster. If you declare a parametric surface with the precompute keyword and then use it twice, all arrays are in memory only once. 



   Example, a unit sphere: 


{\small\begin{verbatim}
  parametric {
    function { sin(u)*cos(v) }
    function { sin(u)*sin(v) }
    function { cos(u) }

    <0,0>, <2*pi,pi>
    contained_by { sphere{0, 1.1} }
    max_gradient ??
    accuracy 0.0001
    precompute 10 x,y,z
    pigment {rgb 1}
  }
\end{verbatim}}

\section{Constructive Solid Geometry}

% reference/000168.html

\index{CSG}

   In addition to all of the primitive shapes POV-\discretionary{}{}{}Ray supports, you can also combine multiple simple shapes into complex shapes using \textit{ Constructive 
 Solid Geometry} (CSG). There are four basic types of CSG operations: union, intersection, difference, and merge. CSG objects can be composed of primitives or 
 other CSG objects to create more, and more complex shapes. 


\subsection{Inside and Outside}

% reference/000169.html



   Most shape primitives, like spheres, boxes and blobs divide the world into two regions. One region is inside the object and one is outside. Given any point 
 in space you can say it is either inside or outside any particular primitive object. Well, it could be exactly on the surface but this case is rather hard to 
 determine due to numerical problems. 



   Even planes have an inside and an outside. By definition, the surface normal of the plane points towards the outside of the plane. You should note that 
 triangles cannot be used as solid objects in CSG since they have no well defined inside and outside. Triangle-\discretionary{}{}{}based shapes ({\small\texttt{mesh, mesh2}}) can 
 only be used in CSG when they are closed objects and have an inside vector specified. 



   \textbf{Note:}: Although triangles, bicubic\_\-patches and some other shapes have no well defined inside and outside, they have a front- and backside which 
 makes it possible to use a texture on the front side and an interior\_\-texture on the back side. 



   CSG uses the concepts of inside and outside to combine shapes together as explained in the following sections. 



   Imagine you have two objects that partially overlap like shown in the figure below. Four different areas of points can be distinguished: points that are 
 neither in object {\small\texttt{A}} nor in object {\small\texttt{B}}, points that are in object {\small\texttt{A}} but not in object {\small\texttt{B}}, 
 points that are not in object {\small\texttt{A}} but in object {\small\texttt{B}} and last not least points that are in object {\small\texttt{ A}} and object {\small\texttt{B}}. 
 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/objoverl} \caption{Two overlapping objects.} \end{figure} 



   Keeping this in mind it will be quite easy to understand how the CSG operations work. 



   When using CSG it is often useful to invert an object so that it will be inside-\discretionary{}{}{}out. The appearance of the object is not changed, just the way that POV-\discretionary{}{}{}Ray 
 perceives it. When the {\small\texttt{inverse}} keyword is used the \textit{ inside} of the shape is flipped to become the \textit{ outside} and vice versa. 



   The inside/outside distinction is not important for a {\small\texttt{union}}, but is important for {\small\texttt{ intersection}}, {\small\texttt{difference}}, 
 and {\small\texttt{ merge}}.Therefore any objects may be combined using {\small\texttt{ union}} but only solid objects, \discretionary{i.}{}{i.}e. objects that have a well-\discretionary{}{}{}defined 
 interior can be used in the other kinds of CSG. The objects described in "Finite Patch Primitives" have no well defined inside/outside. All objects 
 described in the sections "Finite Solid Primitives" and "Infinite Solid Primitives". 


\subsection{Union}

% reference/000170.html

\index{CSG! union}\index{union}\index{union! keyword}\index{Keyword! union}

   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/unionobj} \caption{The union of two objects.} \end{figure} 



   The simplest kind of CSG is the {\small\texttt{union}}. The syntax is: 


{\small\begin{verbatim}
UNION:
    union
    {
        OBJECTS...
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   Unions are simply glue used to bind two or more shapes into a single entity that can be manipulated as a single object. The image above shows the union of {\small\texttt{A}} 
 and {\small\texttt{B}}. The new object created by the union operation can be scaled, translated and rotated as a single shape. The entire union can share a 
 single texture but each object contained in the union may also have its own texture, which will override any texture statements in the parent object. 



   You should be aware that the surfaces inside the union will not be removed. As you can see from the figure this may be a problem for transparent unions. If 
 you want those surfaces to be removed you will have to use the {\small\texttt{ merge}} operations explained in a later section. 



   The following union will contain a box and a sphere. 


{\small\begin{verbatim}
  union {
    box { <-1.5, -1, -1>, <0.5, 1, 1> }
    cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
  }
\end{verbatim}}
\index{composite}

   Earlier versions of POV-\discretionary{}{}{}Ray placed restrictions on unions so you often had to combine objects with {\small\texttt{composite}} statements. Those earlier 
 restrictions have been lifted so {\small\texttt{composite}} is no longer needed. It is still supported for backwards compatibility. 


\subsubsection{Split\_\-Union}

% reference/000171.html

\index{split\_\-union! union}\index{Keyword! split\_\-union}

   {\small\texttt{split\_\-union}} is a boolean keyword that can be added to a union. It has two states {\small\texttt{on}}/{\small\texttt{off}}, its default is {\small\texttt{on}}. 
 



   {\small\texttt{split\_\-union}} is used when photons are shot at the CSG-\discretionary{}{}{}object. The object is split up in its compound parts, photons are shot at each part 
 separately. This is to prevent photons from being shot at 'empty spaces' in the object, for example the holes in a grid. With compact objects, without 'empty 
 spaces' {\small\texttt{split\_\-union off}} can improve photon gathering. 


{\small\begin{verbatim}
  union {
    object {...}
    object {...}
    split_union off
  }
\end{verbatim}}

\subsection{Intersection}

% reference/000172.html

\index{CSG! intersection}\index{intersection}\index{intersection! keyword}\index{Keyword! intersection}

   The {\small\texttt{intersection}} object creates a shape containing only those areas where all components overlap. A point is part of an intersection if it 
 is inside both objects, {\small\texttt{A}} and {\small\texttt{B}}, as show in the figure below. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/isectobj} \caption{The intersection of two objects.} \end{figure} 



   The syntax is: 


{\small\begin{verbatim}
INTERSECTION:
    intersection
    {
        SOLID_OBJECTS...
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   The component objects must have well defined inside/outside properties. Patch objects are not allowed. 



   \textbf{Note:} if all components do not overlap, the intersection object disappears. 



   Here is an example that overlaps: 


{\small\begin{verbatim}
  intersection {
    box { <-1.5, -1, -1>, <0.5, 1, 1> }
    cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
  }
\end{verbatim}}

\subsection{Difference}

% reference/000173.html

\index{CSG! difference}\index{difference}\index{difference! keyword}\index{Keyword! difference}

   The CSG {\small\texttt{difference}} operation takes the intersection between the first object and the inverse of all subsequent objects. Thus only points 
 inside object {\small\texttt{A}} and outside object {\small\texttt{B}} belong to the difference of both objects. 



   The result is a subtraction of the 2nd shape from the first shape as shown in the figure below. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/diffobj} \caption{The difference between two objects.} \end{figure} 



   The syntax is: 


{\small\begin{verbatim}
DIFFERENCE:
    difference
    {
        SOLID_OBJECTS...
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   The component objects must have well defined inside/outside properties. Patch objects are not allowed. 



   \textbf{Note:} if the first object is entirely inside the subtracted objects, the difference object disappears. 



   Here is an example of a properly formed difference: 


{\small\begin{verbatim}
  difference {
    box { <-1.5, -1, -1>, <0.5, 1, 1> }
    cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 }
  }
\end{verbatim}}


   \textbf{Note:} internally, POV-\discretionary{}{}{}Ray simply adds the {\small\texttt{inverse}} keyword to the second (and subsequent) objects and then performs an intersection. 



   The example above is equivalent to: 


{\small\begin{verbatim}
  intersection {
    box { <-1.5, -1, -1>, <0.5, 1, 1> }
    cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 inverse }
  }
\end{verbatim}}

\subsection{Merge}

% reference/000174.html

\index{CSG! merge}\index{merge}\index{merge! keyword}\index{Keyword! merge}

   The {\small\texttt{union}} operation just glues objects together, it does not remove the objects' surfaces inside the {\small\texttt{union}}. Under most 
 circumstances this does not matter. However if a transparent {\small\texttt{ union}} is used, those interior surfaces will be visible. The {\small\texttt{ 
 merge}} operations can be used to avoid this problem. It works just like {\small\texttt{union}} but it eliminates the inner surfaces like shown in the figure 
 below. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/mergeobj} \caption{Merge removes inner surfaces.} \end{figure} 



   The syntax is: 


{\small\begin{verbatim}
MERGE:
    merge
    {
        SOLID_OBJECTS...
        [OBJECT_MODIFIERS...]
    }
\end{verbatim}}


   The component objects must have well defined inside/outside properties. Patch objects are not allowed. 



   \textbf{Note:} that in general {\small\texttt{merge}} is slower rendering than {\small\texttt{union}} when used with non transparent objects. A small test 
 may be needed to determine what is the optimal solution regarding speed and visual result. 


\section{Light Sources}

% reference/000175.html

\index{light\_\-source}\index{light\_\-source! keyword}\index{Keyword! light\_\-source}\index{spotlight! light\_\-source}\index{Keyword! spotlight}\index{shadowless! light\_\-source}\index{Keyword! shadowless}\index{cylinder! light\_\-source}\index{Keyword! cylinder}\index{parallel! light\_\-source}\index{Keyword! parallel}\index{radius! light\_\-source}\index{Keyword! radius}\index{falloff! light\_\-source}\index{Keyword! falloff}\index{tightness! light\_\-source}\index{Keyword! tightness}\index{point\_\-at! light\_\-source}\index{Keyword! point\_\-at}\index{area\_\-light! light\_\-source}\index{Keyword! area\_\-light}\index{adaptive! light\_\-source}\index{Keyword! adaptive}\index{jitter! light\_\-source}\index{Keyword! jitter}\index{circular! light\_\-source}\index{Keyword! circular}\index{orient! light\_\-source}\index{Keyword! orient}\index{looks\_\-like! light\_\-source}\index{Keyword! looks\_\-like}\index{fade\_\-distance! light\_\-source}\index{Keyword! fade\_\-distance}\index{fade\_\-power! light\_\-source}\index{Keyword! fade\_\-power}\index{media\_\-attenuation! light\_\-source}\index{Keyword! media\_\-attenuation}\index{media\_\-interaction! light\_\-source}\index{Keyword! media\_\-interaction}\index{projected\_\-through! light\_\-source}\index{Keyword! projected\_\-through}

   The {\small\texttt{light\_\-source}} is not really an object. Light sources have no visible shape of their own. They are just points or areas which emit light. 
 They are categorized as objects so that they can be combined with regular objects using {\small\texttt{union}}. Their full syntax is: 


{\small\begin{verbatim}
LIGHT_SOURCE:
    light_source
    {
        <Location>, COLOR
        [LIGHT_MODIFIERS...]
    }
LIGHT_MODIFIER:
    LIGHT_TYPE | SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS |
    GENERAL_LIGHT_MODIFIERS
LIGHT_TYPE:
    spotlight | shadowless | cylinder | parallel
SPOTLIGHT_ITEM:
    radius Radius | falloff Falloff | tightness Tightness |
    point_at <Spot>
PARALLEL_ITEM:
    point_at <Spot>
AREA_LIGHT_ITEM:
    area_light <Axis_1>, <Axis_2>, Size_1, Size_2 |
    adaptive Adaptive | jitter Jitter | circular | orient
GENERAL_LIGHT_MODIFIERS:
    looks_like { OBJECT } |
    TRANSFORMATION fade_distance Fade_Distance |
    fade_power Fade_Power | media_attenuation [Bool] |
    media_interaction [Bool] | projected_through
\end{verbatim}}


   Light source default values: \index{Default values! light\_\-source} 


{\small\begin{verbatim}
LIGHT_TYPE        : pointlight
falloff           : 70
media_interaction : on
media_attenuation : off
point_at          : <0,0,0>
radius            : 70
tightness         : 10
\end{verbatim}}


   The different types of light sources and the optional modifiers are described in the following sections. 



   The first two items are common to all light sources. The \textit{{\small\texttt{$<$Location$>$}}} vector gives the location of the light. The \textit{COLOR} 
 gives the color of the light. Only the red, green, and blue components are significant. Any transmit or filter values are ignored. 



   \textbf{Note:} you vary the intensity of the light as well as the color using this parameter. A color such as {\small\texttt{rgb $<$0.\discretionary{5,}{}{5,}0.\discretionary{5,}{}{5,}0.5$>$}} gives 
 a white light that is half the normal intensity. 



   All of the keywords or items in the syntax specification above may appear in any order. Some keywords only have effect if specified with other keywords. The 
 keywords are grouped into functional categories to make it clear which keywords work together. The \textit{GENERAL\_\-LIGHT\_\-MODIFIERS} work with all types of 
 lights and all options. 



   \textbf{Note:} that \textit{TRANSFORMATIONS} such as {\small\texttt{translate}}, {\small\texttt{rotate}} etc. may be applied but no other \textit{OBJECT\_\-MODIFIERS} 
 may be used. 



   There are three mutually exclusive light types. If no \textit{LIGHT\_\-TYPE} is specified it is a point light. The other choices are {\small\texttt{ spotlight}} 
 and {\small\texttt{cylinder}}. 


\subsection{Point Lights}

% reference/000176.html

\index{point light! light\_\-source}\index{light\_\-source! point light}

   The simplest kind of light is a point light. A point light source sends light of the specified color uniformly in all directions. The default light type is a 
 point source. The \textit{{\small\texttt{$<$Location$>$}}} and \textit{ COLOR} is all that is required. For example: 


{\small\begin{verbatim}
  light_source {
    <1000,1000,-1000>, rgb <1,0.75,0> //an orange light
  }
\end{verbatim}}

\subsection{Spotlights}

% reference/000193.html

\index{spotlight! light\_\-source}\index{light\_\-source! spotlight}

   Normally light radiates outward equally in all directions from the source. However the {\small\texttt{spotlight}} keyword can be used to create a cone of 
 light that is bright in the center and falls of to darkness in a soft fringe effect at the edge. 



   Although the cone of light fades to soft edges, objects illuminated by spotlights still cast hard shadows. The syntax is: 


{\small\begin{verbatim}
SPOTLIGHT_SOURCE:
    light_source
    {
        <Location>, COLOR spotlight
        [LIGHT_MODIFIERS...]
    }
LIGHT_MODIFIER:
    SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
SPOTLIGHT_ITEM:
    radius Radius | falloff Falloff | tightness Tightness |
    point_at <Spot>
\end{verbatim}}


   Default values: 


{\small\begin{verbatim}
  radius:    30 degrees
  falloff:   45 degrees
  tightness:  0
\end{verbatim}}
\index{point\_\-at}\index{point\_\-at! spotlight}

   The {\small\texttt{point\_\-at}} keyword tells the spotlight to point at a particular 3D coordinate. A line from the location of the spotlight to the {\small\texttt{point\_\-at}} 
 coordinate forms the center line of the cone of light. The following illustration will be helpful in understanding how these values relate to each other. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/spotgeom} \caption{The geometry of a spotlight.} \end{figure}\index{falloff}\index{radius}\index{tightness}\index{falloff! light\_\-source}\index{radius! light\_\-source}\index{light\_\-source! spotlight, falloff}\index{light\_\-source! spotlight, radius}\index{light\_\-source! spotlight, tightness} 
 



   The {\small\texttt{falloff}}, {\small\texttt{radius}}, and {\small\texttt{ tightness}} keywords control the way that light tapers off at the edges of the 
 cone. These four keywords apply only when the {\small\texttt{ spotlight}} or {\small\texttt{ cylinder}} keywords are used. 



   The {\small\texttt{falloff}} keyword specifies the overall size of the cone of light. This is the point where the light falls off to zero intensity. The 
 float value you specify is the angle, in degrees, between the edge of the cone and center line. The {\small\texttt{ radius}} keyword specifies the size of the 
 "hot-\discretionary{}{}{}spot" at the center of the cone of light. The "hot-\discretionary{}{}{}spot" is a brighter cone of light inside the spotlight cone and has the 
 same center line. The {\small\texttt{radius}} value specifies the angle, in degrees, between the edge of this bright, inner cone and the center line. The 
 light inside the inner cone is of uniform intensity. The light between the inner and outer cones tapers off to zero. 



   For example, assuming a {\small\texttt{tightness 0}}, with {\small\texttt{radius 10}} and {\small\texttt{falloff 20}} the light from the center line out to 
 10 degrees is full intensity. From 10 to 20 degrees from the center line the light falls off to zero intensity. At 20 degrees or greater there is no light. 



   \textbf{Note:} if the radius and falloff values are close or equal the light intensity drops rapidly and the spotlight has a sharp edge. 



   The values for the {\small\texttt{radius}}, and {\small\texttt{tightness}} parameters are half the opening angles of the corresponding cones, both angles 
 have to be smaller than 90 degrees. The light smoothly falls off between the radius and the falloff angle like shown in the figures below (as long as the 
 radius angle is not negative). 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/fixfallo} \caption{Intensity multiplier curve with a fixed falloff angle of 45 degrees.} \end{figure} 
 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/fixedrad} \caption{Intensity multiplier curve with a fixed radius angle of 45 degrees.} \end{figure} 
 



   The {\small\texttt{tightness}} keyword is used to specify an \textit{ additional} exponential softening of the edges. A value other than 0, will affect light 
 within the radius cone as well as light in the falloff cone. The intensity of light at an angle from the center line is given by: \textit{{\small\texttt{intensity 
 * cos(angle)tightness}}}. The default value for tightness is 0. Lower tightness values will make the spotlight brighter, making the spot wider and the edges 
 sharper. Higher values will dim the spotlight, making the spot tighter and the edges softer. Values from 0 to 100 are acceptable. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/diftight} \caption{Intensity multiplier curve with fixed angle and falloff angles of 30 and 60 degrees respectively and different tightness values.} \end{figure} 
 



   You should note from the figures that the radius and falloff angles interact with the tightness parameter. To give the tightness value full control over the 
 spotlight's appearance use radius 0 falloff 90. As you can see from the figure below. In that case the falloff angle has no effect and the lit area is only 
 determined by the tightness parameter. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/negradli} \caption{Intensity multiplier curve with a negative radius angle and different tightness values.} \end{figure} 
 



   Spotlights may be used anyplace that a normal light source is used. Like any light sources, they are invisible. They may also be used in conjunction with 
 area lights. 


\subsection{Cylindrical Lights}

% reference/000192.html

\index{cylinder! light\_\-source}\index{light\_\-source! cylinder}

   The {\small\texttt{cylinder}} keyword specifies a cylindrical light source that is great for simulating laser beams. Cylindrical light sources work pretty 
 much like spotlights except that the light rays are constrained by a cylinder and not a cone. The syntax is: 


{\small\begin{verbatim}
CYLINDER_LIGHT_SOURCE:
    light_source
    {
        <Location>, COLOR cylinder
        [LIGHT_MODIFIERS...]
    }
LIGHT_MODIFIER:
    SPOTLIGHT_ITEM | AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
SPOTLIGHT_ITEM:
    radius Radius | falloff Falloff | tightness Tightness |
    point_at <Spot>
\end{verbatim}}


   Default values: 


{\small\begin{verbatim}
  radius:     0.75 degrees
  falloff:    1    degrees
  tightness:  0
\end{verbatim}}


   The {\small\texttt{point\_\-at}}, {\small\texttt{radius}}, {\small\texttt{falloff}} and {\small\texttt{tightness}} keywords control the same features as with 
 the spotlight. See "Spotlights" for details. 



   You should keep in mind that the cylindrical light source is still a point light source. The rays are emitted from one point and are only constraint by a 
 cylinder. The light rays are not parallel. 


\subsection{Parallel Lights}

% reference/000191.html

\index{parallel! light\_\-source}\index{point\_\-at! parallel}\index{light\_\-source! parallel}\index{parallel}
{\small\begin{verbatim}
syntax:

light_source {
  LOCATION_VECTOR, COLOR
  [LIGHT_SOURCE_ITEMS...]
  parallel
  point_at VECTOR
}
\end{verbatim}}


   The {\small\texttt{parallel}} keyword can be used with any type of light source. 



   \textbf{Note:} for normal point lights, {\small\texttt{point\_\-at}} must come after {\small\texttt{parallel}}. 



   Parallel lights are useful for simulating very distant light sources, such as sunlight. As the name suggests, it makes the light rays parallel. 



   Technically this is done by shooting rays from the closest point on a plane to the object intersection point. The plane is determined by a perpendicular 
 defined by the light {\small\texttt{location}} and the {\small\texttt{point\_\-at}} vector. 



   Two things must be considered when choosing the light location (specifically, its distance): 


\begin{enumerate}
 
 \item 
   Any parts of an object "above" the light plane still get illuminated according to the light direction, but they will not cast or receive 
  shadows. 
 

 \item 
   {\small\texttt{fade\_\-distance}} and {\small\texttt{fade\_\-power}} use the light {\small\texttt{location}} to determine distance for light attenuation, so 
  the attenuation still looks like that of a point source. \newline Area light also uses the light location in its calculations. 
 

\end{enumerate}

\subsection{Area Lights}

% reference/000190.html

\index{area\_\-light! light\_\-source}\index{light\_\-source! area\_\-light}\index{area\_\-light}

   Area light sources occupy a finite, one- or two-\discretionary{}{}{}dimensional area of space. They can cast soft shadows because an object can partially block their light. 
 Point sources are either totally blocked or not blocked. 



   The {\small\texttt{area\_\-light}} keyword in POV-\discretionary{}{}{}Ray creates sources that are rectangular in shape, sort of like a flat panel light. Rather than performing the 
 complex calculations that would be required to model a true area light, it is approximated as an array of point light sources spread out over the area 
 occupied by the light. The array-\discretionary{}{}{}effect applies to shadows only. The object's illumination is still that of a point source. The intensity of each individual 
 point light in the array is dimmed so that the total amount of light emitted by the light is equal to the light color specified in the declaration. The syntax 
 is: 


{\small\begin{verbatim}
AREA_LIGHT_SOURCE:

  light_source {
    LOCATION_VECTOR, COLOR
    area_light
    AXIS_1_VECTOR, AXIS_2_VECTOR, Size_1, Size_2
    [adaptive Adaptive] [ jitter ]
    [ circular ] [ orient ]
    [ [LIGHT_MODIFIERS...]
  }
\end{verbatim}}


   Any type of light source may be an area light. 



   The area\_\-light command defines the location, the size and orientation of the area light as well as the number of lights in the light source array. The 
 location vector is the centre of a rectangle defined by the two vectors \textit{{\small\texttt{$<$Axis\_\-1$>$}}} and \textit{{\small\texttt{$<$Axis\_\-2$>$}}}. 
 These specify the lengths and directions of the edges of the light. 



   \begin{figure} \centering \includegraphics[scale=0.60]{../final/tex/images/reference/areal} \caption{4x4 Area light, location and vectors.} \end{figure} 



   Since the area lights are rectangular in shape these vectors should be perpendicular to each other. The larger the size of the light the thicker the soft 
 part of shadows will be. The integers Size\_\-1 and Size\_\-2 specify the number of rows and columns of point sources of the. The more lights you use the smoother 
 your shadows will be but the longer they will take to render. 



   \textbf{Note:} it is possible to specify spotlight parameters along with the area light parameters to create area spotlights. Using area spotlights is a good 
 way to speed up scenes that use area lights since you can confine the lengthy soft shadow calculations to only the parts of your scene that need them. 



   An interesting effect can be created using a linear light source. Rather than having a rectangular shape, a linear light stretches along a line sort of like 
 a thin fluorescent tube. To create a linear light just create an area light with one of the array dimensions set to 1. 



   \index{jitter} \index{jitter! area\_\-light} \index{light\_\-source! area\_\-light, jitter} The {\small\texttt{jitter}} command is optional. When used it 
 causes the positions of the point lights in the array to be randomly jittered to eliminate any shadow banding that may occur. The jittering is completely 
 random from render to render and should not be used when generating animations. 



   \index{adaptive} \index{light\_\-source! area\_\-light, adaptive} The {\small\texttt{adaptive}} command is used to enable adaptive sampling of the light 
 source. By default POV-\discretionary{}{}{}Ray calculates the amount of light that reaches a surface from an area light by shooting a test ray at every point light within the 
 array. As you can imagine this is very slow. Adaptive sampling on the other hand attempts to approximate the same calculation by using a minimum number of 
 test rays. The number specified after the keyword controls how much adaptive sampling is used. The higher the number the more accurate your shadows will be 
 but the longer they will take to render. If you are not sure what value to use a good starting point is {\small\texttt{ adaptive 1}}. The {\small\texttt{adaptive}} 
 keyword only accepts integer values and cannot be set lower than 0. 



   When performing adaptive sampling POV-\discretionary{}{}{}Ray starts by shooting a test ray at each of the four corners of the area light. If the amount of light received from 
 all four corners is approximately the same then the area light is assumed to be either fully in view or fully blocked. The light intensity is then calculated 
 as the average intensity of the light received from the four corners. However, if the light intensity from the four corners differs significantly then the 
 area light is partially blocked. The area light is split into four quarters and each section is sampled as described above. This allows POV-\discretionary{}{}{}Ray to rapidly 
 approximate how much of the area light is in view without having to shoot a test ray at every light in the array. Visually the sampling goes like shown below. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/arealigh} \caption{Area light adaptive samples.} \end{figure} 



   While the adaptive sampling method is fast (relatively speaking) it can sometimes produce inaccurate shadows. The solution is to reduce the amount of 
 adaptive sampling without completely turning it off. The number after the adaptive keyword adjusts the number of times that the area light will be split 
 before the adaptive phase begins. For example if you use {\small\texttt{ adaptive 0}} a minimum of 4 rays will be shot at the light. If you use {\small\texttt{ 
 adaptive 1}} a minimum of 9 rays will be shot ({\small\texttt{adaptive 2}} gives 25 rays, {\small\texttt{adaptive 3}} gives 81 rays, etc). Obviously the more 
 shadow rays you shoot the slower the rendering will be so you should use the lowest value that gives acceptable results. 



   The number of rays never exceeds the values you specify for rows and columns of points. For example {\small\texttt{area\_\-light \discretionary{x,}{}{x,}y,\discretionary{4,}{}{4,}4}} specifies a 4 by 4 
 array of lights. If you specify {\small\texttt{adaptive 3}} it would mean that you should start with a 9 by 9 array. In this case no adaptive sampling is 
 done. The 4 by 4 array is used.\index{circular}\index{light\_\-source! area\_\-light, circular} 



   The {\small\texttt{circular}} command has been added to area lights in order to better create circular soft shadows. With ordinary area lights the 
 pseudo-\discretionary{}{}{}lights are arranged in a rectangular grid and thus project partly rectangular shadows around all objects, including circular 
 objects. \newline By including the {\small\texttt{circular}} tag in an area light, the light is stretched and squashed so that it looks like a circle: this 
 way, circular or spherical light sources are better simulated. 



   A few things to remember: 


\begin{itemize}
 
 \item 
   Circular area lights can be ellipses: the AXIS\_\-1\_\-VECTOR and AXIS\_\-2\_\-VECTOR define the shape and orientation of the circle; if the vectors are not equal, 
  the light source is elliptical in shape. 
 

 \item 
   Rectangular artefacts may still show up with very large area grids. 
 

 \item 
   There is no point in using {\small\texttt{circular}} with linear area lights or area lights which have a 2x2 size. 
 

 \item 
   The area of a circular light is roughly 78.5 per cent of a similar size rectangular area light. Increase your axis vectors accordingly if you wish to 
  keep the light source area constant. 
 

\end{itemize}
\index{orient}\index{light\_\-source! area\_\-light, orient}

   The {\small\texttt{orient}} command has been added to area lights in order to better create soft shadows. Without this modifier, you have to take care when 
 choosing the axis vectors of an area\_\-light, since they define both its area and orientation. \newline Area lights are two dimensional: shadows facing the area 
 light receive light from a larger surface area than shadows at the sides of the area light.\begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/area2} \caption{Area light facing object} \end{figure} 
 



   Actually, the area from which light is emitted at the sides of the area light is reduced to a single line, only casting soft shadows in one direction.\begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/area1} \caption{Area light not facing object} \end{figure} 
 



   Between these two extremes the surface area emitting light progresses gradually. \newline By including the {\small\texttt{orient}} modifier in an area light, 
 the light is rotated so that for every shadow test, it always faces the point being tested. The initial orientation is no longer important, so you only have 
 to consider the desired dimensions (area) of the light source when specifying the axis vectors. \newline In effect, this makes the area light source appear 
 3-dimensional (\discretionary{e.}{}{e.}g. an area\_\-light with perpendicular axis vectors of the same size and dimensions using {\small\texttt{circular}} \textit{and} {\small\texttt{orient}} 
 simulates a spherical light source). 



   Orient has a few restrictions: 


\begin{enumerate}
 
 \item 
   It can be used with "circular" lights only. 
 

 \item 
   The two axes of the area light must be of equal length. 
 

 \item 
   The two axes of the area light should use an equal number of samples, and that number should be greater than one 
 

\end{enumerate}


   These three rules exist because without them, you can get unpredictable results from the orient feature. 



   If one of the first two rules is broken, POV will issue a warning and correct the problem. If the third rule is broken, you will only get the error message, 
 and POV will not automatically correct the problem. 


\subsection{Shadowless Lights}

% reference/000189.html

\index{shadowless}\index{shadowless! light\_\-source}\index{light\_\-source! shadowless}

   Using the {\small\texttt{shadowless}} keyword you can stop a light source from casting shadows. These lights are sometimes called "fill lights". 
 They are another way to simulate ambient light however shadowless lights have a definite source. The syntax is: 


{\small\begin{verbatim}
SHADOWLESS_LIGHT_SOURCE:
    light_source
    {
        <Location>, COLOR shadowless
        [LIGHT_MODIFIERS...]
    }
LIGHT_MODIFIER:
    AREA_LIGHT_ITEMS | GENERAL_LIGHT_MODIFIERS
\end{verbatim}}


   {\small\texttt{shadowless}} may be used with all types of light sources. The only restriction is that {\small\texttt{shadowless}} should be before or after \textit{all} 
 spotlight or cylinder option keywords. Do not mix or you get the message "Keyword 'the one following shadowless' cannot be used with standard light 
 source". Also note that shadowless lights will not cause highlights on the illuminated objects. 


\subsection{Looks\_\-like}

% reference/000188.html

\index{looks\_\-like! light\_\-source}\index{light\_\-source! looks\_\-like}

   Normally the light source itself has no visible shape. The light simply radiates from an invisible point or area. You may give a light source any shape by 
 adding a {\small\texttt{looks\_\-like \{}}\textit{ OBJECT} {\small\texttt{\}}} statement. 



   There is an implied {\small\texttt{no\_\-shadow}} attached to the {\small\texttt{ looks\_\-like}} object so that light is not blocked by the object. Without the 
 automatic {\small\texttt{no\_\-shadow}} the light inside the object would not escape. The object would, in effect, cast a shadow over everything. 



   If you want the attached object to block light then you should attach it with a {\small\texttt{union}} and not a {\small\texttt{looks\_\-like}} as follows: 


{\small\begin{verbatim}
  union {
    light_source { <100, 200, -300> color White }
    object { My_Lamp_Shape }
  }
\end{verbatim}}


   Presumably parts of the lamp shade are transparent to let some light out. 


\subsection{Projected\_\-Through}

% reference/000187.html

\index{projected\_\-through! light\_\-source}\index{light\_\-source! projected\_\-through}\index{projected\_\-through}

   Syntax: 


{\small\begin{verbatim}
  light_source {
    LOCATION_VECTOR, COLOR
    [LIGHT_SOURCE_ITEMS...]
    projected_through { OBJECT }
  }
\end{verbatim}}


   Projected\_\-through can be used with any type of light source. Any object can be used, provided it has been declared before. \newline Projecting a light 
 through an object can be thought of as the opposite of shadowing: only the light rays that hit the projected\_\-through object will contribute to the scene. \newline This 
 also works with area\_\-lights, producing spots of light with soft edges. \newline Any objects between the light and the projected through object will not cast 
 shadows for this light. Also any surface within the projected through object will not cast shadows. \newline Any textures or interiors on the object will be 
 stripped and the object will not show up in the scene. 


\subsection{Light Fading}

% reference/000186.html

\index{light\_\-source! fade\_\-power}\index{fade\_\-power! light\_\-source}\index{fade\_\-power}

   By default POV-\discretionary{}{}{}Ray does not diminish light from any light source as it travels through space. In order to get a more realistic effect {\small\texttt{ 
 fade\_\-distance}} and {\small\texttt{fade\_\-power}} keywords followed by float values can be used to model the distance based falloff in light intensity. 



   \index{fade\_\-distance} \index{light\_\-source! fade\_\-distance} \index{fade\_\-distance! light\_\-source} The {\small\texttt{fade\_\-distance}} is used to 
 specify the distance at which the full light intensity arrives, i. e. the intensity which was given by the \textit{COLOR} specification. The actual 
 attenuation is described by the {\small\texttt{fade\_\-power}} \textit{{\small\texttt{ Fade\_\-Power}}}, which determines the falloff rate. For example linear or 
 quadratic falloff can be used by setting {\small\texttt{fade\_\-power}} to 1 or 2 respectively. The complete formula to calculate the factor by which the light 
 is attenuated is 



   
\begin{mathequ}
% FILE: lattenua
% --------
\begin{displaymath}
  \mathit{attenuation} =
  \frac{2}
  {1+\left(\frac{d}{\mathit{fade\_distance}}\right)^\mathit{fade\_power}}
\end{displaymath}

\caption{} \end{mathequ}
 



   with \textit{{\small\texttt{d}}} being the distance the light has traveled. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/lfadefx} \caption{Light fading functions for different fading powers.} \end{figure} 
 



   You should note two important facts: First, for \textit{{\small\texttt{Fade\_\-Distance}}} larger than one the light intensity at distances smaller than \textit{{\small\texttt{Fade\_\-Distance}}} 
 actually increases. This is necessary to get the light source color if the distance traveled equals the \textit{{\small\texttt{Fade\_\-Distance}}}. Second, only 
 light coming directly from light sources is attenuated. Reflected or refracted light is not attenuated by distance. 


\subsection{Atmospheric Media Interaction}

% reference/000185.html

\index{media\_\-interaction! light\_\-source}\index{light\_\-source! media\_\-interaction}\index{media\_\-interaction}

   By default light sources will interact with an atmosphere added to the scene. This behavior can be switched off by using {\small\texttt{media\_\-interaction off}} 
 inside the light source statement. 



   \textbf{Note:} in POV-\discretionary{}{}{}Ray 3.0 this feature was turned off and on with the atmosphere keyword. 


\subsection{Atmospheric Attenuation}

% reference/000184.html

\index{media\_\-attenuation}\index{light\_\-source! media\_\-attenuation}

   Normally light coming from light sources is not influenced by fog or atmospheric media. This can be changed by turning the {\small\texttt{media\_\-attenuation on}} 
 for a given light source on. All light coming from this light source will now be diminished as it travels through the fog or media. This results in an 
 distance-\discretionary{}{}{}based, exponential intensity falloff ruled by the used fog or media. If there is no fog or media no change will be seen. 



   \textbf{Note:}in POV-\discretionary{}{}{}Ray 3.0 this feature was turned off and on with the atmospheric\_\-attenuation keyword. 


\section{Light Groups}

% reference/000177.html

\index{global\_\-lights}\index{light\_\-group}\index{light\_\-group! keyword}\index{Keyword! light\_\-group}\index{light\_\-source! light\_\-group}\index{Keyword! light\_\-source}\index{global\_\-lights! light\_\-group}\index{Keyword! global\_\-lights}

   Light groups make it possible to create a 'union' of light\_\-sources and objects, where the objects in the group are illuminated by the lights in the group or, 
 if desired, also by the global light\_\-sources. The light\_\-sources in the group can only illuminate the objects that are in the group. 



   Light\_\-groups are for example useful when creating scenes in which some objects turn out to be too dark but the average light is exactly how it should be, as 
 the light\_\-sources in the group do not contribute to the global lighting. 



   Syntax : 


{\small\begin{verbatim}
light_group {
  LIGHT_GROUP LIGHT  |
  LIGHT_GROUP OBJECT |
  LIGHT_GROUP
  [LIGHT_GROUP MODIFIER]
}

LIGHT_GROUP LIGHT:
     light_source | light_source IDENTIFIER
LIGHT_GROUP OBJECT: 
     OBJECT | OBJECT IDENTIFIER
LIGHT_GROUP MODIFIER: 
     global_lights BOOL | TRANSFORMATION
\end{verbatim}}


   {\small\texttt{global\_\-lights}}. Add this command to the light\_\-group to have objects in the group also be illuminated by global light sources. 



   Light groups may be nested. In this case light groups inherit the light sources of the light group they are contained by. 



   Light groups can be seen as a 'union of an object with light\_\-source' and can be used in CSG. 



   Examples, simple light\_\-group: 


{\small\begin{verbatim}
#declare RedLight = light_source {
  <-500,500,-500>
  rgb <1,0,0>
}

light_group {
  light_source {RedLight}
  sphere {0,1 pigment {rgb 1}}
  global_lights off
}
\end{verbatim}}


   Nested light\_\-group: 


{\small\begin{verbatim}
#declare L1 = light_group {
  light_source {<10,10,0>, rgb <1,0,0>}
  light_source {<0,0,-100>, rgb <0,0,1>}
  sphere {0,1 pigment {rgb 1}}
}

light_group {
  light_source {<0,100,0>, rgb 0.5}
  light_group {L1}
}
\end{verbatim}}


   Light\_\-groups in CSG: 


{\small\begin{verbatim}
difference {
  light_group {
    sphere {0,1 pigment {rgb 1}}
    light_source {<-100,0,-100> rgb <1,0,0>}
    global_lights off
  }
  light_group {
    sphere {<0,1,0>,1 pigment {rgb 1}}
    light_source {<100,100,0> rgb <0,0,1>}
    global_lights off
  }
  rotate <-45,0,0>
}
\end{verbatim}}


   In the last example the result will be a sphere illuminated red, where the part that is differenced away is illuminated blue. In result comparable to the 
 difference between two spheres with a different pigment. 


\section{Object Modifiers}

% reference/000178.html



   A variety of modifiers may be attached to objects. The following items may be applied to any object: 


{\small\begin{verbatim}
OBJECT_MODIFIER:
   clipped_by { UNTEXTURED_SOLID_OBJECT... } |
   clipped_by { bounded_by }                 |
   bounded_by { UNTEXTURED_SOLID_OBJECT... } |
   bounded_by { clipped_by }                 |
   no_shadow                  |
   no_image [ Bool ]          |
   no_reflection [ Bool ]     |
   inverse                    |
   sturm [ Bool ]             |
   hierarchy [ Bool ]         |
   double_illuminate [ Bool ] |
   hollow  [ Bool ]           |
   interior { INTERIOR_ITEMS... }                        |
   material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] } |
   texture { TEXTURE_BODY }   |
   interior_texture { TEXTURE_BODY } |
   pigment { PIGMENT_BODY }   |
   normal { NORMAL_BODY }     |
   finish { FINISH_ITEMS... } |
   photons { PHOTON_ITEMS...}
   TRANSFORMATION
\end{verbatim}}


   Transformations such as translate, rotate and scale have already been discussed. The modifiers "Textures" and its parts "Pigment", 
 "Normal", and "Finish" as well as "Interior", and "Media" (which is part of interior) are each in major chapters of their own 
 below. In the sub-\discretionary{}{}{}sections below we cover several other important modifiers: {\small\texttt{clipped\_\-by}}, {\small\texttt{bounded\_\-by}}, {\small\texttt{material}}, 
 {\small\texttt{inverse}}, {\small\texttt{hollow}}, {\small\texttt{no\_\-shadow}}, {\small\texttt{no\_\-image}}, {\small\texttt{no\_\-reflection}}, {\small\texttt{double\_\-illuminate}} 
 and {\small\texttt{sturm}}. Although the examples below use object statements and object identifiers, these modifiers may be used on any type of object such 
 as sphere, box etc. 


\subsection{Clipped\_\-By}

% reference/000179.html

\index{clipped\_\-by}\index{clipped\_\-by! object modifier}\index{Object modifiers! clipped\_\-by}

   The {\small\texttt{clipped\_\-by}} statement is technically an object modifier but it provides a type of CSG similar to CSG intersection. The syntax is: 


{\small\begin{verbatim}
CLIPPED_BY:
    clipped_by { UNTEXTURED_SOLID_OBJECT... } |
    clipped_by { bounded_by }
\end{verbatim}}


   Where \textit{UNTEXTURED\_\-SOLID\_\-OBJECT} is one or more solid objects which have had no texture applied. For example: 


{\small\begin{verbatim}
  object {
    My_Thing
    clipped_by{plane{y,0}}
  }
\end{verbatim}}


   Every part of the object {\small\texttt{My\_\-Thing}} that is inside the plane is retained while the remaining part is clipped off and discarded. In an {\small\texttt{ 
 intersection}} object the hole is closed off. With {\small\texttt{ clipped\_\-by}} it leaves an opening. For example the following figure shows object {\small\texttt{A}} 
 being clipped by object {\small\texttt{B}}. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/clipobj} \caption{An object clipped by another object.} \end{figure} 



   You may use {\small\texttt{clipped\_\-by}} to slice off portions of any shape. In many cases it will also result in faster rendering times than other methods of 
 altering a shape. Occasionally you will want to use the {\small\texttt{ clipped\_\-by}} and {\small\texttt{bounded\_\-by}} options with the same object. The 
 following shortcut saves typing and uses less memory. 


{\small\begin{verbatim}
  object {
    My_Thing
    bounded_by { box { <0,0,0>, <1,1,1> } }
    clipped_by { bounded_by }
  }
\end{verbatim}}


   This tells POV-\discretionary{}{}{}Ray to use the same box as a clip that was used as a bound. 


\subsection{Bounded\_\-By}

% reference/000201.html

\index{bounded\_\-by}\index{bounded\_\-by! object modifier}\index{Object modifiers! bounded\_\-by}

   The calculations necessary to test if a ray hits an object can be quite time consuming. Each ray has to be tested against every object in the scene. POV-\discretionary{}{}{}Ray 
 attempts to speed up the process by building a set of invisible boxes, called bounding boxes, which cluster the objects together. This way a ray that travels 
 in one part of the scene does not have to be tested against objects in another, far away part of the scene. When a large number of objects are present the 
 boxes are nested inside each other. POV-\discretionary{}{}{}Ray can use bounding boxes on any finite object and even some clipped or bounded quadrics. However infinite objects 
 (such as a planes, quartic, cubic and poly) cannot be automatically bound. CSG objects are automatically bound if they contain finite (and in some cases even 
 infinite) objects. This works by applying the CSG set operations to the bounding boxes of all objects used inside the CSG object. For difference and 
 intersection operations this will hardly ever lead to an optimal bounding box. It is sometimes better (depending on the complexity of the CSG object) to have 
 you place a bounding shape yourself using a {\small\texttt{ bounded\_\-by}} statement. 



   Normally bounding shapes are not necessary but there are cases where they can be used to speed up the rendering of complex objects. Bounding shapes tell the 
 ray-\discretionary{}{}{}tracer that the object is totally enclosed by a simple shape. When tracing rays, the ray is first tested against the simple bounding 
 shape. If it strikes the bounding shape the ray is further tested against the more complicated object inside. Otherwise the entire complex shape is skipped, 
 which greatly speeds rendering. The syntax is: 


{\small\begin{verbatim}
BOUNDED_BY:
    bounded_by { UNTEXTURED_SOLID_OBJECT... } |
    bounded_by { clipped_by }
\end{verbatim}}


   Where \textit{UNTEXTURED\_\-SOLID\_\-OBJECT} is one or more solid objects which have had no texture applied. For example: 


{\small\begin{verbatim}
  intersection {
    sphere { <0,0,0>, 2 }
    plane  { <0,1,0>, 0 }
    plane  { <1,0,0>, 0 }
    bounded_by { sphere { <0,0,0>, 2 } }
  }
\end{verbatim}}


   The best bounding shape is a sphere or a box since these shapes are highly optimized, although, any shape may be used. If the bounding shape is itself a 
 finite shape which responds to bounding slabs then the object which it encloses will also be used in the slab system. 



   While it may a good idea to manually add a {\small\texttt{bounded\_\-by}} to intersection, difference and merge, it is best to \textit{never} bound a union. If 
 a union has no {\small\texttt{ bounded\_\-by}} POV-\discretionary{}{}{}Ray can internally split apart the components of a union and apply automatic bounding slabs to any of its 
 finite parts. Note that some utilities such as {\small\texttt{ raw2pov}} may be able to generate bounds more efficiently than POV-\discretionary{}{}{}Ray's current system. 
 However most unions you create yourself can be easily bounded by the automatic system. For technical reasons POV-\discretionary{}{}{}Ray cannot split a merge object. It is maybe 
 best to hand bound a merge, especially if it is very complex. 



   \textbf{Note:} if bounding shape is too small or positioned incorrectly it may clip the object in undefined ways or the object may not appear at all. To do 
 true clipping, use {\small\texttt{clipped\_\-by}} as explained in the previous section. Occasionally you will want to use the {\small\texttt{clipped\_\-by}} and {\small\texttt{bounded\_\-by}} 
 options with the same object. The following shortcut saves typing and uses less memory. 


{\small\begin{verbatim}
  object {
    My_Thing
    clipped_by{ box { <0,0,0>,<1,1,1 > }}
    bounded_by{ clipped_by }
  }
\end{verbatim}}


   This tells POV-\discretionary{}{}{}Ray to use the same box as a bound that was used as a clip. 


\subsection{Material}

% reference/000200.html

\index{material}\index{material! object modifier}\index{Object modifiers! material}

   One of the changes in POV-\discretionary{}{}{}Ray 3.1 was the removal of several items from {\small\texttt{ texture \{ finish\{}}...{\small\texttt{\} \}}} and to move them to the 
 new {\small\texttt{ interior}} statement. The {\small\texttt{halo}} statement, formerly part of {\small\texttt{texture}}, is now renamed {\small\texttt{media}} 
 and made a part of the {\small\texttt{interior}}. 



   This split was deliberate and purposeful (see "Why are Interior and Media Necessary?") however beta testers pointed out that it made it difficult 
 to entirely describe the surface properties and interior of an object in one statement that can be referenced by a single identifier in a texture library. 



   The result is that we created a "wrapper" around {\small\texttt{ texture}} and {\small\texttt{ interior}} which we call {\small\texttt{material}}. 



   The syntax is: 


{\small\begin{verbatim}
MATERIAL:
    material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] }
MATERIAL_ITEMS:
    TEXTURE | INTERIOR_TEXTURE | INTERIOR | TRANSFORMATIONS
\end{verbatim}}


   For example: 


{\small\begin{verbatim}
#declare MyGlass=material{ texture{ Glass_T } interior{ Glass_I }}
object { MyObject material{ MyGlass}}
\end{verbatim}}


   Internally, the "material" is not attached to the object. The material is just a container that brings the texture and interior to the object. It 
 is the texture and interior itself that is attached to the object. Users should still consider texture and interior as separate items attached to the object. 



   The material is just a "bucket" to carry them. If the object already has a texture, then the material texture is layered over it. If the object 
 already has an interior, the material interior fully replaces it and the old interior is destroyed. Transformations inside the material affect only the 
 textures and interiors which are inside the {\small\texttt{ material\{\}}} wrapper and only those textures or interiors specified are affected. For example: 


{\small\begin{verbatim}
  object {
    MyObject
    material {
      texture { MyTexture }
      scale 4         //affects texture but not object or interior
      interior { MyInterior }
      translate 5*x   //affects texture and interior, not object
    }
  }
\end{verbatim}}


   \textbf{Note:} The {\small\texttt{material}} statement has nothing to do with the {\small\texttt{material\_\-map}} statement. A {\small\texttt{material\_\-map}} is \textit{ 
 not} a way to create patterned material. See "Material Maps" for explanation of this unrelated, yet similarly named, older feature. 


\subsection{Inverse}

% reference/000199.html

\index{inverse}\index{inverse! object modifier}\index{Object modifiers! inverse}

   When using CSG it is often useful to invert an object so that it will be inside-\discretionary{}{}{}out. The appearance of the object is not changed, just the way that POV-\discretionary{}{}{}Ray 
 perceives it. When the {\small\texttt{inverse}} keyword is used the \textit{ inside} of the shape is flipped to become the \textit{outside} and vice versa. 
 For example: 


{\small\begin{verbatim}
  object { MyObject inverse }
\end{verbatim}}


   The inside/outside distinction is also important when attaching {\small\texttt{interior}} to an object especially if {\small\texttt{media}} is also used. 
 Atmospheric media and fog also do not work as expected if your camera is inside an object. Using {\small\texttt{inverse}} is useful to correct that problem. 


\subsection{Hollow}

% reference/000198.html

\index{hollow}\index{hollow! object modifier}\index{Object modifiers! hollow}

   POV-\discretionary{}{}{}Ray by default assumes that objects are made of a solid material that completely fills the interior of an object. By adding the {\small\texttt{ hollow}} 
 keyword to the object you can make it hollow, also see the "Empty and Solid Objects" chapter. That is very useful if you want atmospheric effects to 
 exist inside an object. It is even required for objects containing an interior media. The keyword may optionally be followed by a float expression which is 
 interpreted as a boolean value. For example {\small\texttt{hollow off}} may be used to force it off. When the keyword is specified alone, it is the same as {\small\texttt{hollow 
 on}}. By default {\small\texttt{hollow}} is {\small\texttt{off}} when not specified. 



   In order to get a hollow CSG object you just have to make the top level object hollow. All children will assume the same {\small\texttt{ hollow}} state 
 except when their state is explicitly set. The following example will set both spheres inside the union hollow 


{\small\begin{verbatim}
  union {
    sphere { -0.5*x, 1 }
    sphere {  0.5*x, 1 }
    hollow
  }
\end{verbatim}}


   while the next example will only set the second sphere hollow because the first sphere was explicitly set to be not hollow. 


{\small\begin{verbatim}
  union {
    sphere { -0.5*x, 1 hollow off }
    sphere {  0.5*x, 1 }
    hollow on
  }
\end{verbatim}}

\subsection{No\_\-Shadow}

% reference/000197.html

\index{no\_\-shadow}\index{no\_\-shadow! object modifier}\index{Object modifiers! no\_\-shadow}

   You may specify the {\small\texttt{no\_\-shadow}} keyword in an object to make that object cast no shadow. This is useful for special effects and for creating 
 the illusion that a light source actually is visible. This keyword was necessary in earlier versions of POV-\discretionary{}{}{}Ray which did not have the {\small\texttt{ 
 looks\_\-like}} statement. Now it is useful for creating things like laser beams or other unreal effects. During test rendering it speeds things up if {\small\texttt{no\_\-shadow}} 
 is applied. 



   Simply attach the keyword as follows: 


{\small\begin{verbatim}
  object {
    My_Thing
    no_shadow
  }
\end{verbatim}}

\subsection{No\_\-Image, No\_\-Reflection}

% reference/000196.html

\index{no image}\index{no reflection}\index{no\_\-image}\index{no\_\-image! object modifier}\index{Object modifiers! no\_\-image}\index{no\_\-reflection}\index{no\_\-reflection! object modifier}\index{Object modifiers! no\_\-reflection}

   Syntax: 


{\small\begin{verbatim}
  OBJECT {
    [OBJECT_ITEMS...]
    no_image
    no_reflection
  }
\end{verbatim}}


   These two keywords are very similar in usage and function to the {\small\texttt{no\_\-shadow}} keyword, and control an object's visibility. \newline You can use 
 any combination of the three with your object. 



   When {\small\texttt{no\_\-image}} is used, the object will not be seen by the camera, either directly or through transparent/refractive objects. However, it 
 will still cast shadows, and show up in reflections (unless {\small\texttt{no\_\-reflection }} and/or {\small\texttt{no\_\-shadow}} is used also). 



   When {\small\texttt{no\_\-reflection}} is used, the object will not show up in reflections. It will be seen by the camera (and through transparent/refractive 
 objects) and cast shadows, unless {\small\texttt{no\_\-image}} and/or {\small\texttt{no\_\-shadow }} is used. 



   Using these three keywords you can produce interesting effects like a sphere casting a rectangular shadow, a cube that shows up as a cone in mirrors, etc. 


\subsection{Double\_\-Illuminate}

% reference/000195.html

\index{double\_\-illuminate}\index{double\_\-illuminate! object modifier}\index{Object modifiers! double\_\-illuminate}

   Syntax: 


{\small\begin{verbatim}
  OBJECT {
    [OBJECT_ITEMS...]
    double_illuminate
  }
\end{verbatim}}


   A surface has two sides; usually, only the side facing the light source is illuminated, the other side remains in shadow. When {\small\texttt{double\_\-illuminate}} 
 is used, the other side is also illuminated. \newline This is useful for simulating effects like translucency (as in a lamp shade, sheet of paper, etc). 



   \textbf{Note:} {\small\texttt{double\_\-illuminate}} only illuminates both sides of the same surface, so on a sphere, for example, you will not see the effect 
 unless the sphere is either partially transparent, or if the camera is inside and the light source outside of the sphere (or vise versa). 


\subsection{Sturm}

% reference/000194.html

\index{sturm}\index{sturm! object modifier}\index{Object modifiers! sturm}

   Some of POV-\discretionary{}{}{}Ray's objects allow you to choose between a fast but sometimes inaccurate root solver and a slower but more accurate one. This is the case for 
 all objects that involve the solution of a cubic or quartic polynomial. There are analytic mathematical solutions for those polynomials that can be used. 



   Lower order polynomials are trivial to solve while higher order polynomials require iterative algorithms to solve them. One of those algorithms is the 
 Sturmian root solver. For example: 


{\small\begin{verbatim}
  blob {
    threshold .65
    sphere { <.5,0,0>, .8, 1 }
    sphere { <-.5,0,0>,.8, 1 }
    sturm
  }

\end{verbatim}}


   The keyword may optionally be followed by a float expression which is interpreted as a boolean value. For example {\small\texttt{sturm off}} may be used to 
 force it off. When the keyword is specified alone, it is the same as {\small\texttt{sturm on}}. By default {\small\texttt{sturm}} is {\small\texttt{off}} when 
 not specified. 



   The following list shows all objects for which the Sturmian root solver can be used. 


\begin{itemize}
 
 \item 
   blob 
 

 \item 
   cubic 
 

 \item 
   lathe (only with quadratic splines) 
 

 \item 
   poly 
 

 \item 
   prism (only with cubic splines) 
 

 \item 
   quartic 
 

 \item 
   sor 
 

\end{itemize}

\clearpage \chapter{Textures}

% reference/000180.html

\index{texture}\index{texture! keyword}\index{Keyword! texture}\index{material\_\-map! texture}\index{Keyword! material\_\-map}\index{texture\_\-map! texture}\index{Keyword! texture\_\-map}

   The {\small\texttt{texture}} statement is an object modifier which describes what the surface of an object looks like, \discretionary{i.}{}{i.}e. its material. Textures are 
 combinations of pigments, normals, and finishes. Pigment is the color or pattern of colors inherent in the material. Normal is a method of simulating various 
 patterns of bumps, dents, ripples or waves by modifying the surface normal vector. Finish describes the reflective properties of a material. 



   \textbf{Note:} that in previous versions of POV-\discretionary{}{}{}Ray, the texture also contained information about the interior of an object. This information has been moved 
 to a separate object modifier called {\small\texttt{interior}}. See "Interior" for details. 



   There are three basic kinds of textures: plain, patterned, and layered. A \textit{plain texture} consists of a single pigment, an optional normal, and a 
 single finish. A \textit{patterned texture} combines two or more textures using a block pattern or blending function pattern. Patterned textures may be made 
 quite complex by nesting patterns within patterns. At the innermost levels however, they are made up from plain textures. A \textit{layered texture} consists 
 of two or more semi-\discretionary{}{}{}transparent textures layered on top of one another. 



   \textbf{Note:} although we call a plain texture \textit{plain} it may be a very complex texture with patterned pigments and normals. The term \textit{plain} 
 only means that it has a single pigment, normal, and finish. 



   The syntax for {\small\texttt{texture}} is as follows: 


{\small\begin{verbatim}
TEXTURE:
    PLAIN_TEXTURE | PATTERNED_TEXTURE | LAYERED_TEXTURE
PLAIN_TEXTURE:
    texture
    {
        [TEXTURE_IDENTIFIER]
        [PNF_IDENTIFIER...]
        [PNF_ITEMS...]
    }
PNF_IDENTIFIER:
    PIGMENT_IDENTIFIER | NORMAL_IDENTIFIER | FINISH_IDENTIFIER
PNF_ITEMS:
    PIGMENT | NORMAL | FINISH | TRANSFORMATION
LAYERED_TEXTURE:
    NON_PATTERNED_TEXTURE...
PATTERNED_TEXTURE:
    texture
    {
        [PATTERNED_TEXTURE_ID]
        [TRANSFORMATIONS...]
    } |
    texture
    {
        PATTERN_TYPE
        [TEXTURE_PATTERN_MODIFIERS...]
    } |
    texture
    {
        tiles TEXTURE tile2 TEXTURE
        [TRANSFORMATIONS...]
    } |
    texture
    {
        material_map
        {
            BITMAP_TYPE "bitmap.ext"
            [MATERIAL_MODS...] TEXTURE... [TRANSFORMATIONS...]
        }
    }
TEXTURE_PATTERN_MODIFIER:
    PATTERN_MODIFIER | TEXTURE_LIST |
    texture_map { TEXTURE_MAP_BODY }
\end{verbatim}}


   In the \textit{PLAIN\_\-TEXTURE}, each of the items are optional but if they are present the \textit{TEXTURE\_\-IDENTIFIER} must be first. If no texture identifier 
 is given, then POV-\discretionary{}{}{}Ray creates a copy of the default texture. See "The \#default Directive" for details. 



   Next are optional pigment, normal, and/or finish identifiers which fully override any pigment, normal and finish already specified in the previous texture 
 identifier or default texture. Typically this is used for backward compatibility to allow things like: {\small\texttt{texture \{ MyPigment \}}} where {\small\texttt{MyPigment}} 
 is a pigment identifier. 



   Finally we have optional {\small\texttt{pigment}}, {\small\texttt{normal}} or {\small\texttt{finish}} statements which modify any pigment, normal and finish 
 already specified in the identifier. If no texture identifier is specified the {\small\texttt{ pigment}}, {\small\texttt{normal}} and {\small\texttt{finish}} 
 statements modify the current default values. This is the typical plain texture: 


{\small\begin{verbatim}
  texture {
    pigment { MyPigment }
    normal { MyNormal }
    finish { MyFinish }
    scale SoBig
    rotate SoMuch
    translate SoFar
}
\end{verbatim}}


   The \textit{TRANSFORMATIONS} may be interspersed between the pigment, normal and finish statements but are generally specified last. If they are 
 interspersed, then they modify only those parts of the texture already specified. For example: 


{\small\begin{verbatim}
  texture {
    pigment { MyPigment }
    scale SoBig      //affects pigment only
    normal { MyNormal }
    rotate SoMuch    //affects pigment and normal
    finish { MyFinish }
    translate SoFar  //finish is never transformable no matter what.
                     //Therefore affects pigment and normal only
}
\end{verbatim}}


   Texture identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. 
 An identifier is declared as follows. 


{\small\begin{verbatim}
TEXTURE_DECLARATION:
    #declare IDENTIFIER = TEXTURE |
    #local IDENTIFIER = TEXTURE
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{TEXTURE} is any valid {\small\texttt{texture}} statement. See 
 "\#declare vs. \#local" for information on identifier scope. 



   The sections below describe all of the options available in "Pigment", "Normal", and "Finish" which are the main part of plain 
 textures.. There are also separate sections for "Patterned Textures" and "Layered Textures" which are made up of plain textures. 



   \textbf{Note:} the {\small\texttt{tiles}} and {\small\texttt{material\_\-map}} versions of patterned textures are obsolete and are only supported for backwards 
 compatibility. 


\section{Pigment}

% reference/000202.html

\index{pigment}\index{pigment! keyword}\index{Keyword! pigment}\index{image\_\-map! pigment}\index{Keyword! image\_\-map}\index{color\_\-map! pigment}\index{Keyword! color\_\-map}\index{colour\_\-map! pigment}\index{Keyword! colour\_\-map}\index{pigment\_\-map! pigment}\index{Keyword! pigment\_\-map}\index{quick\_\-color! pigment}\index{Keyword! quick\_\-color}\index{quick\_\-colour! pigment}\index{Keyword! quick\_\-colour}

   The color or pattern of colors for an object is defined by a {\small\texttt{ pigment}} statement. All plain textures must have a pigment. If you do not 
 specify one the default pigment is used. The color you define is the way you want the object to look if fully illuminated. You pick the basic color inherent 
 in the object and POV-\discretionary{}{}{}Ray brightens or darkens it depending on the lighting in the scene. The parameter is called {\small\texttt{pigment}} because we are 
 defining the basic color the object actually is rather than how it looks. 



   The syntax for pigment is: 


{\small\begin{verbatim}
PIGMENT:
    pigment {
        [PIGMENT_IDENTIFIER]
        [PIGMENT_TYPE]
        [PIGMENT_MODIFIER...]
    }
PIGMENT_TYPE:
    PATTERN_TYPE | COLOR |
    image_map { 
        BITMAP_TYPE "bitmap.ext" [IMAGE_MAP_MODS...]
    }
PIGMENT_MODIFIER:
    PATTERN_MODIFIER | COLOR_LIST | PIGMENT_LIST | 
    color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } | 
    pigment_map { PIGMENT_MAP_BODY } | quick_color COLOR |
    quick_colour COLOR
\end{verbatim}}


   Each of the items in a pigment are optional but if they are present, they must be in the order shown. Any items after the \textit{ PIGMENT\_\-IDENTIFIER} modify 
 or override settings given in the identifier. If no identifier is specified then the items modify the pigment values in the current default texture. The \textit{PIGMENT\_\-TYPE} 
 fall into roughly four categories. Each category is discussed the sub-\discretionary{}{}{}sections which follow. The four categories are solid color and image map patterns which 
 are specific to {\small\texttt{pigment}} statements or color list patterns, color mapped patterns which use POV-\discretionary{}{}{}Ray's wide selection of general patterns. See 
 "Patterns" for details about specific patterns. 



   The pattern type is optionally followed by one or more pigment modifiers. In addition to general pattern modifiers such as transformations, turbulence, and 
 warp modifiers, pigments may also have a \textit{COLOR\_\-LIST}, \textit{ PIGMENT\_\-LIST}, {\small\texttt{color\_\-map}}, {\small\texttt{pigment\_\-map}}, and {\small\texttt{quick\_\-color}} 
 which are specific to pigments. See "Pattern Modifiers" for information on general modifiers. The pigment-\discretionary{}{}{}specific modifiers are described in 
 sub-\discretionary{}{}{}sections which follow. Pigment modifiers of any kind apply only to the pigment and not to other parts of the texture. Modifiers must 
 be specified last. 



   A pigment statement is part of a {\small\texttt{texture}} specification. However it can be tedious to use a {\small\texttt{texture}} statement just to add a 
 color to an object. Therefore you may attach a pigment directly to an object without explicitly specifying that it as part of a texture. For example instead 
 of this: 


{\small\begin{verbatim}
  object { My_Object texture {pigment { color Red } } }
\end{verbatim}}


   you may shorten it to: 


{\small\begin{verbatim}
  object { My_Object pigment {color Red } }
\end{verbatim}}


   Doing so creates an entire {\small\texttt{texture}} structure with default {\small\texttt{normal}} and {\small\texttt{finish}} statements just as if you had 
 explicitly typed the full {\small\texttt{ texture \{...\}}} around it. 



   Pigment identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. 
 An identifier is declared as follows. 


{\small\begin{verbatim}
PIGMENT_DECLARATION:
    #declare IDENTIFIER = PIGMENT |
    #local IDENTIFIER = PIGMENT
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{PIGMENT} is any valid {\small\texttt{pigment}} statement. See 
 "\#declare vs. \#local" for information on identifier scope. 


\subsection{Solid Color Pigments}

% reference/000225.html

\index{Pigments! solid color}

   The simplest type of pigment is a solid color. To specify a solid color you simply put a color specification inside a {\small\texttt{pigment}} statement. For 
 example: 


{\small\begin{verbatim}
  pigment { color Orange }
\end{verbatim}}


   A color specification consists of the optional keyword {\small\texttt{ color}} followed by a color identifier or by a specification of the amount of red, 
 green, blue, filtered and unfiltered transparency in the surface. See section "Specifying Colors" for more details about colors. Any pattern 
 modifiers used with a solid color are ignored because there is no pattern to modify. 


\subsection{Color List Pigments}

% reference/000233.html

\index{Pigments! color list}

   There are four color list patterns: {\small\texttt{checker}}, {\small\texttt{ hexagon}}, {\small\texttt{brick}} and {\small\texttt{object}}. The result is a 
 pattern of solid colors with distinct edges rather than a blending of colors as with color mapped patterns. Each of these patterns is covered in more detail 
 in a later section. The syntax is: 


{\small\begin{verbatim}
COLOR_LIST_PIGMENT:
  pigment {brick [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...] }|
  pigment {checker [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...]}|
  pigment { 
     hexagon [COLOR_1, [COLOR_2, [COLOR_3]]] [PIGMENT_MODIFIERS...] 
  }|
  pigment {object OBJECT_IDENTIFIER | OBJECT {} [COLOR_1, COLOR_2]}
\end{verbatim}}


   Each \textit{COLOR\_\-n} is any valid color specification. There should be a comma between each color or the {\small\texttt{color}} keyword should be used as a 
 separator so that POV-\discretionary{}{}{}Ray can determine where each color specification starts and ends. The {\small\texttt{brick}} and {\small\texttt{checker}} pattern 
 expects two colors and {\small\texttt{hexagon}} expects three. If an insufficient number of colors is specified then default colors are used. 


\subsection{Color Maps}

% reference/000232.html

\index{Pigments! color maps}\index{color\_\-map}\index{colour\_\-map}

   Most of the color patterns do not use abrupt color changes of just two or three colors like those in the brick, checker or hexagon patterns. They instead use 
 smooth transitions of many colors that gradually change from one point to the next. The colors are defined in a pigment modifier called a {\small\texttt{color\_\-map}} 
 that describes how the pattern blends from one color to the next. 



   Each of the various pattern types available is in fact a mathematical function that takes any x, y, z location and turns it into a number between 0.0 and 1.0 
 inclusive. That number is used to specify what mix of colors to use from the color map. 



   The syntax for {\small\texttt{ color\_\-map}} is as follows: 


{\small\begin{verbatim}
COLOR_MAP:
    color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY }
COLOR_MAP_BODY:
    COLOR_MAP_IDENTIFIER | COLOR_MAP_ENTRY...
COLOR_MAP_ENTRY:
    [ Value COLOR ] | 
    [ Value_1, Value_2 color COLOR_1 color COLOR_2 ]
\end{verbatim}}


   Where each \textit{{\small\texttt{Value\_\-n}}} is a float values between 0.0 and 1.0 inclusive and each \textit{COLOR\_\-n}, is color specifications. 



   \textbf{Note:} the {\small\texttt{[]}} brackets are part of the actual \textit{ COLOR\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional parts. 
 The brackets surround each entry in the color map. 



   There may be from 2 to 256 entries in the map. The alternate spelling {\small\texttt{colour\_\-map}} may be used. 



   Here is an example: 


{\small\begin{verbatim}
  sphere {
    <0,1,2>, 2
    pigment {
      gradient x       //this is the PATTERN_TYPE
      color_map {
        [0.1  color Red]
        [0.3  color Yellow]
        [0.6  color Blue]
        [0.6  color Green]
        [0.8  color Cyan]
      }
    }
  }
\end{verbatim}}


   The pattern function {\small\texttt{gradient x}} is evaluated and the result is a value from 0.0 to 1.0. If the value is less than the first entry (in this 
 case 0.1) then the first color (red) is used. Values from 0.1 to 0.3 use a blend of red and yellow using linear interpolation of the two colors. Similarly 
 values from 0.3 to 0.6 blend from yellow to blue. 



   The 3rd and 4th entries both have values of 0.6. This causes an immediate abrupt shift of color from blue to green. Specifically a value that is less than 
 0.6 will be blue but exactly equal to 0.6 will be green. Moving along, values from 0.6 to 0.8 will be a blend of green and cyan. Finally any value greater 
 than or equal to 0.8 will be cyan. 



   If you want areas of unchanging color you simply specify the same color for two adjacent entries. For example: 


{\small\begin{verbatim}
  color_map {
    [0.1  color Red]
    [0.3  color Yellow]
    [0.6  color Yellow]
    [0.8  color Green]
  }
\end{verbatim}}


   In this case any value from 0.3 to 0.6 will be pure yellow. 



   The first syntax version of \textit{COLOR\_\-MAP\_\-ENTRY} with one float and one color is the current standard. The other double entry version is obsolete and 
 should be avoided. The previous example would look as follows using the old syntax. 


{\small\begin{verbatim}
  color_map {
    [0.0 0.1  color Red color Red]
    [0.1 0.3  color Red color Yellow]
    [0.3 0.6  color Yellow color Yellow]
    [0.6.0.8  color Yellow color Green]
    [0.8 1.0  color Green color Green]
  }
\end{verbatim}}


   You may use {\small\texttt{color\_\-map}} with any patterns except {\small\texttt{ brick}}, {\small\texttt{checker}}, {\small\texttt{hexagon}}, {\small\texttt{object}} 
 and {\small\texttt{ image\_\-map}}. You may declare and use {\small\texttt{color\_\-map}} identifiers. For example: 


{\small\begin{verbatim}
  #declare Rainbow_Colors=
    color_map {
      [0.0   color Magenta]
      [0.33  color Yellow]
      [0.67  color Cyan]
      [1.0   color Magenta]
    }
  object {
    My_Object
    pigment {
      gradient x
      color_map { Rainbow_Colors }
    }
  }
\end{verbatim}}

\subsection{Pigment Maps and Pigment Lists}

% reference/000231.html

\index{Pigments! pigment list}\index{pigment\_\-map}

   In addition to specifying blended colors with a color map you may create a blend of pigments using a {\small\texttt{pigment\_\-map}}. The syntax for a pigment 
 map is identical to a color map except you specify a pigment in each map entry (and not a color). 



   The syntax for {\small\texttt{pigment\_\-map}} is as follows: 


{\small\begin{verbatim}
PIGMENT_MAP:
    pigment_map { PIGMENT_MAP_BODY }
PIGMENT_MAP_BODY:
    PIGMENT_MAP_IDENTIFIER | PIGMENT_MAP_ENTRY...
PIGMENT_MAP_ENTRY:
    [ Value PIGMENT_BODY ]
\end{verbatim}}


   Where \textit{{\small\texttt{Value}}} is a float value between 0.0 and 1.0 inclusive and each \textit{PIGMENT\_\-BODY} is anything which can be inside a {\small\texttt{pigment\{...\}}} 
 statement. The {\small\texttt{pigment}} keyword and {\small\texttt{\{\}}} braces need not be specified. 



   \textbf{Note:} that the {\small\texttt{[]}} brackets are part of the actual \textit{ PIGMENT\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional 
 parts. The brackets surround each entry in the pigment map. 



   There may be from 2 to 256 entries in the map. 



   For example 


{\small\begin{verbatim}
  sphere {
    <0,1,2>, 2
    pigment {
      gradient x       //this is the PATTERN_TYPE
      pigment_map {
        [0.3 wood scale 0.2]
        [0.3 Jade]    //this is a pigment identifier
        [0.6 Jade]
        [0.9 marble turbulence 1]
      }
    }
  }
\end{verbatim}}


   When the {\small\texttt{gradient x}} function returns values from 0.0 to 0.3 the scaled wood pigment is used. From 0.3 to 0.6 the pigment identifier Jade is 
 used. From 0.6 up to 0.9 a blend of Jade and a turbulent marble is used. From 0.9 on up only the turbulent marble is used. 



   Pigment maps may be nested to any level of complexity you desire. The pigments in a map may have color maps or pigment maps or any type of pigment you want. 
 Any entry of a pigment map may be a solid color however if all entries are solid colors you should use a {\small\texttt{color\_\-map}} which will render slightly 
 faster. 



   Entire pigments may also be used with the block patterns such as {\small\texttt{ checker}}, {\small\texttt{hexagon}} and {\small\texttt{brick}}. For 
 example... 


{\small\begin{verbatim}
  pigment {
    checker
    pigment { Jade scale .8 }
    pigment { White_Marble scale .5 }
  }
\end{verbatim}}


   \textbf{Note:} that in the case of block patterns the {\small\texttt{pigment}} wrapping is required around the pigment information. 



   A pigment map is also used with the {\small\texttt{average}} pigment type. See "Average" for details. 



   You may not use {\small\texttt{pigment\_\-map}} or individual pigments with an {\small\texttt{image\_\-map}}. See section "Texture Maps" for an 
 alternative way to do this. 



   You may declare and use pigment map identifiers but the only way to declare a pigment block pattern list is to declare a pigment identifier for the entire 
 pigment. 


\subsection{Image Maps}

% reference/000230.html

\index{image\_\-map}

   When all else fails and none of the above pigment pattern types meets your needs you can use an {\small\texttt{image\_\-map}} to wrap a 2-D bit-\discretionary{}{}{}mapped image 
 around your 3-D objects. 


\subsubsection{Specifying an Image Map}

% reference/000229.html



   The syntax for an {\small\texttt{image\_\-map}} is: 


{\small\begin{verbatim}
IMAGE_MAP:
    pigment
    {
        image_map
        {
            [BITMAP_TYPE] "bitmap[.ext]"
            [IMAGE_MAP_MODS...]
        }
        [PIGMENT_MODFIERS...]
    }
BITMAP_TYPE:
    gif | tga | iff | ppm | pgm | png | jpeg | tiff | sys
IMAGE_MAP_MOD:
    map_type Type | once | interpolate Type | 
    filter Palette, Amount | filter all Amount |
    transmit Palette, Amount | transmit all Amount
\end{verbatim}}
\index{gif}\index{tga}\index{iff}\index{ppm}\index{pgm}\index{png}\index{jpeg}\index{tiff}\index{sys! image\_\-map}

   After the optional \textit{BITMAP\_\-TYPE} keyword is a string expression containing the name of a bitmapped image file of the specified type. If the \textit{BITMAP\_\-TYPE} 
 is not given, the same type is expected as the type set for output.\newline  Example: 


{\small\begin{verbatim}
  plane {
    -z,0 
    pigment {
      image_map {png "Eggs.png"}
    }
  }

  plane {
    -z,0 
    pigment {
      image_map {"Eggs"}
    }
  }
\end{verbatim}}


   The second method will look for, and use "\discretionary{Eggs.}{}{Eggs.}png" if the output file type is set to be {\small\texttt{png}} (Output\_\-File\_\-Type=N in INI-\discretionary{}{}{}file or 
 +FN on command line). It is particularly useful when the image used in the {\small\texttt{image\_\-map}} is also rendered with POV-\discretionary{}{}{}Ray. 



   Several optional modifiers may follow the file specification. The modifiers are described below. 



   \textbf{Note:} earlier versions of POV-\discretionary{}{}{}Ray allowed some modifiers before the \textit{BITMAP\_\-TYPE} but that syntax is being phased out in favor of the syntax 
 described here. 



   \textbf{Note:} {\small\texttt{sys}} format is a system-\discretionary{}{}{}specific format such as BMP for Windows or Pict for Macintosh. 



   Filenames specified in the {\small\texttt{image\_\-map}} statements will be searched for in the home (current) directory first and, if not found, will then be 
 searched for in directories specified by any {\small\texttt{+L}} or {\small\texttt{ Library\_\-Path}} options active. This would facilitate keeping all your 
 image maps files in a separate subdirectory and giving a {\small\texttt{ Library\_\-Path}} option to specify where your library of image maps are. See "Library 
 Paths" for details. 



   By default, the image is mapped onto the x-\discretionary{}{}{}y-\discretionary{}{}{}plane. The image is \textit{ projected} onto the object as though there were a slide projector somewhere in the 
 -z-\discretionary{}{}{}direction. The image exactly fills the square area from (\discretionary{x,}{}{x,}y) coordinates (\discretionary{0,}{}{0,}0) to (\discretionary{1,}{}{1,}1) regardless of the image's original size in 
 pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired. 



   In the section "Checker", the {\small\texttt{checker}} pigment pattern is explained. The checks are described as solid cubes of colored clay from 
 which objects are carved. With image maps you should imagine that each pixel is a long, thin, square, colored rod that extends parallel to the z-\discretionary{}{}{}axis. The 
 image is made from rows and columns of these rods bundled together and the object is then carved from the bundle. 



   If you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as 
 desired. 



   The file name is optionally followed by one or more \textit{ BITMAP\_\-MODIFIERS}. The {\small\texttt{ filter}}, {\small\texttt{filter all}}, {\small\texttt{transmit}}, 
 and {\small\texttt{ transmit all}} modifiers are specific to image maps and are discussed in the following sections. An {\small\texttt{ image\_\-map}} may also 
 use generic bitmap modifiers {\small\texttt{map\_\-type}}, {\small\texttt{once}} and {\small\texttt{ interpolate}} described in "Bitmap Modifiers" 


\subsubsection{The Filter and Transmit Bitmap Modifiers}

% reference/000228.html

\index{filter! bitmap modfier}\index{transmit! bitmap modifier}\index{all}

   To make all or part of an image map transparent you can specify {\small\texttt{ filter}} and/or {\small\texttt{transmit}} values for the color 
 palette/registers of PNG, GIF or IFF pictures (at least for the modes that use palettes). You can do this by adding the keyword {\small\texttt{filter}} or {\small\texttt{transmit}} 
 following the filename. The keyword is followed by two numbers. The first number is the palette number value and the second is the amount of transparency. The 
 values should be separated by a comma. For example: 


{\small\begin{verbatim}
  image_map {
    gif "mypic.gif"
    filter   0, 0.5 // Make color 0 50\% filtered transparent
    filter   5, 1.0 // Make color 5 100\% filtered transparent
    transmit 8, 0.3 // Make color 8 30\% non-filtered transparent
  }
\end{verbatim}}


   You can give the entire image a {\small\texttt{filter}} or {\small\texttt{ transmit}} value using {\small\texttt{filter all}} \textit{{\small\texttt{ Amount}}} 
 or {\small\texttt{transmit all}} \textit{{\small\texttt{ Amount}}}. For example: 


{\small\begin{verbatim}
  image_map {
    gif "stnglass.gif"
    filter all 0.9
  }
\end{verbatim}}
\index{alpha}

   \textbf{Note:} early versions of POV-\discretionary{}{}{}Ray used the keyword {\small\texttt{alpha}} to specify filtered transparency however that word is often used to describe 
 non-\discretionary{}{}{}filtered transparency. For this reason {\small\texttt{alpha}} is no longer used. 



   See section "Specifying Colors" for details on the differences between filtered and non-\discretionary{}{}{}filtered transparency. 


\subsubsection{Using the Alpha Channel}

% reference/000227.html



   Another way to specify non-\discretionary{}{}{}filtered transmit transparency in an image map is by using the\textit{ alpha channel}. POV-\discretionary{}{}{}Ray will automatically use the alpha 
 channel for transmittance when one is stored in the image. PNG file format allows you to store a different transparency for each color index in the PNG file, 
 if desired. If your paint programs support this feature of PNG you can do the transparency editing within your paint program rather than specifying transmit 
 values for each color in the POV file. Since PNG and TGA image formats can also store full alpha channel (transparency) information you can generate image 
 maps that have transparency which is not dependent on the color of a pixel but rather its location in the image. 



   Although POV uses {\small\texttt{transmit 0.0}} to specify no transparency and {\small\texttt{ 1.0}} to specify full transparency, the alpha data ranges from 
 0 to 255 in the opposite direction. Alpha data 0 means the same as {\small\texttt{ transmit 1.0}} and alpha data 255 produces {\small\texttt{transmit 0.0}}. 


\subsection{Quick Color}

% reference/000226.html

\index{quick\_\-color}\index{quick\_\-colour}

   When developing POV-\discretionary{}{}{}Ray scenes it is often useful to do low quality test runs that render faster. The {\small\texttt{+Q}} command line switch or {\small\texttt{ 
 Quality}} INI option can be used to turn off some time consuming color pattern and lighting calculations to speed things up. See "Quality Settings" 
 for details. However all settings of {\small\texttt{+Q5}} or {\small\texttt{Quality=5}} or lower turns off pigment calculations and creates gray objects. 



   By adding a {\small\texttt{quick\_\-color}} to a pigment you tell POV-\discretionary{}{}{}Ray what solid color to use for quick renders instead of a patterned pigment. For example: 


{\small\begin{verbatim}
  pigment {
    gradient x
    color_map{
      [0.0 color Yellow]
      [0.3 color Cyan]
      [0.6 color Magenta]
      [1.0 color Cyan]
    }
    turbulence 0.5
    lambda 1.5
    omega 0.75
    octaves 8
    quick_color Neon_Pink
  }
\end{verbatim}}


   This tells POV-\discretionary{}{}{}Ray to use solid {\small\texttt{Neon\_\-Pink}} for test runs at quality {\small\texttt{+Q5}} or lower but to use the turbulent gradient pattern 
 for rendering at {\small\texttt{+Q6}} and higher. Solid color pigments such as 


{\small\begin{verbatim}
  pigment {color Magenta}
\end{verbatim}}


   automatically set the {\small\texttt{quick\_\-color}} to that value. You may override this if you want. Suppose you have 10 spheres on the screen and all are 
 yellow. If you want to identify them individually you could give each a different {\small\texttt{quick\_\-color}} like this: 


{\small\begin{verbatim}
  sphere {
    <1,2,3>,4
    pigment { color Yellow  quick_color Red }
  }
  sphere {
    <-1,-2,-3>,4
    pigment { color Yellow  quick_color Blue }
  }
\end{verbatim}}


   and so on. At {\small\texttt{+Q6}} or higher they will all be yellow but at {\small\texttt{+Q5}} or lower each would be different colors so you could 
 identify them. 



   The alternate spelling {\small\texttt{quick\_\-colour}} is also supported. 


\section{Normal}

% reference/000224.html

\index{normal}\index{normal! keyword}\index{Keyword! normal}\index{bump\_\-map! normal}\index{Keyword! bump\_\-map}\index{normal\_\-map! normal}\index{Keyword! normal\_\-map}\index{slope\_\-map! normal}\index{Keyword! slope\_\-map}\index{bump\_\-size! normal}\index{Keyword! bump\_\-size}\index{no\_\-bump\_\-scale! normal}\index{Keyword! no\_\-bump\_\-scale}\index{accuracy! normal}\index{Keyword! accuracy}

   Ray-\discretionary{}{}{}tracing is known for the dramatic way it depicts reflection, refraction and lighting effects. Much of our perception depends on the reflective properties 
 of an object. Ray tracing can exploit this by playing tricks on our perception to make us see complex details that are not really there. 



   Suppose you wanted a very bumpy surface on the object. It would be very difficult to mathematically model lots of bumps. We can however simulate the way 
 bumps look by altering the way light reflects off of the surface. Reflection calculations depend on a vector called a \textit{ surface normal} vector. This is 
 a vector which points away from the surface and is perpendicular to it. By artificially modifying (or perturbing) this normal vector you can simulate bumps. 
 This is done by adding an optional {\small\texttt{ normal}} statement. 



   \textbf{Note:} that attaching a normal pattern does not really modify the surface. It only affects the way light reflects or refracts at the surface so that 
 it looks bumpy. 



   The syntax is: 


{\small\begin{verbatim}
NORMAL:
  normal { [NORMAL_IDENTIFIER] [NORMAL_TYPE] [NORMAL_MODIFIER...] }
NORMAL_TYPE:
  PATTERN_TYPE Amount |
  bump_map { BITMAP_TYPE "bitmap.ext" [BUMP_MAP_MODS...]}
NORMAL_MODIFIER:
  PATTERN_MODIFIER | NORMAL_LIST | normal_map { NORMAL_MAP_BODY } |
  slope_map{ SLOPE_MAP_BODY } | bump_size Amount |
  no_bump_scale Bool | accuracy Float
\end{verbatim}}


   Each of the items in a normal are optional but if they are present, they must be in the order shown. Any items after the \textit{NORMAL\_\-IDENTIFIER} modify or 
 override settings given in the identifier. If no identifier is specified then the items modify the normal values in the current default texture. The \textit{PATTERN\_\-TYPE} 
 may optionally be followed by a float value that controls the apparent depth of the bumps. Typical values range from 0.0 to 1.0 but any value may be used. 
 Negative values invert the pattern. The default value if none is specified is 0.5. 



   There are four basic types of \textit{NORMAL\_\-TYPE}s. They are block pattern normals, continuous pattern normals, specialized normals and bump maps. They 
 differ in the types of modifiers you may use with them. The pattern type is optionally followed by one or more normal modifiers. In addition to general 
 pattern modifiers such as transformations, turbulence, and warp modifiers, normals may also have a \textit{NORMAL\_\-LIST}, {\small\texttt{slope\_\-map}}, {\small\texttt{ 
 normal\_\-map}}, and {\small\texttt{bump\_\-size}} which are specific to normals. See "Pattern Modifiers" for information on general modifiers. The 
 normal-\discretionary{}{}{}specific modifiers are described in sub-\discretionary{}{}{}sections which follow. Normal modifiers of any kind apply only to the normal and not to 
 other parts of the texture. Modifiers must be specified last. 



   Originally POV-\discretionary{}{}{}Ray had some patterns which were exclusively used for pigments while others were exclusively used for normals. Since POV-\discretionary{}{}{}Ray 3.0 you can use 
 any pattern for either pigments or normals. For example it is now valid to use {\small\texttt{ripples}} as a pigment or {\small\texttt{wood}} as a normal 
 type. The patterns {\small\texttt{bumps}}, {\small\texttt{dents}}, {\small\texttt{ ripples}}, {\small\texttt{waves}}, {\small\texttt{ wrinkles}}, and {\small\texttt{ 
 bump\_\-map}} were once exclusively normal patterns which could not be used as pigments. Because these six types use specialized normal modification 
 calculations they cannot have {\small\texttt{ slope\_\-map}}, {\small\texttt{ normal\_\-map}} or wave shape modifiers. All other normal pattern types may use them. 
 Because block patterns {\small\texttt{ checker}}, {\small\texttt{hexagon}}, {\small\texttt{object}} and {\small\texttt{ brick}} do not return a continuous 
 series of values, they cannot use these modifiers either. See "Patterns" for details about specific patterns. 



   A {\small\texttt{ normal}} statement is part of a {\small\texttt{ texture}} specification. However it can be tedious to use a {\small\texttt{ texture}} 
 statement just to add bumps to an object. Therefore you may attach a normal directly to an object without explicitly specifying that it as part of a texture. 
 For example instead of this: 


{\small\begin{verbatim}
  object  {My_Object texture { normal { bumps 0.5 } } }
\end{verbatim}}


   you may shorten it to: 


{\small\begin{verbatim}
  object { My_Object normal { bumps 0.5 } }
\end{verbatim}}


   Doing so creates an entire {\small\texttt{texture}} structure with default {\small\texttt{pigment}} and {\small\texttt{finish}} statements just as if you had 
 explicitly typed the full {\small\texttt{ texture \{...\}}} around it. Normal identifiers may be declared to make scene files more readable and to parameterize 
 scenes so that changing a single declaration changes many values. An identifier is declared as follows. 


{\small\begin{verbatim}
NORMAL_DECLARATION:
    #declare IDENTIFIER = NORMAL |
    #local IDENTIFIER = NORMAL
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{NORMAL} is any valid {\small\texttt{normal}} statement. See 
 "\#declare vs. \#local" for information on identifier scope. 


\subsection{Slope Maps}

% reference/000223.html

\index{slope\_\-map}

   A {\small\texttt{slope\_\-map}} is a normal pattern modifier which gives the user a great deal of control over the exact shape of the bumpy features. Each of 
 the various pattern types available is in fact a mathematical function that takes any x, y, z location and turns it into a number between 0.0 and 1.0 
 inclusive. That number is used to specify where the various high and low spots are. The {\small\texttt{slope\_\-map}} lets you further shape the contours. It is 
 best illustrated with a gradient normal pattern. Suppose you have... 


{\small\begin{verbatim}
  plane{ z, 0
    pigment{ White }
    normal { gradient x }
  }
\end{verbatim}}


   This gives a ramp wave pattern that looks like small linear ramps that climb from the points at x=0 to x=1 and then abruptly drops to 0 again to repeat the 
 ramp from x=1 to x=2. A slope map turns this simple linear ramp into almost any wave shape you want. The syntax is as follows... 


{\small\begin{verbatim}
SLOPE_MAP:
    slope_map { SLOPE_MAP_BODY }
SLOPE_MAP_BODY:
    SLOPE_MAP_IDENTIFIER | SLOPE_MAP_ENTRY...
SLOPE_MAP_ENTRY:
    [ Value, <Height, Slope> ]
\end{verbatim}}


   \textbf{Note:} the {\small\texttt{[]}} brackets are part of the actual \textit{ SLOPE\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional parts. 
 The brackets surround each entry in the slope map. 



   There may be from 2 to 256 entries in the map. 



   Each \textit{{\small\texttt{Value}}} is a float value between 0.0 and 1.0 inclusive and each \textit{{\small\texttt{ $<$Height}}}, \textit{ {\small\texttt{ 
 Slope$>$}}} is a 2 component vector such as $<$\discretionary{0,}{}{0,}1$>$ where the first value represents the apparent height of the wave and the second value represents the 
 slope of the wave at that point. The height should range between 0.0 and 1.0 but any value could be used. 



   The slope value is the change in height per unit of distance. For example a slope of zero means flat, a slope of 1.0 means slope upwards at a 45 degree angle 
 and a slope of -1 means slope down at 45 degrees. Theoretically a slope straight up would have infinite slope. In practice, slope values should be kept in the 
 range -3.0 to +3.0. Keep in mind that this is only the visually apparent slope. A normal does not actually change the surface. 



   For example here is how to make the ramp slope up for the first half and back down on the second half creating a triangle wave with a sharp peak in the 
 center. 


{\small\begin{verbatim}
  normal {
    gradient x       // this is the PATTERN_TYPE
    slope_map {
      [0   <0, 1>]   // start at bottom and slope up
      [0.5 <1, 1>]   // halfway through reach top still climbing
      [0.5 <1,-1>]   // abruptly slope down
      [1   <0,-1>]   // finish on down slope at bottom
    }
  }
\end{verbatim}}


   The pattern function is evaluated and the result is a value from 0.0 to 1.0. The first entry says that at x=0 the apparent height is 0 and the slope is 1. At 
 x=0.5 we are at height 1 and slope is still up at 1. The third entry also specifies that at x=0.5 (actually at some tiny fraction above 0.5) we have height 1 
 but slope -1 which is downwards. Finally at x=1 we are at height 0 again and still sloping down with slope -1. 



   Although this example connects the points using straight lines the shape is actually a cubic spline. This example creates a smooth sine wave. 


{\small\begin{verbatim}
  normal {
    gradient x          // this is the PATTERN_TYPE
    slope_map {
      [0    <0.5, 1>]   // start in middle and slope up
      [0.25 <1.0, 0>]   // flat slope at top of wave
      [0.5  <0.5,-1>]   // slope down at mid point
      [0.75 <0.0, 0>]   // flat slope at bottom
      [1    <0.5, 1>]   // finish in middle and slope up
    }
  }
\end{verbatim}}


   This example starts at height 0.5 sloping up at slope 1. At a fourth of the way through we are at the top of the curve at height 1 with slope 0 which is 
 flat. The space between these two is a gentle curve because the start and end slopes are different. At half way we are at half height sloping down to bottom 
 out at 3/4ths. By the end we are climbing at slope 1 again to complete the cycle. There are more examples in {\small\texttt{ \discretionary{slopemap.}{}{slopemap.}pov}} in the sample 
 scenes. 



   A {\small\texttt{slope\_\-map}} may be used with any pattern except {\small\texttt{ brick}}, {\small\texttt{checker}}, {\small\texttt{object}}, {\small\texttt{hexagon}}, 
 {\small\texttt{ bumps}}, {\small\texttt{dents}}, {\small\texttt{ ripples}}, {\small\texttt{waves}}, {\small\texttt{ wrinkles}} and {\small\texttt{ bump\_\-map}}. 



   You may declare and use slope map identifiers. For example: 


{\small\begin{verbatim}
  #declare Fancy_Wave =
    slope_map {       // Now let's get fancy
      [0.0  <0, 1>]   // Do tiny triangle here
      [0.2  <1, 1>]   //  down
      [0.2  <1,-1>]   //     to
      [0.4  <0,-1>]   //       here.
      [0.4  <0, 0>]   // Flat area
      [0.5  <0, 0>]   //   through here.
      [0.5  <1, 0>]   // Square wave leading edge
      [0.6  <1, 0>]   //   trailing edge
      [0.6  <0, 0>]   // Flat again
      [0.7  <0, 0>]   //   through here.
      [0.7  <0, 3>]   // Start scallop
      [0.8  <1, 0>]   //   flat on top
      [0.9  <0,-3>]   //     finish here.
      [0.9  <0, 0>]   // Flat remaining through 1.0
    }
  object{ My_Object
    pigment { White }
    normal {
      wood
      slope_map { Fancy_Wave }
    }
  }
\end{verbatim}}

\subsubsection{Normals, Accuracy}

% reference/000222.html

\index{accuracy! normals}

   Surface normals that use patterns that were not designed for use with normals (anything other than bumps, dents, waves, ripples, and wrinkles) uses a {\small\texttt{slope\_\-map}} 
 whether you specify one or not. To create a perturbed normal from a pattern, POV-\discretionary{}{}{}Ray samples the pattern at four points in a pyramid surrounding the desired 
 point to determine the gradient of the pattern at the center of the pyramid. The distance that these points are from the center point determines the accuracy 
 of the approximation. Using points too close together causes floating-\discretionary{}{}{}point inaccuracies. However, using points too far apart can lead to artefacts as well as 
 smoothing out features that should not be smooth. 



   Usually, points very close together are desired. POV-\discretionary{}{}{}Ray currently uses a delta or accuracy distance of 0.02. Sometimes it is necessary to decrease this 
 value to get better accuracy if you are viewing a close-\discretionary{}{}{}up of the texture. Other times, it is nice to increase this value to smooth out sharp edges in the 
 normal (for example, when using a 'solid' crackle pattern). For this reason, a new property, {\small\texttt{accuracy}}, has been added to normals. It only 
 makes a difference if the normal uses a {\small\texttt{slope\_\-map}} (either specified or implied). 



   You can specify the value of this accuracy (which is the distance between the sample points when determining the gradient of the pattern for slope\_\-map) by 
 adding {\small\texttt{accuracy $<$float$>$}} to your normal. For all patterns, the default is 0.02. 


\subsection{Normal Maps and Normal Lists}

% reference/000221.html

\index{normal\_\-map}

   Most of the time you will apply single normal pattern to an entire surface but you may also create a pattern or blend of normals using a {\small\texttt{ 
 normal\_\-map}}. The syntax for a {\small\texttt{normal\_\-map}} is identical to a {\small\texttt{pigment\_\-map}} except you specify a {\small\texttt{ normal}} in 
 each map entry. The syntax for {\small\texttt{normal\_\-map}} is as follows: 


{\small\begin{verbatim}
NORMAL_MAP:
    normal_map { NORMAL_MAP_BODY }
NORMAL_MAP_BODY:
    NORMAL_MAP_IDENTIFIER | NORMAL_MAP_ENTRY...
NORMAL_MAP_ENTRY:
    [ Value NORMAL_BODY ]
\end{verbatim}}


   Where \textit{{\small\texttt{Value}}} is a float value between 0.0 and 1.0 inclusive and each \textit{NORMAL\_\-BODY} is anything which can be inside a {\small\texttt{normal\{...\}}} 
 statement. The {\small\texttt{normal}} keyword and {\small\texttt{\{\}}} braces need not be specified. 



   \textbf{Note:} that the {\small\texttt{[]}} brackets are part of the actual \textit{ NORMAL\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional 
 parts. The brackets surround each entry in the normal map. 



   There may be from 2 to 256 entries in the map. 



   For example 


{\small\begin{verbatim}
  normal {
    gradient x       //this is the PATTERN_TYPE
    normal_map {
      [0.3  bumps scale 2]
      [0.3  dents]
      [0.6  dents]
      [0.9  marble turbulence 1]
    }
  }
\end{verbatim}}


   When the {\small\texttt{gradient x}} function returns values from 0.0 to 0.3 then the scaled bumps normal is used. From 0.3 to 0.6 dents pattern is used. 
 From 0.6 up to 0.9 a blend of dents and a turbulent marble is used. From 0.9 on up only the turbulent marble is used. 



   Normal maps may be nested to any level of complexity you desire. The normals in a map may have slope maps or normal maps or any type of normal you want. 



   A normal map is also used with the {\small\texttt{average}} normal type. See "Average" for details. 



   Entire normals in a normal list may also be used with the block patterns such as {\small\texttt{checker}}, {\small\texttt{hexagon}} and {\small\texttt{brick}}. 
 For example... 


{\small\begin{verbatim}
  normal {
    checker
    normal { gradient x scale .2 }
    normal { gradient y scale .2 }
  }
\end{verbatim}}


   \textbf{Note:} in the case of block patterns the {\small\texttt{normal}} wrapping is required around the normal information. 



   You may not use {\small\texttt{ normal\_\-map}} or individual normals with a {\small\texttt{ bump\_\-map}}. See section "Texture Maps" for an alternative 
 way to do this. 



   You may declare and use normal map identifiers but the only way to declare a normal block pattern list is to declare a normal identifier for the entire 
 normal. 


\subsection{Bump Maps}

% reference/000220.html

\index{bump\_\-map}

   When all else fails and none of the above normal pattern types meets your needs you can use a {\small\texttt{bump\_\-map}} to wrap a 2-D bit-\discretionary{}{}{}mapped bump pattern 
 around your 3-D objects. 



   Instead of placing the color of the image on the shape like an {\small\texttt{ image\_\-map}} a {\small\texttt{bump\_\-map}} perturbs the surface normal based on 
 the color of the image at that point. The result looks like the image has been embossed into the surface. By default, a bump map uses the brightness of the 
 actual color of the pixel. Colors are converted to gray scale internally before calculating height. Black is a low spot, white is a high spot. The image's 
 index values may be used instead (see section "Use\_\-Index and Use\_\-Color" below). 


\subsubsection{Specifying a Bump Map}

% reference/000235.html



   The syntax for a {\small\texttt{bump\_\-map}} is: 


{\small\begin{verbatim}
BUMP_MAP:
    normal
    {
        bump_map
        {
            BITMAP_TYPE "bitmap.ext"
            [BUMP_MAP_MODS...]
        }
        [NORMAL_MODFIERS...]
    }
BITMAP_TYPE:
    gif | tga | iff | ppm | pgm | png | jpeg | tiff | sys
BUMP_MAP_MOD:
    map_type Type | once | interpolate Type | use_color | 
    use_colour | bump_size Value
\end{verbatim}}


   After the required \textit{BITMAP\_\-TYPE} keyword is a string expression containing the name of a bitmapped bump file of the specified type. Several optional 
 modifiers may follow the file specification. The modifiers are described below. 



   \textbf{Note:} earlier versions of POV-\discretionary{}{}{}Ray allowed some modifiers before the \textit{BITMAP\_\-TYPE} but that syntax is being phased out in favor of the syntax 
 described here. 



   \textbf{Note:} {\small\texttt{sys}} format is a system-\discretionary{}{}{}specific format such as BMP for Windows or Pict for Macintosh. 



   Filenames specified in the {\small\texttt{bump\_\-map}} statements will be searched for in the home (current) directory first and, if not found, will then be 
 searched for in directories specified by any {\small\texttt{+L}} or {\small\texttt{ Library\_\-Path}} options active. This would facilitate keeping all your bump 
 maps files in a separate subdirectory and giving a {\small\texttt{ Library\_\-Path}} option to specify where your library of bump maps are. See "Library 
 Paths" for details. 



   By default, the bump pattern is mapped onto the x-\discretionary{}{}{}y-\discretionary{}{}{}plane. The bump pattern is \textit{projected} onto the object as though there were a slide projector 
 somewhere in the -z-\discretionary{}{}{}direction. The pattern exactly fills the square area from (\discretionary{x,}{}{x,}y) coordinates (\discretionary{0,}{}{0,}0) to (\discretionary{1,}{}{1,}1) regardless of the pattern's original size in 
 pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired. If 
 you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired. 



   The file name is optionally followed by one or more \textit{ BITMAP\_\-MODIFIERS}. The {\small\texttt{bump\_\-size}}, {\small\texttt{ use\_\-color}} and {\small\texttt{ 
 use\_\-index}} modifiers are specific to bump maps and are discussed in the following sections. See section "Bitmap Modifiers" for the generic 
 bitmap modifiers {\small\texttt{map\_\-type}}, {\small\texttt{once}} and {\small\texttt{ interpolate}} described in "Bitmap Modifiers" 


\subsubsection{Bump\_\-Size}

% reference/000236.html

\index{bump\_\-size}

   The relative bump size can be scaled using the {\small\texttt{bump\_\-size}} modifier. The bump size number can be any number other than 0 but typical values 
 are from about 0.1 to as high as 4.0 or 5.0. 


{\small\begin{verbatim}
  normal {
    bump_map {
      gif "stuff.gif"
      bump_size 5.0
    }
  }
\end{verbatim}}


   Originally {\small\texttt{bump\_\-size}} could only be used inside a bump map but it can now be used with any normal. Typically it is used to override a 
 previously defined size. For example: 


{\small\begin{verbatim}
  normal {
    My_Normal   //this is a previously defined normal identifier
    bump_size 2.0
  }
\end{verbatim}}

\subsubsection{Use\_\-Index and Use\_\-Color}

% reference/000234.html

\index{use\_\-index}\index{use\_\-color}\index{use\_\-colour}

   Usually the bump map converts the color of the pixel in the map to a gray scale intensity value in the range 0.0 to 1.0 and calculates the bumps based on 
 that value. If you specify {\small\texttt{use\_\-index}}, the bump map uses the color's palette number to compute as the height of the bump at that point. So, 
 color number 0 would be low and color number 255 would be high (if the image has 256 palette entries). The actual color of the pixels doesn't matter when 
 using the index. This option is only available on palette based formats. The {\small\texttt{use\_\-color}} keyword may be specified to explicitly note that the 
 color methods should be used instead. The alternate spelling {\small\texttt{use\_\-colour}} is also valid. These modifiers may only be used inside the {\small\texttt{bump\_\-map}} 
 statement. 


\subsection{Scaling normals}

% reference/000219.html

\index{no\_\-bump\_\-scale}

   When scaling a normal, or when scaling an object after a normal is applied to it, the depth of the normal is affected by the scaling. This is not always 
 wanted. If you want to turn off bump scaling for a texture or normal, you can do this by adding the keyword {\small\texttt{no\_\-bump\_\-scale}} to the texture's or 
 normal's modifiers. This modifier will get passed on to all textures or normals contained in that texture or normal. Think of this like the way no\_\-shadow gets 
 passed on to objects contained in a CSG. 



   It is also important to note that if you add {\small\texttt{no\_\-bump\_\-scale}} to a normal or texture that is contained within another pattern (such as within a {\small\texttt{texture\_\-map}} 
 or {\small\texttt{normal\_\-map}}), then the only scaling that will be ignored is the scaling of that texture or normal. Scaling of the parent texture or normal 
 or of the object will affect the depth of the bumps, unless {\small\texttt{no\_\-bump\_\-scale}} is specified at the top-\discretionary{}{}{}level of the texture (or normal, if the 
 normal is not wrapped in a texture). 


\section{Finish}

% reference/000218.html

\index{finish}\index{finish! keyword}\index{Keyword! finish}\index{ambient! finish}\index{Keyword! ambient}\index{diffuse! finish}\index{Keyword! diffuse}\index{brilliance! finish}\index{Keyword! brilliance}\index{phong! finish}\index{Keyword! phong}\index{phong\_\-size! finish}\index{Keyword! phong\_\-size}\index{specular! finish}\index{Keyword! specular}\index{roughness! finish}\index{Keyword! roughness}\index{metallic! finish}\index{Keyword! metallic}\index{crand! finish}\index{Keyword! crand}\index{conserve\_\-energy! finish}\index{Keyword! conserve\_\-energy}\index{irid! finish}\index{Keyword! irid}\index{fresnel! finish}\index{Keyword! fresnel}\index{falloff! finish}\index{Keyword! falloff}\index{exponent! finish}\index{Keyword! exponent}\index{thickness! finish}\index{Keyword! thickness}\index{turbulence! finish}\index{Keyword! turbulence}

   The finish properties of a surface can greatly affect its appearance. How does light reflect? What happens in shadows? What kind of highlights are visible. 
 To answer these questions you need a {\small\texttt{finish}}. 



   The syntax for {\small\texttt{finish}} is as follows:\index{ambient} 


{\small\begin{verbatim}
FINISH:
    finish { [FINISH_IDENTIFIER] [FINISH_ITEMS...] }
FINISH_ITEMS:
    ambient COLOR | diffuse Amount | brilliance Amount |
    phong Amount | phong_size Amount | specular Amount |
    roughness Amount | metallic [Amount] | reflection COLOR |
    crand Amount | conserve_energy BOOL_ON_OF |
    reflection { Color_Reflecting_Min [REFLECTION_ITEMS...] }|
    irid { Irid_Amount [IRID_ITEMS...] }
REFLECTION_ITEMS:
    COLOR_REFLECTION_MAX | fresnel BOOL_ON_OFF |
    falloff FLOAT_FALLOFF | exponent FLOAT_EXPONENT |
    metallic FLOAT_METALLIC
IRID_ITEMS:
    thickness Amount | turbulence Amount
\end{verbatim}}


   The \textit{FINISH\_\-IDENTIFIER} is optional but should proceed all other items. Any items after the \textit{FINISH\_\-IDENTIFIER} modify or override settings 
 given in the \textit{FINISH\_\-IDENTIFIER}. If no identifier is specified then the items modify the finish values in the current default texture. 



   \textbf{Note:} transformations are not allowed inside a finish because finish items cover the entire surface uniformly. Each of the \textit{ FINISH\_\-ITEMS} 
 listed above is described in sub-\discretionary{}{}{}sections below. 



   In earlier versions of POV-\discretionary{}{}{}Ray, the {\small\texttt{refraction}}, {\small\texttt{ ior}}, and {\small\texttt{caustics}} keywords were part of the {\small\texttt{ 
 finish}} statement but they are now part of the {\small\texttt{interior}} statement. They are still supported under {\small\texttt{finish}} for backward 
 compatibility but the results may not be 100\% identical to previous versions. See "Why are Interior and Media Necessary?" for details. 



   A {\small\texttt{finish}} statement is part of a {\small\texttt{texture}} specification. However it can be tedious to use a {\small\texttt{texture}} 
 statement just to add a highlights or other lighting properties to an object. Therefore you may attach a finish directly to an object without explicitly 
 specifying that it as part of a texture. For example instead of this: 


{\small\begin{verbatim}
  object { My_Object texture { finish { phong 0.5 } } }
\end{verbatim}}


   you may shorten it to: 


{\small\begin{verbatim}
  object { My_Object finish { phong 0.5 } }
\end{verbatim}}


   Doing so creates an entire {\small\texttt{texture}} structure with default {\small\texttt{pigment}} and {\small\texttt{normal}} statements just as if you had 
 explicitly typed the full {\small\texttt{ texture \{...\}}} around it. 



   Finish identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An 
 identifier is declared as follows. 


{\small\begin{verbatim}
FINISH_DECLARATION:
    #declare IDENTIFIER = FINISH |
    #local IDENTIFIER = FINISH
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{FINISH} is any valid {\small\texttt{finish}} statement. See 
 "\#declare vs. \#local" for information on identifier scope. 


\subsection{Ambient}

% reference/000217.html



   The light you see in dark shadowed areas comes from diffuse reflection off of other objects. This light cannot be directly modeled using ray-\discretionary{}{}{}tracing. However 
 we can use a trick called \textit{ambient lighting} to simulate the light inside a shadowed area. 



   Ambient light is light that is scattered everywhere in the room. It bounces all over the place and manages to light objects up a bit even where no light is 
 directly shining. Computing real ambient light would take far too much time, so we simulate ambient light by adding a small amount of white light to each 
 texture whether or not a light is actually shining on that texture. 



   This means that the portions of a shape that are completely in shadow will still have a little bit of their surface color. It is almost as if the texture 
 glows, though the ambient light in a texture only affects the shape it is used on. 



   The {\small\texttt{ambient}} keyword controls the amount of ambient light. Usually a single float value is specified even though the syntax calls for a 
 color. For example a float value of {\small\texttt{0.3}} gets promoted to the full color vector {\small\texttt{ $<$0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.3$>$}} which is 
 acceptable because only the red, green and blue parts are used. 



   The default value is 0.1 which gives very little ambient light. The value can range from 0.0 to 1.0. Ambient light affects both shadowed and non-\discretionary{}{}{}shadowed 
 areas so if you turn up the {\small\texttt{ ambient}} value you may want to turn down the {\small\texttt{diffuse}} and {\small\texttt{reflection}} values. 



   \textbf{Note:} that this method does not account for the color of surrounding objects. If you walk into a room that has red walls, floor and ceiling then 
 your white clothing will look pink from the reflected light. POV-\discretionary{}{}{}Ray's ambient shortcut does not account for this. There is also no way to model specular 
 reflected indirect illumination such as the flashlight shining in a mirror. 



   You may color the ambient light using one of two methods. You may specify a color rather than a float after the ambient keyword in each finish statement. For 
 example 


{\small\begin{verbatim}
   finish { ambient rgb <0.3,0.1,0.1> } //a pink ambient
\end{verbatim}}


   You may also specify the overall ambient light source used when calculating the ambient lighting of an object using the global {\small\texttt{ ambient\_\-light}} 
 setting. The formula is given by \textit{ Ambient = Finish\_\-Ambient * Global\_\-Ambient\_\-Light\_\-Source} See section "Ambient Light" for details. 


\subsection{Diffuse Reflection Items}

% reference/000247.html



   When light reflects off of a surface the laws of physics say that it should leave the surface at the exact same angle it came in. This is similar to the way 
 a billiard ball bounces off a bumper of a pool table. This perfect reflection is called \textit{specular reflection}. However only very smooth polished 
 surfaces reflect light in this way. Most of the time, light reflects and is scattered in all directions by the roughness of the surface. This scattering is 
 called \textit{diffuse reflection} because the light diffuses or spreads in a variety of directions. It accounts for the majority of the reflected light we 
 see. 


\subsubsection{Diffuse}

% reference/000246.html



   The keyword {\small\texttt{diffuse}} is used in a {\small\texttt{finish}} statement to control how much of the light coming directly from any light sources 
 is reflected via diffuse reflection. For example 


{\small\begin{verbatim}
  finish { diffuse 0.7 }
\end{verbatim}}


   means that 70\% of the light seen comes from direct illumination from light sources. The default value is {\small\texttt{diffuse 0.6}}. 


\subsubsection{Brilliance}

% reference/000245.html

\index{brilliance}

   The amount of direct light that diffuses from an object depends upon the angle at which it hits the surface. When light hits at a shallow angle it 
 illuminates less. When it is directly above a surface it illuminates more. The {\small\texttt{brilliance}} keyword can be used in a {\small\texttt{finish}} 
 statement to vary the way light falls off depending upon the angle of incidence. This controls the tightness of the basic diffuse illumination on objects and 
 slightly adjusts the appearance of surface shininess. Objects may appear more metallic by increasing their brilliance. The default value is 1.0. Higher values 
 from 5.0 to about 10.0 cause the light to fall off less at medium to low angles. There are no limits to the brilliance value. Experiment to see what works 
 best for a particular situation. This is best used in concert with highlighting. 


\subsubsection{Crand Graininess}

% reference/000244.html

\index{crand}

   Very rough surfaces, such as concrete or sand, exhibit a dark graininess in their apparent color. This is caused by the shadows of the pits or holes in the 
 surface. The {\small\texttt{crand}} keyword can be added to a {\small\texttt{ finish}} to cause a minor random darkening in the diffuse reflection of direct 
 illumination. Typical values range from {\small\texttt{crand 0.01}} to {\small\texttt{crand 0.5}} or higher. The default value is 0. For example: 


{\small\begin{verbatim}
  finish { crand 0.05 }
\end{verbatim}}


   This feature is carried over from the earliest versions of POV-\discretionary{}{}{}Ray and is considered obsolete. This is because the grain or noise introduced by this feature 
 is applied on a pixel-\discretionary{}{}{}by-\discretionary{}{}{}pixel basis. This means that it will look the same on far away objects as on close objects. The effect also looks different depending 
 upon the resolution you are using for the rendering. 



   \textbf{Note:} this should not be used when rendering animations. This is the one of a few truly random features in POV-\discretionary{}{}{}Ray and will produce an annoying 
 flicker of flying pixels on any textures animated with a {\small\texttt{crand}} value. For these reasons it is not a very accurate way to model the rough 
 surface effect. 


\subsection{Highlights}

% reference/000243.html



   Highlights are the bright spots that appear when a light source reflects off of a smooth object. They are a blend of specular reflection and diffuse 
 reflection. They are specular-\discretionary{}{}{}like because they depend upon viewing angle and illumination angle. However they are diffuse-\discretionary{}{}{}like because some scattering 
 occurs. In order to exactly model a highlight you would have to calculate specular reflection off of thousands of microscopic bumps called micro facets. The 
 more that micro facets are facing the viewer the shinier the object appears and the tighter the highlights become. POV-\discretionary{}{}{}Ray uses two different models to 
 simulate highlights without calculating micro facets. They are the \textit{specular} and \textit{Phong} models. 



   \textbf{Note:} specular and Phong highlights are \textit{not} mutually exclusive. It is possible to specify both and they will both take effect. Normally, 
 however, you will only specify one or the other. 


\subsubsection{Phong Highlights}

% reference/000242.html

\index{phong}\index{phong\_\-size}

   The {\small\texttt{phong}} keyword in the {\small\texttt{finish}} statement controls the amount of Phong highlighting on the object. It causes bright shiny 
 spots on the object that are the color of the light source being reflected. 



   The Phong method measures the average of the facets facing in the mirror direction from the light sources to the viewer. 



   Phong's value is typically from 0.0 to 1.0, where 1.0 causes complete saturation to the light source's color at the brightest area (center) of the highlight. 
 The default {\small\texttt{phong 0.0}} gives no highlight. 



   The size of the highlight spot is defined by the {\small\texttt{phong\_\-size}} value. The larger the phong size the tighter, or smaller, the highlight and the 
 shinier the appearance. The smaller the phong size the looser, or larger, the highlight and the less glossy the appearance. 



   Typical values range from 1.0 (very dull) to 250 (highly polished) though any values may be used. Default phong size is 40 (plastic) if {\small\texttt{ 
 phong\_\-size}} is not specified. For example: 


{\small\begin{verbatim}
  finish { phong 0.9 phong_size 60 }
\end{verbatim}}


   If {\small\texttt{phong}} is not specified {\small\texttt{phong\_\-size}} has no effect. 


\subsubsection{Specular Highlight}

% reference/000241.html

\index{specular}

   The {\small\texttt{specular}} keyword in a {\small\texttt{finish}} statement produces a highlight which is very similar to Phong highlighting but it uses 
 slightly different model. The specular model more closely resembles real specular reflection and provides a more credible spreading of the highlights 
 occurring near the object horizons. 



   The specular value is typically from 0.0 to 1.0, where 1.0 causes complete saturation to the light source's color at the brightest area (center) of the 
 highlight. The default {\small\texttt{specular 0.0}} gives no highlight. 



   \index{roughness} The size of the spot is defined by the value given the {\small\texttt{ roughness}} keyword. Typical values range from 1.0 (very rough - 
 large highlight) to 0.0005 (very smooth - small highlight). The default value, if roughness is not specified, is 0.05 (plastic). 



   It is possible to specify wrong values for roughness that will generate an error when you try to render the file. Do not use 0 and if you get errors check to 
 see if you are using a very, very small roughness value that may be causing the error. For example: 


{\small\begin{verbatim}
  finish { specular 0.9 roughness 0.02 }
\end{verbatim}}


   If {\small\texttt{specular}} is not specified {\small\texttt{roughness}} has no effect. 



   \textbf{Note:} that when light is reflected by a surface such as a mirror, it is called \textit{specular reflection} however such reflection is not 
 controlled by the {\small\texttt{specular}} keyword. The {\small\texttt{ reflection}} keyword controls mirror-\discretionary{}{}{}like specular reflection. 


\subsubsection{Metallic Highlight Modifier}

% reference/000240.html

\index{metallic}\index{metallic! highlight}

   The keyword {\small\texttt{metallic}} may be used with {\small\texttt{phong}} or {\small\texttt{specular}} highlights. This keyword indicates that the color 
 of the highlights will be calculated by an empirical function that models the reflectivity of metallic surfaces. 



   Normally highlights are the color of the light source. Adding this keyword filters the highlight so that white light reflected from a metallic surface takes 
 the color specified by the pigment 



   The {\small\texttt{metallic}} keyword may optionally be follow by a numeric value to specify the influence the amount of the effect. If no keyword is 
 specified, the default value is zero. If the keyword is specified without a value, the default value is one. For example: 


{\small\begin{verbatim}
  finish {
    phong 0.9
    phong_size 60
    metallic
  }
\end{verbatim}}


   If {\small\texttt{phong}} or {\small\texttt{specular}} keywords are not specified then {\small\texttt{metallic}} has no effect. 


\subsection{Specular Reflection}

% reference/000239.html

\index{reflection}

   When light does not diffuse and it \textit{does} reflect at the same angle as it hits an object, it is called \textit{specular reflection}. Such mirror-\discretionary{}{}{}like 
 reflection is controlled by the {\small\texttt{reflection \{...\}}} block in a {\small\texttt{finish}} statement. 



   Syntax: 


{\small\begin{verbatim}  
finish {
    reflection {
      [COLOR_REFLECTION_MIN,] COLOR_REFLECTION_MAX
      [fresnel BOOL_ON_OFF]
      [falloff FLOAT_FALLOFF]
      [exponent FLOAT_EXPONENT]
      [metallic FLOAT_METALLIC]
    }
  }
[interior { ior IOR }]

\end{verbatim}}


   The simplest use would be a perfect mirror: 


{\small\begin{verbatim}
  finish { reflection {1.0} ambient 0 diffuse 0 }
\end{verbatim}}


   This gives the object a mirrored finish. It will reflect all other elements in the scene. Usually a single float value is specified after the keyword even 
 though the syntax calls for a color. For example a float value of 0.3 gets promoted to the full color vector $<$0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.\discretionary{3,}{}{3,}0.3$>$ which is acceptable 
 because only the red, green and blue parts are used. 



   The value can range from 0.0 to 1.0. By default there is no reflection. 



   \textbf{Note:} 


\begin{itemize}
 
 \item 
   Adding reflection to a texture makes it take longer to render because an additional ray must be traced. 
 

 \item 
   The reflected light may be tinted by specifying a color rather than a float.\newline  For example: \newline  {\small\texttt{ finish \{ reflection rgb 
  $<$\discretionary{1,}{}{1,}\discretionary{0,}{}{0,}0$>$ \}}} \newline  gives a red mirror that only reflects red light. 
 

 \item 
   Although such reflection is called specular it is not controlled by the {\small\texttt{specular}} keyword. That keyword controls a specular highlight. 
 

 \item 
   The old syntax for simple reflection: "{\small\texttt{reflection COLOR}}" and "reflection\_\-exponent Float" without braces is still 
  supported for backward compatibility. 
 

\end{itemize}


   \index{falloff! reflection} \index{reflection! falloff} {\small\texttt{falloff}} sets a falloff exponent in the variable reflection. This is the exponent 
 telling how fast the reflectivity will fall off, \discretionary{i.}{}{i.}e. linear, squared, cubed, etc. 



   \index{metallic! reflection} \index{refelection! metallic} The {\small\texttt{ metallic}} keyword is similar in function to the "metallic" keyword 
 used for highlights in finishes: it simulates the reflective properties of metallic surfaces, where reflected light takes on the colour of the surface. When {\small\texttt{metallic}} 
 is used, the "reflection" color is multiplied by the pigment color at each point. You can specify an optional float value, which is the amount of 
 influence the {\small\texttt{metallic}} keyword has on the reflected color.{\small\texttt{ metallic}} uses the Fresnel equation so that the color of the light 
 is reflected at glancing angles, and the color of the metal is reflected for angles close to the surface's normal.\index{exponent! reflection}\index{exponent}\index{reflection\_\-exponent}\index{reflection! exponent} 
 



   \textbf{exponent}\newline  POV-\discretionary{}{}{}Ray uses a limited light model that cannot distinguish between objects which are simply brightly colored and objects which are 
 extremely bright. A white piece of paper, a light bulb, the sun, and a supernova, all would be modeled as {\small\texttt{rgb$<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$}} and slightly 
 off-\discretionary{}{}{}white objects would be only slightly darker. It is especially difficult to model partially reflective surfaces in a realistic way. 
 Middle and lower brightness objects typically look too bright when reflected. If you reduce the {\small\texttt{reflection}} value, it tends to darken the 
 bright objects too much. Therefore the optional {\small\texttt{exponent}} keyword has been added. It produces non-\discretionary{}{}{}linear reflection intensities. The default 
 value of 1.0 produces a linear curve. Lower values darken middle and low intensities and keeps high intensity reflections bright. This is a somewhat 
 experimental feature designed for artistic use. It does not directly correspond to any real world reflective properties. 



   \textbf{Variable reflection}\newline  \index{variable reflection} Many materials, such as water, ceramic glaze, and linoleum are more reflective when viewed 
 at shallow angles. This can be simulated by also specifying a minimum reflection in the {\small\texttt{reflection \{...\}}} statement. \newline For example: 


{\small\begin{verbatim}
    finish { reflection { 0.03, 1 }}
\end{verbatim}}


   uses the same function as the standard reflection, but the first parameter sets the minimum reflectivity. It could be a color vector or a float (which is 
 automatically promoted to a gray vector). This minimum value is how reflective the surface will be when viewed from a direction parallel to its normal. \newline  
 The second parameter sets the maximum reflectivity, which could also be a color vector or a float (which is automatically promoted to a gray vector). This 
 maximum parameter is how reflective the surface will be when viewed at a 90-degree angle to its normal. 



   \textbf{Note:} You can make maximum reflection less than minimum reflection if you want, although the result is something that does not occur in nature. \index{fresnel} 
 



   When adding the {\small\texttt{fresnel}} keyword, the Fresnel reflectivity function is used instead of standard reflection. It calculates reflectivity using 
 the finish's IOR. So with a fresnel reflection\_\-type an {\small\texttt{interior \{ ior IOR \}}} statement is required, even with opaque pigments. Remember that 
 in real life many opaque objects have a thin layer of transparent glaze on their surface, and it is the glaze (which -does- have an IOR) that is reflective. 


\subsection{Conserve Energy for Reflection}

% reference/000238.html

\index{conserve\_\-energy}

   One of the features in POV-\discretionary{}{}{}Ray is variable reflection, including realistic Fresnel reflection (see section "Variable Reflection "). Unfortunately, 
 when this is coupled with constant transmittance, the texture can look unrealistic. This unrealism is caused by the scene breaking the law of conservation of 
 energy. As the amount of light reflected changes, the amount of light transmitted should also change (in a give-\discretionary{}{}{}and-\discretionary{}{}{}take relationship). 



   This can be achieved by adding the {\small\texttt{conserve\_\-energy}} keyword to the object's {\small\texttt{finish \{\}}}. \newline When conserve\_\-energy is 
 enabled, POV-\discretionary{}{}{}Ray will multiply the amount filtered and transmitted by what is left over from reflection (for example, if reflection is 80\%, filter/transmit 
 will be multiplied by 20\%). 


\subsection{Iridescence}

% reference/000237.html

\index{irid}

   \textit{Iridescence}, or Newton's thin film interference, simulates the effect of light on surfaces with a microscopic transparent film overlay. The effect 
 is like an oil slick on a puddle of water or the rainbow hues of a soap bubble. This effect is controlled by the {\small\texttt{ irid}} statement specified 
 inside a {\small\texttt{finish}} statement. 



   This parameter modifies the surface color as a function of the angle between the light source and the surface. Since the effect works in conjunction with the 
 position and angle of the light sources to the surface it does not behave in the same ways as a procedural pigment pattern. 



   The syntax is: 


{\small\begin{verbatim}
IRID:
    irid { Irid_Amount [IRID_ITEMS...] }
IRID_ITEMS:
    thickness Amount | turbulence Amount
\end{verbatim}}


   The required \textit{{\small\texttt{Irid\_\-Amount}}} parameter is the contribution of the iridescence effect to the overall surface color. As a rule of thumb 
 keep to around 0.25 (25\% contribution) or less, but experiment. If the surface is coming out too white, try lowering the {\small\texttt{ diffuse}} and 
 possibly the {\small\texttt{ambient}} values of the surface. 



   \index{thickness} The {\small\texttt{ thickness}} keyword represents the film's thickness. This is an awkward parameter to set, since the thickness value has 
 no relationship to the object's scale. Changing it affects the scale or \textit{ busy-\discretionary{}{}{}ness} of the effect. A very thin film will have a high frequency of 
 color changes while a thick film will have large areas of color. The default value is zero. 



   \index{turbulence! irid} The thickness of the film can be varied with the {\small\texttt{ turbulence}} keyword. You can only specify the amount of turbulence 
 with iridescence. The octaves, lambda, and omega values are internally set and are not adjustable by the user at this time. This parameter varies only a 
 single value: the thickness. Therefore the value must be a single float value. It cannot be a vector as in other uses of the {\small\texttt{turbulence}} 
 keyword. 



   In addition, perturbing the object's surface normal through the use of bump patterns will affect iridescence. 



   For the curious, thin film interference occurs because, when the ray hits the surface of the film, part of the light is reflected from that surface, while a 
 portion is transmitted into the film. This \textit{subsurface} ray travels through the film and eventually reflects off the opaque substrate. The light 
 emerges from the film slightly out of phase with the ray that was reflected from the surface. 



   This phase shift creates interference, which varies with the wavelength of the component colors, resulting in some wavelengths being reinforced, while others 
 are cancelled out. When these components are recombined, the result is iridescence. See also the global setting "Irid\_\-Wavelength". 



   The concept used for this feature came from the book \textit{Fundamentals of Three-\discretionary{}{}{}Dimensional Computer Graphics} by Alan Watt (Addison-\discretionary{}{}{}Wesley). 


\section{Halo}

% reference/000216.html

\index{halo}\index{halo! keyword}\index{Keyword! halo}

   Earlier versions of POV-\discretionary{}{}{}Ray used a feature called {\small\texttt{halo}} to simulate fine particles such as smoke, steam, fog, or flames. The {\small\texttt{ 
 halo}} statement was part of the {\small\texttt{texture}} statement. This feature has been discontinued and replaced by the {\small\texttt{interior}} and {\small\texttt{media}} 
 statements which are object modifiers outside the {\small\texttt{ texture}} statement. 



   See "Why are Interior and Media Necessary?" for a detailed explanation on the reasons for the change. See "Media" for details on {\small\texttt{media}}. 
 


\section{Patterned Textures}

% reference/000215.html



   Patterned textures are complex textures made up of multiple textures. The component textures may be plain textures or may be made up of patterned textures. A 
 plain texture has just one pigment, normal and finish statement. Even a pigment with a pigment map is still one pigment and thus considered a plain texture as 
 are normals with normal map statements. 



   Patterned textures use either a {\small\texttt{texture\_\-map}} statement to specify a blend or pattern of textures or they use block textures such as {\small\texttt{checker}} 
 with a texture list or a bitmap similar to an image map called a \textit{material map} specified with a {\small\texttt{material\_\-map}} statement. 



   The syntax is... 


{\small\begin{verbatim}
PATTERNED_TEXTURE:
    texture
    {
        [PATTERNED_TEXTURE_ID]
        [TRANSFORMATIONS...]
    } |
    texture
    {
        PATTERN_TYPE
        [TEXTURE_PATTERN_MODIFIERS...]
    } |
    texture
    {
        tiles TEXTURE tile2 TEXTURE
        [TRANSFORMATIONS...]
    } |
    texture
    {
        material_map
        {
            BITMAP_TYPE "bitmap.ext"
            [BITMAP_MODS...] TEXTURE... [TRANSFORMATIONS...]
        }
    }
TEXTURE_PATTERN_MODIFIER:
    PATTERN_MODIFIER | TEXTURE_LIST |
    texture_map { TEXTURE_MAP_BODY }
\end{verbatim}}


   There are restrictions on using patterned textures. A patterned texture may not be used as a default texture (see section "The \#default Directive"). 
 A patterned texture cannot be used as a layer in a layered texture however you may use layered textures as any of the textures contained within a patterned 
 texture. 


\subsection{Texture Maps}

% reference/000214.html

\index{texture\_\-map}

   In addition to specifying blended color with a color map or a pigment map you may create a blend of textures using {\small\texttt{texture\_\-map}}. The syntax 
 for a texture map is identical to the pigment map except you specify a texture in each map entry. 



   The syntax for {\small\texttt{texture\_\-map}} is as follows: 


{\small\begin{verbatim}
TEXTURE_MAP:
    texture_map { TEXTURE_MAP_BODY }
TEXTURE_MAP_BODY:
  TEXTURE_MAP_IDENTIFIER | TEXTURE_MAP_ENTRY...
TEXTURE_MAP_ENTRY:
    [ Value TEXTURE_BODY ]
\end{verbatim}}


   Where \textit{{\small\texttt{Value}}} is a float value between 0.0 and 1.0 inclusive and each \textit{TEXTURE\_\-BODY} is anything which can be inside a {\small\texttt{texture\{...\}}} 
 statement. The {\small\texttt{texture}} keyword and {\small\texttt{\{\}}} braces need not be specified. 



   \textbf{Note:} the {\small\texttt{[]}} brackets are part of the actual \textit{ TEXTURE\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional parts. 
 The brackets surround each entry in the texture map. 



   There may be from 2 to 256 entries in the map. 



   For example: 


{\small\begin{verbatim}
  texture {
    gradient x       //this is the PATTERN_TYPE
    texture_map {
      [0.3  pigment{Red} finish{phong 1}]
      [0.3  T_Wood11]    //this is a texture identifier
      [0.6  T_Wood11]
      [0.9  pigment{DMFWood4} finish{Shiny}]
    }
  }
\end{verbatim}}


   When the {\small\texttt{gradient x}} function returns values from 0.0 to 0.3 the red highlighted texture is used. From 0.3 to 0.6 the texture identifier {\small\texttt{T\_\-Wood11}} 
 is used. From 0.6 up to 0.9 a blend of {\small\texttt{ T\_\-Wood11}} and a shiny {\small\texttt{DMFWood4}} is used. From 0.9 on up only the shiny wood is used. 



   Texture maps may be nested to any level of complexity you desire. The textures in a map may have color maps or texture maps or any type of texture you want. 



   The blended area of a texture map works by fully calculating both contributing textures in their entirety and then linearly interpolating the apparent 
 colors. This means that reflection, refraction and lighting calculations are done twice for every point. This is in contrast to using a pigment map and a 
 normal map in a plain texture, where the pigment is computed, then the normal, then reflection, refraction and lighting are calculated once for that point. 



   Entire textures may also be used with the block patterns such as {\small\texttt{ checker}}, {\small\texttt{hexagon}} and {\small\texttt{brick}}. For 
 example... 


{\small\begin{verbatim}
  texture {
    checker
      texture { T_Wood12 scale .8 }
      texture {
        pigment { White_Marble }
        finish { Shiny }
        scale .5
      }
    }
  }
\end{verbatim}}


   \textbf{Note:} that in the case of block patterns the {\small\texttt{texture}} wrapping is required around the texture information. Also note that this 
 syntax prohibits the use of a layered texture however you can work around this by declaring a texture identifier for the layered texture and referencing the 
 identifier. 



   A texture map is also used with the {\small\texttt{ average}} texture type. See "Average" for details. 



   You may declare and use texture map identifiers but the only way to declare a texture block pattern list is to declare a texture identifier for the entire 
 texture. 


\subsection{Tiles}

% reference/000213.html

\index{tile2}\index{tiles}

   Earlier versions of POV-\discretionary{}{}{}Ray had a patterned texture called a \textit{tiles texture}. It used the {\small\texttt{tiles}} and {\small\texttt{tile2}} keywords 
 to create a checkered pattern of textures. 


{\small\begin{verbatim}
TILES_TEXTURE:
    texture
    {
        tiles TEXTURE tile2 TEXTURE
        [TRANSFORMATIONS...]
    }
\end{verbatim}}


   Although it is still supported for backwards compatibility you should use a {\small\texttt{checker}} block texture pattern described in section "Texture 
 Maps" rather than tiles textures. 


\subsection{Material Maps}

% reference/000249.html

\index{material\_\-map}

   The {\small\texttt{material\_\-map}} patterned texture extends the concept of image maps to apply to entire textures rather than solid colors. A material map 
 allows you to wrap a 2-D bit-\discretionary{}{}{}mapped texture pattern around your 3-D objects. 



   Instead of placing a solid color of the image on the shape like an image map, an entire texture is specified based on the index or color of the image at that 
 point. You must specify a list of textures to be used like a \textit{ texture palette} rather than the usual color palette. 



   When used with mapped file types such as GIF, and some PNG and TGA images, the index of the pixel is used as an index into the list of textures you supply. 
 For unmapped file types such as some PNG and TGA images the 8 bit value of the red component in the range 0-255 is used as an index. 



   If the index of a pixel is greater than the number of textures in your list then the index is taken modulo N where N is the length of your list of textures. 



   \textbf{Note:} The {\small\texttt{ material\_\-map}} statement has nothing to do with the {\small\texttt{ material}} statement. A {\small\texttt{material\_\-map}} 
 is \textit{ not} a way to create patterned {\small\texttt{material}}. See "Material" for explanation of this unrelated, yet similarly named, older 
 feature. 


\subsubsection{Specifying a Material Map}

% reference/000248.html



   The syntax for a {\small\texttt{material\_\-map}} is: 


{\small\begin{verbatim}
MATERIAL_MAP:
    texture
    {
        material_map
        {
            BITMAP_TYPE "bitmap.ext"
            [BITMAP_MODS...] TEXTURE... [TRANSFORMATIONS...]
        }
    }
BITMAP_TYPE:
    gif | tga | iff | ppm | pgm | png | jpeg | tiff | sys
BITMAP_MOD:
    map_type Type | once | interpolate Type
\end{verbatim}}


   After the required \textit{BITMAP\_\-TYPE} keyword is a string expression containing the name of a bitmapped material file of the specified type. Several 
 optional modifiers may follow the file specification. The modifiers are described below. 



   \textbf{Note:} earlier versions of POV-\discretionary{}{}{}Ray allowed some modifiers before the \textit{BITMAP\_\-TYPE} but that syntax is being phased out in favor of the syntax 
 described here. 



   \textbf{Note:} {\small\texttt{sys}} format is a system-\discretionary{}{}{}specific format such as BMP for Windows or Pict for Macintosh. 



   Filenames specified in the {\small\texttt{material\_\-map}} statements will be searched for in the home (current) directory first and, if not found, will then 
 be searched for in directories specified by any {\small\texttt{ +L}} or {\small\texttt{Library\_\-Path}} options active. This would facilitate keeping all your 
 material maps files in a separate subdirectory and giving a {\small\texttt{ Library\_\-Path}} option to specify where your library of material maps are. See 
 "Library Paths" for details. 



   By default, the material is mapped onto the x-\discretionary{}{}{}y-\discretionary{}{}{}plane. The material is \textit{ projected} onto the object as though there were a slide projector somewhere 
 in the -z-\discretionary{}{}{}direction. The material exactly fills the square area from (\discretionary{x,}{}{x,}y) coordinates (\discretionary{0,}{}{0,}0) to (\discretionary{1,}{}{1,}1) regardless of the material's original size in pixels. If 
 you would like to change this default you may translate, rotate or scale the texture to map it onto the object's surface as desired. 



   The file name is optionally followed by one or more \textit{ BITMAP\_\-MODIFIERS}. There are no modifiers which are unique to a {\small\texttt{ material\_\-map}}. 
 It only uses the generic bitmap modifiers {\small\texttt{ map\_\-type}}, {\small\texttt{once}} and {\small\texttt{ interpolate}} described in "Bitmap 
 Modifiers". 



   Although {\small\texttt{ interpolate}} is legal in material maps, the color index is interpolated before the texture is chosen. It does not interpolate the 
 final color as you might hope it would. In general, interpolation of material maps serves no useful purpose but this may be fixed in future versions. 



   Next is one or more {\small\texttt{texture}} statements. Each texture in the list corresponds to an index in the bitmap file. For example: 


{\small\begin{verbatim}
  texture {
     material_map {
        png "povmap.png"
        texture {  //used with index 0
           pigment {color red 0.3 green 0.1 blue 1}
           normal  {ripples 0.85 frequency 10 }
           finish  {specular 0.75}
           scale 5
        }
        texture {  //used with index 1
           pigment {White}
           finish {
             ambient 0 diffuse 0 
             reflection 0.9 specular 0.75
           }
        }
        // used with index 2
        texture {pigment{NeonPink} finish{Luminous}}
        texture {  //used with index 3
           pigment {
              gradient y
              color_map {
                 [0.00 rgb < 1 , 0 , 0>]
                 [0.33 rgb < 0 , 0 , 1>]
                 [0.66 rgb < 0 , 1 , 0>]
                 [1.00 rgb < 1 , 0 , 0>]
              }
           }
           finish{specular 0.75}
           scale 8
        }
     }
     scale 30
     translate <-15, -15, 0>
  }
\end{verbatim}}


   After a {\small\texttt{material\_\-map}} statement but still inside the texture statement you may apply any legal texture modifiers. 



   \textbf{Note:} no other pigment, normal, or finish statements may be added to the texture outside the material map. 



   The following is illegal: 


{\small\begin{verbatim}
  texture {
    material_map {
      gif "matmap.gif"
      texture {T1}
      texture {T2}
      texture {T3}
    }
    finish {phong 1.0}
  }
\end{verbatim}}


   The finish must be individually added to each texture. Earlier versions of POV-\discretionary{}{}{}Ray allowed such specifications but they were ignored. The above restrictions 
 on syntax were necessary for various bug fixes. This means some POV-\discretionary{}{}{}Ray 1.0 scenes using material maps many need minor modifications that cannot be done 
 automatically with the version compatibility mode. 



   If particular index values are not used in an image then it may be necessary to supply dummy textures. It may be necessary to use a paint program or other 
 utility to examine the map file's palette to determine how to arrange the texture list. 



   The textures within a material map texture may be layered but material map textures do not work as part of a layered texture. To use a layered texture inside 
 a material map you must declare it as a texture identifier and invoke it in the texture list. 


\section{Layered Textures}

% reference/000212.html



   It is possible to create a variety of special effects using layered textures. A layered texture consists of several textures that are partially transparent 
 and are laid one on top of the other to create a more complex texture. The different texture layers show through the transparent portions to create the 
 appearance of one texture that is a combination of several textures. 



   You create layered textures by listing two or more textures one right after the other. The last texture listed will be the top layer, the first one listed 
 will be the bottom layer. All textures in a layered texture other than the bottom layer should have some transparency. For example: 


{\small\begin{verbatim}
  object {
    My_Object
    texture {T1}  // the bottom layer
    texture {T2}  // a semi-transparent layer
    texture {T3}  // the top semi-transparent layer
  }
\end{verbatim}}


   In this example T2 shows only where T3 is transparent and T1 shows only where T2 and T3 are transparent. 



   The color of underlying layers is filtered by upper layers but the results do not look exactly like a series of transparent surfaces. If you had a stack of 
 surfaces with the textures applied to each, the light would be filtered twice: once on the way in as the lower layers are illuminated by filtered light and 
 once on the way out. Layered textures do not filter the illumination on the way in. Other parts of the lighting calculations work differently as well. The 
 results look great and allow for fantastic looking textures but they are simply different from multiple surfaces. See {\small\texttt{ \discretionary{stones.}{}{stones.}inc}} in the 
 standard include files directory for some magnificent layered textures. 



   \textbf{Note:} in versions predating POV-\discretionary{}{}{}Ray 3.5, {\small\texttt{filter}} used to work the same as {\small\texttt{transmit}} in layered textures. It has been 
 changed to work as filter should. This can change the appearance of "pre 3.5" textures a lot. The {\small\texttt{\#version}} directive can be used to 
 get the "pre 3.5" behaviour. 



   \textbf{Note:} layered textures must use the {\small\texttt{texture}} wrapped around any pigment, normal or finish statements. Do not use multiple pigment, 
 normal or finish statements without putting them inside the texture statement. 



   Layered textures may be declared. For example 


{\small\begin{verbatim}
  #declare Layered_Examp =
    texture {T1}
    texture {T2}
    texture {T3}
\end{verbatim}}


   may be invoked as follows: 


{\small\begin{verbatim}
  object {
    My_Object
    texture {
      Layer_Examp
      // Any pigment, normal or finish here
      // modifies the bottom layer only.
    }
  }
\end{verbatim}}


   \textbf{Note:} No macros are allowed in layered textures. The problem is that if a macro would contain a declare the parser could no longer guess that two or 
 more texture identifiers are supposed to belong to the layered texture and not some other declare. 



   If you wish to use a layered texture in a block pattern, such as {\small\texttt{ checker}}, {\small\texttt{hexagon}}, or {\small\texttt{brick}}, or in a {\small\texttt{ 
 material\_\-map}}, you must declare it first and then reference it inside a single texture statement. A patterned texture cannot be used as a layer in a 
 layered texture however you may use layered textures as any of the textures contained within a patterned texture. 


\section{UV Mapping}

% reference/000211.html

\index{uv\_\-mapping}

   All textures in POV-\discretionary{}{}{}Ray are defined in 3 dimensions. Even planar image mapping is done this way. However, it is sometimes more desirable to have the texture 
 defined for the surface of the object. This is especially true for bicubic\_\-patch objects and mesh objects, that can be stretched and compressed. When the 
 object is stretched or compressed, it would be nice for the texture to be \textit{glued} to the object's surface and follow the object's deformations. 



   When uv\_\-mapping is used, then that object's texture will be mapped to it using surface coordinates (u and v) instead of spatial coordinates (x, y, and z). 
 This is done by taking a slice of the object's regular 3D texture from the XY plane (Z=0) and wrapping it around the surface of the object, following the 
 object's surface coordinates. 



   \textbf{Note:} some textures should be rotated to fit the slice in the XY plane. 



   Syntax: 


{\small\begin{verbatim}
texture {
 uv_mapping pigment{PIGMENT_BODY} | pigment{uv_mapping PIGMENT_BODY}
 uv_mapping normal {NORMAL_BODY } | normal {uv_mapping NORMAL_BODY }
 uv_mapping texture{TEXTURE_BODY} | texture{uv_mapping TEXTURE_BODY)
}
\end{verbatim}}

\subsection{Supported Objects}

% reference/000210.html



   Surface mapping is currently defined for the following objects: 


\begin{itemize}
 
 \item 
   \textbf{bicubic\_\-patch} : UV coordinates are based on the patch's parametric coordinates. They stretch with the control points. The default range is 
  (0..1) and can be changed.\newline   
 

 \item 
   \textbf{mesh, mesh2} : UV coordinates are defined for each vertex and interpolated between.\newline   
 

 \item 
   \textbf{lathe, sor} : modified spherical mapping... the u coordinate (0..1) wraps around the y axis, while the v coordinate is linked to the object's 
  control points (also ranging 0..1). \newline Surface of Revolution also has special disc mapping on the end caps if the object is not 'open'.\newline   
 

 \item 
   \textbf{sphere} : boring spherical mapping.\newline   
 

 \item 
   \textbf{box} : the image is \textit{wrapped} around the box, as shown below.\newline   \newline \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/boxmap} \caption{UV Boxmap} \end{figure} 
  
 

 \item 
   \textbf{parametric} : In this case the map is not taken from a "fixed" set of coordinates but the map is taken from the area defined by the 
  boundaries of the uv-\discretionary{}{}{}space, in which the parametric surface has to be calculated.\newline   
 

 \item 
   \textbf{torus} : The map is taken from the area $<$\discretionary{0,}{}{0,}0$>$$<$\discretionary{1,}{}{1,}1$>$ where the u-\discretionary{}{}{}coordinate is wrapped around the major radius and the the 
  v-\discretionary{}{}{}coordinate is wrapped around the minor radius. 
 

\end{itemize}

\subsection{UV Vectors}

% reference/000209.html



   With the keyword {\small\texttt{uv\_\-vectors}}, the UV coordinates of the corners can be controlled for bicubic patches and standard triangle mesh. 



   For bicubic patches the UV coordinates can be specified for each of the four corners of the patch. This goes right before the control points. \newline The 
 syntax is: 



   {\small\texttt{  uv\_\-vectors $<$corner1$>$,$<$corner2$>$,$<$corner3$>$, $<$corner4$>$}} \newline with default \newline {\small\texttt{  uv\_\-vectors 
 $<$\discretionary{0,}{}{0,}0$>$,$<$\discretionary{1,}{}{1,}0$>$,$<$\discretionary{1,}{}{1,}1$>$,$<$\discretionary{0,}{}{0,}1$>$}} 



   For standard triangle meshes (not mesh2) you can specify the UV coordinates for each of the three vertices {\small\texttt{uv\_\-vectors 
 $<$uv1$>$,$<$uv2$>$,$<$uv3$>$}} inside each mesh triangle. This goes right after the coordinates (or coordinates \& normals with smooth triangles) and 
 right before the texture. \newline Example: 


{\small\begin{verbatim}
  mesh {
    triangle {
      <0,0,0>, <0.5,0,0>, <0.5,0.5,0>
      uv_vectors <0,0>, <1,0>, <1,1>
    }
    triangle {
      <0,0,0>, <0.5,0.5,0>, <0,0.5,0>
      uv_vectors <0,0>, <1,1>, <0,1>
    }
    texture {
      uv_mapping pigment {
        image_map {
          sys "SomeImage"
          map_type 0
          interpolate 0
        }
      }
    }
  }
\end{verbatim}}

\section{Triangle Texture Interpolation}

% reference/000208.html

\index{texture\_\-list}\index{texture\_\-list! keyword}\index{Keyword! texture\_\-list}

   This feature is utilized in a number of visualization approaches: triangles with individual textures for each vertex, which are interpolated during 
 rendering. 



   Syntax: 


{\small\begin{verbatim}
MESH_TRIANGLE:
  triangle { 
    <Corner_1>,
    <Corner_2>,
    <Corner_3>
    [MESH_TEXTURE]
  }   |
  smooth_triangle { 
    <Corner_1>, <Normal_1>, 
    <Corner_2>, <Normal_2>, 
    <Corner_3>, <Normal_3> 
    [MESH_TEXTURE] 
  }

MESH_TEXTURE:
  texture { TEXTURE_IDENTIFIER } |
  texture_list {
    TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER TEXTURE_IDENTIFIER
  }
\end{verbatim}}


   To specify three vertex textures for the triangle, simply use {\small\texttt{texture\_\-list}} instead of texture. 


\section{Interior Texture}

% reference/000207.html

\index{interior\_\-texture}\index{interior\_\-texture! keyword}\index{Keyword! interior\_\-texture}

   Syntax: 


{\small\begin{verbatim}
object {
  texture { TEXTURE_ITEMS... }
  interior_texture { TEXTURE_ITEMS...}
}
\end{verbatim}}


   All surfaces have an exterior and interior surface. The {\small\texttt{interior\_\-texture}} simply allows to specify a separate texture for the interior 
 surface of the object. For objects with no well defined inside/outside (bicubic\_\-patch, triangle, ...) the {\small\texttt{interior\_\-texture}} is applied to the 
 backside of the surface. Interior surface textures use exactly the same syntax and should work in exactly the same way as regular surface textures, except 
 that they use the keyword {\small\texttt{interior\_\-texture}} instead of {\small\texttt{texture}}. 



   \textbf{Note:} Do not confuse {\small\texttt{interior\_\-texture \{\}}} with {\small\texttt{interior \{\}}}: the first one specifies surface properties, the second 
 one specifies volume properties. 


\section{Cutaway Textures}

% reference/000206.html

\index{cutaway\_\-textures}

   Syntax: 


{\small\begin{verbatim}
  difference | intersection {
    OBJECT_1_<strong>WITH</strong>_TEXTURES
    OBJECT_2_<strong>WITH_NO</strong>_TEXTURE
    cutaway_textures
  }
\end{verbatim}}


   When using a CSG difference or intersection to \textit{cut} away parts of an object, it is sometimes desirable to allow the object to retain its original 
 texture. Generally, however, the texture of the surface that was used to do the cutting will be displayed. \newline Also, if the cutting object was not given 
 a texture by the user, the default texture is assigned to it. 



   By using the {\small\texttt{cutaway\_\-textures}} keyword in a CSG difference or intersection, you specify that you do not want the default texture on the 
 intersected surface, but instead, the textures of the parent objects in the CSG should be used. \newline POV-\discretionary{}{}{}Ray will determine which texture(s) to use by 
 doing insidedness tests on the objects in the difference or intersection. If the intersection point is inside an object, that object's texture will be used 
 (and evaluated at the interior point). \newline If the parent object is a CSG of objects with different textures, then the textures on overlapping parts will 
 be averaged together. 


\section{Patterns}

% reference/000205.html



   POV-\discretionary{}{}{}Ray uses a method called \textit{three-\discretionary{}{}{}dimensional solid texturing} to define the color, bumpiness and other properties of an object. You specify the way 
 that the texture varies over a surface by specifying a \textit{ pattern}. Patterns are used in pigments, normals and texture maps as well as media density. 



   All patterns in POV-\discretionary{}{}{}Ray are three dimensional. For every point in space, each pattern has a unique value. Patterns do not wrap around a surface like putting 
 wallpaper on an object. The patterns exist in 3d and the objects are carved from them like carving an object from a solid block of wood or stone. 



   Consider a block of wood. It contains light and dark bands that are concentric cylinders being the growth rings of the wood. On the end of the block you see 
 these concentric circles. Along its length you see lines that are the veins. However the pattern exists throughout the entire block. If you cut or carve the 
 wood it reveals the pattern inside. Similarly an onion consists of concentric spheres that are visible only when you slice it. Marble stone consists of wavy 
 layers of colored sediments that harden into rock. 



   These solid patterns can be simulated using mathematical functions. Other random patterns such as granite or bumps and dents can be generated using a random 
 number system and a noise function. 



   In each case, the x, y, z coordinate of a point on a surface is used to compute some mathematical function that returns a float value. When used with color 
 maps or pigment maps, that value looks up the color of the pigment to be used. In normal statements the pattern function result modifies or perturbs the 
 surface normal vector to give a bumpy appearance. Used with a texture map, the function result determines which combinations of entire textures to be used. 
 When used with media density it specifies the density of the particles or gasses. 



   The following sections describe each pattern. See the sections "Pigment", "Normal" "Patterned Textures" and "Density" 
 for more details on how to use patterns. Unless mentioned otherwise, all patterns use the {\small\texttt{ramp\_\-wave}} wave type by default but may use any wave 
 type and may be used with {\small\texttt{color\_\-map}}, {\small\texttt{pigment\_\-map}}, {\small\texttt{normal\_\-map}}, {\small\texttt{slope\_\-map}}, {\small\texttt{ 
 texture\_\-map}}, {\small\texttt{density}}, and {\small\texttt{density\_\-map}}. 



   \textbf{Note:} Some patterns have a built in default color\_\-map that does not result in a grey-\discretionary{}{}{}scale pattern. This may lead to unexpected results when one of 
 these patterns is used without a user specified color\_\-map, for example in functions or media. 



   These patterns are: 


\begin{itemize}
 
 \item 
   {\small\texttt{agate}} 
 

 \item 
   {\small\texttt{bozo}} 
 

 \item 
   {\small\texttt{brick}} 
 

 \item 
   {\small\texttt{checker}} 
 

 \item 
   {\small\texttt{mandel}} 
 

 \item 
   {\small\texttt{hexagon}} 
 

 \item 
   {\small\texttt{marble}} 
 

 \item 
   {\small\texttt{radial}} 
 

 \item 
   {\small\texttt{wood}} 
 

\end{itemize}

\subsection{Agate}

% reference/000204.html

\index{agate}\index{agate! keyword}\index{agate! pattern}\index{Keyword! agate}\index{Pattern! agate}\index{agate\_\-turb! agate}\index{Keyword! agate\_\-turb}

   The {\small\texttt{agate}} pattern is a banded pattern similar to marble but it uses a specialized built-\discretionary{}{}{}in turbulence function that is different from the 
 traditional turbulence. The traditional turbulence can be used as well but it is generally not necessary because agate is already very turbulent. You may 
 control the amount of the built-\discretionary{}{}{}in turbulence by adding the optional {\small\texttt{ agate\_\-turb}} keyword followed by a float value. For example: 


{\small\begin{verbatim}
  pigment {
    agate
    agate_turb 0.5
    color_map {MyMap}
  }
\end{verbatim}}


   The {\small\texttt{agate}} pattern has a default color\_\-map built in that results in a brown and white pattern with smooth transitions. 



   Agate as used in a normal: 


{\small\begin{verbatim}
  normal {
    agate [Bump_Size]
    [MODIFIERS...]
  }
\end{verbatim}}

\subsection{Average}

% reference/000283.html

\index{average}\index{average! keyword}\index{average! pattern}\index{Keyword! average}\index{Pattern! average}\index{pigment\_\-map! average}\index{Keyword! pigment\_\-map}

   Technically {\small\texttt{average}} is not a pattern type but it is listed here because the syntax is similar to other patterns. Typically a pattern type 
 specifies how colors or normals are chosen from a {\small\texttt{pigment\_\-map}}, {\small\texttt{texture\_\-map}}, {\small\texttt{density\_\-map}}, or {\small\texttt{normal\_\-map 
 }}, however {\small\texttt{average}} tells POV-\discretionary{}{}{}Ray to average together all of the patterns you specify. Average was originally designed to be used in a normal 
 statement with a {\small\texttt{normal\_\-map}} as a method of specifying more than one normal pattern on the same surface. However average may be used in a 
 pigment statement with a {\small\texttt{ pigment\_\-map}} or in a texture statement with a {\small\texttt{ texture\_\-map}} or media density with {\small\texttt{density\_\-map}} 
 to average colors too. 



   When used with pigments, the syntax is: 


{\small\begin{verbatim}
AVERAGED_PIGMENT:
    pigment
    {
        pigment_map
        {
            PIGMENT_MAP_ENTRY...
        }
    }
PIGMENT_MAP_ENTRY:
    [ [Weight] PIGMENT_BODY ]
\end{verbatim}}


   Where \textit{{\small\texttt{Weight}}} is an optional float value that defaults to 1.0 if not specified. This weight value is the relative weight applied to 
 that pigment. Each \textit{PIGMENT\_\-BODY} is anything which can be inside a {\small\texttt{pigment\{...\}}} statement. The {\small\texttt{pigment}} keyword and {\small\texttt{\{\}}} 
 braces need not be specified. 



   \textbf{Note:} that the {\small\texttt{[]}} brackets are part of the actual \textit{ PIGMENT\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional 
 parts. The brackets surround each entry in the {\small\texttt{pigment\_\-map}}. 



   There may be from 2 to 256 entries in the map. 



   For example 


{\small\begin{verbatim}
    pigment {
      average
      pigment_map {
        [1.0  Pigment_1]
        [2.0  Pigment_2]
        [0.5  Pigment_3]
      }
    }
\end{verbatim}}


   All three pigments are evaluated. The weight values are multiplied by the resulting color. It is then divided by the total of the weights which, in this 
 example is 3.5. When used with {\small\texttt{texture\_\-map}} or {\small\texttt{ density\_\-map}} it works the same way. 



   When used with a {\small\texttt{ normal\_\-map}} in a normal statement, multiple copies of the original surface normal are created and are perturbed by each 
 pattern. The perturbed normals are then weighted, added and normalized. 



   See the sections "Pigment Maps and Pigment Lists", "Normal Maps and Normal Lists", "Texture Maps", and "Density Maps and 
 Density Lists" for more information. 


\subsection{Boxed}

% reference/000282.html

\index{boxed}\index{boxed! keyword}\index{boxed! pattern}\index{Keyword! boxed}\index{Pattern! boxed}

   The {\small\texttt{boxed}} pattern creates a 2x2x2 unit cube centered at the origin. It is computed by: \textit{ value =1.0- min(1, max(abs(X), abs(Y), 
 abs(Z)))} It starts at 1.0 at the origin and decreases to a minimum value of 0.0 as it approaches any plane which is one unit from the origin. It remains at 
 0.0 for all areas beyond that distance. This pattern was originally created for use with {\small\texttt{halo}} or {\small\texttt{media}} but it may be used 
 anywhere any pattern may be used. 


\subsection{Bozo}

% reference/000281.html

\index{bozo}\index{bozo! keyword}\index{bozo! pattern}\index{Keyword! bozo}\index{Pattern! bozo}

   The {\small\texttt{bozo}} pattern is a very smooth, random noise function that is traditionally used with some turbulence to create clouds. The {\small\texttt{ 
 spotted}} pattern is identical to {\small\texttt{bozo}} but in early versions of POV-\discretionary{}{}{}Ray spotted did not allow turbulence to be added. Turbulence can now be 
 added to any pattern so these are redundant but both are retained for backwards compatibility. The {\small\texttt{bumps}} pattern is also identical to {\small\texttt{bozo}} 
 when used anywhere except in a {\small\texttt{ normal}} statement. When used as a normal pattern, {\small\texttt{bumps}} uses a slightly different method to 
 perturb the normal with a similar noise function. 



   The {\small\texttt{bozo}} noise function has the following properties: 



   1. It is defined over 3D space \discretionary{i.}{}{i.}e., it takes x, y, and z and returns the noise value there. 



   2. If two points are far apart, the noise values at those points are relatively random. 



   3. If two points are close together, the noise values at those points are close to each other. 



   You can visualize this as having a large room and a thermometer that ranges from 0.0 to 1.0. Each point in the room has a temperature. Points that are far 
 apart have relatively random temperatures. Points that are close together have close temperatures. The temperature changes smoothly but randomly as we move 
 through the room. 



   Now let's place an object into this room along with an artist. The artist measures the temperature at each point on the object and paints that point a 
 different color depending on the temperature. What do we get? A POV-\discretionary{}{}{}Ray bozo texture! 



   The {\small\texttt{bozo}} pattern has a default color\_\-map built in that results in a green, blue, red and white pattern with sharp transitions. 



   \textbf{Note:} The appearance of the bozo pattern depends on the noise\_\-generator used. The default type is 2. This may be changed using the {\small\texttt{noise\_\-generator}} 
 keyword (See section "Pattern Modifiers / Noise\_\-generator"). 


\subsection{Brick}

% reference/000280.html

\index{brick}\index{brick! keyword}\index{brick! pattern}\index{Keyword! brick}\index{Pattern! brick}\index{brick\_\-size! brick}\index{Keyword! brick\_\-size}\index{mortar! brick}\index{Keyword! mortar}

   The {\small\texttt{brick}} pattern generates a pattern of bricks. The bricks are offset by half a brick length on every other row in the x- and z-\discretionary{}{}{}directions. 
 A layer of mortar surrounds each brick. The syntax is given by 


{\small\begin{verbatim}
 pigment {
   brick COLOR_1, COLOR_2
   [brick_size <Size>] [mortar Size]
 }
\end{verbatim}}


   where \textit{COLOR\_\-1} is the color of the mortar and \textit{COLOR\_\-2} is the color of the brick itself. If no colors are specified a default deep red and 
 dark gray are used. The default size of the brick and mortar together is $<$8, 3, 4.5$>$ units. The default thickness of the mortar is 0.5 units. These 
 values may be changed using the optional {\small\texttt{ brick\_\-size}} and {\small\texttt{mortar}} pattern modifiers. You may also use pigment statements in 
 place of the colors. For example: 


{\small\begin{verbatim}
  pigment {
    brick pigment{Jade}, pigment{Black_Marble}
  }
\end{verbatim}}


   This example uses normals: 


{\small\begin{verbatim}
  normal { brick 0.5 }
\end{verbatim}}


   The float value is an optional bump size. You may also use full normal statements. For example: 


{\small\begin{verbatim}
  normal {
    brick normal{bumps 0.2}, normal{granite 0.3}
  }
\end{verbatim}}


   When used with textures, the syntax is 


{\small\begin{verbatim}
  texture {
    brick texture{T_Gold_1A}, texture{Stone12}
  }
\end{verbatim}}


   This is a block pattern which cannot use wave types, {\small\texttt{ color\_\-map}}, or {\small\texttt{slope\_\-map}} modifiers. 



   The {\small\texttt{brick}} pattern has a default color\_\-map built in that results in red bricks and grey mortar. 


\subsection{Bumps}

% reference/000279.html

\index{bumps}\index{bumps! keyword}\index{bumps! pattern}\index{Keyword! bumps}\index{Pattern! bumps}

   The {\small\texttt{bumps}} pattern was originally designed only to be used as a normal pattern. It uses a very smooth, random noise function that creates the 
 look of rolling hills when scaled large or a bumpy orange peel when scaled small. Usually the bumps are about 1 unit apart. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{ slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{bumps}} pattern is identical to {\small\texttt{bozo}} or {\small\texttt{spotted}} and 
 is similar to normal bumps but is not identical as are most normals when compared to pigments. 



   \textbf{Note:} The appearance of the bumps pattern depends on the noise\_\-generator used. The default type is 2. This may be changed using the {\small\texttt{noise\_\-generator}} 
 keyword (See section "Pattern Modifiers / Noise\_\-generator"). 


\subsection{Cells}

% reference/000278.html

\index{cells}\index{cells! keyword}\index{cells! pattern}\index{Keyword! cells}\index{Pattern! cells}

   The {\small\texttt{cells}} pattern fills 3d space with unit cubes. Each cube gets a random value from 0 to 1. 



   {\small\texttt{cells}} is not very suitable as a normal as it has no smooth transitions of one grey value to another. 


\subsection{Checker}

% reference/000277.html

\index{checker}\index{checker! keyword}\index{checker! pattern}\index{Keyword! checker}\index{Pattern! checker}

   The {\small\texttt{checker}} pattern produces a checkered pattern consisting of alternating squares of two colors. The syntax is: 


{\small\begin{verbatim}
  pigment { checker [COLOR_1 [, COLOR_2]] [PATTERN_MODIFIERS...] }
\end{verbatim}}


   If no colors are specified then default blue and green colors are used. 



   The checker pattern is actually a series of cubes that are one unit in size. Imagine a bunch of 1 inch cubes made from two different colors of modeling clay. 
 Now imagine arranging the cubes in an alternating check pattern and stacking them in layer after layer so that the colors still alternate in every direction. 
 Eventually you would have a larger cube. The pattern of checks on each side is what the POV-\discretionary{}{}{}Ray checker pattern produces when applied to a box object. Finally 
 imagine cutting away at the cube until it is carved into a smooth sphere or any other shape. This is what the checker pattern would look like on an object of 
 any kind. 



   You may also use pigment statements in place of the colors. For example: 


{\small\begin{verbatim}
  pigment { checker pigment{Jade}, pigment{Black_Marble} }
\end{verbatim}}


   This example uses normals: 


{\small\begin{verbatim}
  normal { checker 0.5 }
\end{verbatim}}


   The float value is an optional bump size. You may also use full normal statements. For example: 


{\small\begin{verbatim}
  normal {
    checker normal{gradient x scale .2},
            normal{gradient y scale .2}
  }
\end{verbatim}}


   When used with textures, the syntax is 


{\small\begin{verbatim}
  texture { checker texture{T_Wood_3A},texture{Stone12} }
\end{verbatim}}


   The {\small\texttt{checker}} pattern has a default color\_\-map built in that results in blue and green tiles. 



   This use of checker as a texture pattern replaces the special tiles texture in previous versions of POV-\discretionary{}{}{}Ray. You may still use {\small\texttt{ tiles}} but it 
 may be phased out in future versions so checker textures are best. 



   This is a block pattern which cannot use wave types, {\small\texttt{ color\_\-map}}, or {\small\texttt{slope\_\-map}} modifiers. 


\subsection{Crackle Patterns}

% reference/000276.html

\index{crackle}\index{crackle! keyword}\index{crackle! pattern}\index{Keyword! crackle}\index{Pattern! crackle}\index{form! crackle}\index{Keyword! form}\index{metric! crackle}\index{Keyword! metric}\index{offset! crackle}\index{Keyword! offset}\index{solid! crackle}\index{Keyword! solid}\index{form}\index{metric}\index{solid}

   The {\small\texttt{crackle}} pattern is a set of random tiled multifaceted cells. 



   There is a choice between different types: 



   \textbf{Standard Crackle} \newline Mathematically, the set crackle(p)=0 is a 3D Voronoi diagram of a field of semi random points and crackle(p) $<$ 0 is the 
 distance from the set along the shortest path (a Voronoi diagram is the locus of points equidistant from their two nearest neighbors from a set of disjoint 
 points, like the membranes in suds are to the centers of the bubbles). 



   With a large scale and no turbulence it makes a pretty good stone wall or floor. \newline With a small scale and no turbulence it makes a pretty good crackle 
 ceramic glaze. \newline Using high turbulence it makes a good marble that avoids the problem of apparent parallel layers in traditional marble. 



   \textbf{Form} 


{\small\begin{verbatim}
  pigment {
    crackle form <FORM_VECTOR>
    [PIGMENT_ITEMS ...]
  }
  normal {
    crackle [Bump_Size]
    form <FORM_VECTOR>
    [NORMAL_ITEMS ...]
  }
\end{verbatim}}


   Form determines the linear combination of distances used to create the pattern. Form is a vector. \newline The first component determines the multiple of the 
 distance to the closest point to be used in determining the value of the pattern at a particular point. \newline The second component determines the 
 coefficient applied to the second-\discretionary{}{}{}closest distance. \newline The third component corresponds to the third-\discretionary{}{}{}closest distance. 



   The standard form is $<$-\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}0$>$ (also the default), corresponding to the difference in the distances to the closest and second-\discretionary{}{}{}closest points in the cell 
 array. Another commonly-\discretionary{}{}{}used form is $<$\discretionary{1,}{}{1,}\discretionary{0,}{}{0,}0$>$, corresponding to the distance to the closest point, which produces a pattern that looks roughly like a 
 random collection of intersecting spheres or cells. \newline Other forms can create very interesting effects, but it is best to keep the sum of the 
 coefficients low. \newline If the final computed value is too low or too high, the resultant pigment will be saturated with the color at the low or high end 
 of the {\small\texttt{color\_\-map}}. In this case, try multiplying the form vector by a constant. 



   \textbf{Metric} 


{\small\begin{verbatim}
  pigment {
    crackle metric METRIC_VALUE
    [PIGMENT_ITEMS ...]
  }
  normal {
    crackle [Bump_Size]
    metric METRIC_VALUE
    [NORMAL_ITEMS ...]
  }
\end{verbatim}}


   Changing the metric changes the function used to determine which cell center is closer, for purposes of determining which cell a particular point falls in. 
 The standard Euclidean distance function has a metric of 2. Changing the metric value changes the boundaries of the cells. A metric value of 3, for example, 
 causes the boundaries to curve, while a very large metric constrains the boundaries to a very small set of possible orientations. \newline The default for 
 metric is 2, as used by the standard crackle texture. \newline Metrics other than 1 or 2 can lead to substantially longer render times, as the method used to 
 calculate such metrics is not as efficient. 



   \textbf{Offset} 


{\small\begin{verbatim}
  pigment {
    crackle offset OFFSET_VALUE
    [PIGMENT_ITEMS ...]
  }
  normal {
    crackle [Bump_Size]
    offset OFFSET_VALUE
    [NORMAL_ITEMS ...]
  }
\end{verbatim}}


   The offset is used to displace the pattern from the standard xyz space along a fourth dimension. \newline It can be used to round off the "pointy" 
 parts of a cellular normal texture or procedural heightfield by keeping the distances from becoming zero. \newline It can also be used to move the calculated 
 values into a specific range if the result is saturated at one end of the color\_\-map. \newline The default offset is zero. 



   \textbf{Solid} 


{\small\begin{verbatim}
  pigment {
    crackle solid
    [PIGMENT_ITEMS ...]
  }
  normal {
    crackle [Bump_Size]
    solid
    [NORMAL_ITEMS ...]
  }
\end{verbatim}}


   Causes the same value to be generated for every point within a specific cell. This has practical applications in making easy stained-\discretionary{}{}{}glass windows or 
 flagstones. There is no provision for mortar, but mortar may be created by layering or texture-\discretionary{}{}{}mapping a standard crackle texture with a solid one. \newline The 
 default for this parameter is off. 


\subsection{Cylindrical}

% reference/000275.html

\index{cylindrical}\index{cylindrical! keyword}\index{cylindrical! pattern}\index{Keyword! cylindrical}\index{Pattern! cylindrical}

   The {\small\texttt{cylindrical}} pattern creates a one unit radius cylinder along the Y axis. It is computed by: \textit{ value = 1.0-min(1, sqrt(X\^{}2 + Z\^{}2))} 
 It starts at 1.0 at the origin and decreases to a minimum value of 0.0 as it approaches a distance of 1 unit from the Y axis. It remains at 0.0 for all areas 
 beyond that distance. This pattern was originally created for use with {\small\texttt{halo}} or {\small\texttt{media}} but it may be used anywhere any pattern 
 may be used. 


\subsection{Density\_\-File}

% reference/000274.html

\index{density\_\-file}\index{density\_\-file! keyword}\index{density\_\-file! pattern}\index{Keyword! density\_\-file}\index{Pattern! density\_\-file}\index{df3! density\_\-file}\index{Keyword! df3}\index{interpolate! density\_\-file}\index{Keyword! interpolate}\index{df3}

   The {\small\texttt{density\_\-file}} pattern is a 3-D bitmap pattern that occupies a unit cube from location $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$. The data file is a 
 raw binary file format created for POV-\discretionary{}{}{}Ray called {\small\texttt{ df3}} format. The syntax provides for the possibility of implementing other formats in the 
 future. This pattern was originally created for use with {\small\texttt{ halo}} or {\small\texttt{media}} but it may be used anywhere any pattern may be used. 
 The syntax is: 


{\small\begin{verbatim}
    pigment
    {
        density_file df3 "filename.df3"
        [interpolate Type] [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   where \textit{{\small\texttt{"\discretionary{filename.}{}{filename.}df3"}}} is a file name of the data file. 



   As a normal pattern, the syntax is 


{\small\begin{verbatim}
    normal
    {
        density_file df3 "filename.df3" [, Bump_Size]
        [interpolate Type]
        [NORMAL_MODIFIERS...]
    }
\end{verbatim}}


   The optional float \textit{{\small\texttt{Bump\_\-Size}}} should follow the file name and any other modifiers follow that. 



   The density pattern occupies the unit cube regardless of the dimensions in voxels. It remains at 0.0 for all areas beyond the unit cube. The data in the 
 range of 0 to 255, in case of 8 bit resolution, are scaled into a float value in the range 0.0 to 1.0. 



   The {\small\texttt{interpolate}} keyword may be specified to add interpolation of the data. The default value of zero specifies no interpolation. A value of 
 one specifies tri-\discretionary{}{}{}linear interpolation, a value of two specifies tri-\discretionary{}{}{}cubic interpolation 



   See the sample scenes for data file {\small\texttt{include$\backslash$\discretionary{}{}{}\discretionary{spiral.}{}{spiral.}df3}},and the scenes which use it: {\small\texttt{scenes$\backslash$\discretionary{}{}{}textures$\backslash$\discretionary{}{}{}patterns$\backslash$\discretionary{}{}{}\discretionary{densfile.}{}{densfile.}pov}}, {\small\texttt{ 
 scenes$\backslash$\discretionary{}{}{}interior$\backslash$\discretionary{}{}{}media$\backslash$\discretionary{}{}{}\discretionary{galaxy.}{}{galaxy.}pov}} for 
 examples. 


\subsubsection{df3 file format}

% reference/000273.html



   


\begin{description}
 
 \item 
   Header: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The {\small\texttt{df3}} format consists of a 6 byte header of three 16-bit 
  integers with high order byte first. These three values give the \discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z size of the data in pixels (or more appropriately called \textit{voxels }). 
 \end{list}

 \item 
   Data: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The header is followed by x*y*z unsigned integer bytes of data with a resolution of 
  8, 16 or 32 bit. The data are written with high order byte first (big-\discretionary{}{}{}endian). The resolution of the data is determined by the size of the df3-file. That is, 
  if the file is twice (minus header, of course) as long as an 8 bit file then it is assumed to contain 16 bit ints and if it is four times as long 32 bit 
  ints. 
 \end{list}

\end{description}

\subsection{Dents}

% reference/000272.html

\index{dents}\index{dents! keyword}\index{dents! pattern}\index{Keyword! dents}\index{Pattern! dents}

   The {\small\texttt{dents}} pattern was originally designed only to be used as a normal pattern. It is especially interesting when used with metallic 
 textures. It gives impressions into the metal surface that look like dents have been beaten into the surface with a hammer. Usually the dents are about 1 unit 
 apart. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{dents}} pattern is similar to normal dents but is not identical as are most normals 
 when compared to pigments. 


\subsection{Facets}

% reference/000271.html

\index{coords}\index{size}\index{facets}\index{facets! keyword}\index{facets! pattern}\index{Keyword! facets}\index{Pattern! facets}\index{coords! facets}\index{Keyword! coords}\index{size! facets}\index{Keyword! size}
{\small\begin{verbatim}
  normal {
    facets [coords SCALE_VALUE | size FACTOR]
    [NORMAL_ITEMS...]
  }
\end{verbatim}}


   The {\small\texttt{facets}} pattern is designed to be used as a normal, it is not suitable for use as a pigment: it will cause an error. \newline  There are 
 two forms of the facets pattern. One is most suited for use with rounded surfaces, and one is most suited for use with flat surfaces. 



   If {\small\texttt{coords}} is specified, the facets pattern creates facets with a size on the same order as the specified SCALE\_\-VALUE. This version of facets 
 is most suited for use with flat surfaces, but will also work with curved surfaces. The boundaries of the facets coincide with the boundaries of the cells in 
 the standard crackle pattern. The coords version of this pattern may be quite similar to a crackle normal pattern with solid specified. 



   If {\small\texttt{size}} is specified, the facets texture uses a different function that creates facets only on curved surfaces. The FACTOR determines how 
 many facets are created, with smaller values creating more facets, but it is not directly related to any real-\discretionary{}{}{}world measurement. The same factor will create 
 the same pattern of facets on a sphere of any size. \newline This pattern creates facets by snapping normal vectors to the closest vectors in a perturbed grid 
 of normal vectors. Because of this, if a surface has normal vectors that do not vary along one or more axes, there will be no facet boundaries along those 
 axes. 


\subsection{Fractal Patterns}

% reference/000270.html



   Fractal patterns supported in POV-\discretionary{}{}{}Ray: 


\begin{itemize}
 
 \item 
   The Mandelbrot set with exponents up to 33.(The formula for these is: {\small\texttt{z(n+1) = z(n)\^{}p + c}}, where {\small\texttt{p}} is the 
  correspondent exponent.) 
 

 \item 
   The equivalent Julia sets. 
 

 \item 
   The magnet1 and magnet2 fractals (which are derived from some magnetic renormalization transformations; see the fractint help for more details). \newline Both 
  'Mandelbrot' and 'Julia' versions of them are supported. 
 

\end{itemize}


   For the Mandelbrot and Julia sets, higher exponents will be slower for two reasons: 


\begin{enumerate}
 
 \item 
   For the exponents \discretionary{2,}{}{2,}3 and 4 an optimized algorithm is used. Higher exponents use a generic algorithm for raising a complex number to an integer 
  exponent, and this is a bit slower than an optimized version for a certain exponent. 
 

 \item 
   The higher the exponent, the slower it will be. This is because the amount of operations needed to raise a complex number to an integer exponent is 
  directly proportional to the exponent. This means that exponent 10 will be (very) roughly twice as slow as exponent 5. 
 

\end{enumerate}
\index{mandel}\index{mandel! keyword}\index{mandel! pattern}\index{Keyword! mandel}\index{Pattern! mandel}\index{julia}\index{julia! keyword}\index{julia! pattern}\index{Keyword! julia}\index{Pattern! julia}\index{magnet}\index{magnet! keyword}\index{magnet! pattern}\index{Keyword! magnet}\index{Pattern! magnet}\index{exponent! mandel}\index{exponent! julia}\index{exterior! mandel}\index{exterior! julia}\index{exterior! magnet}\index{interior! mandel}\index{interior! julia}\index{interior! magnet}\index{Keyword! exponent}\index{Keyword! exterior}\index{Keyword! interior}\index{exterior}

   Syntax: 


{\small\begin{verbatim}
MANDELBROT:
  mandel ITERATIONS [, BUMP_SIZE]
  [exponent EXPONENT]
  [exterior EXTERIOR_TYPE, FACTOR]
  [interior INTERIOR_TYPE, FACTOR]
  
JULIA:
  julia COMPLEX, ITERATIONS [, BUMP_SIZE]
  [exponent EXPONENT]
  [exterior EXTERIOR_TYPE, FACTOR]
  [interior INTERIOR_TYPE, FACTOR]

MAGNET MANDEL:
  magnet MAGNET_TYPE mandel ITERATIONS [, BUMP_SIZE]
  [exterior EXTERIOR_TYPE, FACTOR]
  [interior INTERIOR_TYPE, FACTOR]

MAGNET JULIA:
  magnet MAGNET_TYPE julia COMPLEX, ITERATIONS [, BUMP_SIZE]
  [exterior EXTERIOR_TYPE, FACTOR]
  [interior INTERIOR_TYPE, FACTOR]
\end{verbatim}}


   Where: 



   {\small\texttt{ITERATIONS}} is the number of times to iterate the algorithm. 



   {\small\texttt{COMPLEX}} is a 2D vector denoting a complex number. 



   {\small\texttt{MAGNET\_\-TYPE}} is either 1 or 2. 



   {\small\texttt{exponent}} is an integer between 2 and 33. If not given, the default is 2. 



   {\small\texttt{interior}} and {\small\texttt{exterior}} specify special coloring algorithms. You can specify one of them or both at the same time. They only 
 work with the fractal patterns. \newline {\small\texttt{EXTERIOR\_\-TYPE}} and {\small\texttt{INTERIOR\_\-TYPE}} are integer values between 0 and 6 (inclusive). 
 When not specified, the default value of INTERIOR\_\-TYPE is 0 and for EXTERIOR\_\-TYPE 1. \newline {\small\texttt{FACTOR}} is a float. The return value of the 
 pattern is multiplied by {\small\texttt{FACTOR}} before returning it. This can be used to scale the value range of the pattern when using interior and 
 exterior coloring (this is often needed to get the desired effect). The default value of FACTOR is 1. 



   The different values of EXTERIOR\_\-TYPE and INTERIOR\_\-TYPE have the following meaning: 


\begin{itemize}
 
 \item 
   0 : Returns just 1 
 

 \item 
   1 : For exterior: The number of iterations until bailout divided by ITERATIONS. \newline     Note: this is not scaled by FACTOR 
  (since it is internally scaled by 1/ITERATIONS instead). \newline     For interior: The absolute value of the smallest point in the orbit 
  of the calculated point 
 

 \item 
   2 : Real part of the last point in the orbit 
 

 \item 
   3 : Imaginary part of the last point in the orbit 
 

 \item 
   4 : Squared real part of the last point in the orbit 
 

 \item 
   5 : Squared imaginary part of the last point in the orbit 
 

 \item 
   6 : Absolute value of the last point in the orbit 
 

\end{itemize}


   Example: 


{\small\begin{verbatim}
  box {
    <-2, -2, 0>, <2, 2, 0.1>
    pigment {
      julia <0.353, 0.288>, 30
      interior 1, 1
      color_map { 
	    [0 rgb 0]
        [0.2 rgb x]
        [0.4 rgb x+y]
        [1 rgb 1]
        [1 rgb 0]
      }
    }
  }
\end{verbatim}}

\subsection{Function as pattern}

% reference/000269.html

\index{function! as pattern}\index{function! pattern}\index{Pattern! function}

   Allows you to use a function \{ \} block as pattern. 


{\small\begin{verbatim}
   pigment {
      function { USER_DEFINED_FUNCTIONS }
      [PIGMENT_MODIFIERS...]
   }
\end{verbatim}}


   Declaring a function:\newline  By default a function takes three parameters (\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z) and you do not have to explicitly specify the parameter names when 
 declaring it. When using the identifier, the parameters must be specified. 


{\small\begin{verbatim}
    #declare Foo = function { x + y + z}
    pigment {
      function { Foo(x, y, z) }
        [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   On the other hand, if you need more or less than three parameters when declaring a function, you also have to explicitly specify the parameter names. 


{\small\begin{verbatim}
    #declare Foo = function(x,y,z,t) { x + y + z + t}
    pigment {
      function { Foo(x, y, z, 4) }
        [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   Using function in a normal: 


{\small\begin{verbatim}
    #declare Foo = function { x + y + z}
    normal {
      function { Foo(x, y, z) } [Bump_Size]
      [MODIFIERS...]
    }
\end{verbatim}}

\subsubsection{What can be used}

% reference/000268.html



   All float expressions and operators (see section "User-\discretionary{}{}{}Defined Functions") which are legal in POV-\discretionary{}{}{}Ray. Of special interest here is the {\small\texttt{pattern}} 
 option, that makes it possible to use patterns as functions 


{\small\begin{verbatim}
 #declare FOO = function {
    pattern {
      checker
    }
  }
\end{verbatim}}


   User defined functions (like equations). 



   Since pigments can be declared as functions, they can also be used in functions. They must be declared first. When using the identifier, you have to specify 
 which component of the color vector should be used. To do this, the dot notation is used: Function(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z).red 


{\small\begin{verbatim}
   #declare FOO = function {pigment { checker } }
   pigment {
      function { FOO(x,y,z).green }
      [PIGMENT_MODIFIERS...]
   }
\end{verbatim}}


   POV-\discretionary{}{}{}Ray has a large amount of pre-\discretionary{}{}{}defined functions. These are mainly algebraic surfaces but there is also a mesh function and noise3d function. See section "Internal 
 Functions" for a complete list and some explanation on the parameters to use. These internal functions can be included through the \discretionary{functions.}{}{functions.}inc include file. 


{\small\begin{verbatim} 
   #include "functions.inc"
   #declare FOO = function {pigment { checker } }
   pigment {
      function { FOO(x,y,z).green \& f_noise3d(x*2, y*3,z)}
      [PIGMENT_MODIFIERS...]
   }
\end{verbatim}}

\subsection{Function Image}

% reference/000267.html

\index{function! internal bitmap}\index{function image! pattern}\index{Pattern! function image}

   Syntax :{\small\texttt{function Width, Height \{ FUNCTION\_\-BODY \}}} 



   Not a real pattern, but listed here for convenience. This keyword defines a new 'internal' bitmap image type. The pixels of the image are derived from the 
 Function\_\-Body, with Function\_\-Body either being a regular function, a pattern function or a pigment function. In case of a pigment function the output image 
 will be in color, in case of a pattern or regular function the output image will be grayscale. All variants of grayscale pigment functions are available using 
 the regular function syntax, too. In either case the image will use 16 bit per component 



   \textbf{Note:} functions are evaluated on the x-\discretionary{}{}{}y plane. This is different from the pattern image type for the reason that it makes using uv functions 
 easier. 



   Width and Height specify the resolution of the resulting 'internal' bitmap image. The image is taken from the square region {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$, 
 $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}0$>$}} 



   The {\small\texttt{function}} statement can be used wherever an image specifier like {\small\texttt{tga}} or {\small\texttt{png}} may be used. Some uses 
 include creating heightfields from procedural textures or wrapping a slice of a 3d texture or function around a cylinder or extrude it along an axis. 



   Examples: 


{\small\begin{verbatim}
   plane { 
      y, -1 
      pigment { 
         image_map { 
            function 10,10 { 
               pigment { checker 1,0 scale .5  }
            }
         }
         rotate x*90
      } 
   }
\end{verbatim}}

{\small\begin{verbatim}
   height_field {
      function 200,200 {
         pattern {
            bozo
         }
      }
      translate -0.5
      scale 10
      pigment {rgb 1}
   }
\end{verbatim}}


   \textbf{Note:} that for height fields and other situations where color is not needed it is easier to use {\small\texttt{function \discretionary{n,}{}{n,}n \{pattern\{...\}\}}} than {\small\texttt{function 
 \discretionary{n,}{}{n,}n \{pigment\{...\}\}}}. The pattern functions are returning a scalar, not a color vector, thus a pattern is grayscale. 


\subsection{Gradient}

% reference/000266.html

\index{gradient}\index{gradient! keyword}\index{gradient! pattern}\index{Keyword! gradient}\index{Pattern! gradient}

   One of the simplest patterns is the {\small\texttt{gradient}} pattern. It is specified as 


{\small\begin{verbatim}
    pigment {
        gradient <Orientation>
        [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   where \textit{{\small\texttt{$<$Orientation$>$}}} is a vector pointing in the direction that the colors blend. For example 


{\small\begin{verbatim}
   pigment { gradient x } // bands of color vary as you move
                          // along the "x" direction.
\end{verbatim}}


   produces a series of smooth bands of color that look like layers of colors next to each other. Points at x=0 are the first color in the color map. As the x 
 location increases it smoothly turns to the last color at x=1. Then it starts over with the first again and gradually turns into the last color at x=2. In 
 POV-\discretionary{}{}{}Ray versions older than 3.5 the pattern reverses for negative values of x. As per POV-\discretionary{}{}{}Ray 3.5 this is not the case anymore [1]. Using {\small\texttt{gradient 
 y}} or {\small\texttt{gradient z}} makes the colors blend along the y- or z-\discretionary{}{}{}axis. Any vector may be used but x, y and z are most common. 



   As a normal pattern, gradient generates a saw-\discretionary{}{}{}tooth or ramped wave appearance. The syntax is 


{\small\begin{verbatim}
    normal {
        gradient <Orientation> [, Bump_Size]
        [NORMAL_MODIFIERS...]
    }
\end{verbatim}}


   where the vector \textit{{\small\texttt{$<$Orientation$>$}}} is a required parameter but the float \textit{{\small\texttt{Bump\_\-Size}}} which follows is 
 optional. 



   \textbf{Note:} the comma is required especially if \textit{Bump\_\-Size} is negative. 



   [1] If only the range -1 to 1 was used of the old gradient, for example in a {\small\texttt{sky\_\-sphere}}, it can be replaced by the {\small\texttt{planar}} 
 or {\small\texttt{marble}} pattern and revert the color\_\-map. Also rotate the pattern for other orientations than {\small\texttt{y}}. A more general solution 
 is to use {\small\texttt{function\{abs(x)\}}} as a pattern instead of {\small\texttt{gradient x}} and similar for {\small\texttt{gradient y}} and {\small\texttt{gradient 
 z}}. 


\subsection{Granite}

% reference/000265.html

\index{granite}\index{granite! keyword}\index{granite! pattern}\index{Keyword! granite}\index{Pattern! granite}

   The {\small\texttt{granite}} pattern uses a simple 1/f fractal noise function to give a good granite pattern. This pattern is used with creative color maps 
 in {\small\texttt{\discretionary{stones.}{}{stones.}inc}} to create some gorgeous layered stone textures. 



   As a normal pattern it creates an extremely bumpy surface that looks like a gravel driveway or rough stone. 



   \textbf{Note:} The appearance of the granite pattern depends on the noise\_\-generator used. The default type is 2. This may be changed using the {\small\texttt{noise\_\-generator}} 
 keyword (See section "Pattern Modifiers / Noise\_\-generator"). 


\subsection{Hexagon}

% reference/000264.html

\index{hexagon}\index{hexagon! keyword}\index{hexagon! pattern}\index{Keyword! hexagon}\index{Pattern! hexagon}

   The {\small\texttt{hexagon}} pattern is a block pattern that generates a repeating pattern of hexagons in the x-\discretionary{}{}{}z-\discretionary{}{}{}plane. In this instance imagine tall rods 
 that are hexagonal in shape and are parallel to the y-\discretionary{}{}{}axis and grouped in bundles like shown in the example image. Three separate colors should be specified 
 as follows: 


{\small\begin{verbatim}
    pigment {
        hexagon [COLOR_1 [, COLOR_2 [, COLOR_3]]]
        [PATTERN_MODIFIERS...]
    }
\end{verbatim}}


   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/hexpat} \caption{The hexagon pattern.} \end{figure} 



   The three colors will repeat the hexagonal pattern with hexagon \textit{ COLOR\_\-1} centered at the origin, \textit{COLOR\_\-2} in the +z-\discretionary{}{}{}direction and \textit{COLOR\_\-3} 
 to either side. Each side of the hexagon is one unit long. The hexagonal rods of color extend infinitely in the +y- and -y-\discretionary{}{}{}directions. If no colors are 
 specified then default blue, green and red colors are used. 



   You may also use pigment statements in place of the colors. For example: 


{\small\begin{verbatim}
  pigment {
    hexagon 
    pigment { Jade },
    pigment { White_Marble },
    pigment { Black_Marble }
  }
\end{verbatim}}


   This example uses normals: 


{\small\begin{verbatim}
  normal { hexagon 0.5 }
\end{verbatim}}


   The float value is an optional bump size. You may also use full normal statements. For example: 


{\small\begin{verbatim}
  normal {
    hexagon
      normal { gradient x scale .2 },
      normal { gradient y scale .2 },
      normal { bumps scale .2 }
  }
\end{verbatim}}


   When used with textures, the syntax is... 


{\small\begin{verbatim}
  texture {
    hexagon
      texture { T_Gold_3A },
      texture { T_Wood_3A },
      texture { Stone12 }
  }
\end{verbatim}}


   The {\small\texttt{hexagon}} pattern has a default color\_\-map built in that results in red, blue and green tiles. 



   This is a block pattern which cannot use wave types, {\small\texttt{ color\_\-map}}, or {\small\texttt{slope\_\-map}} modifiers. 


\subsection{Image Pattern}

% reference/000263.html



   Instead of placing the color of the image on the object like an image\_\-map an image\_\-pattern specifies an entire texture item (color, pigment, normal or 
 texture) based on the gray value at that point. \newline This gray-\discretionary{}{}{}value is checked against a list and the corresponding item is then used for the texture at 
 that particular point. For values between listed items, an averaged texture is calculated. \newline It takes a standard image specification and has one 
 option, {\small\texttt{use\_\-alpha}} which works similar to {\small\texttt{use\_\-color}} or {\small\texttt{use\_\-index}}.\index{image\_\-pattern}\index{image\_\-pattern! keyword}\index{image\_\-pattern! pattern}\index{Keyword! image\_\-pattern}\index{Pattern! image\_\-pattern}\index{map\_\-type! image\_\-pattern}\index{Keyword! map\_\-type}\index{once! image\_\-pattern}\index{Keyword! once}\index{interpolate! image\_\-pattern}\index{Keyword! interpolate}\index{use\_\-alpha! image\_\-pattern}\index{Keyword! use\_\-alpha}\index{use\_\-alpha} 
 



   Syntax: 


{\small\begin{verbatim}
PIGMENT:
  pigment {
    IMAGE_PATTERN
    color_map { COLOR_MAP_BODY } |
    colour_map { COLOR_MAP_BODY } | 
    pigment_map { PIGMENT_MAP_BODY }
  }

NORMAL:
  normal {
    IMAGE_PATTERN [Bump_Size]
    normal_map { NORMAL_MAP_BODY }
  }

TEXTURE:
  texture {
    IMAGE_PATTERN
    texture_map { TEXTURE_MAP_BODY }
  }

IMAGE_PATTERN
    image_pattern {
      BITMAP_TYPE "bitmap.ext"
      [IMAGE_MAP_MODS...]
    }
IMAGE_MAP_MOD:
    map_type Type | once | interpolate Type | use_alpha
ITEM_MAP_BODY:
    ITEM_MAP_IDENTIFIER | ITEM_MAP_ENTRY...
ITEM_MAP_ENTRY:
    [ GRAY_VALUE  ITEM_MAP_ENTRY... ]
\end{verbatim}}


   It is also useful for creating texture "masks", like the following: 


{\small\begin{verbatim}
 texture {
   image_pattern { tga "image.tga" use_alpha }
   texture_map {
     [0 Mytex ]
     [1 pigment { transmit 1 } ]
   }
 }
\end{verbatim}}


   \textbf{Note:} This pattern uses an image to get the gray values from. If you want exactly the same possibilities but need to get gray values from a pigment, 
 you can use the pigment\_\-pattern. 


\subsection{Leopard}

% reference/000262.html

\index{leopard}\index{leopard! keyword}\index{leopard! pattern}\index{Keyword! leopard}\index{Pattern! leopard}

   Leopard creates regular geometric pattern of circular spots. The formula used is: \textit{ value = Sqr((sin(x)+sin(y)+sin(z))/3)} 


\subsection{Marble}

% reference/000261.html

\index{marble}\index{marble! keyword}\index{marble! pattern}\index{Keyword! marble}\index{Pattern! marble}

   The {\small\texttt{marble}} pattern is very similar to the {\small\texttt{gradient x}} pattern. The gradient pattern uses a default {\small\texttt{ramp\_\-wave}} 
 wave type which means it uses colors from the color map from 0.0 up to 1.0 at location x=1 but then jumps back to the first color for x $>$ 1 and repeats the 
 pattern again and again. However the {\small\texttt{marble}} pattern uses the {\small\texttt{triangle\_\-wave}} wave type in which it uses the color map from 0 
 to 1 but then it reverses the map and blends from 1 back to zero. For example: 


{\small\begin{verbatim}
  pigment {
    gradient x
    color_map {
      [0.0  color Yellow]
      [1.0  color Cyan]
    }
  }
\end{verbatim}}


   This blends from yellow to cyan and then it abruptly changes back to yellow and repeats. However replacing {\small\texttt{gradient x}} with {\small\texttt{ 
 marble}} smoothly blends from yellow to cyan as the x coordinate goes from 0.0 to 0.5 and then smoothly blends back from cyan to yellow by x=1.0. 



   Earlier versions of POV-\discretionary{}{}{}Ray did not allow you to change wave types. Now that wave types can be changed for most any pattern, the distinction between {\small\texttt{marble}} 
 and {\small\texttt{gradient x}} is only a matter of default wave types. 



   When used with turbulence and an appropriate color map, this pattern looks like veins of color of real marble, jade or other types of stone. By default, 
 marble has no turbulence. 



   The {\small\texttt{marble}} pattern has a default color\_\-map built in that results in a red, black and white pattern with smooth and sharp transitions. 


\subsection{Object Pattern}

% reference/000260.html

\index{object}\index{object! keyword}\index{object! pattern}\index{Keyword! object}\index{Pattern! object}

   The {\small\texttt{object}} pattern takes an object as input. It generates a, two item, color list pattern. Whether a point is assigned to one item or the 
 other depends on whether it is inside the specified object or not. 



   Object's used in the {\small\texttt{object}} pattern cannot have a texture and must be solid - these are the same limitations as for {\small\texttt{bounded\_\-by}} 
 and {\small\texttt{clipped\_\-by}}. 



   Syntax: 


{\small\begin{verbatim}
 object {
   OBJECT_IDENTIFIER | OBJECT {}
   LIST_ITEM_A, LIST_ITEM_B
 }
\end{verbatim}}


   Where OBJ\_\-IDENTIFIER is the target object (which must be declared), or use the full object syntax. LIST\_\-ITEM\_\-A and LIST\_\-ITEM\_\-B are the colors, pigments, or 
 whatever the pattern is controlling. LIST\_\-ITEM\_\-A is used for all points outside the object, and LIST\_\-ITEM\_\-B is used for all points inside the object. 



   Example: 


{\small\begin{verbatim}
 pigment {
    object {
       myTextObject 
       color White 
       color Red
    }
    turbulence 0.15
 }
\end{verbatim}}


   \textbf{Note:} This is a block pattern which cannot use wave types, color\_\-map, or slope\_\-map modifiers. 


\subsection{Onion}

% reference/000259.html

\index{onion}\index{onion! keyword}\index{onion! pattern}\index{Keyword! onion}\index{Pattern! onion}

   The {\small\texttt{onion}} is a pattern of concentric spheres like the layers of an onion. \textit{ Value = mod(sqrt(Sqr(X)+Sqr(Y)+Sqr(Z)), 1.0)} Each layer 
 is one unit thick. 


\subsection{Pigment Pattern}

% reference/000258.html

\index{pigment\_\-pattern}\index{pigment\_\-pattern! keyword}\index{pigment\_\-pattern! pattern}\index{Keyword! pigment\_\-pattern}\index{Pattern! pigment\_\-pattern}

   Use any pigment as a pattern. Instead of using the pattern directly on the object, a pigment\_\-pattern converts the pigment to gray-\discretionary{}{}{}scale first. For each 
 point, the gray-\discretionary{}{}{}value is checked against a list and the corresponding item is then used for the texture at that particular point. For values between listed 
 items, an averaged texture is calculated. \newline Texture items can be color, pigment, normal or texture and are specified in a color\_\-map, pigment\_\-map, 
 normal\_\-map or texture\_\-map. \newline It takes a standard pigment specification. 



   Syntax: 


{\small\begin{verbatim}
PIGMENT:
  pigment {
    pigment_pattern { PIGMENT_BODY }
    color_map { COLOR_MAP_BODY } |
    colour_map { COLOR_MAP_BODY } | 
    pigment_map { PIGMENT_MAP_BODY }
  }

NORMAL:
  normal {
    pigment_pattern { PIGMENT_BODY } [Bump_Size]
    normal_map { NORMAL_MAP_BODY }
  }

TEXTURE:
  texture {
    pigment_pattern { PIGMENT_BODY }
    texture_map { TEXTURE_MAP_BODY }
  }

ITEM_MAP_BODY:
    ITEM_MAP_IDENTIFIER | ITEM_MAP_ENTRY...
ITEM_MAP_ENTRY:
    [ GRAY_VALUE  ITEM_MAP_ENTRY... ]
\end{verbatim}}


   This pattern is also useful when parent and children patterns need to be transformed independently from each other. Transforming the pigment\_\-pattern will not 
 affect the child textures. When any of the child textures should be transformed, apply it to the specific MAP\_\-ENTRY. 



   This can be used with any pigments, ranging from a simple checker to very complicated nested pigments. For example: 


{\small\begin{verbatim}
 pigment {
   pigment_pattern {
     checker White, Black
     scale 2
     turbulence .5
   }
   pigment_map {
     [ 0, checker Red, Green scale .5 ]
     [ 1, checker Blue, Yellow scale .2 ]
   }
 }
\end{verbatim}}


   \textbf{Note:} This pattern uses a pigment to get the gray values from. If you want to get the pattern from an image, you should use the image\_\-pattern. 


\subsection{Planar}

% reference/000257.html

\index{planar}\index{planar! keyword}\index{planar! pattern}\index{Keyword! planar}\index{Pattern! planar}

   The {\small\texttt{planar}} pattern creates a horizontal stripe plus or minus one unit above and below the X-\discretionary{}{}{}Z plane. It is computed by: \textit{ value =1.0- 
 min(1, abs(Y))} It starts at 1.0 at the origin and decreases to a minimum value of 0.0 as the Y values approaches a distance of 1 unit from the X-\discretionary{}{}{}Z plane. It 
 remains at 0.0 for all areas beyond that distance. This pattern was originally created for use with {\small\texttt{halo}} or {\small\texttt{ media}} but it 
 may be used anywhere any pattern may be used. 


\subsection{Quilted}

% reference/000256.html

\index{quilted}\index{quilted! keyword}\index{quilted! pattern}\index{Keyword! quilted}\index{Pattern! quilted}\index{control0! quilted}\index{Keyword! control0}\index{control1! quilted}\index{Keyword! control1}

   The {\small\texttt{quilted}} pattern was originally designed only to be used as a normal pattern. The quilted pattern is so named because it can create a 
 pattern somewhat like a quilt or a tiled surface. The squares are actually 3-D cubes that are 1 unit in size. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{ slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{quilted}} pattern is similar to normal quilted but is not identical as are most normals 
 when compared to pigments. 



   The two parameters {\small\texttt{control0}} and {\small\texttt{ control1}} are used to adjust the curvature of the \textit{ seam} or \textit{ gouge} area 
 between the {\small\texttt{quilts}}. 



   The syntax is: 


{\small\begin{verbatim}
    pigment { quilted [QUILTED_MODIFIERS...] }
QUILTED_MODIFIERS:
  control0 Value_0 | control1 Value_1 | PIGMENT_MODIFIERS
\end{verbatim}}


   The values should generally be kept to around the 0.0 to 1.0 range. The default value is 1.0 if none is specified. Think of this gouge between the tiles in 
 cross-\discretionary{}{}{}section as a sloped line. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/quiltpt1} \caption{Quilted pattern with c0=0 and different values for c1.} \end{figure} 
 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/quiltpt2} \caption{Quilted pattern with c0=0.33 and different values for c1.} \end{figure} 
 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/quiltpt3} \caption{Quilted pattern with c0=0.67 and different values for c1.} \end{figure} 
 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/quiltpt4} \caption{Quilted pattern with c0=1 and different values for c1.} \end{figure} 
 



   This straight slope can be made to curve by adjusting the two control values. The control values adjust the slope at the top and bottom of the curve. A 
 control values of 0 at both ends will give a linear slope, as shown above, yielding a hard edge. A control value of 1 at both ends will give an "s" 
 shaped curve, resulting in a softer, more rounded edge. 



   The syntax for use as a normal is: 


{\small\begin{verbatim}
  normal { 
    quilted [Bump_Size]
    [QUILTED_MODIFIERS...] 
  }
QUILTED_MODIFIERS:
  control0 Value_0 | control1 Value_1 | PIGMENT_MODIFIERS
\end{verbatim}}

\subsection{Radial}

% reference/000255.html

\index{radial}\index{radial! keyword}\index{radial! pattern}\index{Keyword! radial}\index{Pattern! radial}\index{frequency! radial}\index{Keyword! frequency}

   The {\small\texttt{radial}} pattern is a radial blend that wraps around the +y-\discretionary{}{}{}axis. The color for value 0.0 starts at the +x-\discretionary{}{}{}direction and wraps the color 
 map around from east to west with 0.25 in the -z-\discretionary{}{}{}direction, 0.5 in -x, 0.75 at +z and back to 1.0 at +x. Typically the pattern is used with a {\small\texttt{ 
 frequency}} modifier to create multiple bands that radiate from the y-\discretionary{}{}{}axis. For example: 


{\small\begin{verbatim}
  pigment {
    radial color_map{[0.5 Black][0.5 White]}
    frequency 10
  }
\end{verbatim}}


   creates 10 white bands and 10 black bands radiating from the y axis. 



   The {\small\texttt{radial}} pattern has a default color\_\-map built in that results in a yellow, magenta and cyan pattern with smooth transitions. 


\subsection{Ripples}

% reference/000254.html

\index{ripples}\index{ripples! keyword}\index{ripples! pattern}\index{Keyword! ripples}\index{Pattern! ripples}

   The {\small\texttt{ripples}} pattern was originally designed only to be used as a normal pattern. It makes the surface look like ripples of water. The 
 ripples radiate from 10 random locations inside the unit cube area $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$. Scale the pattern to make the centers closer or farther 
 apart. 



   Usually the ripples from any given center are about 1 unit apart. The {\small\texttt{ frequency}} keyword changes the spacing between ripples. The {\small\texttt{ 
 phase}} keyword can be used to move the ripples outwards for realistic animation. 



   The number of ripple centers can be changed with the global parameter global\_\-settings\{number\_\-of\_\-waves Count \} 



   somewhere in the scene. This affects the entire scene. You cannot change the number of wave centers on individual patterns. See section 
 "Number\_\-Of\_\-Waves" for details. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{ slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{ripples}} pattern is similar to normal ripples but is not identical as are most normals 
 when compared to pigments. 


\subsection{Slope}

% reference/000253.html

\index{altitude}\index{slope}\index{slope! keyword}\index{slope! pattern}\index{Keyword! slope}\index{Pattern! slope}\index{altitude! slope}\index{Keyword! altitude}

   The {\small\texttt{slope}} pattern uses the normal of a surface to calculate the slope at a given point. It then creates the pattern value dependent on the 
 slope and optionally the altitude. It can be used for pigments, normals and textures, but not for media densities. For pigments the syntax is: 


{\small\begin{verbatim}
  pigment {
    slope {
      <Direction> [, Lo_slope, Hi_slope ]
      [ altitude <Altitude> [, Lo_alt, Hi_alt ]]
    }
    [PIGMENT_MODIFIERS...]
  }
\end{verbatim}}


   The slope value at a given point is dependent on the angle between the {\small\texttt{$<$Direction$>$}} vector and the normal of the surface at that point. 
 For example: \newline - When the surface normal points in the opposite direction of the {\small\texttt{$<$Direction$>$}} vector (180 degrees), the slope is 
 0.0. \newline - When the surface normal is perpendicular to the {\small\texttt{$<$Direction$>$}} vector (90 degrees), the slope is 0.5. \newline - When the 
 surface normal is parallel to the {\small\texttt{$<$Direction$>$}} vector (0 degrees), the slope is 1.0. 



   When using the simplest variant of the syntax: 


{\small\begin{verbatim}
  slope { <Direction> }
\end{verbatim}}


   the pattern value for a given point is the same as the slope value. {\small\texttt{$<$Direction$>$}} is a 3-dimensional vector and will usually be {\small\texttt{$<$0,-\discretionary{1,}{}{1,}0$>$}} 
 for landscapes, but any direction can be used. 



   By specifying {\small\texttt{Lo\_\-slope}} and {\small\texttt{Hi\_\-slope}} you get more control: 


{\small\begin{verbatim}
  slope { <Direction>, Lo_slope, Hi_slope }
\end{verbatim}}


   {\small\texttt{Lo\_\-slope}} and {\small\texttt{Hi\_\-slope}} specifies which range of slopes are used, so you can control which slope values return which pattern 
 values. {\small\texttt{Lo\_\-slope}} is the slope value that returns 0.0 and {\small\texttt{Hi\_\-slope}} is the slope value that returns 1.0. 



   For example, if you have a height\_\-field and {\small\texttt{$<$Direction$>$}} is set to {\small\texttt{$<$0,-\discretionary{1,}{}{1,}0$>$}}, then the slope values would only 
 range from 0.0 to 0.5 because height\_\-fields cannot have overhangs. If you do not specify {\small\texttt{Lo\_\-slope}} and {\small\texttt{Hi\_\-slope}}, you should 
 keep in mind that the texture for the flat (horizontal) areas must be set at 0.0 and the texture for the steep (vertical) areas at 0.5 when designing the 
 texture\_\-map. The part from 0.5 up to 1.0 is not used then. But, by setting {\small\texttt{Lo\_\-slope}} and {\small\texttt{Hi\_\-slope}} to 0.0 and 0.5 
 respectively, the slope range will be stretched over the entire map, and the texture\_\-map can then be defined from 0.0 to 1.0. 



   By adding an optional {\small\texttt{$<$Altitude$>$}} vector: 


{\small\begin{verbatim}
  slope {
    <Direction>
    altitude <Altitude>
  }
\end{verbatim}}


   the pattern will be influenced not only by the slope but also by a special gradient. {\small\texttt{$<$Altitude$>$}} is a 3-dimensional vector that 
 specifies the direction of the gradient. When {\small\texttt{$<$Altitude$>$}} is specified, the pattern value is a weighted average of the slope value and 
 the gradient value. The weights are the lengths of the vectors {\small\texttt{$<$Direction$>$}} and {\small\texttt{$<$Altitude$>$}}. So if {\small\texttt{$<$Direction$>$}} 
 is much longer than {\small\texttt{$<$Altitude$>$}} it means that the slope has greater effect on the results than the gradient. If on the other hand {\small\texttt{$<$Altitude$>$}} 
 is longer, it means that the gradient has more effect on the results than the slope. 



   When adding the {\small\texttt{$<$Altitude$>$}} vector, the default gradient is defined from 0 to 1 units along the specified axis. This is fine when your 
 object is defined within this range, otherwise a correction is needed. This can be done with the optional {\small\texttt{Lo\_\-alt}} and {\small\texttt{Hi\_\-alt}} 
 parameters: 


{\small\begin{verbatim}
  slope {
    <Direction>
    altitude <Altitude>, Lo_alt, Hi_alt
  }
\end{verbatim}}


   They define the range of the gradient along the axis defined by the $<$Altitude$>$ vector. 



   For example, with an {\small\texttt{$<$Altitude$>$}} vector set to y and an object going from -3 to 2 on the y axis, the {\small\texttt{Lo\_\-alt}} and {\small\texttt{Hi\_\-alt}} 
 parameters should be set to -3 and 2 respectively. 



   \textbf{Note:} 


\begin{itemize}
 
 \item 
   You may use the turbulence keyword inside slope pattern definitions but it may cause unexpected results. Turbulence is a 3-dimensional distortion of a 
  pattern. Since slope is only defined on surfaces of objects, a 3-dimensional turbulence is not applicable to the slope component. However, if you are using 
  altitude, the altitude component of the pattern will be affected by turbulence. 
 

 \item 
   If your object is larger than the range of altitude you have specified, you may experience unexpected discontinuities. In that case it is best to 
  adjust the {\small\texttt{Lo\_\-alt}} and {\small\texttt{Hi\_\-alt}} values so they fit to your object. 
 

 \item 
   The slope pattern does not work for the sky\_\-sphere, because the sky\_\-sphere is a background feature and does not have a surface. similarly, it does not 
  work for media densities. 
 

\end{itemize}

\subsection{Spherical}

% reference/000252.html

\index{spherical}\index{spherical! keyword}\index{spherical! pattern}\index{Keyword! spherical}\index{Pattern! spherical}

   The {\small\texttt{spherical}} pattern creates a one unit radius sphere, with its center at the origin. It is computed by: \textit{ value = 1.0-min(1, 
 sqrt(X\^{}2 + Y\^{}2 + Z\^{}2))} It starts at 1.0 at the origin and decreases to a minimum value of 0.0 as it approaches a distance of 1 unit from the origin in any 
 direction. It remains at 0.0 for all areas beyond that distance. This pattern was originally created for use with {\small\texttt{halo}} or {\small\texttt{media}} 
 but it may be used anywhere any pattern may be used. 


\subsection{Spiral1}

% reference/000251.html

\index{spiral1}\index{spiral1! keyword}\index{spiral1! pattern}\index{Keyword! spiral1}\index{Pattern! spiral1}\index{spiral}

   The {\small\texttt{spiral1}} pattern creates a spiral that winds around the z-\discretionary{}{}{}axis similar to a screw. When viewed sliced in the x-\discretionary{}{}{}y plane, it looks like the 
 spiral arms of a galaxy. Its syntax is: 


{\small\begin{verbatim}
    pigment
    {
        spiral1 Number_of_Arms
        [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   The \textit{{\small\texttt{Number\_\-of\_\-Arms}}} value determines how may arms are winding around the z-\discretionary{}{}{}axis. 



   As a normal pattern, the syntax is 


{\small\begin{verbatim}
    normal
    {
        spiral1 Number_of_Arms [, Bump_Size]
        [NORMAL_MODIFIERS...]
    }
\end{verbatim}}


   where the {\small\texttt{Number\_\-of\_\-Arms}} value is a required parameter but the float \textit{{\small\texttt{Bump\_\-Size}}} which follows is optional. 



   \textbf{Note:} the comma is required especially if \textit{Bump\_\-Size} is negative. 



   The pattern uses the {\small\texttt{triangle\_\-wave}} wave type by default but may use any wave type. 


\subsection{Spiral2}

% reference/000250.html

\index{spiral2}\index{spiral2! keyword}\index{spiral2! pattern}\index{Keyword! spiral2}\index{Pattern! spiral2}

   The {\small\texttt{spiral2}} pattern creates a double spiral that winds around the z-\discretionary{}{}{}axis similar to {\small\texttt{spiral1}} except that it has two 
 overlapping spirals which twist in opposite directions. The result sometimes looks like a basket weave or perhaps the skin of pineapple. The center of a 
 sunflower also has a similar double spiral pattern. Its syntax is: 


{\small\begin{verbatim}
    pigment
    {
        spiral2 Number_of_Arms
        [PIGMENT_MODIFIERS...]
    }
\end{verbatim}}


   The \textit{{\small\texttt{Number\_\-of\_\-Arms}}} value determines how may arms are winding around the z-\discretionary{}{}{}axis. As a normal pattern, the syntax is 


{\small\begin{verbatim}
    normal
    {
        spiral2 Number_of_Arms [, Bump_Size]
        [NORMAL_MODIFIERS...]
    }
\end{verbatim}}


   where the {\small\texttt{Number\_\-of\_\-Arms}} value is a required parameter but the float \textit{{\small\texttt{Bump\_\-Size}}} which follows is optional. 



   \textbf{Note:} the comma is required especially if \textit{Bump\_\-Size} is negative. The pattern uses the {\small\texttt{triangle\_\-wave}} wave type by default 
 but may use any wave type. 


\subsection{Spotted}

% reference/000284.html

\index{spotted}\index{spotted! keyword}\index{spotted! pattern}\index{Keyword! spotted}\index{Pattern! spotted}

   The {\small\texttt{spotted}} pattern is identical to the {\small\texttt{bozo}} pattern. Early versions of POV-\discretionary{}{}{}Ray did not allow turbulence to be used with 
 spotted. Now that any pattern can use turbulence there is no difference between {\small\texttt{bozo}} and {\small\texttt{spotted}}. See section 
 "Bozo" for details. 


\subsection{Waves}

% reference/000285.html

\index{waves}\index{waves! keyword}\index{waves! pattern}\index{Keyword! waves}\index{Pattern! waves}

   The {\small\texttt{waves}} pattern was originally designed only to be used as a normal pattern. It makes the surface look like waves on water. The {\small\texttt{ 
 waves}} pattern looks similar to the {\small\texttt{ripples}} pattern except the features are rounder and broader. The effect is to make waves that look more 
 like deep ocean waves. The waves radiate from 10 random locations inside the unit cube area $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$. Scale the pattern to make the 
 centers closer or farther apart. 



   Usually the waves from any given center are about 1 unit apart. The {\small\texttt{ frequency}} keyword changes the spacing between waves. The {\small\texttt{ 
 phase}} keyword can be used to move the waves outwards for realistic animation. 



   The number of wave centers can be changed with the global parameter 


{\small\begin{verbatim}
 global_settings { number_of_waves Count }
\end{verbatim}}


   somewhere in the scene. This affects the entire scene. You cannot change the number of wave centers on individual patterns. See section 
 "Number\_\-Of\_\-Waves" for details. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{ slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{waves}} pattern is similar to normal waves but is not identical as are most normals 
 when compared to pigments. 


\subsection{Wood}

% reference/000286.html

\index{wood}\index{wood! keyword}\index{wood! pattern}\index{Keyword! wood}\index{Pattern! wood}

   The {\small\texttt{wood}} pattern consists of concentric cylinders centered on the z-\discretionary{}{}{}axis. When appropriately colored, the bands look like the growth rings 
 and veins in real wood. Small amounts of turbulence should be added to make it look more realistic. By default, wood has no turbulence. 



   Unlike most patterns, the {\small\texttt{wood}} pattern uses the {\small\texttt{ triangle\_\-wave}} wave type by default. This means that like marble, wood uses 
 color map values 0.0 to 1.0 then repeats the colors in reverse order from 1.0 to 0.0. However you may use any wave type. 



   The {\small\texttt{wood}} pattern has a default color\_\-map built in that results in a light and dark brown pattern with sharp transitions. 


\subsection{Wrinkles}

% reference/000287.html

\index{wrinkles}\index{wrinkles! keyword}\index{wrinkles! pattern}\index{Keyword! wrinkles}\index{Pattern! wrinkles}

   The {\small\texttt{wrinkles}} pattern was originally designed only to be used as a normal pattern. It uses a 1/f noise pattern similar to granite but the 
 features in wrinkles are sharper. The pattern can be used to simulate wrinkled cellophane or foil. It also makes an excellent stucco texture. 



   When used as a normal pattern, this pattern uses a specialized normal perturbation function. This means that the pattern cannot be used with {\small\texttt{ 
 normal\_\-map}}, {\small\texttt{slope\_\-map}} or wave type modifiers in a {\small\texttt{ normal}} statement. 



   When used as a pigment pattern or texture pattern, the {\small\texttt{wrinkles}} pattern is similar to normal wrinkles but is not identical as are most 
 normals when compared to pigments. 



   \textbf{Note:} The appearance of the wrinkles pattern depends on the noise\_\-generator used. The default type is 2. This may be changed using the {\small\texttt{noise\_\-generator}} 
 keyword (See section "Pattern Modifiers / Noise\_\-generator"). 


\section{Pattern Modifiers}

% reference/000203.html

\index{noise\_\-generator}\index{noise\_\-generator! pattern modifier}\index{Pattern modifiers! noise\_\-generator}\index{turbulence}\index{turbulence! pattern modifier}\index{Pattern modifiers! turbulence}\index{octaves}\index{octaves! pattern modifier}\index{Pattern modifiers! octaves}\index{omega}\index{omega! pattern modifier}\index{Pattern modifiers! omega}\index{lambda}\index{lambda! pattern modifier}\index{Pattern modifiers! lambda}\index{frequency}\index{frequency! pattern modifier}\index{Pattern modifiers! frequency}\index{phase}\index{phase! pattern modifier}\index{Pattern modifiers! phase}\index{ramp\_\-wave}\index{ramp\_\-wave! pattern modifier}\index{Pattern modifiers! ramp\_\-wave}\index{triangle\_\-wave}\index{triangle\_\-wave! pattern modifier}\index{Pattern modifiers! triangle\_\-wave}\index{sine\_\-wave}\index{sine\_\-wave! pattern modifier}\index{Pattern modifiers! sine\_\-wave}\index{scallop\_\-wave}\index{scallop\_\-wave! pattern modifier}\index{Pattern modifiers! scallop\_\-wave}\index{cubic\_\-wave}\index{cubic\_\-wave! pattern modifier}\index{Pattern modifiers! cubic\_\-wave}\index{poly\_\-wave}\index{poly\_\-wave! pattern modifier}\index{Pattern modifiers! poly\_\-wave}\index{agate\_\-turb}\index{agate\_\-turb! pattern modifier}\index{Pattern modifiers! agate\_\-turb}\index{brick\_\-size}\index{brick\_\-size! pattern modifier}\index{Pattern modifiers! brick\_\-size}\index{mortar}\index{mortar! pattern modifier}\index{Pattern modifiers! mortar}\index{interpolate}\index{interpolate! pattern modifier}\index{Pattern modifiers! interpolate}\index{control0}\index{control0! pattern modifier}\index{Pattern modifiers! control0}\index{control1}\index{control1! pattern modifier}\index{Pattern modifiers! control1}\index{warp}\index{warp! pattern modifier}\index{Pattern modifiers! warp}

   Pattern modifiers are statements or parameters which modify how a pattern is evaluated or tells what to do with the pattern. The complete syntax is: 


{\small\begin{verbatim}
PATTERN_MODIFIER:
    BLEND_MAP_MODIFIER | AGATE_MODIFIER | DENSITY_FILE_MODIFIER |
    QUILTED_MODIFIER | BRICK_MODIFIER | SLOPE_MODIFIER |
    noise_generator Number| turbulence <Amount> |
    octaves Count | omega Amount | lambda Amount |
    warp { [WARP_ITEMS...] } | TRANSFORMATION
BLEND_MAP_MODIFIER:
    frequency Amount | phase Amount | ramp_wave | triangle_wave |
    sine_wave | scallop_wave | cubic_wave | poly_wave [Exponent]
AGATE_MODIFIER:
    agate_turb Value
BRICK_MODIFIER:
    brick_size Size | mortar Size 
DENSITY_FILE_MODIFIER:
    interpolate Type
SLOPE_MODIFIERS:
	<Altitude> 
	<Lo_slope,Hi_slope>
    <Lo_alt,	Hi_alt>
QUILTED_MODIFIER:
    control0 Value | control1 Value
PIGMENT_MODIFIER:
    PATTERN_MODIFIER | COLOR_LIST | PIGMENT_LIST |
    color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
    pigment_map{ PIGMENT_MAP_BODY } | quick_color COLOR |
    quick_colour COLOR
COLOR NORMAL_MODIFIER:
    PATTERN_MODIFIER | NORMAL_LIST |
    normal_map { NORMAL_MAP_BODY } | slope_map{ SLOPE_MAP_BODY } |
    bump_size Amount
TEXTURE_PATTERN_MODIFIER:
    PATTERN_MODIFIER | TEXTURE_LIST |
    texture_map{ TEXTURE_MAP_BODY }
DENSITY_MODIFIER:
    PATTERN_MODIFIER | DENSITY_LIST | COLOR_LIST |
    color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
    density_map { DENSITY_MAP_BODY }
\end{verbatim}}


   Default values for pattern modifiers: \index{Default values! pattern modifiers} 


{\small\begin{verbatim}
dist_exp        : 0
falloff         : 2.0
frequency       : 1.0
lambda          : 2.0
major_radius    : 1
map_type        : 0
noise_generator : 2
octaves         : 6
omega           : 0.5  
orientation     : <0,0,1>
phase           : 0.0
poly_wave       : 1.0
strength        : 1.0
turbulence      : <0,0,0>
\end{verbatim}}


   The modifiers \textit{PIGMENT\_\-LIST}, {\small\texttt{quick\_\-color}}, and {\small\texttt{ pigment\_\-map}} apply only to pigments. See section "Pigment" 
 for details on these pigment-\discretionary{}{}{}specific pattern modifiers. 



   The modifiers \textit{ COLOR\_\-LIST} and {\small\texttt{color\_\-map}} apply only to pigments and densities. See sections "Pigment" and "Density" 
 for details on these pigment-\discretionary{}{}{}specific pattern modifiers. 



   The modifiers \textit{ NORMAL\_\-LIST}, {\small\texttt{bump\_\-size}}, {\small\texttt{ slope\_\-map}} and {\small\texttt{ normal\_\-map}} apply only to normals. See 
 section "Normal" for details on these normal-\discretionary{}{}{}specific pattern modifiers. 



   The \textit{TEXTURE\_\-LIST} and {\small\texttt{texture\_\-map}} modifiers can only be used with patterned textures. See section "Texture Maps" for 
 details. 



   The \textit{ DENSITY\_\-LIST} and {\small\texttt{ density\_\-map}} modifiers only work with {\small\texttt{media\{density\{..\}\}}} statements. See "Density" 
 for details. 



   The {\small\texttt{agate\_\-turb}} modifier can only be used with the {\small\texttt{ agate}} pattern. See "Agate" for details. 



   The {\small\texttt{ brick\_\-size}} and {\small\texttt{mortar}} modifiers can only be used with the {\small\texttt{ brick}} pattern. See "Brick" for 
 details. 



   The {\small\texttt{ control0}} and {\small\texttt{control1}} modifiers can only be used with the {\small\texttt{quilted}} pattern. See "Quilted" 
 for details. 



   The {\small\texttt{ interpolate}} modifier can only be used with the {\small\texttt{ density\_\-file}} pattern. See "Density\_\-File" for details. 



   The general purpose pattern modifiers in the following sections can be used with {\small\texttt{pigment}}, {\small\texttt{normal}}, {\small\texttt{texture}}, 
 or {\small\texttt{ density}} patterns. 


\subsection{Transforming Patterns}

% reference/000288.html



   The most common pattern modifiers are the transformation modifiers {\small\texttt{ translate}}, {\small\texttt{rotate}}, {\small\texttt{scale}}, {\small\texttt{ 
 transform}}, and {\small\texttt{matrix}}. For details on these commands see section "Transformations". 



   These modifiers may be placed inside pigment, normal, texture, and density statements to change the position, size and orientation of the patterns. 



   Transformations are performed in the order in which you specify them. However in general the order of transformations relative to other pattern modifiers 
 such as {\small\texttt{ turbulence}}, {\small\texttt{ color\_\-map}} and other maps is not important. For example scaling before or after turbulence makes no 
 difference. The turbulence is done first, then the scaling regardless of which is specified first. However the order in which transformations are performed 
 relative to {\small\texttt{warp}} statements is important. See "Warps" for details. 


\subsection{Frequency and Phase}

% reference/000296.html

\index{frequency! pattern modifier}\index{phase! pattern modifier}

   The {\small\texttt{frequency}} and {\small\texttt{phase}} modifiers act as a type of scale and translate modifiers for various blend maps. They only have 
 effect when blend maps are used. Blend maps are {\small\texttt{ color\_\-map}}, {\small\texttt{pigment\_\-map}}, {\small\texttt{normal\_\-map}}, {\small\texttt{ 
 slope\_\-map}}, {\small\texttt{density\_\-map}}, and {\small\texttt{texture\_\-map}}. This discussion uses a color map as an example but the same principles apply 
 to the other blend map types. 



   The {\small\texttt{frequency}} keyword adjusts the number of times that a color map repeats over one cycle of a pattern. For example {\small\texttt{ gradient}} 
 covers color map values 0 to 1 over the range from x=0 to x=1. By adding {\small\texttt{frequency 2.0}} the color map repeats twice over that same range. The 
 same effect can be achieved using {\small\texttt{scale 0.5*x}} so the frequency keyword is not that useful for patterns like gradient. 



   However the radial pattern wraps the color map around the +y-\discretionary{}{}{}axis once. If you wanted two copies of the map (or 3 or 10 or 100) you would have to build a 
 bigger map. Adding {\small\texttt{ frequency 2.0}} causes the color map to be used twice per revolution. Try this: 


{\small\begin{verbatim}
  pigment {
    radial
    color_map{[0.5 color Red][0.5 color White]}
    frequency 6
  }
\end{verbatim}}


   The result is six sets of red and white radial stripes evenly spaced around the object. 



   The float after {\small\texttt{frequency}} can be any value. Values greater than 1.0 causes more than one copy of the map to be used. Values from 0.0 to 1.0 
 cause a fraction of the map to be used. Negative values reverses the map. 



   The {\small\texttt{phase}} value causes the map entries to be shifted so that the map starts and ends at a different place. In the example above if you 
 render successive frames at {\small\texttt{phase 0}} then {\small\texttt{phase 0.1}}, {\small\texttt{phase 0.2}}, etc. you could create an animation that 
 rotates the stripes. The same effect can be easily achieved by rotating the {\small\texttt{ radial}} pigment using {\small\texttt{ rotate y*Angle}} but there 
 are other uses where phase can be handy. 



   Sometimes you create a great looking gradient or wood color map but you want the grain slightly adjusted in or out. You could re-\discretionary{}{}{}order the color map entries 
 but that is a pain. A phase adjustment will shift everything but keep the same scale. Try animating a {\small\texttt{mandel}} pigment for a color palette 
 rotation effect. 



   These values work by applying the following formula 



   \textit{ New\_\-Value = fmod ( Old\_\-Value * Frequency + Phase, 1.0 ). } 



   The {\small\texttt{frequency}} and {\small\texttt{phase}} modifiers have no effect on block patterns {\small\texttt{ checker}}, {\small\texttt{brick}}, and {\small\texttt{ 
 hexagon}} nor do they effect {\small\texttt{image\_\-map}}, {\small\texttt{ bump\_\-map}} or {\small\texttt{ material\_\-map}}. They also have no effect in normal 
 statements when used with {\small\texttt{bumps}}, {\small\texttt{dents}}, {\small\texttt{quilted}} or {\small\texttt{ wrinkles}} because these normal patterns 
 cannot use {\small\texttt{ normal\_\-map}} or {\small\texttt{slope\_\-map}}. 



   They can be used with normal patterns {\small\texttt{ripples}} and {\small\texttt{ waves}} even though these two patterns cannot use {\small\texttt{ 
 normal\_\-map}} or {\small\texttt{slope\_\-map}} either. When used with {\small\texttt{ ripples}} or {\small\texttt{waves}}, {\small\texttt{ frequency}} adjusts 
 the space between features and {\small\texttt{phase}} can be adjusted from 0.0 to 1.0 to cause the ripples or waves to move relative to their center for 
 animating the features. 


\subsection{Waveforms}

% reference/000295.html

\index{ramp\_\-wave! pattern modifier}

   POV-\discretionary{}{}{}Ray allows you to apply various wave forms to the pattern function before applying it to a blend map. Blend maps are {\small\texttt{color\_\-map}}, {\small\texttt{pigment\_\-map}}, 
 {\small\texttt{normal\_\-map}}, {\small\texttt{slope\_\-map}}, {\small\texttt{density\_\-map}}, and {\small\texttt{texture\_\-map}}. 



   Most of the patterns which use a blend map, use the entries in the map in order from 0.0 to 1.0. The effect can most easily be seen when these patterns are 
 used as normal patterns with no maps. Patterns such as {\small\texttt{ gradient}} or {\small\texttt{ onion}} generate a groove or slot that looks like a ramp 
 that drops off sharply. This is called a {\small\texttt{ramp\_\-wave}} wave type and it is the default wave type for most patterns. However the {\small\texttt{wood}} 
 and {\small\texttt{ marble}} patterns use the map from 0.0 to 1.0 and then reverses it and runs it from 1.0 to 0.0. The result is a wave form which slopes 
 upwards to a peak, then slopes down again in a {\small\texttt{ triangle\_\-wave}}. In earlier versions of POV-\discretionary{}{}{}Ray there was no way to change the wave types. You 
 could simulate a triangle wave on a ramp wave pattern by duplicating the map entries in reverse, however there was no way to use a ramp wave on wood or 
 marble. 



   Now any pattern that takes a map can have the default wave type overridden. For example: 


{\small\begin{verbatim}
  pigment { wood color_map { MyMap } ramp_wave }
\end{verbatim}}
\index{sine\_\-wave! pattern modifier}\index{scallop\_\-wave! pattern modifier}\index{cubic\_\-wave! pattern modifier}\index{poly\_\-wave! pattern modifier}

   Also available are {\small\texttt{sine\_\-wave}}, {\small\texttt{scallop\_\-wave}}, {\small\texttt{cubic\_\-wave}} and {\small\texttt{poly\_\-wave}} types. These types 
 are of most use in normal patterns as a type of built-\discretionary{}{}{}in slope map. The {\small\texttt{ sine\_\-wave}} takes the zig-\discretionary{}{}{}zag of a ramp wave and turns it into a 
 gentle rolling wave with smooth transitions. The {\small\texttt{scallop\_\-wave}} uses the absolute value of the sine wave which looks like corduroy when scaled 
 small or like a stack of cylinders when scaled larger. The {\small\texttt{ cubic\_\-wave}} is a gentle cubic curve from 0.0 to 1.0 with zero slope at the start 
 and end. The {\small\texttt{poly\_\-wave}} is an exponential function. It is followed by an optional float value which specifies exponent. For example {\small\texttt{poly\_\-wave 
 2}} starts low and climbs rapidly at the end while {\small\texttt{poly\_\-wave 0.5}} climbs rapidly at first and levels off at the end. If no float value is 
 specified, the default is 1.0 which produces a linear function identical to {\small\texttt{ramp\_\-wave}}. 



   Although any of these wave types can be used for pigments, normals, textures, or density the effect of many of the wave types are not as noticeable on 
 pigments, textures, or density as they are for normals. 



   Wave type modifiers have no effect on block patterns {\small\texttt{ checker}}, {\small\texttt{brick}}, {\small\texttt{object}} and {\small\texttt{hexagon}} 
 nor do they effect {\small\texttt{ image\_\-map}}, {\small\texttt{bump\_\-map}} or {\small\texttt{ material\_\-map}}. They also have no effect in normal statements 
 when used with {\small\texttt{bumps}}, {\small\texttt{dents}}, {\small\texttt{quilted}}, {\small\texttt{ ripples}}, {\small\texttt{ waves}}, or {\small\texttt{wrinkles}} 
 because these normal patterns cannot use {\small\texttt{normal\_\-map}} or {\small\texttt{ slope\_\-map}}. 


\subsection{Noise Generators}

% reference/000294.html

\index{noise generator! pattern modifier}

   There are three noise generators implemented. Changing the {\small\texttt{noise\_\-generator}} will change the appearance of noise based patterns, like bozo and 
 granite. 


\begin{itemize}
 
 \item 
   {\small\texttt{noise\_\-generator 1}} the noise that was used in POV\_\-Ray 3.1 
 

 \item 
   {\small\texttt{noise\_\-generator 2}} 'range corrected' version of the old noise, it does not show the plateaus seen with {\small\texttt{noise\_\-generator 1}} 
  
 

 \item 
   {\small\texttt{noise\_\-generator 3}} generates Perlin noise 
 

\end{itemize}


   The default is {\small\texttt{noise\_\-generator 2}} 



   \textbf{Note:} The noise\_\-generator can also be set in {\small\texttt{global\_\-settings}} 


\subsection{Turbulence}

% reference/000293.html



   The {\small\texttt{turbulence}} pattern modifier is still supported for compatibility issues, but it is better nowadays to use the {\small\texttt{warp 
 \{turbulence\}}} feature, which does not have turbulence's limitation in transformation order (turbulence is always applied first, before any scale, translate 
 or rotate, whatever the order you specify). For a detailed discussion see 'Turbulence versus Turbulence Warp' 



   The old-\discretionary{}{}{}style turbulence is handled slightly differently when used with the agate, marble, spiral1, spiral2, and wood textures. 


\subsection{Warps}

% reference/000292.html

\index{warp! keyword}\index{warp! pattern modifier}\index{Keyword! warp}\index{Pattern modifier! warp}\index{repeat! warp}\index{Keyword! repeat}\index{black\_\-hole! warp}\index{Keyword! black\_\-hole}\index{turbulence! warp}\index{Keyword! turbulence}\index{cylindrical! warp}\index{Keyword! cylindrical}\index{dist\_\-exp! warp}\index{Keyword! dist\_\-exp}\index{spherical! warp}\index{Keyword! spherical}\index{toroidal! warp}\index{Keyword! toroidal}\index{orientation! warp}\index{Keyword! orientation}\index{planar! warp}\index{Keyword! planar}\index{offset! warp}\index{Keyword! offset}\index{flip! warp}\index{Keyword! flip}\index{strength! warp}\index{Keyword! strength}\index{falloff! warp}\index{Keyword! falloff}\index{inverse! warp}\index{Keyword! inverse}\index{octaves! warp}\index{Keyword! octaves}\index{omega! warp}\index{Keyword! omega}\index{lambda! warp}\index{Keyword! lambda}

   The {\small\texttt{warp}} statement is a pattern modifier that is similar to turbulence. Turbulence works by taking the pattern evaluation point and pushing 
 it about in a series of random steps. However warps push the point in very well-\discretionary{}{}{}defined, non-\discretionary{}{}{}random, geometric ways. The {\small\texttt{warp}} statement also 
 overcomes some limitations of traditional turbulence and transformations by giving the user more control over the order in which turbulence, transformation 
 and warp modifiers are applied to the pattern. 



   Currently there are seven types of warps but the syntax was designed to allow future expansion. The turbulence warp provides an alternative way to specify 
 turbulence. The others modify the pattern in geometric ways. 



   The syntax for using a {\small\texttt{warp}} statement is: 


{\small\begin{verbatim}
WARP:
    warp { WARP_ITEM }
WARP_ITEM:
    repeat <Direction> [REPEAT_ITEMS...] |
    black_hole <Location>, Radius [BLACK_HOLE_ITEMS...] | 
    turbulence <Amount> [TURB_ITEMS...]
    cylindrical  [ orientation VECTOR | dist_exp FLOAT ]
    spherical  [ orientation VECTOR | dist_exp FLOAT ]
    toroidal  [ orientation VECTOR | dist_exp FLOAT |
                major_radius FLOAT ]
    planar [ VECTOR , FLOAT ]
REPEAT_ITEMS:
    offset <Amount> | 
    flip <Axis>
BLACK_HOLE_ITEMS:
    strength Strength | falloff Amount | inverse |
    repeat <Repeat> | turbulence <Amount>
TURB_ITEMS:
    octaves Count | omega Amount | lambda Amount
\end{verbatim}}


   You may have as many separate warp statements as you like in each pattern. The placement of warp statements relative to other modifiers such as {\small\texttt{ 
 color\_\-map}} or {\small\texttt{turbulence}} is not important. However placement of warp statements relative to each other and to transformations is 
 significant. Multiple warps and transformations are evaluated in the order in which you specify them. For example if you translate, then warp or warp, then 
 translate, the results can be different. 


\subsubsection{Black Hole Warp}

% reference/000291.html

\index{black\_\-hole}\index{black\_\-hole! warp}\index{strength! black\_\-hole warp}\index{falloff! warp}\index{warp! falloff}

   A {\small\texttt{black\_\-hole}} warp is so named because of its similarity to real black holes. Just like the real thing, you cannot actually see a black hole. 
 The only way to detect its presence is by the effect it has on things that surround it. 



   Take, for example, a wood grain. Using POV-\discretionary{}{}{}Ray's normal turbulence and other texture modifier functions, you can get a nice, random appearance to the grain. 
 But in its randomness it is regular - it is regularly random! Adding a black hole allows you to create a localized disturbance in a wood grain in either one 
 or multiple locations. The black hole can have the effect of either \textit{sucking} the surrounding texture into itself (like the real thing) or \textit{pushing} 
 it away. In the latter case, applied to a wood grain, it would look to the viewer as if there were a knothole in the wood. In this text we use a wood grain 
 regularly as an example, because it is ideally suitable to explaining black holes. However, black holes may in fact be used with any texture or pattern. The 
 effect that the black hole has on the texture can be specified. By default, it \textit{sucks} with the strength calculated exponentially (inverse-\discretionary{}{}{}square). You 
 can change this if you like. 



   Black holes may be used anywhere a warp is permitted. The syntax is: 


{\small\begin{verbatim}
BLACK_HOLE_WARP:
    warp
    {
        black_hole <Location>, Radius
        [BLACK_HOLE_ITEMS...]
    }
BLACK_HOLE_ITEMS:
    strength Strength | falloff Amount | inverse | type Type | 
    repeat <Repeat> | turbulence <Amount>
\end{verbatim}}


   The minimal requirement is the {\small\texttt{black\_\-hole}} keyword followed by a vector \textit{{\small\texttt{$<$Location$>$}}} followed by a comma and a 
 float \textit{{\small\texttt{Radius}}}. Black holes effect all points within the spherical region around the location and within the radius. This is 
 optionally followed by any number of other keywords which control how the texture is warped. 



   The {\small\texttt{falloff}} keyword may be used with a float value to specify the power by which the effect of the black hole falls off. The default is two. 
 The force of the black hole at any given point, before applying the {\small\texttt{strength}} modifier, is as follows. 



   First, convert the distance from the point to the center to a proportion (0 to 1) that the point is from the edge of the black hole. A point on the perimeter 
 of the black hole will be 0.0; a point at the center will be 1.0; a point exactly halfway will be 0.5, and so forth. Mentally you can consider this to be a 
 closeness factor. A closeness of 1.0 is as close as you can get to the center (\discretionary{i.}{}{i.}e. at the center), a closeness of 0.0 is as far away as you can get from the 
 center and still be inside the black hole and a closeness of 0.5 means the point is exactly halfway between the two. 



   Call this value c. Raise c to the power specified in {\small\texttt{falloff}}. By default Falloff is 2, so this is c\^{}2 or c squared. The resulting value is 
 the force of the black hole at that exact location and is used, after applying the {\small\texttt{strength}} scaling factor as described below, to determine 
 how much the point is perturbed in space. For example, if c is 0.5 the force is 0.5\^{}2 or 0.25. If c is 0.25 the force is 0.125. But if c is exactly 1.0 the 
 force is 1.0. Recall that as c gets smaller the point is farther from the center of the black hole. Using the default power of 2, you can see that as c 
 reduces, the force reduces exponentially in an inverse-\discretionary{}{}{}square relationship. Put in plain English, it means that the force is much stronger (by a power of two) 
 towards the center than it is at the outside. 



   By increasing {\small\texttt{falloff}}, you can increase the magnitude of the falloff. A large value will mean points towards the perimeter will hardly be 
 affected at all and points towards the center will be affected strongly. A value of 1.0 for {\small\texttt{falloff}} will mean that the effect is linear. A 
 point that is exactly halfway to the center of the black hole will be affected by a force of exactly 0.5. A value of {\small\texttt{falloff}} of less than one 
 but greater than zero means that as you get closer to the outside, the force increases rather than decreases. This can have some uses but there is a side 
 effect. Recall that the effect of a black hole ceases outside its perimeter. This means that points just within the perimeter will be affected strongly and 
 those just outside not at all. This would lead to a visible border, shaped as a sphere. A value for {\small\texttt{ falloff}} of 0 would mean that the force 
 would be 1.0 for all points within the black hole, since any number larger 0 raised to the power of 0 is 1.0. 



   The {\small\texttt{strength}} keyword may be specified with a float value to give you a bit more control over how much a point is perturbed by the black 
 hole. Basically, the force of the black hole (as determined above) is multiplied by the value of {\small\texttt{strength}}, which defaults to 1.0. If you set 
 strength to 0.5, for example, all points within the black hole will be moved by only half as much as they would have been. If you set it to 2.0 they will be 
 moved twice as much. 



   There is a rider to the latter example, though - the movement is clipped to a maximum of the original distance from the center. That is to say, a point that 
 is 0.75 units from the center may only be moved by a maximum of 0.75 units either towards the center or away from it, regardless of the value of {\small\texttt{ 
 strength}}. The result of this clipping is that you will have an exclusion area near the center of the black hole where all points whose final force value 
 exceeded or equaled 1.0 were moved by a fixed amount. 



   If the {\small\texttt{inverse}} keyword is specified then the points \textit{ pushed} away from the center instead of being pulled in. 



   The {\small\texttt{repeat}} keyword followed by a vector, allows you to simulate the effect of many black holes without having to explicitly declare them. 
 Repeat is a vector that tells POV-\discretionary{}{}{}Ray to use this black hole at multiple locations. Using {\small\texttt{repeat}} logically divides your scene up into cubes, 
 the first being located at $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ and going to \textit{{\small\texttt{ $<$Repeat$>$}}}. Suppose your repeat vector was $<$\discretionary{1,}{}{1,}\discretionary{5,}{}{5,}2$>$. The first cube 
 would be from $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$ \discretionary{1,}{}{1,}\discretionary{5,}{}{5,}2$>$. This cube repeats, so there would be one at $<$ -1,-5,-2$>$, $<$\discretionary{1,}{}{1,}\discretionary{5,}{}{5,}2$>$, $<$\discretionary{2,}{}{2,}\discretionary{10,}{}{10,}4$>$ and so forth in 
 all directions, ad infinitum. 



   When you use {\small\texttt{repeat}}, the center of the black hole does not specify an absolute location in your scene but an offset into each block. It is 
 only possible to use positive offsets. Negative values will produce undefined results. 



   Suppose your center was $<$0.\discretionary{5,}{}{5,}\discretionary{1,}{}{1,}0.25$>$ and the repeat vector is $<$\discretionary{2,}{}{2,}\discretionary{2,}{}{2,}2$>$. This gives us a block at $<$ \discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ and $<$\discretionary{2,}{}{2,}\discretionary{2,}{}{2,}2$>$, etc. The 
 centers of the black hole's for these blocks would be $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ + $<$ 0.\discretionary{5,}{}{5,}1.\discretionary{0,}{}{0,}0.25$>$, i. e. $<$0.\discretionary{5,}{}{5,}1.\discretionary{0,}{}{0,}0.25$>$, and $<$ \discretionary{2,}{}{2,}\discretionary{2,}{}{2,}2$>$ + 
 $<$0.\discretionary{5,}{}{5,}1.\discretionary{0,}{}{0,}0.25$>$, i. e. $<$ \discretionary{2,}{}{2,}\discretionary{5,}{}{5,}3.\discretionary{0,}{}{0,}2.25$>$. 



   Due to the way repeats are calculated internally, there is a restriction on the values you specify for the repeat vector. Basically, each black hole must be 
 totally enclosed within each block (or cube), with no part crossing into a neighboring one. This means that, for each of the x, y and z dimensions, the offset 
 of the center may not be less than the radius, and the repeat value for that dimension must be $>$=the center plus the radius since any other values would 
 allow the black hole to cross a boundary. Put another way, for each of x, y and z 



   Radius $<$= Offset or Center $<$= Repeat - Radius. 



   If the repeat vector in any dimension is too small to fit this criteria, it will be increased and a warning message issued. If the center is less than the 
 radius it will also be moved but no message will be issued. 



   Note that none of the above should be read to mean that you cannot overlap black holes. You most certainly can and in fact this can produce some most useful 
 effects. The restriction only applies to elements of the {\small\texttt{ same}} black hole which is repeating. You can declare a second black hole that also 
 repeats and its elements can quite happily overlap the first and causing the appropriate interactions. It is legal for the repeat value for any dimension to 
 be 0, meaning that POV-\discretionary{}{}{}Ray will not repeat the black hole in that direction. 



   The {\small\texttt{turbulence}} can only be used in a black hole with {\small\texttt{ repeat}}. It allows an element of randomness to be inserted into the 
 way the black holes repeat, to cause a more natural look. A good example would be an array of knotholes in wood - it would look rather artificial if each 
 knothole were an exact distance from the previous. 



   The {\small\texttt{ turbulence}} vector is a measurement that is added to each individual black hole in an array, after each axis of the vector is multiplied 
 by a different random amount ranging from 0 to 1. The resulting actual position of the black hole's center for that particular repeat element is random (but 
 consistent, so renders will be repeatable) and somewhere within the above coordinates. There is a rider on the use of turbulence, which basically is the same 
 as that of the repeat vector. You cannot specify a value which would cause a black hole to potentially cross outside of its particular block. 



   In summary: For each of x, y and z the offset of the center must be $>$=radius and the value of the repeat must be $>$= center + radius + turbulence. The 
 exception being that repeat may be 0 for any dimension, which means do not repeat in that direction. 



   Some examples are given by 


{\small\begin{verbatim}
  warp {
    black_hole <0, 0, 0>, 0.5
  }
  warp {
    black_hole <0.15, 0.125, 0>, 0.5
    falloff 7
    strength 1.0
    repeat <1.25, 1.25, 0>
    turbulence <0.25, 0.25, 0>
    inverse
  }
  warp {
    black_hole <0, 0, 0>, 1.0
    falloff 2
    strength 2
    inverse
  }
\end{verbatim}}

\subsubsection{Repeat Warp}

% reference/000300.html

\index{repeat}

   The {\small\texttt{repeat}} warp causes a section of the pattern to be repeated over and over. It takes a slice out of the pattern and makes multiple copies 
 of it side-\discretionary{}{}{}by-\discretionary{}{}{}side. The warp has many uses but was originally designed to make it easy to model wood veneer textures. Veneer is made by taking very thin 
 slices from a log and placing them side-\discretionary{}{}{}by-\discretionary{}{}{}side on some other backing material. You see side-\discretionary{}{}{}by-\discretionary{}{}{}side nearly identical ring patterns but each will be a slice 
 perhaps 1/32th of an inch deeper. 



   The syntax for a repeat warp is 


{\small\begin{verbatim}
REPEAT_WARP:
    warp { repeat <Direction> [REPEAT_ITEMS...] }
REPEAT_ITEMS:
    offset <Amount> | flip <Axis>
\end{verbatim}}


   The {\small\texttt{repeat}} vector specifies the direction in which the pattern repeats and the width of the repeated area. This vector must lie entirely 
 along an axis. In other words, two of its three components must be 0. For example 


{\small\begin{verbatim}
  pigment {
    wood
    warp { repeat 2*x }
  }
\end{verbatim}}
\index{offset}\index{offset! repeat warp}

   which means that from x=0 to x=2 you get whatever the pattern usually is. But from x=2 to x=4 you get the same thing exactly shifted two units over in the 
 x-\discretionary{}{}{}direction. To evaluate it you simply take the x-\discretionary{}{}{}coordinate modulo 2. Unfortunately you get exact duplicates which is not very realistic. 
 The optional {\small\texttt{offset}} vector tells how much to translate the pattern each time it repeats. For example 


{\small\begin{verbatim}
  pigment {
    wood
    warp {repeat x*2  offset z*0.05}
  }
\end{verbatim}}


   means that we slice the first copy from x=0 to x=2 at z=0 but at x=2 to x=4 we offset to z=0.05. In the 4 to 6 interval we slice at z=0.10. At the n-\discretionary{}{}{}th copy 
 we slice at 0.05 n z. Thus each copy is slightly different. There are no restrictions on the offset vector. 



   \index{flip} Finally the {\small\texttt{flip}} vector causes the pattern to be flipped or mirrored every other copy of the pattern. The first copy of the 
 pattern in the positive direction from the axis is not flipped. The next farther is, the next is not, etc. The flip vector is a three component x, y, z vector 
 but each component is treated as a boolean value that tells if you should or should not flip along a given axis. For example 


{\small\begin{verbatim}
  pigment {
    wood
    warp {repeat 2*x  flip <1,1,0>}
  }
\end{verbatim}}


   means that every other copy of the pattern will be mirrored about the x- and y- axis but not the z-\discretionary{}{}{}axis. A non-\discretionary{}{}{}zero value means flip and zero means do not 
 flip about that axis. The magnitude of the values in the flip vector does not matter. 


\subsubsection{Turbulence versus Turbulence Warp}

% reference/000299.html

\index{turbulence! warp}

   The POV-\discretionary{}{}{}Ray language contains an ambiguity and limitation on the way you specify {\small\texttt{turbulence}} and transformations such as {\small\texttt{ 
 translate}}, {\small\texttt{rotate}}, {\small\texttt{scale}}, {\small\texttt{ matrix}}, and {\small\texttt{transform}} transforms. Usually the turbulence is 
 done first. Then all translate, rotate, scale, matrix, and transform operations are always done after turbulence regardless of the order in which you specify 
 them. For example this 


{\small\begin{verbatim}
 pigment {
   wood
   scale .5
   turbulence .2
 }
\end{verbatim}}


   works exactly the same as 


{\small\begin{verbatim}
 pigment {
   wood
   turbulence .2
   scale .5
 }
\end{verbatim}}


   The turbulence is always first. A better example of this limitation is with uneven turbulence and rotations. 


{\small\begin{verbatim}
  pigment {
    wood
    turbulence 0.5*y
    rotate z*60
  }
  // as compared to
  pigment {
   wood
   rotate z*60
   turbulence 0.5*y
  }
\end{verbatim}}


   The results will be the same either way even though you would think it should look different. 



   We cannot change this basic behavior in POV-\discretionary{}{}{}Ray now because lots of scenes would potentially render differently if suddenly the order transformation vs. 
 turbulence mattered when in the past, it did not. 



   However, by specifying our turbulence inside warp statement you tell POV-\discretionary{}{}{}Ray that the order in which turbulence, transformations and other warps are applied 
 is significant. Here is an example of a turbulence warp. 


{\small\begin{verbatim}
  warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
\end{verbatim}}


   The significance is that this 


{\small\begin{verbatim}
 pigment {
   wood
   translate <1,2,3> rotate x*45 scale 2
   warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
 }
\end{verbatim}}


   produces \textit{different results} than this... 


{\small\begin{verbatim}
 pigment {
   wood
   warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
   translate <1,2,3> rotate x*45 scale 2
 }
\end{verbatim}}


   You may specify turbulence without using a warp statement. However you cannot control the order in which they are evaluated unless you put them in a warp. 



   The evaluation rules are as follows: 


\begin{enumerate}
 
 \item 
   First any turbulence not inside a warp statement is applied regardless of the order in which it appears relative to warps or transformations. 
 

 \item 
   Next each warp statement, translate, rotate, scale or matrix one-\discretionary{}{}{}by-\discretionary{}{}{}one, is applied in the order the user specifies. If you want turbulence done in a 
  specific order, you simply specify it inside a warp in the proper place. 
 

\end{enumerate}

\subsubsection{Turbulence Warp}

% reference/000298.html



   Inside the {\small\texttt{warp}} statement, the keyword {\small\texttt{turbulence}} followed by a float or vector may be used to stir up any {\small\texttt{pigment}}, 
 {\small\texttt{normal}} or {\small\texttt{density}}. A number of optional parameters may be used with turbulence to control how it is computed. The syntax is: 


{\small\begin{verbatim}
TURBULENCE_ITEM:
    turbulence <Amount> | octaves Count |
    omega Amount | lambda Amount
\end{verbatim}}


   Typical turbulence values range from the default 0.0, which is no turbulence, to 1.0 or more, which is very turbulent. If a vector is specified different 
 amounts of turbulence are applied in the x-, y- and z-\discretionary{}{}{}direction. For example 


{\small\begin{verbatim}
  turbulence <1.0, 0.6, 0.1>
\end{verbatim}}


   has much turbulence in the x-\discretionary{}{}{}direction, a moderate amount in the y-\discretionary{}{}{}direction and a small amount in the z-\discretionary{}{}{}direction. 



   Turbulence uses a random noise function called \textit{DNoise}. This is similar to the noise used in the {\small\texttt{bozo}} pattern except that instead of 
 giving a single value it gives a direction. You can think of it as the direction that the wind is blowing at that spot. Points close together generate almost 
 the same value but points far apart are randomly different. 



   Turbulence uses \textit{DNoise} to push a point around in several steps called {\small\texttt{octaves}}. We locate the point we want to evaluate, then push 
 it around a bit using turbulence to get to a different point then look up the color or pattern of the new point. 



   It says in effect \textit{ "Do not give me the color at this spot... take a few random steps in different directions and give me that color"}. Each 
 step is typically half as long as the one before. For example: 



   \begin{figure} \centering \includegraphics[scale=0.60]{../final/tex/images/reference/turbrand} \caption{Turbulence random walk.} \end{figure} 



   The magnitude of these steps is controlled by the turbulence value. There are three additional parameters which control how turbulence is computed. They are {\small\texttt{octaves}}, 
 {\small\texttt{lambda}} and {\small\texttt{ omega}}. Each is optional. Each is followed by a single float value. Each has no effect when there is no 
 turbulence. \subsubsection{Octaves}
% reference/000480.html

\index{octaves! pattern modifier} 



   The {\small\texttt{octaves}} keyword may be followed by an integer value to control the number of steps of turbulence that are computed. Legal values range 
 from 1 to $<$10. The default value of 6 is a fairly high value; you will not see much change by setting it to a higher value because the extra steps are too 
 small. Float values are truncated to integer. Smaller numbers of octaves give a gentler, wavy turbulence and computes faster. Higher octaves create more 
 jagged or fuzzy turbulence and takes longer to compute.\subsubsection{Lambda}
% reference/000481.html

\index{lambda! pattern modifier} 



   The {\small\texttt{lambda}} parameter controls how statistically different the random move of an octave is compared to its previous octave. The default value 
 is 2.0 which is quite random. Values close to lambda 1.0 will straighten out the randomness of the path in the diagram above. The zig-\discretionary{}{}{}zag steps in the 
 calculation are in nearly the same direction. Higher values can look more \textit{swirly} under some circumstances.\subsubsection{Omega}
% reference/000482.html

\index{omega! pattern modifier} 
 



   The {\small\texttt{omega}} value controls how large each successive octave step is compared to the previous value. Each successive octave of turbulence is 
 multiplied by the omega value. The default {\small\texttt{omega 0.5}} means that each octave is 1/2 the size of the previous one. Higher omega values mean 
 that 2nd, 3rd, 4th and up octaves contribute more turbulence giving a sharper, \textit{crinkly} look while smaller omegas give a fuzzy kind of turbulence that 
 gets blurry in places. 


\subsubsection{Mapping using warps}

% reference/000297.html

\index{toroidal}\index{orientation}\index{dist\_\-exp}\index{major\_\-radius}\index{cylindrical! warp}\index{warp! cylindrical}\index{spherical! warp}\index{warp! spherical}\index{planar! warp}\index{warp! planar}\index{toroidal! warp}\index{warp! toroidal}

   Syntax: 


{\small\begin{verbatim}
  CYLINDRICAL_WARP:
    warp { cylindrical [CYLINDRICAL_ITEMS...]}
  CYLINDRICAL_ITEMS:  
    orientation VECTOR | dist_exp FLOAT
  SPHERICAL_WARP:
    warp { spherical [SPHERICAL_ITEMS...]}
  SPHERICAL_ITEMS:  
    orientation VECTOR | dist_exp FLOAT
  TOROIDAL_WARP:
    warp { toroidal [TOROIDAL_ITEMS...]}
  TOROIDAL_ITEMS:  
    orientation VECTOR | dist_exp FLOAT | major_radius FLOAT
  PLANAR_WARP:
    warp { planar [ VECTOR , FLOAT ]}
  \end{verbatim}}


   With the {\small\texttt{cylindrical, spherical}} and {\small\texttt{toroidal}} warps you can wrap checkers, bricks and other patterns around cylinders, 
 spheres, toruses and other objects. In essence, these warps use the same mapping as the image maps use. 



   However it does 3D mapping and some concession had to be made on depth. This is controllable by {\small\texttt{dist\_\-exp}} (distance exponent). In the default 
 of 0, imagine a box $<$\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}1$>$ (actually it is $<$\discretionary{0,}{}{0,}0$>$, $<${\small\texttt{dist\^{}dist\_\discretionary{exp,}{}{exp,}dist\^{}dist\_\-exp}}$>$) stretching to infinity along 
 the orientation vector. The warp takes its points from that box. 



   For a sphere {\small\texttt{distance}} is distance from origin, cylinder is distance from y-\discretionary{}{}{}axis, torus is distance from major radius. (or distance is minor 
 radius if you prefer to look at it that way) 



   Defaults: {\small\texttt{ orientation $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}1$>$\newline  dist\_\-exp 0\newline  major\_\-radius 1\newline  }} 



   Examples: 


{\small\begin{verbatim}
   torus {
     1, 0.5
     pigment {
       hexagon
       scale 0.1
       warp {
         toroidal 
         orientation y 
         dist_exp 1 
         major_radius 1
       }
     }
   }
   sphere {
     0,1
     pigment {
       hexagon
       scale <0.5/pi,0.25/pi,1>*0.1
       warp {
         spherical
         orientation y 
         dist_exp 1 
       }
     }
   }
   cylinder {
     -y, y, 1
     pigment {
       hexagon
       scale <0.5/pi, 1, 1>*0.1
       warp {
         cylindrical 
         orientation y 
         dist_exp 1 
       }
     }
   }
\end{verbatim}}


   The {\small\texttt{planar}} warp was made to make a pattern act like an image\_\-map, of infinite size and can be useful in combination with other 
 mapping-\discretionary{}{}{}warps. By default the pigment in the XY-\discretionary{}{}{}plane is extruded along the Z-\discretionary{}{}{}axis. The pigment can be taken from an other plane, by 
 specifying the optional vector (normal of the plane) and float (distance along the normal). The result, again, is extruded along the Z-\discretionary{}{}{}axis. 


\subsection{Bitmap Modifiers}

% reference/000290.html



   A bitmap modifier is a modifier used inside an {\small\texttt{image\_\-map}}, {\small\texttt{bump\_\-map}} or {\small\texttt{material\_\-map}} to specify how the 2-D 
 bitmap is to be applied to the 3-D surface. Several bitmap modifiers apply to specific kinds of maps and they are covered in the appropriate sections. The 
 bitmap modifiers discussed in the following sections are applicable to all three types of bitmaps. 


\subsubsection{The once Option}

% reference/000289.html

\index{once}

   Normally there are an infinite number of repeating image maps, bump maps or material maps created over every unit square of the x-\discretionary{}{}{}y-\discretionary{}{}{}plane like tiles. By 
 adding the {\small\texttt{once}} keyword after a file name you can eliminate all other copies of the map except the one at (\discretionary{0,}{}{0,}0) to (\discretionary{1,}{}{1,}1). In image maps, 
 areas outside this unit square are treated as fully transparent. In bump maps, areas outside this unit square are left flat with no normal modification. In 
 material maps, areas outside this unit square are textured with the first texture of the texture list. 



   For example: 


{\small\begin{verbatim}
  image_map {
    gif "mypic.gif"
    once
  }
\end{verbatim}}

\subsubsection{The map\_\-type Option}

% reference/000302.html

\index{map\_\-type}

   The default projection of the image onto the x-\discretionary{}{}{}y-\discretionary{}{}{}plane is called a \textit{ planar map type}. This option may be changed by adding the {\small\texttt{ 
 map\_\-type}} keyword followed by an integer number specifying the way to wrap the image around the object. 



   A {\small\texttt{map\_\-type 0}} gives the default planar mapping already described. 



   A {\small\texttt{map\_\-type 1}} gives a spherical mapping. It assumes that the object is a sphere of any size sitting at the origin. The y-\discretionary{}{}{}axis is the 
 north/south pole of the spherical mapping. The top and bottom edges of the image just touch the pole regardless of any scaling. The left edge of the image 
 begins at the positive x-\discretionary{}{}{}axis and wraps the image around the sphere from west to east in a -y-\discretionary{}{}{}rotation. The image covers the sphere exactly once. The {\small\texttt{ 
 once}} keyword has no meaning for this mapping type. 



   With {\small\texttt{ map\_\-type 2}} you get a cylindrical mapping. It assumes that a cylinder of any diameter lies along the y-\discretionary{}{}{}axis. The image wraps around the 
 cylinder just like the spherical map but the image remains one unit tall from y=0 to y=1. This band of color is repeated at all heights unless the {\small\texttt{ 
 once}} keyword is applied. 



   Finally {\small\texttt{map\_\-type 5}} is a torus or donut shaped mapping. It assumes that a torus of major radius one sits at the origin in the x-\discretionary{}{}{}z-\discretionary{}{}{}plane. The 
 image is wrapped around similar to spherical or cylindrical maps. However the top and bottom edges of the map wrap over and under the torus where they meet 
 each other on the inner rim. 



   Types 3 and 4 are still under development. 



   \textbf{Note:} that the {\small\texttt{ map\_\-type}} option may also be applied to {\small\texttt{ bump\_\-map}} and {\small\texttt{material\_\-map}} statements. 



   For example: 


{\small\begin{verbatim}
  sphere{<0,0,0>,1
    pigment{
      image_map {
        gif "world.gif"
        map_type 1
      }
    }
  }
\end{verbatim}}

\subsubsection{The interpolate Option}

% reference/000301.html

\index{interpolate! pattern modifier}

   Adding the {\small\texttt{interpolate}} keyword can smooth the jagged look of a bitmap. When POV-\discretionary{}{}{}Ray checks a color for an image map or a bump amount for a 
 bump map, it often checks a point that is not directly on top of one pixel but sort of between several differently colored pixels. Interpolations return an 
 in-\discretionary{}{}{}between value so that the steps between the pixels in the map will look smoother. 



   Although {\small\texttt{interpolate}} is legal in material maps, the color index is interpolated before the texture is chosen. It does not interpolate the 
 final color as you might hope it would. In general, interpolation of material maps serves no useful purpose but this may be fixed in future versions. 



   There are currently two types of interpolation: {\small\texttt{ interpolate 2}} gives bilinear interpolation while {\small\texttt{interpolate 4}} gives 
 normalized distance. For example: 


{\small\begin{verbatim}
  image_map {
    gif "mypic.gif"
    interpolate 2
  }
\end{verbatim}}


   Default is no interpolation. Normalized distance is the slightly faster of the two, bilinear does a better job of picking the between color. Normally 
 bilinear is used. 



   If your map looks jaggy, try using interpolation instead of going to a higher resolution image. The results can be very good. 


\clearpage \chapter{Interior \& Media \& Photons}

% reference/000181.html


\section{Interior}

% reference/000303.html

\index{interior}\index{interior! keyword}\index{Keyword! interior}\index{ior! interior}\index{Keyword! ior}\index{caustics! interior}\index{Keyword! caustics}\index{dispersion! interior}\index{Keyword! dispersion}\index{dispersion\_\-samples! interior}\index{Keyword! dispersion\_\-samples}\index{fade\_\-distance! interior}\index{Keyword! fade\_\-distance}\index{fade\_\-power! interior}\index{Keyword! fade\_\-power}\index{fade\_\-color! interior}\index{Keyword! fade\_\-color}

   Introduced in POV-\discretionary{}{}{}Ray 3.1 is an object modifier statement called {\small\texttt{ interior}}. The syntax is: 


{\small\begin{verbatim}
INTERIOR:
    interior { [INTERIOR_IDENTIFIER] [INTERIOR_ITEMS...] }
INTERIOR_ITEM:
    ior Value | caustics Value | dispersion Value | 
    dispersion_samples Samples | fade_distance Distance | 
    fade_power Power | fade_color <Color>
    MEDIA...
\end{verbatim}}


   Interior default values: \index{Default values! interior} 


{\small\begin{verbatim}
ior                : 1.0
caustics           : 0.0
dispersion         : 1.0
dispersion_samples : 7
fade_distance      : 0.0 
fade_power         : 0.0
fade_color         : <0,0,0>
\end{verbatim}}
\index{open}

   The {\small\texttt{interior}} contains items which describe the properties of the interior of the object. This is in contrast to the {\small\texttt{ texture}} 
 and {\small\texttt{interior\_\-texture}} which describe the surface properties only. The interior of an object is only of interest if it has a transparent 
 texture which allows you to see inside the object. It also applies only to solid objects which have a well-\discretionary{}{}{}defined inside/outside distinction. 



   \textbf{Note:} the {\small\texttt{open}} keyword, or {\small\texttt{clipped\_\-by}} modifier also allows you to see inside but interior features may not render 
 properly. They should be avoided if accurate interiors are required. 



   Interior identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. 
 An identifier is declared as follows. 


{\small\begin{verbatim}
INTERIOR_DECLARATION:
    #declare IDENTIFIER = INTERIOR |
    #local IDENTIFIER = INTERIOR
\end{verbatim}}


   Where \textit{IDENTIFIER} is the name of the identifier up to 40 characters long and \textit{INTERIOR} is any valid {\small\texttt{interior}} statement. See 
 "\#declare vs. \#local" for information on identifier scope. 


\subsection{Why are Interior and Media Necessary?}

% reference/000306.html



   In previous versions of POV-\discretionary{}{}{}Ray, most of the items in the {\small\texttt{interior}} statement were previously part of the {\small\texttt{finish}} statement. 
 Also the {\small\texttt{halo}} statement which was once part of the {\small\texttt{texture}} statement has been discontinued and has been replaced by the {\small\texttt{media}} 
 statement which is part of {\small\texttt{interior}}. 



   You are probably asking \textbf{WHY?} As explained earlier, the {\small\texttt{interior}} contains items which describe the properties of the interior of the 
 object. This is in contrast to the {\small\texttt{texture}} which describes the surface properties only. However this is not just a philosophical change. 
 There were serious inconsistencies in the old model. 



   The main problem arises when a {\small\texttt{texture\_\-map}} or other patterned texture is used. These features allow you to create textures that are a blend 
 of two textures and which vary the entire texture from one point to another. It does its blending by fully evaluating the apparent color as though only one 
 texture was applied and then fully reevaluating it with the other texture. The two final results are blended. 



   It is totally illogical to have a ray enter an object with one index or refraction and then recalculate with another index. The result is not an average of 
 the two ior values. Similarly it makes no sense to have a ray enter at one ior and exit at a different ior without transitioning between them along the way. 
 POV-\discretionary{}{}{}Ray only calculates refraction as the ray enters or leaves. It cannot incrementally compute a changing ior through the interior of an 
 object. Real world objects such as optical fibers or no-\discretionary{}{}{}line bifocal eyeglasses can have variable iors but POV-\discretionary{}{}{}Ray cannot simulate them. 



   Similarly the {\small\texttt{halo}} calculations were not performed as the syntax implied. Using a {\small\texttt{halo}} in such multi-\discretionary{}{}{}textured objects did 
 not vary the {\small\texttt{halo}} through the interior of the object. Rather, it computed two separate halos through the whole object and averaged the 
 results. The new design for {\small\texttt{media}} which replaces {\small\texttt{ halo}} makes it possible to have media that varies throughout the interior 
 of the object according to a pattern but it does so independently of the surface texture. Because there are other changes in the design of this feature which 
 make it significantly different, it was not only moved to the {\small\texttt{interior}} but the name was changed. 



   During our development, someone asked if we will create patterned interiors or a hypothetical {\small\texttt{interior\_\-map}} feature. We will not. That would 
 defeat the whole purpose of moving these features in the first place. They cannot be patterned and have logical or self-\discretionary{}{}{}consistent results. 


\subsection{Empty and Solid Objects}

% reference/000313.html

\index{Objects! empty and solid}

   It is very important that you know the basic concept behind empty and solid objects in POV-\discretionary{}{}{}Ray to fully understand how features like interior and 
 translucency are used. Objects in POV-\discretionary{}{}{}Ray can either be solid, empty or filled with (small) particles. 



   A solid object is made from the material specified by its pigment and finish statements (and to some degree its normal statement). By default all objects are 
 assumed to be solid. If you assign a stone texture to a sphere you will get a ball made completely of stone. It is like you had cut this ball from a block of 
 stone. A glass ball is a massive sphere made of glass. You should be aware that solid objects are conceptual things. If you clip away parts of the sphere you 
 will clearly see that the interior is empty and it just has a very thin surface. 



   This is not contrary to the concept of a solid object used in POV-\discretionary{}{}{}Ray. It is assumed that all space inside the sphere is covered by the sphere's {\small\texttt{ 
 interior}}. Light passing through the object is affected by attenuation and refraction properties. However there is no room for any other particles like those 
 used by fog or interior media. 



   Empty objects are created by adding the {\small\texttt{hollow}} keyword (see "Hollow") to the object statement. An empty (or hollow) object is 
 assumed to be made of a very thin surface which is of the material specified by the pigment, finish and normal statements. The object's interior is empty, it 
 normally contains air molecules. 



   An empty object can be filled with particles by adding fog or atmospheric media to the scene or by adding an interior media to the object. It is very 
 important to understand that in order to fill an object with any kind of particles it first has to be made hollow. 



   There is a pitfall in the empty/solid object implementation that you have to be aware of. 



   In order to be able to put solid objects inside a media or fog, a test has to be made for every ray that passes through the media. If this ray travels 
 through a solid object the media will not be calculated. This is what anyone will expect. A solid glass sphere in a fog bank does not contain fog. 



   The problem arises when the camera ray is inside any non-\discretionary{}{}{}hollow object. In this case the ray is already traveling through a solid object and even if the 
 media's container object is hit and it is hollow, the media will not be calculated. There is no way of telling between these two cases. 



   POV-\discretionary{}{}{}Ray has to determine whether the camera is inside any object prior to tracing a camera ray in order to be able to correctly render medias when the camera 
 is inside the container object. There is no way around doing this. 



   The solution to this problem (that will often happen with infinite objects like planes) is to make those objects hollow too. Thus the ray will travel through 
 a hollow object, will hit the container object and the media will be calculated. 


\subsection{Scaling objects with an interior}

% reference/000312.html



   All the statements that can be put in an interior represent aspects of the matter that an object is made of. Scaling an object, changing its size, does not 
 change its matter. Two pieces of the same quality steel, one twice as big as the other, both have the same density. The bigger piece is quite a bit heavier 
 though. 



   So, in POV-\discretionary{}{}{}Ray, if you design a lens from a glass with an ior of 1.5 and you scale it bigger, the focal distance of the lens will get longer as the ior stays 
 the same. For light attenuation it means that an object will be "darker" after being scaled up. The light intensity decreases a certain amount per 
 pov-\discretionary{}{}{}unit. The object has become bigger, more pov-\discretionary{}{}{}units, so more light is faded. The {\small\texttt{fade\_\-distance, fade\_\-power}} themselves 
 have not been changed. 



   The same applies to media. Imagine media as a density of particles, you specify 100 particles per cubic pov-\discretionary{}{}{}unit. If we scale a 1 cubic pov-\discretionary{}{}{}unit object to be 
 twice as big in every direction, we will have a total of 800 particles in the object. The object will look different, as we have more particles to look 
 through. Yet the objects density is still 100 particles per cubic pov-\discretionary{}{}{}unit. In media this "particle density" is set by the color after {\small\texttt{emission}}, 
 {\small\texttt{absorption}}, or in the {\small\texttt{scattering}} statement 


{\small\begin{verbatim}
#version 3.5;
global_settings {assumed_gamma 1.0}
camera {location <0, 0,-12.0> look_at 0 angle 30 }
#declare Container_T= texture {
   pigment {rgbt <1,1,1,1>}
   finish {ambient 0 diffuse 0}
}

#declare Scale=2;

box {                  //The reference
   <-1,-1,0>,<1,1,.3>
   hollow
   texture {Container_T}
   interior {
      media {
         intervals 1         
         samples 1,1          
         emission 1
      }
   }
   translate <-2.1,0,0>
}

box {                  //Object scaled twice as big
   <-1,-1,0>,<1,1,.3>  //looks different but same
   hollow                          //particle density
   texture {Container_T}
   interior {
      media {
         intervals 1         
         samples 1,1          
         emission 1
      }
   }
   scale Scale
   translate<0,0,12>
}

box {                  //Object scaled twice as big       
   <-1,-1,0>,<1,1,.3>  //looks the same but particle
   hollow                          //density scaled down
   texture {Container_T}
   interior {
      media {
         intervals 1         
         samples 1,1          
         emission 1/Scale
      }
   }
   scale Scale
   translate<0,0,12>
   translate<4.2,0,0>
}
\end{verbatim}}


   The third object in the scene above, shows what to do, if you want to scale the object \textit{and} want it to keep the same look as before. The interior 
 feature has to be divided by the same amount, that the object was scaled by. This is only possible when the object is scaled uniform. 



   In general, the correct approach is to scale the media density proportionally to the change in container volume. For non-\discretionary{}{}{}uniform scaling to get an 
 unambiguous result, that can be explained in physical terms, we need to do: 


{\small\begin{verbatim}
Density*sqrt(3)/vlength(Scale)
\end{verbatim}}


   where Density is your original media density and Scale is the scaling vector applied to the container. 



   \textbf{Note:} the density modifiers inside the {\small\texttt{density\{\}}} statement are scaled along with the object. 


\subsection{Refraction}

% reference/000311.html

\index{ior}

   When light passes through a surface either into or out of a dense medium the path of the ray of light is bent. Such bending is called \textit{ refraction}. 
 The amount of bending or refracting of light depends upon the density of the material. Air, water, crystal and diamonds all have different densities and thus 
 refract differently. The \textit{index of refraction} or \textit{ior} value is used by scientists to describe the relative density of substances. The {\small\texttt{ior}} 
 keyword is used in POV-\discretionary{}{}{}Ray in the {\small\texttt{interior}} to turn on refraction and to specify the ior value. For example: 


{\small\begin{verbatim}
  object { MyObject pigment {Clear } interior { ior 1.5 } }
\end{verbatim}}


   The default ior value of 1.0 will give no refraction. The index of refraction for air is 1.0, water is 1.33, glass is 1.5 and diamond is 2.4. 



   Normally transparent or semi-\discretionary{}{}{}transparent surfaces in POV-\discretionary{}{}{}Ray do not refract light. Earlier versions of POV-\discretionary{}{}{}Ray required you to use the {\small\texttt{ 
 refraction}} keyword in the {\small\texttt{finish}} statement to turn on refraction. This is no longer necessary. Any non-\discretionary{}{}{}zero {\small\texttt{ior}} value now 
 turns refraction on. 



   In addition to turning refraction on or off, the old {\small\texttt{refraction}} keyword was followed by a float value from 0.0 to 1.0. Values in between 0.0 
 and 1.0 would darken the refracted light in ways that do not correspond to any physical property. Many POV-\discretionary{}{}{}Ray scenes were created with intermediate 
 refraction values before this bug was discovered so the feature has been maintained. A more appropriate way to reduce the brightness of refracted light is to 
 change the {\small\texttt{filter}} or {\small\texttt{transmit}} value in the colors specified in the pigment statement or to use the {\small\texttt{fade\_\-power}} 
 and {\small\texttt{fade\_\-distance}} keywords. See "Attenuation". 



   \textbf{Note:} neither the {\small\texttt{ior}} nor {\small\texttt{refraction}} keywords cause the object to be transparent. Transparency only occurs if 
 there is a non-\discretionary{}{}{}zero {\small\texttt{filter}} or {\small\texttt{ transmit}} value in the color. 



   The {\small\texttt{refraction}} and {\small\texttt{ior}} keywords were originally specified in {\small\texttt{finish}} but are now properly specified in {\small\texttt{ 
 interior}}. They are accepted in {\small\texttt{finish}} for backward compatibility and generate a warning message. 


\subsection{Dispersion}

% reference/000310.html

\index{dispersion\_\-samples}

   For all materials with a ior different from 1.0 the refractive index is not constant throughout the spectrum. It changes as a function of wavelength. 
 Generally the refractive index decreases as the wavelength increases. Therefore light passing through a material will be separated according to wavelength. 
 This is known as chromatic dispersion. 



   By default POV-\discretionary{}{}{}Ray does not calculate dispersion as light travels through a transparent object. In order to get a more realistic effect the {\small\texttt{dispersion 
 }} and {\small\texttt{dispersion\_\-samples}} keywords can be added to the {\small\texttt{interior\{\}}} block. They will simulate dispersion by creating a 
 prismatic color effect in the object.\index{dispersion} 



   The {\small\texttt{dispersion}} value is the ratio of refractive indices for violet to red. It controls the strength of dispersion (how much the colors are 
 spread out) used. A DISPERSION\_\-VALUE of 1 will give no dispersion, good values are 1.01 to 1.1. 



   \textbf{Note:} there will be no dispersion, unless the {\small\texttt{ior}} keyword has been specified in {\small\texttt{interior\{ \}}}. An ior of 1 is legal. 
 The ior has no influence on the dispersion strength, only on the angle of refraction. 



   As POV-\discretionary{}{}{}Ray does not use wavelengths for raytracing, a spectrum is simulated. The {\small\texttt{dispersion\_\-samples}} value controls the amount of color-\discretionary{}{}{}steps 
 and smoothness in the spectrum. The default value is 7, the minimum is 2. Values up to 100 or higher may be needed to get a very smooth result. 


\subsubsection{Dispersion \& Caustics}

% reference/000483.html



   Dispersion only affects the interior of an object and has no effect on faked caustics (See "Faked Caustics"). \newline To see the effects of 
 dispersion in caustics, photon mapping is needed (See the sections "Photons" and "Dispersion \& Photons"). 


\subsection{Attenuation}

% reference/000309.html

\index{fade\_\-power! interior}\index{fade\_\-distance! interior}\index{fade\_\-color}\index{fade\_\-colour}\index{interior! fade\_\-power}\index{interior! fade\_\-distance}

   Light attenuation is used to model the decrease in light intensity as the light travels through a transparent object. The keywords {\small\texttt{fade\_\-power}}, 
 {\small\texttt{fade\_\-distance}} and {\small\texttt{fade\_\-color}} are specified in the {\small\texttt{interior}} statement. 



   The {\small\texttt{fade\_\-distance}} value determines the distance the light has to travel to reach half intensity while the {\small\texttt{fade\_\-power}} value 
 determines how fast the light will fall off. {\small\texttt{fade\_\-color}} colorizes the attenuation. For realistic effects a fade power of 1 to 2 should be 
 used. Default values for {\small\texttt{fade\_\-power}} and {\small\texttt{fade\_\-distance}} is 0.0 which turns this feature off. Default for {\small\texttt{fade\_\-color}} 
 is {\small\texttt{$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}}, if {\small\texttt{fade\_\-color}} is {\small\texttt{$<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}1$>$}} there is no attenuation. The actual colors give colored 
 attenuation. {\small\texttt{$<$\discretionary{1,}{}{1,}\discretionary{0,}{}{0,}0$>$}} looks red, not cyan as in media. 



   The attenuation is calculated by a formula similar to that used for light source attenuation. 



   
\begin{mathequ}
% FILE: medatten
% --------
\begin{displaymath}
  \mathit{attenuation} =
  \frac{1}
  {1+\left(\frac{d}{\mathit{fade\_distance}}\right)^\mathit{fade\_power}}
\end{displaymath}

\caption{} \end{mathequ}
 



   If you set fade\_\-power in the interior of an object at 1000 or above, a realistic exponential attenuation function will be used: 


{\small\begin{verbatim}   Attenuation = exp(-depth/fade_dist)\end{verbatim}}


   The {\small\texttt{fade\_\-power}} and {\small\texttt{fade\_\-distance}} keywords were originally specified in {\small\texttt{finish}} but are now properly 
 specified in {\small\texttt{interior}}. They are accepted in {\small\texttt{finish}} for backward compatibility and generate a warning message. 


\subsection{Simulated Caustics}

% reference/000308.html

\index{caustics}\index{caustics! simulated}

   Caustics are light effects that occur if light is reflected or refracted by specular reflective or refractive surfaces. Imagine a glass of water standing on 
 a table. If sunlight falls onto the glass you will see spots of light on the table. Some of the spots are caused by light being reflected by the glass while 
 some of them are caused by light being refracted by the water in the glass. 



   Since it is a very difficult and time-\discretionary{}{}{}consuming process to actually calculate those effects (though it is not impossible, see the sections "Photons") 
 POV-\discretionary{}{}{}Ray uses a quite simple method to simulate caustics caused by refraction. The method calculates the angle between the incoming light 
 ray and the surface normal. Where they are nearly parallel it makes the shadow brighter. Where the angle is greater, the effect is diminished. Unlike 
 real-\discretionary{}{}{}world caustics, the effect does not vary based on distance. This caustic effect is limited to areas that are shaded by the 
 transparent object. You will get no caustic effects from reflective surfaces nor in parts that are not shaded by the object. 



   The {\small\texttt{caustics}} \textit{{\small\texttt{Power}}} keyword controls the effect. Values typically range from 0.0 to 1.0 or higher. Zero is the 
 default which is no caustics. Low, non-\discretionary{}{}{}zero values give broad hot-\discretionary{}{}{}spots while higher values give tighter, smaller simulated focal points. 



   The {\small\texttt{ caustics}} keyword was originally specified in {\small\texttt{ finish}} but is now properly specified in {\small\texttt{interior}}. It is 
 accepted in {\small\texttt{ finish}} for backward compatibility and generates a warning message. 


\subsection{Object-\discretionary{}{}{}Media}

% reference/000307.html

\index{object media}\index{media! object}

   The {\small\texttt{interior}} statement may contain one or more {\small\texttt{media}} statements. Media is used to simulate suspended particles such as 
 smoke, haze, or dust. Or visible gasses such as steam or fire and explosions. When used with an object interior, the effect is constrained by the object's 
 shape. The calculations begin when the ray enters an object and ends when it leaves the object. This section only discusses media when used with object 
 interior. The complete syntax and an explanation of all of the parameters and options for {\small\texttt{media}} is given in the section "Media". 



   Typically the object itself is given a fully transparent texture however media also works in partially transparent objects. The texture pattern itself does 
 not effect the interior media except perhaps to create shadows on it. The texture pattern of an object applies only to the surface shell. Any interior media 
 patterns are totally independent of the texture. 



   In previous versions of POV-\discretionary{}{}{}Ray, this feature was called {\small\texttt{ halo}} and was part of the {\small\texttt{ texture}} specification along with {\small\texttt{ 
 pigment}}, {\small\texttt{ normal}}, and {\small\texttt{finish}}. See "Why are Interior and Media Necessary?" for an explanation of the reasons for 
 the change. 



   Media may also be specified outside an object to simulate atmospheric media. There is no constraining object in this case. If you only want media effects in 
 a particular area, you should use object media rather than only relying upon the media pattern. In general it will be faster and more accurate because it only 
 calculates inside the constraining object. See "Atmospheric Media" for details on unconstrained uses of media. 



   You may specify more than one {\small\texttt{media}} statement per {\small\texttt{ interior}} statement. In that case, all of the media participate and where 
 they overlap, they add together. 



   Any object which is supposed to have media effects inside it, whether those effects are object media or atmospheric media, must have the {\small\texttt{hollow 
 on}} keyword applied. Otherwise the media is blocked. See "Empty and Solid Objects" for details. 


\section{Media}

% reference/000305.html

\index{atmosphere}\index{media! reference}

   The {\small\texttt{media}} statement is used to specify particulate matter suspended in a medium such air or water. It can be used to specify smoke, haze, 
 fog, gas, fire, dust etc. Previous versions of POV-\discretionary{}{}{}Ray had two incompatible systems for generating such effects. One was {\small\texttt{halo}} for effects 
 enclosed in a transparent or semi-\discretionary{}{}{}transparent object. The other was {\small\texttt{atmosphere}} for effects that permeated the entire scene. This duplication 
 of systems was complex and unnecessary. Both {\small\texttt{ halo}} and {\small\texttt{atmosphere}} have been eliminated. See "Why are Interior and Media 
 Necessary?" for further details on this change. See "Object Media" for details on how to use {\small\texttt{media}} with objects. See "Atmospheric 
 Media" for details on using {\small\texttt{media}} for atmospheric effects outside of objects. This section and the sub-\discretionary{}{}{}sections which follow explains 
 the details of the various {\small\texttt{ media}} options which are useful for either object media or atmospheric media. 



   Media works by sampling the density of particles at some specified number of points along the ray's path. Sub-\discretionary{}{}{}samples are also taken until the results reach 
 a specified confidence level. POV-\discretionary{}{}{}Ray provides three methods of sampling. When used in an object's {\small\texttt{ interior}} statement, sampling only occurs 
 inside the object. When used for atmospheric media, the samples run from the camera location until the ray strikes an object. Therefore for localized effects, 
 it is best to use an enclosing object even though the density pattern might only produce results in a small area whether the media was enclosed or not. 



   The complete syntax for a {\small\texttt{media}} statement is as follows:\index{media}\index{media! keyword}\index{Keyword! media}\index{method! media}\index{Keyword! method}\index{intervals! media}\index{Keyword! intervals}\index{samples! media}\index{Keyword! samples}\index{confidence! media}\index{Keyword! confidence}\index{variance! media}\index{Keyword! variance}\index{ratio! media}\index{Keyword! ratio}\index{absorption! media}\index{Keyword! absorption}\index{emission! media}\index{Keyword! emission}\index{aa\_\-threshold! media}\index{Keyword! aa\_\-threshold}\index{aa\_\-level! media}\index{Keyword! aa\_\-level}\index{scattering! media}\index{Keyword! scattering}\index{eccentricity! media}\index{Keyword! eccentricity}\index{extinction! media}\index{Keyword! extinction}\index{density! media}\index{Keyword! density} 
 


{\small\begin{verbatim}
MEDIA:
    media { [MEDIA_IDENTIFIER] [MEDIA_ITEMS...] }
MEDIA_ITEMS:
    method Number | intervals Number | samples Min, Max |
    confidence Value  | variance Value | ratio Value |
    absorption COLOR | emission COLOR | aa_threshold Value |
    aa_level Value | 
    scattering { 
       Type, COLOR [ eccentricity Value ] [ extinction Value ]
    }  | 
    density { 
       [DENSITY_IDENTIFIER] [PATTERN_TYPE] [DENSITY_MODIFIER...]
    }   | 
    TRANSFORMATIONS
DENSITY_MODIFIER:
    PATTERN_MODIFIER | DENSITY_LIST | COLOR_LIST |
    color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
    density_map { DENSITY_MAP_BODY }
\end{verbatim}}


   Media default values: \index{Default values! media} 


{\small\begin{verbatim}
aa_level     : 4
aa_threshold : 0.1
absorption   : <0,0,0>
confidence   : 0.9
emission     : <0,0,0>
intervals    : 10
method       : 3
ratio        : 0.9
samples      : Min 1, Max 1
variance     : 1/128
SCATTERING
  COLOR        : <0,0,0>
  eccentricity : 0.0
  extinction   : 1.0
\end{verbatim}}


   If a media identifier is specified, it must be the first item. All other media items may be specified in any order. All are optional. You may have multiple {\small\texttt{density}} 
 statements in a single {\small\texttt{media}} statement. See "Multiple Density vs. Multiple Media" for details. Transformations apply only the {\small\texttt{density}} 
 statements which have been already specified. Any {\small\texttt{density}} after a transformation is not affected. If the {\small\texttt{media}} has no {\small\texttt{density}} 
 statements and none was specified in any media identifier, then the transformation has no effect. All other media items except for {\small\texttt{ density}} 
 and transformations override default values or any previously set values for this {\small\texttt{media}} statement. 



   \textbf{Note:} some media effects depend upon light sources. However the participation of a light source depends upon the {\small\texttt{media\_\-interaction}} 
 and {\small\texttt{media\_\-attenuation}} keywords. See "Atmospheric Media Interaction" and "Atmospheric Attenuation" for details. 



   \textbf{Note:} In the POV-\discretionary{}{}{}Ray 3.1 documentation it said: "Note a strange design side-\discretionary{}{}{}effect was discovered during testing and it was too difficult to 
 fix. If the enclosing object uses {\small\texttt{transmit}} rather than {\small\texttt{filter}} for transparency, then the {\small\texttt{media}} casts no 
 shadows." This is not the case anymore since POV-\discretionary{}{}{}Ray 3.5. Whether you specify {\small\texttt{transmit}} or {\small\texttt{filter}} to create a transparent 
 container object, the {\small\texttt{media}} will always cast a shadow. If a shadow is not desired, use the {\small\texttt{no\_\-shadow}} keyword for the 
 container object. 


\subsection{Media Types}

% reference/000314.html

\index{media! types}

   There are three types of particle interaction in {\small\texttt{media}}: absorbing, emitting, and scattering. All three activities may occur in a single 
 media. Each of these three specifications requires a color. Only the red, green, and blue components of the color are used. The filter and transmit values are 
 ignored. For this reason it is permissible to use one float value to specify an intensity of white color. For example the following two lines are legal and 
 produce the same results: 


{\small\begin{verbatim}
  emission 0.75
  emission rgb<0.75,0.75,0.75>
\end{verbatim}}

\subsubsection{Absorption}

% reference/000320.html



   The {\small\texttt{absorption}} keyword specifies a color of light which is absorbed when looking through the media. For example {\small\texttt{absorption 
 rgb$<$\discretionary{0,}{}{0,}\discretionary{1,}{}{1,}0$>$}} blocks the green light but permits red and blue to get through. Therefore a white object behind 
 the media will appear magenta. 



   The default value is {\small\texttt{rgb$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}} which means no light is absorbed -- all light passes through normally. 


\subsubsection{Emission}

% reference/000319.html

\index{emission}

   The {\small\texttt{emission}} keyword specifies a color of the light emitted from the particles. Although we say they "emit" light, this only means 
 that they are visible without any illumination shining on them. They do not really emit light that is cast on to nearby objects. This is similar to an object 
 with high {\small\texttt{ambient}} values. The default value is {\small\texttt{ rgb$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}} which means no light is emitted. 


\subsubsection{Scattering}

% reference/000318.html

\index{scattering}

   The syntax of a {\small\texttt{scattering}} statement is: 


{\small\begin{verbatim}
SCATTERING:
    scattering { 
        Type, COLOR [ eccentricity Value ] [ extinction Value ] 
    }
\end{verbatim}}


   The first float value specifies the type of scattering. This is followed by the color of the scattered light. The default value if no {\small\texttt{ 
 scattering}} statement is given is {\small\texttt{rgb$<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$}} which means no scattering occurs. 



   \index{extinction} \index{absorption} The scattering effect is only visible when light is shining on the media from a light source. This is similar to {\small\texttt{diffuse}} 
 reflection off of an object. In addition to reflecting light, a scattering media also absorbs light like an {\small\texttt{ absorption}} media. The balance 
 between how much absorption occurs for a given amount of scattering is controlled by the optional {\small\texttt{ extinction}} keyword and a single float 
 value. The default value of 1.0 gives an extinction effect that matches the scattering. Values such as {\small\texttt{extinction 0.25}} give 25\% the normal 
 amount. Using {\small\texttt{ extinction 0.0}} turns it off completely. Any value other than the 1.0 default is contrary to the real physical model but 
 decreasing extinction can give you more artistic flexibility. 



   The integer value \textit{{\small\texttt{ Type}}} specifies one of five different scattering phase functions representing the different models: isotropic, 
 Mie (haze and murky atmosphere), Rayleigh, and Henyey-\discretionary{}{}{}Greenstein. 



   Type 1, \textit{isotropic scattering} is the simplest form of scattering because it is independent of direction. The amount of light scattered by particles 
 in the atmosphere does not depend on the angle between the viewing direction and the incoming light. 



   Types 2 and 3 are \textit{Mie haze} and \textit{Mie murky} scattering which are used for relatively small particles such as minuscule water droplets of fog, 
 cloud particles, and particles responsible for the polluted sky. In this model the scattering is extremely directional in the forward direction \discretionary{i.}{}{i.}e. the 
 amount of scattered light is largest when the incident light is anti-\discretionary{}{}{}parallel to the viewing direction (the light goes directly to the viewer). It is smallest 
 when the incident light is parallel to the viewing direction. The haze and murky atmosphere models differ in their scattering characteristics. The murky model 
 is much more directional than the haze model. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/miehaze} \caption{The Mie haze scattering function} \end{figure} 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/miemurky} \caption{The Mie murky scattering function.} \end{figure} 



   Type 4 \textit{Rayleigh scattering} models the scattering for extremely small particles such as molecules of the air. The amount of scattered light depends 
 on the incident light angle. It is largest when the incident light is parallel or anti-\discretionary{}{}{}parallel to the viewing direction and smallest when the incident light 
 is perpendicular to the viewing direction. You should note that the Rayleigh model used in POV-\discretionary{}{}{}Ray does not take the dependency of scattering on the 
 wavelength into account. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/raylscat} \caption{The Rayleigh scattering function.} \end{figure} \index{eccentricity} 
 



   Type 5 is the \textit{Henyey-\discretionary{}{}{}Greenstein scattering} model. It is based on an analytical function and can be used to model a large variety of different 
 scattering types. The function models an ellipse with a given eccentricity e. This eccentricity is specified by the optional keyword {\small\texttt{ 
 eccentricity}} which is only used for scattering type five. The default eccentricity value of zero defines isotropic scattering while positive values lead to 
 scattering in the direction of the light and negative values lead to scattering in the opposite direction of the light. Larger values of e (or smaller values 
 in the negative case) increase the directional property of the scattering. 



   \begin{figure} \centering\includegraphics[scale=0.30]{../final/tex/images/reference/hgscatt} \caption{The Henyey-\discretionary{}{}{}Greenstein scattering function for different eccentricity values.} \end{figure} 
 


\subsection{Sampling Parameters \& Methods}

% reference/000317.html

\index{intervals}

   Media effects are calculated by sampling the media along the path of the ray. It uses a method called \textit{Monte Carlo integration.} The {\small\texttt{intervals}} 
 keyword may be used to specify the integer number of intervals used to sample the ray. The default number of intervals is 10. For object media the intervals 
 are spread between the entry and exit points as the ray passes through the container object. For atmospheric media, the intervals spans the entire length of 
 the ray from its start until it hits an object. For media types which interact with spotlights or cylinder lights, the intervals which are not illuminated by 
 these light types are weighted differently than the illuminated intervals when distributing samples.\index{ratio} 



   The {\small\texttt{ratio}} keyword distributes intervals differently between lit and unlit areas. The default value of {\small\texttt{ratio 0.9}} means that 
 lit intervals get more samples than unlit intervals. Note that the total number of intervals must exceed the number of illuminated intervals. If a ray passes 
 in and out of 8 spotlights but you have only specified 5 intervals then an error occurs.\index{samples} 



   The {\small\texttt{samples}} \textit{{\small\texttt{Min}}}, \textit{{\small\texttt{ Max}}} keyword specifies the minimum and maximum number of samples taken 
 per interval. The default values are {\small\texttt{samples \discretionary{1,}{}{1,}1}}. \index{confidence! media}\index{variance! media} 



   As each interval is sampled, the variance is computed. If the variance is below a threshold value, then no more samples are needed. The {\small\texttt{variance}} 
 and {\small\texttt{confidence}} keywords specify the permitted variance allowed and the confidence that you are within that variance. The exact calculations 
 are quite complex and involve chi-\discretionary{}{}{}squared tests and other statistical principles too messy to describe here. The default values are {\small\texttt{variance 
 1.0/128}} and {\small\texttt{confidence 0.9}}. For slower more accurate results, decrease the variance and increase the confidence. 



   \textbf{Note:} the maximum number of samples limits the calculations even if the proper variance and confidence are never reached.\index{method} 



   The {\small\texttt{method}} keyword lets you specify what sampling method is used, POV-\discretionary{}{}{}Ray provides three. {\small\texttt{Method 1}} is the method described 
 above. 



   Sample {\small\texttt{method 2}} distributes samples evenly along the viewing ray or light ray. The latter can make things look smoother sometimes. If you 
 specify a max samples higher than the minimum samples, POV will take additional samples, but they will be random, just like in method 1. Therefore, it is 
 suggested you set the max samples equal to the minimum samples. {\small\texttt{jitter}} will cause method 2 to look similar to method 1. It should be followed 
 by a float, and a value of 1 will stagger the samples in the full range between samples.\index{aa\_\-level}\index{aa\_\-threshold} 



   Sample {\small\texttt{method 3}} uses adaptive sampling (similar to adaptive anti-\discretionary{}{}{}aliasing) which is very much like the sampling method used in POV-\discretionary{}{}{}Ray 3.0's 
 atmosphere. This code was written from the ground-\discretionary{}{}{}up to work with media, however. Adaptive sampling works by taking another sample between two existing 
 samples if there is too much variance in the original two samples. This leads to fewer samples being taken in areas where the effect from the media remains 
 constant. The adaptive sampling is only performed if the minimum samples are set to 3 or more. 



   You can specify the anti-\discretionary{}{}{}aliasing recursion depth using the {\small\texttt{aa\_\-level}} keyword followed by an integer. You can specify the anti-\discretionary{}{}{}aliasing 
 threshold by using the {\small\texttt{aa\_\-threshold}} followed by a float. The default for {\small\texttt{aa\_\-level}} is 4 and the default {\small\texttt{aa\_\-threshold}} 
 is 0.1. {\small\texttt{jitter}} also works with method 3. Sample method 3 ignores the maximum samples value. It is usually best to only use one interval with 
 method 3. Too many intervals can lead to artefacts, and POV will create more intervals if it needs them. 


\subsection{Density}

% reference/000316.html

\index{media! density}

   Particles of media are normally distributed in constant density throughout the media. However the {\small\texttt{density}} statement allows you to vary the 
 density across space using any of POV-\discretionary{}{}{}Ray's pattern functions such as those used in textures. If no {\small\texttt{density}} statement is given then the 
 density remains a constant value of 1.0 throughout the media. More than one {\small\texttt{density}} may be specified per {\small\texttt{media}} statement. 
 See "Multiple Density vs. Multiple Media". The syntax for {\small\texttt{density}} is: 


{\small\begin{verbatim}
DENSITY:
    density
    {
        [DENSITY_IDENTIFIER]
        [DENSITY_TYPE]
        [DENSITY_MODIFIER...]
    }
DENSITY_TYPE:
    PATTERN_TYPE | COLOR 
DENSITY_MODIFIER:
    PATTERN_MODIFIER | DENSITY_LIST | color_map { COLOR_MAP_BODY } |
    colour_map { COLOR_MAP_BODY } | density_map { DENSITY_MAP_BODY }
\end{verbatim}}


   The {\small\texttt{density}} statement may begin with an optional density identifier. All subsequent values modify the defaults or the values in the 
 identifier. The next item is a pattern type. This is any one of POV-\discretionary{}{}{}Ray's pattern functions such as {\small\texttt{bozo}}, {\small\texttt{wood}}, {\small\texttt{gradient}}, 
 {\small\texttt{waves}}, etc. Of particular usefulness are the {\small\texttt{spherical}}, {\small\texttt{planar}}, {\small\texttt{ cylindrical}}, and {\small\texttt{boxed}} 
 patterns which were previously available only for use with our discontinued {\small\texttt{halo}} feature. All patterns return a value from 0.0 to 1.0. This 
 value is interpreted as the density of the media at that particular point. See "Patterns" for details on particular pattern types. Although a solid \textit{COLOR} 
 pattern is legal, in general it is used only when the {\small\texttt{density}} statement is inside a {\small\texttt{density\_\-map}}. 


\subsubsection{General Density Modifiers}

% reference/000315.html



   A {\small\texttt{density}} statement may be modified by any of the general pattern modifiers such as transformations, {\small\texttt{turbulence}} and {\small\texttt{ 
 warp}}. See "Pattern Modifiers" for details. In addition there are several density-\discretionary{}{}{}specific modifiers which can be used. 


\subsubsection{Density with color\_\-map}

% reference/000321.html

\index{color\_\-map! density}

   Typically a {\small\texttt{media}} uses just one constant color throughout. Even if you vary the density, it is usually just one color which is specified by 
 the {\small\texttt{absorption}}, {\small\texttt{emission}}, or {\small\texttt{ scattering}} keywords. However when using {\small\texttt{emission}} to simulate 
 fire or explosions, the center of the flame (high density area) is typically brighter and white or yellow. The outer edge of the flame (less density) fades to 
 orange, red, or in some cases deep blue. To model the density-\discretionary{}{}{}dependent change in color which is visible, you may specify a {\small\texttt{ color\_\-map}}. The 
 pattern function returns a value from 0.0 to 1.0 and the value is passed to the color map to compute what color or blend of colors is used. See "Color 
 Maps" for details on how pattern values work with {\small\texttt{color\_\-map}}. This resulting color is multiplied by the {\small\texttt{ absorption}}, {\small\texttt{emission}} 
 and {\small\texttt{ scattering}} color. Currently there is no way to specify different color maps for each media type within the same {\small\texttt{media}} 
 statement. 



   Consider this example: 


{\small\begin{verbatim}
  media{
    emission 0.75
    scattering {1, 0.5}
    density { spherical
      color_map {
        [0.0 rgb <0,0,0.5>]
        [0.5 rgb <0.8, 0.8, 0.4>]
        [1.0 rgb <1,1,1>]
      }
    }
  }
\end{verbatim}}


   The color map ranges from white at density 1.0 to bright yellow at density 0.5 to deep blue at density 0. Assume we sample a point at density 0.5. The 
 emission is 0.75*$<$0.\discretionary{8,}{}{8,}0.\discretionary{8,}{}{8,}0.4$>$ or $<$0.\discretionary{6,}{}{6,}0.\discretionary{6,}{}{6,}0.3$>$. Similarly the scattering color is 0.5*$<$0.\discretionary{8,}{}{8,}0.\discretionary{8,}{}{8,}0.4$>$ or $<$0.\discretionary{4,}{}{4,}0.\discretionary{4,}{}{4,}0.2$>$. 



   For block pattern types {\small\texttt{checker}}, {\small\texttt{ hexagon}}, and {\small\texttt{ brick}} you may specify a color list such as this: 


{\small\begin{verbatim}
  density{
    checker 
    density {rgb<1,0,0>}
    density {rgb<0,0,0>}
  }
\end{verbatim}}


   See "Color List Pigments" which describes how {\small\texttt{pigment}} uses a color list. The same principles apply when using them with {\small\texttt{density}}. 
 


\subsubsection{Density Maps and Density Lists}

% reference/000322.html

\index{density\_\-map}

   In addition to specifying blended colors with a color map you may create a blend of densities using a {\small\texttt{density\_\-map}}. The syntax for a density 
 map is identical to a color map except you specify a density in each map entry (and not a color). 



   The syntax for {\small\texttt{density\_\-map}} is as follows: 


{\small\begin{verbatim}
DENSITY_MAP:
    density_map { DENSITY_MAP_BODY }
DENSITY_MAP_BODY:
    DENSITY_MAP_IDENTIFIER | DENSITY_MAP_ENTRY...
DENSITY_MAP_ENTRY:
    [ Value DENSITY_BODY ]
\end{verbatim}}


   Where \textit{{\small\texttt{Value}}} is a float value between 0.0 and 1.0 inclusive and each \textit{DENSITY\_\-BODY} is anything which can be inside a {\small\texttt{density\{...\}}} 
 statement. The {\small\texttt{density}} keyword and {\small\texttt{\{\}}} braces need not be specified. 



   \textbf{Note:} the {\small\texttt{[]}} brackets are part of the actual \textit{ DENSITY\_\-MAP\_\-ENTRY}. They are not notational symbols denoting optional parts. 
 The brackets surround each entry in the density map. 



   There may be from 2 to 256 entries in the map. 



   Density maps may be nested to any level of complexity you desire. The densities in a map may have color maps or density maps or any type of density you want. 



   Entire densities may also be used with the block patterns such as {\small\texttt{ checker}}, {\small\texttt{hexagon}} and {\small\texttt{brick}}. For 
 example... 


{\small\begin{verbatim}
  density {
    checker
    density { Flame scale .8 }
    density { Fire scale .5 }
  }
\end{verbatim}}


   \textbf{Note:} in the case of block patterns the {\small\texttt{density}} wrapping is required around the density information. 



   A density map is also used with the {\small\texttt{average}} density type. See "Average" for details. 



   You may declare and use density map identifiers but the only way to declare a density block pattern list is to declare a density identifier for the entire 
 density. 


\subsubsection{Multiple Density vs. Multiple Media}

% reference/000323.html



   It is possible to have more than one {\small\texttt{media}} specified per object and it is legal to have more than one {\small\texttt{density}} per {\small\texttt{ 
 media}}. The effects are quite different. Consider this example: 


{\small\begin{verbatim}
  object {
    MyObject
    pigment { rgbf 1 }
    interior {
      media {
        density { Some_Density }
        density { Another_Density }
      }
    }
  }
\end{verbatim}}


   As the media is sampled, calculations are performed for each density pattern at each sample point. The resulting samples are multiplied together. Suppose one 
 density returned {\small\texttt{rgb$<$.8,.8,.4$>$}} and the other returned {\small\texttt{rgb$<$.25,.\discretionary{25,}{}{25,}0$>$}}. The resulting color is {\small\texttt{ 
 rgb$<$.2,.\discretionary{2,}{}{2,}0$>$}}. 



   \textbf{Note:} in areas where one density returns zero, it will wipe out the other density. The end result is that only density areas which overlap will be 
 visible. This is similar to a CSG intersection operation. Now consider 


{\small\begin{verbatim}
  object { 
    MyObject
    pigment { rgbf 1 }
    interior {
      media {
        density { Some_Density }
      }
      media {
        density { Another_Density }
      }
    }
  }
\end{verbatim}}


   In this case each media is computed independently. The resulting colors are added together. Suppose one density and media returned {\small\texttt{ 
 rgb$<$.8,.8,.4$>$}} and the other returned {\small\texttt{ rgb$<$.25,.\discretionary{25,}{}{25,}0$>$}}. The resulting color is {\small\texttt{ rgb$<$1.\discretionary{05,}{}{05,}1.05,.4$>$}}. The end 
 result is that density areas which overlap will be especially bright and all areas will be visible. This is similar to a CSG union operation. See the sample 
 scene {\small\texttt{scenes$\backslash$\discretionary{}{}{}interior$\backslash$\discretionary{}{}{}media$\backslash$\discretionary{}{}{}\discretionary{media4.}{}{media4.}pov}} for an example which illustrates this. 


\section{Photons}

% reference/000304.html


\subsection{Overview}

% reference/000324.html



   The basic goal of this implementation of the photon map is to render true reflective and refractive caustics. The photon map was first introduced by Henrik 
 Wann Jensen (see Suggested Reading). 



   Photon mapping is a technique which uses a forward ray-\discretionary{}{}{}tracing pre-\discretionary{}{}{}processing step to render refractive and reflective caustics realistically. This means 
 that mirrors can reflect light rays and lenses can focus light. 



   Photon mapping works by shooting packets of light (photons) from light sources into the scene. The photons are directed towards specific objects. When a 
 photon hits an object after passing through (or bouncing off of) the target object, the ray intersection is stored in memory. This data is later used to 
 estimate the amount of light contributed by reflective and refractive caustics. 


\subsubsection{Examples}

% reference/000331.html



   \begin{figure} \centering \includegraphics[scale=0.60]{../final/tex/images/reference/photons1} \caption{Reflective caustics} \end{figure} 



   This image shows refractive caustics from a sphere and a cylinder. Both use an index of refraction of {\small\texttt{1.2}}. Also visible is a small amount of 
 reflective caustics from the metal sphere, and also from the clear cylinder and sphere. 



   \begin{figure} \centering \includegraphics[scale=0.60]{../final/tex/images/reference/photons2} \caption{Photons used for lenses and caustics} \end{figure} 



   Here we have three lenses and three light sources. The middle lens has photon mapping turned off. You can also see some reflective caustics from the brass 
 box (some light reflects and hits the blue box, other light bounces through the nearest lens and is focused in the lower left corner of the image). 


\subsection{Using Photon Mapping in Your Scene}

% reference/000330.html



   When designing a scene with photons, it helps to think of the scene objects in two categories. Objects in the first category will show photon caustics when 
 hit by photons. Objects in the second category cause photon caustics by reflecting or refracting photons. Some objects may be in both categories, and some 
 objects may be in neither category. 



   Category 1 - Objects that show photon caustics 



   By default, all objects are in the first category. Whenever a photon hits an object, the photon is stored and will later be used to render caustics on that 
 object. This means that, by default, caustics from photons can appear on any surface. To speed up rendering, you can take objects out of this category. You do 
 this with the line: {\small\texttt{photons\{collect off\}}}. If you use this syntax, caustics from photons will not appear on the object. This will save both 
 memory and computational time during rendering. 



   Category 2 - Objects that cause photon caustics 



   By default, there are no objects in the second category. If you want your object to cause caustics, you need to do two things. First, make your object into a 
 "target." You do this with the {\small\texttt{target}} keyword. This enables light sources to shoot photons at your object. Second, you need to specify if 
 your object reflects photons, refracts photons, or both. This is done with the {\small\texttt{reflection on}} and {\small\texttt{refraction on}} keywords. To 
 allow an object to reflect and refract photons, you would use the following lines of code inside the object: 


{\small\begin{verbatim}
photons{
  target
  reflection on
  refraction on
}
\end{verbatim}}


   Generally speaking, you do not want an object to be in both categories. Most objects that cause photon caustics do not themselves have much color or 
 brightness. Usually they simply refract or reflect their surroundings. For this reason, it is usually a waste of time to display photon caustics on such 
 surfaces. Even if computed, the effects from the caustics would be so dim that they would go unnoticed. 



   Sometimes, you may also wish to add {\small\texttt{photons\{collect off\}}} to other clear or reflective objects, even if they are not photon targets. Again, 
 this is done to prevent unnecessary computation of caustic lighting. 



   Finally, you may wish to enable photon reflection and refraction for a surface, even if it is not a target. This allows indirect photons (photons that have 
 already hit a target and been reflected or refracted) to continue their journey after hitting this object. 


\subsubsection{Photon Global Settings}

% reference/000329.html

\index{photons}\index{refraction}
{\small\begin{verbatim}global_photon_block:
photons {
  spacing <photon_spacing> | count <photons_to_shoot>

  [gather <min_gather>, <max_gather>]
  [media <max_steps> [,<factor>]]
  [jitter <jitter_amount>]
  [max_trace_level <photon_trace_level>]
  [adc_bailout <photon_adc_bailout>]
  [save_file "filename" | load_file "filename"]
  [autostop <autostop_fraction>]
  [expand_thresholds <percent_increase>, <expand_min>]
  [radius <gather_radius>,<multiplier>,
          <gather_radius_media>,<multiplier>]
}\end{verbatim}}


   All photons default values: \index{Default values! photons} 


{\small\begin{verbatim}
Global :
  expand_min    : 40 
  gather        : 20, 100
  jitter        : 0.4
  media         : 0
  
Object :
  collect       : on
  refraction    : off
  reflection    : off
  split_union   : on
  target        : 1.0
    
Light_source:
  area_light    : off
  refraction    : off
  reflection    : off

\end{verbatim}}


   To specify photon gathering and storage options you need to add a photons block to the global\_\-settings section of your scene. 



   For example: 


{\small\begin{verbatim}
 global_settings {
   photons {
     count 20000
     autostop 0
     jitter .4
   }
 }
\end{verbatim}}


   The number of photons generated can be set using either the spacing or count keywords: 


\begin{itemize}
 \index{spacing}
 \item 
   If spacing is used, it specifies approximately the average distance between photons on surfaces. If you cut the spacing in half, you will get four 
  times as many surface photons, and eight times as many media photons. 
 

 \item 
   If count is used, POV-\discretionary{}{}{}Ray will shoot the approximately number of photons specified. The actual number of photons that result from this will almost 
  always be at least slightly different from the number specified. Still, if you double the photons\_\-to\_\-shoot value, then twice as many photons will be shot. If 
  you cut the value in half, then half the number of photons will be shot. 
  \begin{itemize}
   
   \item 
     It may be less, because POV shoots photons at a target object's bounding box, which means that some photons will miss the target object. 
   

   \item 
     On the other hand, may be more, because each time one object hits an object that has both reflection and refraction, two photons are created (one for 
    reflection and one for refraction). 
   

   \item 
     POV will attempt to compensate for these two factors, but it can only estimate how many photons will actually be generated. Sometimes this estimation 
    is rather poor, but the feature is still usable. 
   

  \end{itemize}
   
 

\end{itemize}
\index{gather}

   The keyword {\small\texttt{gather}} allows you to specify how many photons are gathered at each point during the regular rendering step. The first number 
 (default 20) is the minimum number to gather, while the second number (default 100) is the maximum number to gather. These are good values and you should only 
 use different ones if you know what you are doing.\index{media! photons}\index{photons! media} 



   The keyword {\small\texttt{media}} turns on media photons. The parameter {\small\texttt{max\_\-steps}} specifies the maximum number of photons to deposit over 
 an interval. The optional parameter factor specifies the difference in media spacing compared to surface spacing. You can increase factor and decrease 
 max\_\-steps if too many photons are being deposited in media.\index{jitter! photons} 



   The keyword {\small\texttt{jitter}} specifies the amount of jitter used in the sampling of light rays in the pre-\discretionary{}{}{}processing step. The default value is good 
 and usually does not need to be changed.\index{max\_\-trace\_\-level! photons}\index{adc\_\-bailout! photons} 



   The keywords {\small\texttt{max\_\-trace\_\-level}} and {\small\texttt{adc\_\-bailout}} allow you to specify these attributes for the photon-\discretionary{}{}{}tracing step. If you do 
 not specify these, the values for the primary ray-\discretionary{}{}{}tracing step will be used.\index{load\_\-file! photons}\index{save\_\-file! photons} 



   The keywords {\small\texttt{save\_\-file}} and {\small\texttt{load\_\-file}} allow you to save and load photon maps. If you load a photon map, no photons will be 
 shot. The photon map file contains all surface (caustic) and media photons.\index{radius! photons} 



   {\small\texttt{radius}} is used for gathering photons. The larger the radius, the longer it takes to gather photons. But if you use too small of a radius, 
 you might not get enough photons to get a good estimate. Therefore, choosing a good radius is important. Normally POV-\discretionary{}{}{}Ray looks through the photon map and 
 uses some ad-\discretionary{}{}{}hoc statistical analysis to determine a reasonable radius. Sometimes it does a good job, sometimes it does not. The radius keyword lets you 
 override or adjust POV-\discretionary{}{}{}Ray's guess. 



   {\small\texttt{radius}} parameters (all are optional): 


\begin{enumerate}
 
 \item 
   Manually set the gather radius for surface photons. If this is either zero or if you leave it out, POV-\discretionary{}{}{}Ray will analyze and guess. 
 

 \item 
   Adjust the radius for surface photons by setting a multiplier. If POV-\discretionary{}{}{}Ray, for example, is picking a radius that you think is too big (render is too 
  slow), you can use "{\small\texttt{radius ,0.5}}" to lower the radius (multiply by 0.5) and speed up the render at the cost of quality. 
 

 \item 
   Manually set the gather radius for media photons. 
 

 \item 
   Adjust the radius for media photons by setting a multiplier. 
 

\end{enumerate}
\index{autostop}

   The keywords {\small\texttt{autostop}} and {\small\texttt{expand\_\-thresholds}} will be explained later. 


\subsubsection{Shooting Photons at an Object}

% reference/000334.html


{\small\begin{verbatim}
object_photon_block:
photons {
  [target [<spacing_multiplier>]]
  [refraction on|off]
  [reflection on|off]
  [collect on|off]
  [pass_through]
}
\end{verbatim}}


   To shoot photons at an object, you need to tell POV that the object receives photons. To do this, create a {\small\texttt{photons \{ \}}} block within the 
 object. For example: 


{\small\begin{verbatim}
 object {
   MyObject
   photons {
     target
     refraction on
     reflection on
     collect off
   }
 }
\end{verbatim}}


   In this example, the object both reflects and refracts photons. Either of these options could be turned off (by specifying reflection off, for example). By 
 using this, you can have an object with a reflective finish which does not reflect photons for speed and memory reasons.\index{target} 



   The keyword {\small\texttt{target}} makes this object a target.\index{spacing\_\-multiplier} 



   The density of the photons can be adjusted by specifying the {\small\texttt{spacing\_\-multiplier}}. If, for example, you specify a {\small\texttt{spacing\_\-multiplier}} 
 of 0.5, then the spacing for photons hitting this object will be 1/2 of the distance of the spacing for other objects. 



   \textbf{Note:} This means four times as many surface photons, and eight times as many media photons.\index{collect} 



   The keyword {\small\texttt{collect off}} causes the object to ignore photons. Photons are neither deposited nor gathered on that object.\index{pass\_\-through} 
 



   The keyword {\small\texttt{pass\_\-through}} causes photons to pass through the object \textbf{unaffected} on their way to a target object. Once a photon hits 
 the target object, it will ignore the {\small\texttt{pass\_\-through}} flag. This is basically a photon version of the {\small\texttt{no\_\-shadow}} keyword, with 
 the exception that media within the object will still be affected by the photons (unless that media specifies collect off). If you use the {\small\texttt{no\_\-shadow}} 
 keyword, the object will be tagged as {\small\texttt{pass\_\-through}} automatically. You can then turn off {\small\texttt{pass\_\-through}} if necessary by simply 
 using {\small\texttt{photons \{ pass\_\-through off \}}}. 



   \textbf{Note:} Photons will not be shot at an object unless you specify the {\small\texttt{target}} keyword. Simply turning refraction on will not suffice. 



   When shooting photons at a CSG-\discretionary{}{}{}union, it may sometimes be of advantage to use {\small\texttt{split\_\-union off}} inside the union. POV-\discretionary{}{}{}Ray will be forced to 
 shoot at the whole object, instead of splitting it up and shooting photons at its compound parts. 


\subsubsection{Photons and Light Sources}

% reference/000333.html

\index{Light Sources! and photons}
{\small\begin{verbatim}
 light_photon_block:
 photons {
   [refraction on | off]
   [reflection on | off]
   [area_light]
 }
\end{verbatim}}


   Example: 


{\small\begin{verbatim}
 light_source {
   MyLight
   photons {
     refraction on
     reflection on
   }
 }
\end{verbatim}}


   Sometimes, you want photons to be shot from one light source and not another. In that case, you can turn photons on for an object, but specify {\small\texttt{photons 
 \{ reflection off refraction off \}}} in the light source's definition. You can also turn off only reflection or only refraction for any light source. 


\subsubsection{Photons and Media}

% reference/000332.html

\index{Media! and photons}
{\small\begin{verbatim}
 global_settings {
   photons {
     count 10000
     media 100
   }
 }
\end{verbatim}}


   Photons also interact fully with media. This means that volumetric photons are stored in scattering media. This is enabled by using the keyword media within 
 the photons block. 



   To store photons in media, POV deposits photons as it steps through the media during the photon-\discretionary{}{}{}tracing phase of the render. It will deposit these photons as 
 it traces caustic photons, so the number of media photons is dependent on the number of caustic photons. As a light ray passes through a section of media, the 
 photons are deposited, separated by approximately the same distance that separates surface photons. 



   You can specify a factor as a second optional parameter to the media keyword. If, for example, factor is set to 2.0, then photons will be spaced twice as far 
 apart as they would otherwise have been spaced. 



   Sometimes, however, if a section of media is very large, using these settings could create a large number of photons very fast and overload memory. 
 Therefore, following the media keyword, you must specify the maximum number of photons that are deposited for each ray that travels through each section of 
 media. A setting of 100 should probably work in most cases. 



   You can put {\small\texttt{collect off}} into media to make that media ignore photons. Photons will neither be deposited nor gathered in a media that is 
 ignoring them. Photons will also not be gathered nor deposited in non-\discretionary{}{}{}scattering media. However, if multiple medias exist in the same space, and at least one 
 does not ignore photons and is scattering, then photons will be deposited in that interval and will be gathered for use with all media in that interval. 


\subsection{Photons FAQ}

% reference/000328.html



   \textit{I made an object with IOR 1.0 and the shadows look weird.} 



   If the borders of your shadows look odd when using photon mapping, do not be alarmed. This is an unfortunate side-\discretionary{}{}{}effect of the method. If you increase the 
 density of photons (by decreasing spacing and gather radius) you will notice the problem diminish. We suggest not using photons if your object does not cause 
 much refraction (such as with a window pane or other flat piece of glass or any objects with an IOR very close to 1.0). 



   \textit{My scene takes forever to render.} 



   When POV-\discretionary{}{}{}Ray builds the photon maps, it continually displays in the status bar the number of photons that have been shot. Is POV-\discretionary{}{}{}Ray stuck in this step and 
 does it keep shooting lots and lots of photons? 



   \textit{yes} 



   If you are shooting photons at an infinite object (like a plane), then you should expect this. Either be patient or do not shoot photons at infinite objects. 



   Are you shooting photons at a CSG difference? Sometimes POV-\discretionary{}{}{}Ray does a bad job creating bounding boxes for these objects. And since photons are shot at the 
 bounding box, you could get bad results. Try manually bounding the object. You can also try the autostop feature (try {\small\texttt{autostop 0}}). See the 
 docs for more info on autostop. 



   \textit{no} 



   Does your scene have lots of glass (or other clear objects)? Glass is slow and you need to be patient. 



   \textit{My scene has polka dots but renders really quickly. Why?} 



   You should increase the number of photons (or decrease the spacing). 



   \textit{The photons in my scene show up only as small, bright dots. How can I fix this?} 



   The automatic calculation of the gather radius is probably not working correctly, most likely because there are many photons not visible in your scene which 
 are affecting the statistical analysis. 



   You can fix this by either reducing the number of photons that are in your scene but not visible to the camera (which confuse the auto-\discretionary{}{}{}computation), or by 
 specifying the initial gather radius manually by using the keyword radius. If you must manually specify a gather radius, it is usually best to also use 
 spacing instead of count, and then set radius and spacing to a \discretionary{5:}{}{5:}1 (\discretionary{radius:}{}{radius:}spacing) ratio. 



   \textit{Adding photons slowed down my scene a lot, and I see polka dots.} 



   This is usually caused by having both high- and low-\discretionary{}{}{}density photons in the same scene. The low density ones cause polka dots, while the high density ones 
 slow down the scene. It is usually best if the all photons are on the same order of magnitude for spacing and brightness. Be careful if you are shooting 
 photons objects close to and far from a light source. There is an optional parameter to the target keyword which allows you to adjust the spacing of photons 
 at the target object. You may need to adjust this factor for objects very close to or surrounding the light source. 



   \textit{I added photons, but I do not see any caustics.} 



   When POV-\discretionary{}{}{}Ray builds the photon maps, it continually displays in the status bar the number of photons that have been shot. Did it show any photons being shot? 



   \textit{no} 



   Try avoiding {\small\texttt{autostop}}, or you might want to bound your object manually. 



   Try increasing the number of photons (or decreasing the spacing). 



   \textit{yes} 



   \textit{Were any photons stored (the number after {\small\texttt{total}} in the rendering message as POV-\discretionary{}{}{}Ray shoots photons)?} 



   \textit{no} 



   It is possible that the photons are not hitting the target object (because another object is between the light source and the other object). 



   \textit{yes} 



   The photons may be diverging more than you expect. They are probably there, but you cannot see them since they are spread out too much 



   \textit{The base of my glass object is really bright.} 



   Use {\small\texttt{collect off}} with that object. 



   \textit{Will area lights work with photon mapping?} 



   Photons do work with area lights. However, normally photon mapping ignores all area light options and treats all light sources as point lights. If you would 
 like photon mapping to use your area light options, you must specify the "area\_\-light" keyword \textbf{within} the {\small\texttt{photons \{ \}}} block 
 in your light source's code. Doing this will not increase the number of photons shot by the light source, but it might cause regular patterns to show up in 
 the rendered caustics (possibly splotchiness). 



   \textit{What do the stats mean?} 



   In the stats, {\small\texttt{photons shot}} means how many light rays were shot from the light sources. {\small\texttt{photons stored}} means how many 
 photons are deposited on surfaces in the scene. If you turn on reflection and refraction, you could get more photons stored than photons shot, since the each 
 ray can get split into two. 


\subsection{Photon Tips}

% reference/000327.html


\begin{itemize}
 
 \begin{itemize}
  
  \item 
    Use {\small\texttt{collect off}} in objects that photons do not hit. Just put {\small\texttt{photons \{ collect off \}}} in the object's definition. 
  

  \item 
    Use {\small\texttt{collect off}} in glass objects. 
  

  \item 
    Use {\small\texttt{autostop}} unless it causes problems. 
  

  \item 
    A big tip is to make sure that all of the final densities of photons are of the same general magnitude. You do not want spots with really high density 
   photons and another area with really low density photons. You will always have some variation (which is a good thing), but having really big differences in 
   photon density is what causes some scenes to take many hours to render. 
  

 \end{itemize}

\end{itemize}

\subsection{Advanced Techniques}

% reference/000326.html


\subsubsection{Autostop}

% reference/000325.html



   \begin{figure} \centering \includegraphics[scale=0.60]{../final/tex/images/reference/shootph} \caption{Example of the photon autostop option} \end{figure} 



   To understand the {\small\texttt{autostop}} option, you need to understand the way photons are shot from light sources. Photons are shot in a spiral pattern 
 with uniform angular density. Imagine a sphere with a spiral starting at one of the poles and spiraling out in ever-\discretionary{}{}{}increasing circles to the equator. Two 
 angles are involved here. The first, phi, is the how far progress has been made in the current circle of the spiral. The second, theta, is how far we are from 
 the pole to the equator. Now, imagine this sphere centered at the light source with the pole where the spiral starts pointed towards the center of the object 
 receiving photons. Now, photons are shot out of the light in this spiral pattern. 



   Normally, POV does not stop shooting photons until the target object's entire bounding box has been thoroughly covered. Sometimes, however, an object is much 
 smaller than its bounding box. At these times, we want to stop shooting if we do a complete circle in the spiral without hitting the object. Unfortunately, 
 some objects (such as copper rings), have holes in the middle. Since we start shooting at the middle of the object, the photons just go through the hole in 
 the middle, thus fooling the system into thinking that it is done. To avoid this, the {\small\texttt{autostop}} keyword lets you specify how far the system 
 must go before this auto-\discretionary{}{}{}stopping feature kicks in. The value specified is a fraction of the object's bounding box. Valid values are 0.0 through 1.0 (0\% 
 through 100\%). POV will continue to shoot photons until the spiral has exceeded this value or the bounding box is completely covered. If a complete circle of 
 photons fails to hit the target object after the spiral has passed the autostop threshold, POV will then stop shooting photons. 



   The {\small\texttt{autostop}} feature will also not kick in until at least one photon has hit the object. This allows you to use {\small\texttt{autostop 0}} 
 even with objects that have holes in the middle. 



   \textbf{Note:}If the light source is within the object's bounding box, the photons are shot in all directions from the light source. 


\subsubsection{Adaptive Search Radius}

% reference/000335.html



   Unless photons are interacting with media, POV-\discretionary{}{}{}Ray uses an adaptive search radius while gathering photons. If the minimum number of photons is not found in 
 the original search radius, the radius is expanded and searched again. Using this adaptive search radius can both decrease the amount of time it takes to 
 render the image, and sharpen the borders in the caustic patterns.\index{expand\_\-thresholds} 



   Sometimes this adaptive search technique can create unwanted artefacts at borders. To remove these artefacts, a few thresholds are used, which can be 
 specified by {\small\texttt{expand\_\-thresholds}}. For example, if expanding the radius increases the estimated density of photons by too much (threshold is 
 percent\_\-increase, default is 20\%, or 0.2), the expanded search is discarded and the old search is used instead. However, if too few photons are gathered in 
 the expanded search ({\small\texttt{expand\_\-min}}, default is 40), the new search will be used always, even if it means more than a 20\% increase in photon 
 density. 


\subsubsection{Photons and Dispersion}

% reference/000336.html

\index{photons! dispersion}\index{dispersion! photons}

   When dispersion is specified for interior of a transparent object, photons will make use of that and show "colored" caustics. 


\subsubsection{Saving and Loading Photon Maps}

% reference/000337.html



   It is possible to save and load photon maps to speed up rendering. The photon map itself is view-\discretionary{}{}{}independent, so if you want to animate a scene that contains 
 photons and you know the photon map will not change during the animation, you can save it on the first frame and then load it for all subsequent frames. 



   To save the photon map, put the line 


{\small\begin{verbatim}
 save_file "myfile.ph"
\end{verbatim}}


   into the {\small\texttt{photons \{ \}}} block inside the {\small\texttt{global\_\-settings}} section. 



   Loading the photon map is the same, but with {\small\texttt{load\_\-file}} instead of {\small\texttt{save\_\-file}}. You cannot both load and save a photon map in 
 the POV file. If you load the photon map, it will load all of the photons. No photons will be shot if the map is loaded from a file. All other options (such 
 as gather radius) must still be specified in the POV scene file and are not loaded with the photon map. 



   When can you safely re-\discretionary{}{}{}use a saved photon map? 


\begin{itemize}
 
 \item 
   Moving the camera is \textit{always} safe. 
 

 \item 
   Moving lights that do not cast photons is \textit{always} safe. 
 

 \item 
   Moving objects that do not have photons shot at them, that do not receive photons, and would not receive photons in the new location is \textit{always} 
  safe. 
 

 \item 
   Moving an object that recieves photons to a new location where it does not receive photons is \textit{sometimes} safe. 
 

 \item 
   Moving an object to a location where it recieves photons is \textit{not} safe 
 

 \item 
   Moving an object that has photons shot at it is \textit{not} safe 
 

 \item 
   Moving a light that casts photons is \textit{not} safe. 
 

 \item 
   Changing the texture of an object that recieves photons is safe. 
 

 \item 
   Changing the texture of an object that has photons shot at it produces results that are not realistic, but can be useful sometimes. 
 

\end{itemize}


   In general, changes to the scene geometry require photons to be re-\discretionary{}{}{}shot. Changing the camera parameters or changing the image resolution does not. 


\clearpage \chapter{Include Files}

% reference/000182.html

\index{include! standard files}

   The "Standard Include File" section describes the include files that can be found in every standard distribution of POV-\discretionary{}{}{}Ray. It is supposed to be 
 used as a reference for looking up things. It does not contain detailed explanations on how scenes are written or how POV-\discretionary{}{}{}Ray is used. It just explains all 
 features, their syntax, applications, limits, drawbacks, etc. 


\section{\discretionary{arrays.}{}{arrays.}inc}

% reference/000338.html



   This file contains macros for manipulating arrays.\index{Rand\_\-Array\_\-Item} 



   {\small\texttt{Rand\_\-Array\_\-Item(Array, Stream)}}. Randomly Picks an item from a 1D array.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array from which to choose the item. 
 

 \item 
   {\small\texttt{Stream}} = A random number stream. 
 

\end{itemize}
\index{Resize\_\-Array}

   {\small\texttt{Resize\_\-Array(Array, NewSize)}}. Resize a 1D array, retaining its contents.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array to be resized. 
 

 \item 
   {\small\texttt{NewSize}} = The desired new size of the array. 
 

\end{itemize}
\index{Reverse\_\-Array}

   {\small\texttt{Reverse\_\-Array(Array)}}. Reverses the order of items in a 1D array.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array to be reversed. 
 

\end{itemize}
\index{Sort\_\-Compare}

   {\small\texttt{Sort\_\-Compare(Array, IdxA, IdxB)}}. This macro is used by the {\small\texttt{Sort\_\-Array()}} and {\small\texttt{Sort\_\-Partial\_\-Array()}} macros. 
 The given macro works for 1D arrays of floats, but you can redefine it in your scene file for more complex situations, arrays of vectors or multidimensional 
 arrays for example. Just make sure your macro returns true if the item at IdxA $<$ the item at IdxB, and otherwise returns false.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array containing the data being sorted. 
 

 \item 
   {\small\texttt{IdxA, IdxB}} = The array offsets of the data elements being compared. 
 

\end{itemize}
\index{Sort\_\-Swap\_\-Data}

   {\small\texttt{Sort\_\-Swap\_\-Data(Array, IdxA, IdxB)}}. This macro is used by the {\small\texttt{Sort\_\-Array()}} and {\small\texttt{Sort\_\-Partial\_\-Array()}} macros. 
 The given macro works for 1D arrays only, but you can redefine it in your scene file to handle multidimensional arrays if needed. The only requirement is that 
 your macro swaps the data at IdxA with that at IdxB.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array containing the data being sorted. 
 

 \item 
   {\small\texttt{IdxA, IdxB}} = The array offsets of the data elements being swapped. 
 

\end{itemize}
\index{Sort\_\-Array}

   {\small\texttt{Sort\_\-Array(Array)}}. This macro sorts a 1D array of floats, though you can redefine the {\small\texttt{Sort\_\-Compare()}} and {\small\texttt{Sort\_\-Swap\_\-Data()}} 
 macros to handle multidimensional arrays and other data types.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array to be sorted. 
 

\end{itemize}
\index{Sort\_\-Partial\_\-Array}

   {\small\texttt{Sort\_\-Partial\_\-Array(Array, FirstInd, LastInd)}}. This macro is like {\small\texttt{Sort\_\-Array()}}, but sorts a specific range of an array 
 instead of the whole array.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Array}} = The array to be sorted. 
 

 \item 
   {\small\texttt{FirstInd, LastInd}} = The start and end indices of the range being sorted. 
 

\end{itemize}

\section{\discretionary{chars.}{}{chars.}inc}

% reference/000345.html



   This file includes 26 upper-\discretionary{}{}{}case letter and other characters defined as objects. The size of all characters is 4 * 5 * 1. The center of the bottom side of a 
 character face is set to the origin, so you may need to translate a character appropriately before rotating it about the x or z axes. 



   Letters:\newline  {\small\texttt{ char\_\-A, char\_\-B, char\_\-C,\newline  char\_\-D, char\_\-E, char\_\-F,\newline  char\_\-G, char\_\-H, char\_\-I,\newline  char\_\-J, char\_\-K, char\_\-L,\newline  
 char\_\-M, char\_\-N, char\_\-O,\newline  char\_\-P, char\_\-Q, char\_\-R,\newline  char\_\-S, char\_\-T, char\_\-U,\newline  char\_\-V, char\_\-W, char\_\-X,\newline  char\_\-Y, char\_\-Z\newline  }} 
 



   Numerals:\newline  {\small\texttt{ char\_\-0, char\_\-1,\newline  char\_\-2, char\_\-3,\newline  char\_\-4, char\_\-5,\newline  char\_\-6, char\_\-7,\newline  char\_\-8, char\_\-9\newline  
 }} 



   Symbols:\newline  {\small\texttt{ char\_\-Dash, char\_\-Plus, char\_\-ExclPt,\newline  char\_\-Amps, char\_\-Num, char\_\-Dol,\newline  char\_\-Perc, char\_\-Astr, char\_\-Hat, \newline  
 char\_\-LPar, char\_\-RPar, char\_\-AtSign,\newline  char\_\-LSqu, char\_\-RSqu\newline  }} 



   Usage: 


{\small\begin{verbatim}
 #include "chars.inc"
 .
 .
 object {char_A ...}
\end{verbatim}}

\section{\discretionary{colors.}{}{colors.}inc}

% reference/000344.html



   This file is mainly a list of predefined colors, but also has a few color manipulation macros. 


\subsection{Predefined colors}

% reference/000343.html


\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/red} \newline Color Red 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/green} \newline Color Green 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/blue} \newline Color Blue } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/yellow} \newline Color Yellow 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/cyan} \newline Color Cyan 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/magenta} \newline Color Magenta } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/clear} \newline Color Clear 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/white} \newline Color White 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/black} \newline Color Black } \\ 
 

\end{tabular*} \caption{Primary colors} \end{table}

\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray05} \newline Color Gray05 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray10} \newline Color Gray10 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray15} \newline Color Gray15 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray20} \newline Color Gray20 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray25} \newline Color Gray25 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray30} \newline Color Gray30 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray35} \newline Color Gray35 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray40} \newline Color Gray40 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray45} \newline Color Gray45 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray50} \newline Color Gray50 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray55} \newline Color Gray55 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray60} \newline Color Gray60 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray65} \newline Color Gray65 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray70} \newline Color Gray70 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray75} \newline Color Gray75 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray80} \newline Color Gray80 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray85} \newline Color Gray85 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray90} \newline Color Gray90 } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray95} \newline Color Gray95 
  } & 

  {\centering 
    
  } & 
{\centering  } \\ 
 

\end{tabular*} \caption{Shades of gray...from 5\% to 95\%, in 5\% increments} \end{table}

\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/dimgray} \newline Color DimGray 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gray} \newline Color Gray 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/lightgray} \newline Color LightGray } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/vlightgray} \newline Color VLightGray 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/aquamarine} \newline Color Aquamarine 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/blueviolet} \newline Color BlueViolet } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/brown} \newline Color Brown 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/cadetblue} \newline Color CadetBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/coral} \newline Color Coral } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/cornflowerblue} \newline Color CornflowerBlue 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkgreen} \newline Color DarkGreen 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkolivegreen} \newline Color DarkOliveGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkorchid} \newline Color DarkOrchid 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkslateblue} \newline Color DarkSlateBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkslategray} \newline Color DarkSlateGray } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkturquoise} \newline Color DarkTurquoise 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/firebrick} \newline Color Firebrick 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/forestgreen} \newline Color ForestGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/gold} \newline Color Gold 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/goldenrod} \newline Color Goldenrod 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/greenyellow} \newline Color GreenYellow } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/indianred} \newline Color IndianRed 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/khaki} \newline Color Khaki 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/lightblue} \newline Color LightBlue } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/lightsteelblue} \newline Color LightSteelBlue 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/limegreen} \newline Color LimeGreen 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/maroon} \newline Color Maroon } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumaquamarine} \newline Color MediumAquamarine 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumblue} \newline Color MediumBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumforestgreen} \newline Color MediumForestGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumgoldenrod} \newline Color MediumGoldenrod 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumorchid} \newline Color MediumOrchid 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumseagreen} \newline Color MediumSeaGreen } \\ 
 

\end{tabular*} \caption{Misc. colors - plate 1} \end{table}

\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumslateblue} \newline Color MediumSlateBlue 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumspringgreen} \newline Color MediumSpringGreen 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumturquoise} \newline Color MediumTurquoise } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumvioletred} \newline Color MediumVioletRed 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/midnightblue} \newline Color MidnightBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/navy} \newline Color Navy } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/navyblue} \newline Color NavyBlue 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/orange} \newline Color Orange 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/orangered} \newline Color OrangeRed } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/orchid} \newline Color Orchid 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/palegreen} \newline Color PaleGreen 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/pink} \newline Color Pink } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/plum} \newline Color Plum 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/salmon} \newline Color Salmon 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/seagreen} \newline Color SeaGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/sienna} \newline Color Sienna 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/skyblue} \newline Color SkyBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/slateblue} \newline Color SlateBlue } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/springgreen} \newline Color SpringGreen 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/steelblue} \newline Color SteelBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/tan} \newline Color Tan } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/thistle} \newline Color Thistle 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/turquoise} \newline Color Turquoise 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/violet} \newline Color Violet } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/violetred} \newline Color VioletRed 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/wheat} \newline Color Wheat 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/yellowgreen} \newline Color YellowGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/summersky} \newline Color SummerSky 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/richblue} \newline Color RichBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/brass} \newline Color Brass } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/copper} \newline Color Copper 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/bronze} \newline Color Bronze 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/bronze2} \newline Color Bronze2 } \\ 
 

\end{tabular*} \caption{Misc. colors - plate 2} \end{table}

\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/silver} \newline Color Silver 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/brightgold} \newline Color BrightGold 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/oldgold} \newline Color OldGold } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/feldspar} \newline Color Feldspar 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/quartz} \newline Color Quartz 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mica} \newline Color Mica } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/neonpink} \newline Color NeonPink 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkpurple} \newline Color DarkPurple 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/neonblue} \newline Color NeonBlue } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/coolcopper} \newline Color CoolCopper 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mandarinorange} \newline Color MandarinOrange 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/lightwood} \newline Color LightWood } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/mediumwood} \newline Color MediumWood 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkwood} \newline Color DarkWood 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/spicypink} \newline Color SpicyPink } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/semisweetchoc} \newline Color SemiSweetChoc 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/bakerschoc} \newline Color BakersChoc 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/flesh} \newline Color Flesh } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/newtan} \newline Color NewTan 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/newmidnightblue} \newline Color NewMidnightBlue 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/verydarkbrown} \newline Color VeryDarkBrown } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darkbrown} \newline Color DarkBrown 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/darktan} \newline Color DarkTan 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/greencopper} \newline Color GreenCopper } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/dkgreencopper} \newline Color DkGreenCopper 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/dustyrose} \newline Color DustyRose 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/huntersgreen} \newline Color HuntersGreen } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/scarlet} \newline Color Scarlet 
  } & 

  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/med_purple} \newline Color Med\_\-Purple 
  } & 
{\centering  \includegraphics[scale=0.40]{../final/tex/images/reference/colors/light_purple} \newline Color Light\_\-Purple } \\ 
 

 
  
  {\centering 
    \includegraphics[scale=0.40]{../final/tex/images/reference/colors/very_light_purple} \newline Color Very\_\-Light\_\-Purple 
  } & 

  {\centering 
    
  } & 
{\centering  } \\ 
 

\end{tabular*} \caption{Misc. colors - plate 3} \end{table}

\subsection{Color macros}

% reference/000373.html



   In POV-\discretionary{}{}{}Ray all colors are handled in RGB color space with a component for the amount of red, green and blue light. However, not everybody thinks this is the 
 most intuitive way to specify colors. For your convenience there are macros included in \discretionary{colors.}{}{colors.}inc that converts between a few different types of color spaces.\newline  
 The three supported color spaces: 


\begin{itemize}
 
 \item 
   {\small\texttt{RGB}} = $<$ Red, Green, Blue, Filter, Transmit $>$ 
 

 \item 
   {\small\texttt{HSL}} = $<$ Hue, Saturation, Lightness, Filter, Transmit $>$ 
 

 \item 
   {\small\texttt{HSV}} = $<$ Hue, Saturation, Value, Filter, Transmit $>$ 
 

\end{itemize}
\index{CHSL2RGB}

   {\small\texttt{CHSL2RGB(Color)}}. Converts a color given in {\small\texttt{HSL}} space to one in {\small\texttt{RGB}} space.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Color}} = {\small\texttt{HSL}} color to be converted. 
 

\end{itemize}
\index{CRGB2HSL}

   {\small\texttt{CRGB2HSL(Color)}}. Converts a color given in {\small\texttt{RGB}} space to one in {\small\texttt{HSL}} space.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Color}} = {\small\texttt{RGB}} color to be converted. 
 

\end{itemize}
\index{CHSV2RGB}

   {\small\texttt{CHSV2RGB(Color)}}. Converts a color given in {\small\texttt{HSV}} space to one in {\small\texttt{RGB}} space.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Color}} = {\small\texttt{HSV}} color to be converted. 
 

\end{itemize}
\index{CRGB2HSV}

   {\small\texttt{CRGB2HSV(Color)}}. Converts a color given in {\small\texttt{RGB}} space to one in {\small\texttt{HSV}} space.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Color}} = {\small\texttt{RGB}} color to be converted. 
 

\end{itemize}
\index{Convert\_\-Color}

   {\small\texttt{Convert\_\-Color(SourceType, DestType, Color)}}. Converts a color from one color space to another. Color spaces available are: {\small\texttt{RGB}}, 
 {\small\texttt{HSL}}, and {\small\texttt{HSV}}.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{SourceType}} = Color space of input color. 
 

 \item 
   {\small\texttt{DestType}} = Desired output color space. 
 

 \item 
   {\small\texttt{Color}} = Color to be converted, in SourceType color space. 
 

\end{itemize}

\section{\discretionary{consts.}{}{consts.}inc}

% reference/000342.html



   This file defines a number of constants, including things such as mapping types and ior definitions. 


\subsection{Vector constants}

% reference/000341.html


\begin{description}
 
 \item 
   {\small\texttt{o}} = $<$ 0, 0, 0$>$ (origin) 
 

 \item 
   {\small\texttt{xy}} = $<$ 1, 1, 0$>$ 
 

 \item 
   {\small\texttt{yz}} = $<$ 0, 1, 1$>$ 
 

 \item 
   {\small\texttt{xz}} = $<$ 1, 0, 1$>$ 
 

\end{description}

\subsection{Map type constants}

% reference/000380.html


\begin{description}
 
 \item 
   {\small\texttt{Plane\_\-Map}} = 0 
 

 \item 
   {\small\texttt{Sphere\_\-Map}} = 1 
 

 \item 
   {\small\texttt{Cylinder\_\-Map}} = 2 
 

 \item 
   {\small\texttt{Torus\_\-Map}} = 5 
 

\end{description}

\subsection{Interpolation type constants}

% reference/000379.html


\begin{description}
 
 \item 
   {\small\texttt{Bi}} = 2 
 

 \item 
   {\small\texttt{Norm}} = 4 
 

\end{description}

\subsection{Fog type constants}

% reference/000378.html


\begin{description}
 
 \item 
   {\small\texttt{Uniform\_\-Fog}} = 1 
 

 \item 
   {\small\texttt{Ground\_\-Fog}} = 2 
 

\end{description}

\subsection{Focal blur hexgrid constants}

% reference/000377.html


\begin{description}
 
 \item 
   {\small\texttt{Hex\_\-Blur1}} = 7 
 

 \item 
   {\small\texttt{Hex\_\-Blur2}} = 19 
 

 \item 
   {\small\texttt{Hex\_\-Blur3}} = 37 
 

\end{description}

\subsection{IORs}

% reference/000376.html


\begin{description}
 
 \item 
   {\small\texttt{Air\_\-Ior}} = 1.000292 
 

 \item 
   {\small\texttt{Amethyst\_\-Ior}} = 1.550 
 

 \item 
   {\small\texttt{Apatite\_\-Ior}} = 1.635 
 

 \item 
   {\small\texttt{Aquamarine\_\-Ior}} = 1.575 
 

 \item 
   {\small\texttt{Beryl\_\-Ior}} = 1.575 
 

 \item 
   {\small\texttt{Citrine\_\-Ior}} = 1.550 
 

 \item 
   {\small\texttt{Crown\_\-Glass\_\-Ior}} = 1.51 
 

 \item 
   {\small\texttt{Corundum\_\-Ior}} = 1.765 
 

 \item 
   {\small\texttt{Diamond\_\-Ior}} = 2.47 
 

 \item 
   {\small\texttt{Emerald\_\-Ior}} = 1.575 
 

 \item 
   {\small\texttt{Flint\_\-Glass\_\-Ior}} = 1.71 
 

 \item 
   {\small\texttt{Flint\_\-Glass\_\-Heavy\_\-Ior}} = 1.8 
 

 \item 
   {\small\texttt{Flint\_\-Glass\_\-Medium\_\-Ior}} = 1.63 
 

 \item 
   {\small\texttt{Flint\_\-Glass\_\-Light\_\-Ior}} = 1.6 
 

 \item 
   {\small\texttt{Fluorite\_\-Ior}} = 1.434 
 

 \item 
   {\small\texttt{Gypsum\_\-Ior}} = 1.525 
 

 \item 
   {\small\texttt{Ice\_\-Ior}} = 1.31 
 

 \item 
   {\small\texttt{Plexiglas\_\-Ior}} = 1.5 
 

 \item 
   {\small\texttt{Quartz\_\-Ior}} = 1.550 
 

 \item 
   {\small\texttt{Quartz\_\-Glass\_\-Ior }}= 1.458 
 

 \item 
   {\small\texttt{Ruby\_\-Ior}} = 1.765 
 

 \item 
   {\small\texttt{Salt\_\-Ior}} = 1.544 
 

 \item 
   {\small\texttt{Sapphire\_\-Ior}} = 1.765 
 

 \item 
   {\small\texttt{Topaz\_\-Ior}} = 1.620 
 

 \item 
   {\small\texttt{Tourmaline\_\-Ior}} = 1.650 
 

 \item 
   {\small\texttt{Water\_\-Ior}} = 1.33 
 

\end{description}

\subsection{Dispersion amounts}

% reference/000375.html


\begin{description}
 
 \item 
   {\small\texttt{Quartz\_\-Glass\_\-Dispersion}} = 1.012 
 

 \item 
   {\small\texttt{Water\_\-Dispersion}} = 1.007 
 

 \item 
   {\small\texttt{Diamond\_\-Dispersion}} = 1.035 
 

 \item 
   {\small\texttt{Sapphire\_\-Dispersion}} = 1.015 
 

\end{description}

\subsection{Scattering media type constants}

% reference/000374.html


\begin{description}
 
 \item 
   {\small\texttt{ISOTROPIC\_\-SCATTERING}} = 1; 
 

 \item 
   {\small\texttt{MIE\_\-HAZY\_\-SCATTERING}} = 2; 
 

 \item 
   {\small\texttt{MIE\_\-MURKY\_\-SCATTERING}} = 3; 
 

 \item 
   {\small\texttt{RAYLEIGH\_\-SCATTERING}} = 4; 
 

 \item 
   {\small\texttt{HENYEY\_\-GREENSTEIN\_\-SCATTERING}} = 5; 
 

\end{description}

\section{\discretionary{debug.}{}{debug.}inc}

% reference/000340.html



   This file contains a set of macros designed to make debugging easier. It also functions like the old \discretionary{debug.}{}{debug.}inc, with the exception that you have to call the 
 Debug\_\-Inc\_\-Stack() macro to get the include stack output. 



   {\small\texttt{Debug\_\-Inc\_\-Stack()}}. Activates include file tracking, each included file will send a debug message when it is included.\newline  Parameters: 
 None. 



   {\small\texttt{Set\_\-Debug(Bool)}}. Activate or deactivate the debugging macros.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Bool}} = A boolean (true/false) value. 
 

\end{itemize}


   {\small\texttt{Debug\_\-Message(Str)}}. If debugging, sends the message to the debug stream.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Str}} = The desired message. 
 

\end{itemize}
\index{debug! \discretionary{debug.}{}{debug.}inc}\index{warning! \discretionary{debug.}{}{debug.}inc}\index{error! \discretionary{debug.}{}{debug.}inc}

   {\small\texttt{Debug(Condition, Message)\newline  Warning(Condition, Message)\newline  Error(Condition, Message)}}\newline  These macros send a message to 
 the \#debug, \#warning, and \#error streams depending on a given condition. They are just a shortcut for an {\small\texttt{\#if()...\#end}} block, intended to make 
 scenes easier to read.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Condition}} = Any boolean expression. 
 

 \item 
   {\small\texttt{Message}} = The message to be sent if Condition evaluates as "true". 
 

\end{itemize}

\section{\discretionary{finish.}{}{finish.}inc}

% reference/000339.html



   This file contains some predefined finishes. 


\begin{description}
 
 \item 
   {\small\texttt{Dull}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dull, with a large, soft specular highlight. 
 \end{list}

 \item 
   {\small\texttt{Shiny}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Shiny, with a small, tight specular highlight. 
 \end{list}

 \item 
   {\small\texttt{Glossy}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very shiny with very tight specular highlights and a fair amount of reflection. 
 \end{list}

 \item 
   {\small\texttt{Phong\_\-Dull}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dull, with a large, soft phong highlight. 
 \end{list}

 \item 
   {\small\texttt{Phong\_\-Shiny}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Shiny, with a small, tight phong highlight. 
 \end{list}

 \item 
   {\small\texttt{Phong\_\-Glossy}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very shiny with very tight phong highlights and a fair amount of reflection. 
 \end{list}

 \item 
   {\small\texttt{Luminous}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A glowing surface, unaffected by light\_\-sources. 
 \end{list}

 \item 
   {\small\texttt{Mirror}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A perfectly reflective surface, no highlights or shading. 
 \end{list}

\end{description}

\section{\discretionary{functions.}{}{functions.}inc}

% reference/000346.html

\index{internal! \discretionary{functions.}{}{functions.}inc}

   This include file contains interfaces to internal functions as well as several predefined functions. The ID's used to access the internal functions through 
 calls to "internal(XX)", are not guaranteed to stay the same between POV-\discretionary{}{}{}Ray versions, so users are encouraged to use the functions declared here. 



   The number of required parameters and what they control are also given in the include file, this chapter gives more information. \newline For starter values 
 of the parameters, check the "i\_\discretionary{internal.}{}{internal.}pov" demo file. 



   Syntax to be used: 


{\small\begin{verbatim}  #include "functions.inc"
  isosurface {
    function { f_torus_gumdrop(x,y,z, P0) }
    ...
  }

  pigment {
    function { f_cross_ellipsoids(x,y,z, P0, P1, P2, P3) }
    COLOR_MAP ...
  )
\end{verbatim}}


   Some special parameters are found in several of these functions. These are described in the next section and later referred to as "Cross section 
 type", "Field Strength", "Field Limit", "SOR" parameters. 


\subsection{Common Parameters}

% reference/000347.html



   \textbf{Cross Section Type:}\index{Cross Section Type} \newline In the helixes and spiral functions, the 9th parameter is the cross section type. \newline Some 
 shapes are: 


\begin{description}
 
 \item 
   {\small\texttt{0}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   square 
 \end{list}

 \item 
   {\small\texttt{0.0 to 1.0}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   rounded squares 
 \end{list}

 \item 
   {\small\texttt{1}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   circle 
 \end{list}

 \item 
   {\small\texttt{1.0 to 2.0}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   rounded diamonds 
 \end{list}

 \item 
   {\small\texttt{2}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   diamond 
 \end{list}

 \item 
   {\small\texttt{2.0 to 3.0}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   partially concave diamonds 
 \end{list}

 \item 
   {\small\texttt{3}} : 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   concave diamond 
 \end{list}

\end{description}

\subsubsection{Field Strength}

% reference/000389.html



   The numerical value at a point in space generated by the function is multiplied by the Field Strength. The set of points where the function evaluates to zero 
 are unaffected by any positive value of this parameter, so if you are just using the function on its own with threshold = 0, the generated surface is still 
 the same. \newline In some cases, the field strength has a considerable effect on the speed and accuracy of rendering the surface. In general, increasing the 
 field strength speeds up the rendering, but if you set the value too high the surface starts to break up and may disappear completely. \newline Setting the 
 field strength to a negative value produces the inverse of the surface, like making the function negative. 


\subsubsection{Field Limit}

% reference/000388.html



   This will not make any difference to the generated surface if you are using threshold that is within the field limit (and will kill the surface completely if 
 the threshold is greater than the field limit). However, it may make a huge difference to the rendering times. \newline If you use the function to generate a 
 pigment, then all points that are a long way from the surface will have the same color, the color that corresponds to the numerical value of the field limit. 


\subsubsection{SOR Switch}

% reference/000387.html



   If greater than zero, the curve is swept out as a surface of revolution (SOR). \newline If the value is zero or negative, the curve is extruded linearly in 
 the Z direction.\newline  


\subsubsection{SOR Offset}

% reference/000386.html



   If the SOR switch is on, then the curve is shifted this distance in the X direction before being swept out. 


\subsubsection{SOR Angle}

% reference/000385.html



   If the SOR switch is on, then the curve is rotated this number of degrees about the Z axis before being swept out. 


\subsubsection{Invert Isosurface}

% reference/000384.html



   Sometimes, when you render a surface, you may find that you get only the shape of the container. This could be caused by the fact that some of the build in 
 functions are defined inside out. \newline We can invert the isosurface by negating the whole function: \newline {\small\texttt{  -(function) - 
 threshold}} 


\subsection{Internal Functions}

% reference/000383.html



   Here is a list of the internal functions in the order they appear in the "\discretionary{functions.}{}{functions.}inc" include file\index{f\_\-algbr\_\-cyl1} 



   {\small\texttt{f\_\-algbr\_\-cyl1(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. An algebraic cylinder is what you get if you take any 2d curve and plot it in 3d. The 2d curve is 
 simply extruded along the third axis, in this case the z axis. \newline With the SOR Switch switched on, the figure-\discretionary{}{}{}of-\discretionary{}{}{}eight curve will be rotated around the 
 Y axis instead of being extruded along the Z axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength 
 

 \item 
   {\small\texttt{P1}} : Field Limit 
 

 \item 
   {\small\texttt{P2}} : SOR Switch 
 

 \item 
   {\small\texttt{P3}} : SOR Offset 
 

 \item 
   {\small\texttt{P4}} : SOR Angle 
 

\end{itemize}
\index{f\_\-algbr\_\-cyl2}

   {\small\texttt{f\_\-algbr\_\-cyl2(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. An algebraic cylinder is what you get if you take any 2d curve and plot it in 3d. The 2d curve is 
 simply extruded along the third axis, in this case the z axis. \newline With the SOR Switch switched on, the cross section curve will be rotated around the Y 
 axis instead of being extruded along the Z axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Field Limit 
 

 \item 
   {\small\texttt{P2}} : SOR Switch 
 

 \item 
   {\small\texttt{P3}} : SOR Offset 
 

 \item 
   {\small\texttt{P4}} : SOR Angle 
 

\end{itemize}
\index{f\_\-algbr\_\-cyl3}

   {\small\texttt{f\_\-algbr\_\-cyl3(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. An algebraic cylinder is what you get if you take any 2d curve and plot it in 3d. The 2d curve is 
 simply extruded along the third axis, in this case the Z axis. \newline With the SOR Switch switched on, the cross section curve will be rotated around the Y 
 axis instead of being extruded along the Z axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Field Limit 
 

 \item 
   {\small\texttt{P2}} : SOR Switch 
 

 \item 
   {\small\texttt{P3}} : SOR Offset 
 

 \item 
   {\small\texttt{P4}} : SOR Angle 
 

\end{itemize}
\index{f\_\-algbr\_\-cyl4}

   {\small\texttt{f\_\-algbr\_\-cyl4(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. An algebraic cylinder is what you get if you take any 2d curve and plot it in 3d. The 2d curve is 
 simply extruded along the third axis, in this case the z axis. \newline With the SOR Switch switched on, the cross section curve will be rotated around the Y 
 axis instead of being extruded along the Z axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Field Limit 
 

 \item 
   {\small\texttt{P2}} : SOR Switch 
 

 \item 
   {\small\texttt{P3}} : SOR Offset 
 

 \item 
   {\small\texttt{P4}} : SOR Angle 
 

\end{itemize}
\index{f\_\-bicorn}

   {\small\texttt{f\_\-bicorn(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1)}}. The surface is a surface of revolution. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Scale. The mathematics of this surface suggest that the shape should be different for different values of this parameter. In 
  practice the difference in shape is hard to spot. Setting the scale to 3 gives a surface with a radius of about 1 unit 
 

\end{itemize}
\index{f\_\-bifolia}

   {\small\texttt{f\_\-bifolia(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1)}}. The bifolia surface looks something like the top part of a a paraboloid bounded below by another paraboloid. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Scale. The surface is always the same shape. Changing this parameter has the same effect as adding a scale modifier. Setting the 
  scale to 1 gives a surface with a radius of about 1 unit 
 

\end{itemize}
\index{f\_\-blob}

   {\small\texttt{f\_\-blob(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. This function generates blobs that are similar to a CSG blob with two spherical components. This function 
 only seems to work with negative threshold settings. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : X distance between the two components 
 

 \item 
   {\small\texttt{P1}} : Blob strength of component 1 
 

 \item 
   {\small\texttt{P2}} : Inverse blob radius of component 1 
 

 \item 
   {\small\texttt{P3}} : Blob strength of component 2 
 

 \item 
   {\small\texttt{P4}} : Inverse blob radius of component 2 
 

\end{itemize}
\index{f\_\-blob2}

   {\small\texttt{f\_\-blob2(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The surface is similar to a CSG blob with two spherical components. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Separation. One blob component is at the origin, and the other is this distance away on the X axis 
 

 \item 
   {\small\texttt{P1}} : Inverse size. Increase this to decrease the size of the surface 
 

 \item 
   {\small\texttt{P2}} : Blob strength 
 

 \item 
   {\small\texttt{P3}} : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same effect as setting this parameter to zero 
  and the threshold to -1 
 

\end{itemize}
\index{f\_\-boy\_\-surface}

   {\small\texttt{f\_\-boy\_\-surface(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1)}}. For this surface, it helps if the field strength is set low, otherwise the surface has a tendency to break up 
 or disappear entirely. This has the side effect of making the rendering times extremely long. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Scale. The surface is always the same shape. Changing this parameter has the same effect as adding a scale modifier 
 

\end{itemize}
\index{f\_\-comma}

   {\small\texttt{f\_\-comma(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The 'comma' surface is very much like a comma-\discretionary{}{}{}shape. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Scale 
 

\end{itemize}
\index{f\_\-cross\_\-ellipsoids}

   {\small\texttt{f\_\-cross\_\-ellipsoids(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The 'cross ellipsoids' surface is like the union of three crossed ellipsoids, one oriented along 
 each axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Eccentricity. When less than 1, the ellipsoids are oblate, when greater than 1 the ellipsoids are prolate, when zero the 
  ellipsoids are spherical (and hence the whole surface is a sphere) 
 

 \item 
   {\small\texttt{P1}} : Inverse size. Increase this to decrease the size of the surface 
 

 \item 
   {\small\texttt{P2}} : Diameter. Increase this to increase the size of the ellipsoids 
 

 \item 
   {\small\texttt{P3}} : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same effect as setting this parameter to zero 
  and the threshold to -1 
 

\end{itemize}
\index{f\_\-crossed\_\-trough}

   {\small\texttt{f\_\-crossed\_\-trough(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-cubic\_\-saddle}

   {\small\texttt{f\_\-cubic\_\-saddle(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. For this surface, it helps if the field strength is set quite low, otherwise the surface has a tendency to break 
 up or disappear entirely. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-cushion}

   {\small\texttt{f\_\-cushion(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-devils\_\-curve}

   {\small\texttt{f\_\-devils\_\-curve(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-devils\_\-curve\_\-2d}

   {\small\texttt{f\_\-devils\_\-curve\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The {\small\texttt{f\_\-devils\_\-curve\_\-2d}} curve can be extruded along the z axis, or using 
 the SOR parameters it can be made into a surface of revolution. The X and Y factors control the size of the central feature. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : X factor 
 

 \item 
   {\small\texttt{P2}} : Y factor 
 

 \item 
   {\small\texttt{P3}} : SOR Switch 
 

 \item 
   {\small\texttt{P4}} : SOR Offset 
 

 \item 
   {\small\texttt{P5}} : SOR Angle 
 

\end{itemize}
\index{f\_\-dupin\_\-cyclid}

   {\small\texttt{f\_\-dupin\_\-cyclid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Major radius of torus 
 

 \item 
   {\small\texttt{P2}} : Minor radius of torus 
 

 \item 
   {\small\texttt{P3}} : X displacement of torus 
 

 \item 
   {\small\texttt{P4}} : Y displacement of torus 
 

 \item 
   {\small\texttt{P5}} : Radius of inversion 
 

\end{itemize}
\index{f\_\-ellipsoid}

   {\small\texttt{f\_\-ellipsoid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}}. {\small\texttt{f\_\-ellipsoid}} generates spheres and ellipsoids. Needs "threshold 1".\newline Setting 
 these scaling parameters to 1/n gives exactly the same effect as performing a scale operation to increase the scaling by n in the corresponding direction. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : X scale (inverse) 
 

 \item 
   {\small\texttt{P1}} : Y scale (inverse) 
 

 \item 
   {\small\texttt{P2}} : Z scale (inverse) 
 

\end{itemize}
\index{f\_\-enneper}

   {\small\texttt{f\_\-enneper(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-flange\_\-cover}

   {\small\texttt{f\_\-flange\_\-cover(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Spikiness. Set this to very low values to increase the spikes. Set it to 1 and you get a sphere 
 

 \item 
   {\small\texttt{P1}} : Inverse size. Increase this to decrease the size of the surface. (The other parameters also drastically affect the size, but this 
  parameter has no other effects) 
 

 \item 
   {\small\texttt{P2}} : Flange. Increase this to increase the flanges that appear between the spikes. Set it to 1 for no flanges 
 

 \item 
   {\small\texttt{P3}} : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same effect as setting this parameter to zero 
  and the threshold to -1 
 

\end{itemize}
\index{f\_\-folium\_\-surface}

   {\small\texttt{f\_\-folium\_\-surface(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}}. A 'folium surface' looks something like a paraboloid glued to a plane. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Neck width factor - the larger you set this, the narrower the neck where the paraboloid meets the plane 
 

 \item 
   {\small\texttt{P2}} : Divergence - the higher you set this value, the wider the paraboloid gets 
 

\end{itemize}
\index{f\_\-folium\_\-surface\_\-2d}

   {\small\texttt{f\_\-folium\_\-surface\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The {\small\texttt{f\_\-folium\_\-surface\_\-2d}} curve can be rotated around the X axis to 
 generate the same 3d surface as the {\small\texttt{f\_\-folium\_\-surface}}, or it can be extruded in the Z direction (by switching the SOR switch off) 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Neck width factor - same as the 3d surface if you are revolving it around the Y axis 
 

 \item 
   {\small\texttt{P2}} : Divergence - same as the 3d surface if you are revolving it around the Y axis 
 

 \item 
   {\small\texttt{P3}} : SOR Switch 
 

 \item 
   {\small\texttt{P4}} : SOR Offset 
 

 \item 
   {\small\texttt{P5}} : SOR Angle 
 

\end{itemize}
\index{f\_\-glob}

   {\small\texttt{f\_\-glob(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. One part of this surface would actually go off to infinity if it were not restricted by the contained\_\-by shape. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-heart}

   {\small\texttt{f\_\-heart(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-helical\_\-torus}

   {\small\texttt{f\_\-helical\_\-torus(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9)}}. With some sets of parameters, it looks like a torus with a helical winding 
 around it. The winding optionally has grooves around the outside. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Major radius 
 

 \item 
   {\small\texttt{P1}} : Number of winding loops 
 

 \item 
   {\small\texttt{P2}} : Twistiness of winding. When zero, each winding loop is separate. When set to one, each loop twists into the next one. When set to 
  two, each loop twists into the one after next 
 

 \item 
   {\small\texttt{P3}} : Fatness of winding? 
 

 \item 
   {\small\texttt{P4}} : Threshold. Setting this parameter to 1 and the threshold to zero has s similar effect as setting this parameter to zero and the 
  threshold to 1 
 

 \item 
   {\small\texttt{P5}} : Negative minor radius? Reducing this parameter increases the minor radius of the central torus. Increasing it can make the torus 
  disappear and be replaced by a vertical column. The value at which the surface switches from one form to the other depends on several other parameters 
 

 \item 
   {\small\texttt{P6}} : Another fatness of winding control? 
 

 \item 
   {\small\texttt{P7}} : Groove period. Increase this for more grooves 
 

 \item 
   {\small\texttt{P8}} : Groove amplitude. Increase this for deeper grooves 
 

 \item 
   {\small\texttt{P9}} : Groove phase. Set this to zero for symmetrical grooves 
 

\end{itemize}
\index{f\_\-helix1}

   {\small\texttt{f\_\-helix1(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5, P6)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Number of helixes - \discretionary{e.}{}{e.}g. 2 for a double helix 
 

 \item 
   {\small\texttt{P1}} : Period - is related to the number of turns per unit length 
 

 \item 
   {\small\texttt{P2}} : Minor radius (major radius $>$ minor radius) 
 

 \item 
   {\small\texttt{P3}} : Major radius 
 

 \item 
   {\small\texttt{P4}} : Shape parameter. If this is greater than 1 then the tube becomes fatter in the y direction 
 

 \item 
   {\small\texttt{P5}} : Cross section type 
 

 \item 
   {\small\texttt{P6}} : Cross section rotation angle (degrees) 
 

\end{itemize}
\index{f\_\-helix2}

   {\small\texttt{f\_\-helix2(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5, P6)}}. Needs a negated function 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Not used 
 

 \item 
   {\small\texttt{P1}} : Period - is related to the number of turns per unit length 
 

 \item 
   {\small\texttt{P2}} : Minor radius (minor radius $>$ major radius) 
 

 \item 
   {\small\texttt{P3}} : Major radius 
 

 \item 
   {\small\texttt{P4}} : Not used 
 

 \item 
   {\small\texttt{P5}} : Cross section type 
 

 \item 
   {\small\texttt{P6}} : Cross section rotation angle (degrees) 
 

\end{itemize}
\index{f\_\-hex\_\-x}

   {\small\texttt{f\_\-hex\_\-x(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. This creates a grid of hexagonal cylinders stretching along the z-\discretionary{}{}{}axis. The fatness is controlled by the threshold 
 value. When this value equals 0.8660254 or cos(30) the sides will touch, because this is the distance between centers. Negating the function will inverse the 
 surface and create a honey-\discretionary{}{}{}comb structure. This function is also useful as pigment function. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : No effect (but the syntax requires at least one parameter) 
 

\end{itemize}
\index{f\_\-hex\_\-y}

   {\small\texttt{f\_\-hex\_\-y(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. This is function forms a lattice of infinite boxes stretching along the z-\discretionary{}{}{}axis. The fatness is controlled by the 
 threshold value. These boxes are rotated 60 degrees around centers, which are 0.8660254 or cos(30) away from each other. This function is also useful as 
 pigment function. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : No effect (but the syntax requires at least one parameter) 
 

\end{itemize}
\index{f\_\-hetero\_\-mf}

   {\small\texttt{f\_\-hetero\_\-mf(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. {\small\texttt{f\_\-hetero\_\-mf (\discretionary{x,}{}{x,}\discretionary{0,}{}{0,}z)}} makes multifractal height fields and patterns of '1/f' 
 noise \newline 'Multifractal' refers to their characteristic of having a fractal dimension which varies with altitude. Built from summing noise of a number of 
 frequencies, the hetero\_\-mf parameters determine how many, and which frequencies are to be summed. \newline An advantage to using these instead of a 
 height\_\-field \{\} from an image (a number of height field programs output multifractal types of images) is that the hetero\_\-mf function domain extends 
 arbitrarily far in the x and z directions so huge landscapes can be made without losing resolution or having to tile a height field. Other functions of 
 interest are {\small\texttt{f\_\-ridged\_\-mf}} and {\small\texttt{f\_\-ridge}}. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : H is the negative of the exponent of the basis noise frequencies used in building these functions (each frequency f's amplitude 
  is weighted by the factor f - H ). In landscapes, and many natural forms, the amplitude of high frequency contributions are usually less than the lower 
  frequencies. \newline When H is 1, the fractalization is relatively smooth ("1/f noise"). \newline As H nears 0, the high frequencies contribute 
  equally with low frequencies as in "white noise". 
 

 \item 
   {\small\texttt{P1}} : Lacunarity' is the multiplier used to get from one 'octave' to the next. This parameter affects the size of the frequency gaps in 
  the pattern. Make this greater than 1.0 
 

 \item 
   {\small\texttt{P2}} : Octaves is the number of different frequencies added to the fractal. Each 'Octave' frequency is the previous one multiplied by 
  'Lacunarity', so that using a large number of octaves can get into very high frequencies very quickly. 
 

 \item 
   {\small\texttt{P3}} : Offset is the 'base altitude' (sea level) used for the heterogeneous scaling 
 

 \item 
   {\small\texttt{P4}} : T scales the 'heterogeneity' of the fractal. T=0 gives 'straight 1/f' (no heterogeneous scaling). T=1 suppresses higher 
  frequencies at lower altitudes 
 

 \item 
   {\small\texttt{P5}} : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values. 
 

\end{itemize}
\index{f\_\-hunt\_\-surface}

   {\small\texttt{f\_\-hunt\_\-surface(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-hyperbolic\_\-torus}

   {\small\texttt{f\_\-hyperbolic\_\-torus(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Major radius: separation between the centers of the tubes at the closest point 
 

 \item 
   {\small\texttt{P2}} : Minor radius: thickness of the tubes at the closest point 
 

\end{itemize}
\index{f\_\-isect\_\-ellipsoids}

   {\small\texttt{f\_\-isect\_\-ellipsoids(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The 'isect ellipsoids' surface is like the intersection of three crossed ellipsoids, one oriented 
 along each axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Eccentricity. When less than 1, the ellipsoids are oblate, when greater than 1 the ellipsoids are prolate, when zero the 
  ellipsoids are spherical (and hence the whole surface is a sphere) 
 

 \item 
   {\small\texttt{P1}} : Inverse size. Increase this to decrease the size of the surface 
 

 \item 
   {\small\texttt{P2}} : Diameter. Increase this to increase the size of the ellipsoids 
 

 \item 
   {\small\texttt{P3}} : Threshold. Setting this parameter to 1 and the threshold to zero has exactly the same effect as setting this parameter to zero 
  and the threshold to -1 
 

\end{itemize}
\index{f\_\-kampyle\_\-of\_\-eudoxus}

   {\small\texttt{f\_\-kampyle\_\-of\_\-eudoxus(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}}. The 'kampyle of eudoxus' is like two infinite planes with a dimple at the center. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Dimple: When zero, the two dimples punch right through and meet at the center. Non-\discretionary{}{}{}zero values give less dimpling 
 

 \item 
   {\small\texttt{P2}} : Closeness: Higher values make the two planes become closer 
 

\end{itemize}
\index{f\_\-kampyle\_\-of\_\-eudoxus\_\-2d}

   {\small\texttt{f\_\-kampyle\_\-of\_\-eudoxus\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}The 2d curve that generates the above surface can be extruded in the Z direction or 
 rotated about various axes by using the SOR parameters. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Dimple: When zero, the two dimples punch right through and meet at the center. Non-\discretionary{}{}{}zero values give less dimpling 
 

 \item 
   {\small\texttt{P2}} : Closeness: Higher values make the two planes become closer 
 

 \item 
   {\small\texttt{P3}} : SOR Switch 
 

 \item 
   {\small\texttt{P4}} : SOR Offset 
 

 \item 
   {\small\texttt{P5}} : SOR Angle 
 

\end{itemize}
\index{f\_\-klein\_\-bottle}

   {\small\texttt{f\_\-klein\_\-bottle(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-kummer\_\-surface\_\-v1}

   {\small\texttt{f\_\-kummer\_\-surface\_\-v1(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The Kummer surface consists of a collection of radiating rods. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-kummer\_\-surface\_\-v2}

   {\small\texttt{f\_\-kummer\_\-surface\_\-v2(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. Version 2 of the kummer surface only looks like radiating rods when the parameters are set to 
 particular negative values. For positive values it tends to look rather like a superellipsoid. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Rod width (negative): Setting this parameter to larger negative values increases the diameter of the rods 
 

 \item 
   {\small\texttt{P2}} : Divergence (negative): Setting this number to -1 causes the rods to become approximately cylindrical. Larger negative values 
  cause the rods to become fatter further from the origin. Smaller negative numbers cause the rods to become narrower away from the origin, and have a finite 
  length 
 

 \item 
   {\small\texttt{P3}} : Influences the length of half of the rods. Changing the sign affects the other half of the rods. 0 has no effect 
 

\end{itemize}
\index{f\_\-lemniscate\_\-of\_\-gerono}

   {\small\texttt{f\_\-lemniscate\_\-of\_\-gerono(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The "Lemniscate of Gerono" surface is an hourglass shape. Two teardrops with their ends 
 connected. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-lemniscate\_\-of\_\-gerono\_\-2d}

   {\small\texttt{f\_\-lemniscate\_\-of\_\-gerono\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The 2d version of the Lemniscate can be extruded in the Z direction, or used as a 
 surface of revolution to generate the equivalent of the 3d version, or revolved in different ways. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Size: increasing this makes the 2d curve larger and less rounded 
 

 \item 
   {\small\texttt{P2}} : Width: increasing this makes the 2d curve fatter 
 

 \item 
   {\small\texttt{P3}} : SOR Switch 
 

 \item 
   {\small\texttt{P4}} : SOR Offset 
 

 \item 
   {\small\texttt{P5}} : SOR Angle 
 

\end{itemize}
\index{f\_\-mesh1}

   {\small\texttt{f\_\-mesh1(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}} The overall thickness of the threads is controlled by the isosurface threshold, not by a parameter. If 
 you render a mesh1 with zero threshold, the threads have zero thickness and are therefore invisible. Parameters P2 and P4 control the shape of the thread 
 relative to this threshold parameter. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Distance between neighboring threads in the x direction 
 

 \item 
   {\small\texttt{P1}} : Distance between neighboring threads in the z direction 
 

 \item 
   {\small\texttt{P2}} : Relative thickness in the x and z directions 
 

 \item 
   {\small\texttt{P3}} : Amplitude of the weaving effect. Set to zero for a flat grid 
 

 \item 
   {\small\texttt{P4}} : Relative thickness in the y direction 
 

\end{itemize}
\index{f\_\-mitre}

   {\small\texttt{f\_\-mitre(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The 'Mitre' surface looks a bit like an ellipsoid which has been nipped at each end with a pair of sharp nosed pliers. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-nodal\_\-cubic}

   {\small\texttt{f\_\-nodal\_\-cubic(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The 'Nodal Cubic' is something like what you would get if you were to extrude the Stophid2D curve along the X axis 
 and then lean it over. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-noise3d}

   {\small\texttt{f\_\-noise3d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z)}}\index{f\_\-noise\_\-generator} 



   {\small\texttt{f\_\-noise\_\-generator(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Noise generator number 
 

\end{itemize}
\index{f\_\-odd}

   {\small\texttt{f\_\-odd(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-ovals\_\-of\_\-cassini}

   {\small\texttt{f\_\-ovals\_\-of\_\-cassini(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The Ovals of Cassini are a generalization of the torus shape. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Major radius - like the major radius of a torus 
 

 \item 
   {\small\texttt{P2}} : Filling. Set this to zero, and you get a torus. Set this to a higher value and the hole in the middle starts to heal up. Set it 
  even higher and you get an ellipsoid with a dimple 
 

 \item 
   {\small\texttt{P3}} : Thickness. The higher you set this value, the plumper is the result 
 

\end{itemize}
\index{f\_\-paraboloid}

   {\small\texttt{f\_\-paraboloid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. This paraboloid is the surface of revolution that you get if you rotate a parabola about the Y axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-parabolic\_\-torus}

   {\small\texttt{f\_\-parabolic\_\-torus(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Major radius 
 

 \item 
   {\small\texttt{P2}} : Minor radius 
 

\end{itemize}
\index{f\_\-ph}

   {\small\texttt{f\_\-ph(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z)}} = atan2( sqrt( x*x + z*z ), y ) \newline When used alone, the "PH" function gives a surface that consists of all 
 points that are at a particular latitude, \discretionary{i.}{}{i.}e. a cone. If you use a threshold of zero (the default) this gives a cone of width zero, which is invisible. Also 
 look at {\small\texttt{f\_\-th}} and {\small\texttt{f\_\-r}} \index{f\_\-pillow} 



   {\small\texttt{f\_\-pillow(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength 
 

\end{itemize}
\index{f\_\-piriform}

   {\small\texttt{f\_\-piriform(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The piriform surface looks rather like half a lemniscate. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength 
 

\end{itemize}
\index{f\_\-piriform\_\-2d}

   {\small\texttt{f\_\-piriform\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5, P6)}}. The 2d version of the "Piriform" can be extruded in the Z direction, or used as 
 a surface of revolution to generate the equivalent of the 3d version. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Size factor 1: increasing this makes the curve larger 
 

 \item 
   {\small\texttt{P2}} : Size factor 2: making this less negative makes the curve larger but also thinner 
 

 \item 
   {\small\texttt{P3}} : Fatness: increasing this makes the curve fatter 
 

 \item 
   {\small\texttt{P4}} : SOR Switch 
 

 \item 
   {\small\texttt{P5}} : SOR Offset 
 

 \item 
   {\small\texttt{P6}} : SOR Angle 
 

\end{itemize}
\index{f\_\-poly4}

   {\small\texttt{f\_\-poly4(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}}. This {\small\texttt{f\_\-poly4}} can be used to generate the surface of revolution of any polynomial up to 
 degree 4.\newline To put it another way: If we call the parameters A, B, C, D, E; then this function generates the surface of revolution formed by revolving 
 "x = A + By + Cy2 + Dy3 + Ey4" around the Y axis. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Constant 
 

 \item 
   {\small\texttt{P1}} : Y coefficient 
 

 \item 
   {\small\texttt{P2}} : Y2 coefficient 
 

 \item 
   {\small\texttt{P3}} : Y3 coefficient 
 

 \item 
   {\small\texttt{P4}} : Y4 coefficient 
 

\end{itemize}
\index{f\_\-polytubes}

   {\small\texttt{f\_\-polytubes(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The 'Polytubes' surface consists of a number of tubes. Each tube follows a 2d curve which is 
 specified by a polynomial of degree 4 or less. If we look at the parameters, then this function generates "P0" tubes which all follow the equation 
 " x = P1 + P2y + P3y2 + P4y3 + P5y4 " arranged around the Y axis. \newline This function needs a positive threshold (fatness of the tubes). 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Number of tubes 
 

 \item 
   {\small\texttt{P1}} : Constant 
 

 \item 
   {\small\texttt{P2}} : Y coefficient 
 

 \item 
   {\small\texttt{P3}} : Y2 coefficient 
 

 \item 
   {\small\texttt{P4}} : Y3 coefficient 
 

 \item 
   {\small\texttt{P5}} : Y4 coefficient 
 

\end{itemize}
\index{f\_\-quantum}

   {\small\texttt{f\_\-quantum(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. It resembles the shape of the electron density cloud for one of the d orbitals. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Not used, but required 
 

\end{itemize}
\index{f\_\-quartic\_\-paraboloid}

   {\small\texttt{f\_\-quartic\_\-paraboloid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The 'Quartic Paraboloid' is similar to a paraboloid, but has a squarer shape. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-quartic\_\-saddle}

   {\small\texttt{f\_\-quartic\_\-saddle(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The 'Quartic saddle' is similar to a saddle, but has a squarer shape. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength 
 

\end{itemize}
\index{f\_\-quartic\_\-cylinder}

   {\small\texttt{f\_\-quartic\_\-cylinder(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}}. The 'Quartic cylinder' looks a bit like a cylinder that is swallowed an egg. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Diameter of the "egg" 
 

 \item 
   {\small\texttt{P2}} : Controls the width of the tube and the vertical scale of the "egg" 
 

\end{itemize}
\index{f\_\-r}

   {\small\texttt{f\_\-r(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z)}} = sqrt( x*x + y*y + z*z ) \newline When used alone, the "R" function gives a surface that consists of all the points 
 that are a specific distance (threshold value) from the origin, \discretionary{i.}{}{i.}e. a sphere. Also look at {\small\texttt{f\_\-ph}} and {\small\texttt{f\_\-th}} \index{f\_\-ridge} 



   {\small\texttt{f\_\-ridge(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. This function is mainly intended for modifying other surfaces as you might use a height field or to 
 use as pigment function. Other functions of interest are {\small\texttt{f\_\-hetero\_\-mf}} and {\small\texttt{f\_\-ridged\_\-mf}}. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Lambda 
 

 \item 
   {\small\texttt{P1}} : Octaves 
 

 \item 
   {\small\texttt{P2}} : Omega 
 

 \item 
   {\small\texttt{P3}} : Offset 
 

 \item 
   {\small\texttt{P4}} : Ridge 
 

 \item 
   {\small\texttt{P5}} : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values. 
 

\end{itemize}
\index{f\_\-ridged\_\-mf}

   {\small\texttt{f\_\-ridged\_\-mf(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The "Ridged Multifractal" surface can be used to create multifractal height fields and 
 patterns. 'Multifractal' refers to their characteristic of having a fractal dimension which varies with altitude. They are built from summing noise of a 
 number of frequencies. The f\_\-ridged\_\-mf parameters determine how many, and which frequencies are to be summed, and how the different frequencies are weighted 
 in the sum. \newline An advantage to using these instead of a {\small\texttt{height\_\-field\{\}}} from an image is that the ridged\_\-mf function domain extends 
 arbitrarily far in the x and z directions so huge landscapes can be made without losing resolution or having to tile a height field. Other functions of 
 interest are {\small\texttt{f\_\-hetero\_\-mf}} and {\small\texttt{f\_\-ridge}}. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : H is the negative of the exponent of the basis noise frequencies used in building these functions (each frequency f's amplitude 
  is weighted by the factor fE- H ). When H is 1, the fractalization is relatively smooth. As H nears 0, the high frequencies contribute equally with low 
  frequencies 
 

 \item 
   {\small\texttt{P1}} : Lacunarity is the multiplier used to get from one "octave" to the next in the "fractalization". \newline This 
  parameter affects the size of the frequency gaps in the pattern. (Use values greater than 1.0) 
 

 \item 
   {\small\texttt{P2}} : Octaves is the number of different frequencies added to the fractal. Each octave frequency is the previous one multiplied by 
  "Lacunarity". So, using a large number of octaves can get into very high frequencies very quickly 
 

 \item 
   {\small\texttt{P3}} : Offset gives a fractal whose fractal dimension changes from altitude to altitude. The high frequencies at low altitudes are more 
  damped than at higher altitudes, so that lower altitudes are smoother than higher areas 
 

 \item 
   {\small\texttt{P4}} : Gain weights the successive contributions to the accumulated fractal result to make creases stick up as ridges 
 

 \item 
   {\small\texttt{P5}} : Generator type used to generate the noise3d. 0, 1, 2 and 3 are legal values. 
 

\end{itemize}
\index{f\_\-rounded\_\-box}

   {\small\texttt{f\_\-rounded\_\-box(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The Rounded Box is defined in a cube from $<$-1, -1, -1$>$ to $<$1, 1, 1$>$. By changing the 
 " Scale" parameters, the size can be adjusted, without affecting the Radius of curvature. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Radius of curvature. Zero gives square corners, 0.1 gives corners that match "sphere \{0, 0.1\}" 
 

 \item 
   {\small\texttt{P1}} : Scale x 
 

 \item 
   {\small\texttt{P2}} : Scale y 
 

 \item 
   {\small\texttt{P3}} : Scale z 
 

\end{itemize}
\index{f\_\-sphere}

   {\small\texttt{f\_\-sphere(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}}: radius of the sphere 
 

\end{itemize}
\index{f\_\-spikes}

   {\small\texttt{f\_\-spikes(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Spikiness. Set this to very low values to increase the spikes. Set it to 1 and you get a sphere 
 

 \item 
   {\small\texttt{P1}} : Hollowness. Increasing this causes the sides to bend in more 
 

 \item 
   {\small\texttt{P2}} : Size. Increasing this increases the size of the object 
 

 \item 
   {\small\texttt{P3}} : Roundness. This parameter has a subtle effect on the roundness of the spikes 
 

 \item 
   {\small\texttt{P4}} : Fatness. Increasing this makes the spikes fatter 
 

\end{itemize}
\index{f\_\-spikes\_\-2d}

   {\small\texttt{f\_\-spikes\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}} =2-D function : f = f( x, z ) - y 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Height of central spike 
 

 \item 
   {\small\texttt{P1}} : Frequency of spikes in the X direction 
 

 \item 
   {\small\texttt{P2}} : Frequency of spikes in the Z direction 
 

 \item 
   {\small\texttt{P3}} : Rate at which the spikes reduce as you move away from the center 
 

\end{itemize}
\index{f\_\-spiral}

   {\small\texttt{f\_\-spiral(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Distance between windings 
 

 \item 
   {\small\texttt{P1}} : Thickness 
 

 \item 
   {\small\texttt{P2}} : Outer diameter of the spiral. The surface behaves as if it is contained\_\-by a sphere of this diameter 
 

 \item 
   {\small\texttt{P3}} : Not used 
 

 \item 
   {\small\texttt{P4}} : Not used 
 

 \item 
   {\small\texttt{P5}} : Cross section type 
 

\end{itemize}
\index{f\_\-steiners\_\-roman}

   {\small\texttt{f\_\-steiners\_\-roman(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The "Steiners Roman" is composed of four identical triangular pads which together make up a sort of 
 rounded tetrahedron. There are creases along the X, Y and Z axes where the pads meet. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-strophoid}

   {\small\texttt{f\_\-strophoid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3)}}. The "Strophoid" is like an infinite plane with a bulb sticking out of it. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Size of bulb. Larger values give larger bulbs. Negative values give a bulb on the other side of the plane 
 

 \item 
   {\small\texttt{P2}} : Sharpness. When zero, the bulb is like a sphere that just touches the plane. When positive, there is a crossover point. When 
  negative the bulb simply bulges out of the plane like a pimple 
 

 \item 
   {\small\texttt{P3}} : Flatness. Higher values make the top end of the bulb fatter 
 

\end{itemize}
\index{f\_\-strophoid\_\-2d}

   {\small\texttt{f\_\-strophoid\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5, P6)}}. The 2d strophoid curve can be extruded in the Z direction or rotated about various axes 
 by using the SOR parameters. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength 
 

 \item 
   {\small\texttt{P1}} : Size of bulb. Larger values give larger bulbs. Negative values give a bulb on the other side of the plane 
 

 \item 
   {\small\texttt{P2}} : Sharpness. When zero, the bulb is like a sphere that just touches the plane. When positive, there is a crossover point. When 
  negative the bulb simply bulges out of the plane like a pimple 
 

 \item 
   {\small\texttt{P3}} : Fatness. Higher values make the top end of the bulb fatter 
 

 \item 
   {\small\texttt{P4}} : SOR Switch 
 

 \item 
   {\small\texttt{P5}} : SOR Offset 
 

 \item 
   {\small\texttt{P6}} : SOR Angle 
 

\end{itemize}
\index{f\_\-superellipsoid}

   {\small\texttt{f\_\-superellipsoid(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1)}}. Needs a negative field strength or a negated function. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : east-\discretionary{}{}{}west exponentx 
 

 \item 
   {\small\texttt{P1}} : north-\discretionary{}{}{}south exponent 
 

\end{itemize}
\index{f\_\-th}

   {\small\texttt{f\_\-th(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z)}} = atan2( x, z ) \newline {\small\texttt{f\_\-th()}} is a function that is only useful when combined with other surfaces. \newline It 
 produces a value which is equal to the "theta" angle, in radians, at any point. The theta angle is like the longitude coordinate on the Earth. It 
 stays the same as you move north or south, but varies from east to west. Also look at {\small\texttt{f\_\-ph}} and {\small\texttt{f\_\-r}} \index{f\_\-torus} 



   {\small\texttt{f\_\-torus(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Major radius 
 

 \item 
   {\small\texttt{P1}} : Minor radius 
 

\end{itemize}
\index{f\_\-torus2}

   {\small\texttt{f\_\-torus2(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2)}}. This is different from the f\_\-torus function which just has the major and minor radii as parameters. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Major radius 
 

 \item 
   {\small\texttt{P2}} : Minor radius 
 

\end{itemize}
\index{f\_\-torus\_\-gumdrop}

   {\small\texttt{f\_\-torus\_\-gumdrop(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}}. The "Torus Gumdrop" surface is something like a torus with a couple of gumdrops hanging off the end. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-umbrella}

   {\small\texttt{f\_\-umbrella(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0)}} 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

\end{itemize}
\index{f\_\-witch\_\-of\_\-agnesi}

   {\small\texttt{f\_\-witch\_\-of\_\-agnesi(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The "Witch of Agnesi" surface looks something like a witches hat. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Controls the width of the spike. The height of the spike is always about 1 unit 
 

\end{itemize}
\index{f\_\-witch\_\-of\_\-agnesi\_\-2d}

   {\small\texttt{f\_\-witch\_\-of\_\-agnesi\_\-2d(\discretionary{x,}{}{x,}\discretionary{y,}{}{y,}z, P0, P1, P2, P3, P4, P5)}}. The 2d version of the "Witch of Agnesi" curve can be extruded in the Z 
 direction or rotated about various axes by use of the SOR parameters. 


\begin{itemize}
 
 \item 
   {\small\texttt{P0}} : Field Strength (Needs a negative field strength or a negated function) 
 

 \item 
   {\small\texttt{P1}} : Controls the size of the spike 
 

 \item 
   {\small\texttt{P2}} : Controls the height of the spike 
 

 \item 
   {\small\texttt{P3}} : SOR Switch 
 

 \item 
   {\small\texttt{P4}} : SOR Offset 
 

 \item 
   {\small\texttt{P5}} : SOR Angle 
 

\end{itemize}

\subsection{Pre defined functions}

% reference/000382.html

\index{eval\_\-pigment}

   {\small\texttt{eval\_\-pigment(Pigm, Vect)}}, This macro evaluates the color of a pigment at a specific point. Some pigments require more information than 
 simply a point, slope pattern based pigments for example, and will not work with this macro. However, most pigments will work fine.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Vect}} = The point at which to evaluate the pigment. 
 

 \item 
   {\small\texttt{Pigm}} = The pigment to evaluate. 
 

\end{itemize}
\index{f\_\-snoise3d}

   {\small\texttt{f\_\-snoise3d(x, y, z)}}. Just like f\_\-noise3d(), but returns values in the range [-1, 1]. \index{f\_\-sine\_\-wave} 



   {\small\texttt{f\_\-sine\_\-wave(val, amplitude, frequency)}}. Turns a ramping waveform into a sine waveform. \index{f\_\-scallop\_\-wave} 



   {\small\texttt{f\_\-scallop\_\-wave(val, amplitude, frequency)}}. Turns a ramping waveform into a "scallop\_\-wave" waveform. 


\subsubsection{Pattern functions}

% reference/000381.html



   Predefined pattern functions, useful for building custom function patterns or performing "displacement mapping" on isosurfaces. Many of them are 
 not really useful for these purposes, they are simply included for completeness. 



   Some are not implemented at all because they require special parameters that must be specified in the definition, or information that is not available to 
 pattern functions. For this reason, you probably would want to define your own versions of these functions. 



   All of these functions take three parameters, the XYZ coordinates of the point to evaluate the pattern at. 


\begin{description}
 
 \item 
   {\small\texttt{f\_\-agate(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-boxed(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-bozo(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-brick(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-bumps(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-checker(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-crackle(x, y, z)}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This pattern has many more options, this function uses the defaults. 
 \end{list}

 \item 
   {\small\texttt{f\_\-cylindrical(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-dents(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-gradientX(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-gradientY(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-gradientZ(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-granite(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-hexagon(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-leopard(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-mandel(x, y, z)}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Only the basic mandel pattern is implemented, its variants and the other fractal 
  patterns are not implemented. 
 \end{list}

 \item 
   {\small\texttt{f\_\-marble(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-onion(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-planar(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-radial(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-ripples(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-spherical(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-spiral1(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-spiral2(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-spotted(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-waves(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-wood(x, y, z)}} 
 

 \item 
   {\small\texttt{f\_\-wrinkles(x, y, z)}} 
 

\end{description}

\section{\discretionary{glass.}{}{glass.}inc, glass\_\discretionary{old.}{}{old.}inc}

% reference/000348.html



   This file contains glass materials using new features introduced in POV 3.1 and 3.5. The old \discretionary{glass.}{}{glass.}inc file is still included for backwards compatibility (it 
 is named glass\_\discretionary{old.}{}{old.}inc, and is included by \discretionary{glass.}{}{glass.}inc, so you do not need to change any scenes), but these materials will give more realistic results. 


\subsection{Glass colors (with transparency)}

% reference/000349.html


\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Glass\_\-Beerbottle\newline  Col\_\-Glass\_\-Bluish\newline  Col\_\-Glass\_\-Clear\newline  Col\_\-Glass\_\-Dark\_\-Green\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Glass\_\-General\newline  Col\_\-Glass\_\-Green\newline  Col\_\-Glass\_\-Old\newline  Col\_\-Glass\_\-Orange\newline  }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Glass\_\-Ruby\newline  Col\_\-Glass\_\-Vicksbottle\newline  Col\_\-Glass\_\-Winebottle\newline  Col\_\-Glass\_\-Yellow\newline  }} } \\ 
 

\end{tabular*} \caption{\discretionary{glass.}{}{glass.}inc glass colors with transparency} \end{table}

\subsection{Glass colors (without transparency, for fade\_\-color)}

% reference/000393.html


\begin{table} \centering\begin{tabular*}{402pt}[t]{@{} p{133pt}@{} p{133pt}@{} p{133pt}@{} }
 
 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Amber\_\-01\newline  Col\_\-Amber\_\-02\newline  Col\_\-Amber\_\-03\newline  Col\_\-Amber\_\-04\newline  Col\_\-Amber\_\-05\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Amber\_\-06\newline  Col\_\-Amber\_\-07\newline  Col\_\-Amber\_\-08\newline  Col\_\-Amber\_\-09\newline  Col\_\-Amethyst\_\-01\newline  }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Amethyst\_\-02\newline  Col\_\-Amethyst\_\-03\newline  Col\_\-Amethyst\_\-04\newline  Col\_\-Amethyst\_\-05\newline  Col\_\-Amethyst\_\-06\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Apatite\_\-01\newline  Col\_\-Apatite\_\-02\newline  Col\_\-Apatite\_\-03\newline  Col\_\-Apatite\_\-04\newline  Col\_\-Apatite\_\-05\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Aquamarine\_\-01\newline  Col\_\-Aquamarine\_\-02\newline  Col\_\-Aquamarine\_\-03\newline  Col\_\-Aquamarine\_\-04\newline  Col\_\-Aquamarine\_\-05\newline  
   }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Aquamarine\_\-06\newline  Col\_\-Azurite\_\-01\newline  Col\_\-Azurite\_\-02\newline  Col\_\-Azurite\_\-03\newline  Col\_\-Azurite\_\-04\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Beerbottle\newline  Col\_\-Blue\_\-01\newline  Col\_\-Blue\_\-02\newline  Col\_\-Blue\_\-03\newline  Col\_\-Blue\_\-04\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Citrine\_\-01\newline  Col\_\-Dark\_\-Green\newline  Col\_\-Emerald\_\-01\newline  Col\_\-Emerald\_\-02\newline  Col\_\-Emerald\_\-03\newline  }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Emerald\_\-04\newline  Col\_\-Emerald\_\-05\newline  Col\_\-Emerald\_\-06\newline  Col\_\-Emerald\_\-07\newline  Col\_\-Fluorite\_\-01\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Fluorite\_\-02\newline  Col\_\-Fluorite\_\-03\newline  Col\_\-Fluorite\_\-04\newline  Col\_\-Fluorite\_\-05\newline  Col\_\-Fluorite\_\-06\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Fluorite\_\-07\newline  Col\_\-Fluorite\_\-08\newline  Col\_\-Fluorite\_\-09\newline  Col\_\-Green\newline  Col\_\-Green\_\-01\newline  }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Green\_\-02\newline  Col\_\-Green\_\-03\newline  Col\_\-Green\_\-04\newline  Col\_\-Gypsum\_\-01\newline  Col\_\-Gypsum\_\-02\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Gypsum\_\-03\newline  Col\_\-Gypsum\_\-04\newline  Col\_\-Gypsum\_\-05\newline  Col\_\-Gypsum\_\-06\newline  Col\_\-Orange\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Red\_\-01\newline  Col\_\-Red\_\-02\newline  Col\_\-Red\_\-03\newline  Col\_\-Red\_\-04\newline  Col\_\-Ruby\newline  }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Ruby\_\-01\newline  Col\_\-Ruby\_\-02\newline  Col\_\-Ruby\_\-03\newline  Col\_\-Ruby\_\-04\newline  Col\_\-Ruby\_\-05\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Sapphire\_\-01\newline  Col\_\-Sapphire\_\-02\newline  Col\_\-Sapphire\_\-03\newline  Col\_\-Topaz\_\-01\newline  Col\_\-Topaz\_\-02\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ Col\_\-Topaz\_\-03\newline  Col\_\-Tourmaline\_\-01\newline  Col\_\-Tourmaline\_\-02\newline  Col\_\-Tourmaline\_\-03\newline  Col\_\-Tourmaline\_\-04\newline  
   }} 
  } & 
{\raggedleft  {\small\texttt{ Col\_\-Tourmaline\_\-05\newline  Col\_\-Tourmaline\_\-06\newline  Col\_\-Vicksbottle\newline  Col\_\-Winebottle\newline  Col\_\-Yellow\newline  }} } \\ 
 

 
  
  {\raggedleft 
    {\small\texttt{ Col\_\-Yellow\_\-01\newline  Col\_\-Yellow\_\-02\newline  Col\_\-Yellow\_\-03\newline  Col\_\-Yellow\_\-04\newline  }} 
  } & 

  {\raggedleft 
    {\small\texttt{ }} 
  } & 
{\raggedleft  {\small\texttt{ }} } \\ 
 

\end{tabular*} \caption{\discretionary{glass.}{}{glass.}inc glass colors without transparency for fade\_\-color} \end{table}

\subsection{Glass finishes}

% reference/000392.html

{\small\texttt{F\_\-Glass5, ..., F\_\-Glass10}}
\subsection{Glass interiors}

% reference/000391.html


\begin{description}
 
 \item 
   {\small\texttt{I\_\-Glass1, ..., I\_\-Glass4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{I\_\-Glass\_\-Fade\_\-Sqr1}} (identical to {\small\texttt{I\_\-Glass1}}) 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{I\_\-Glass\_\-Fade\_\-Exp1}} (identical to {\small\texttt{I\_\-Glass2}}) 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{I\_\-Glass\_\-Fade\_\-Exp2}} (identical to {\small\texttt{I\_\-Glass3}}) 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{I\_\-Glass\_\-Fade\_\-Exp3}} (identical to {\small\texttt{I\_\-Glass4}}) 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Glass interiors with various fade\_\-power settings. 
 \end{list}

 \item 
   {\small\texttt{I\_\-Glass\_\-Dispersion1, I\_\-Glass\_\-Dispersion2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Glass interiors with dispersion. {\small\texttt{I\_\-Glass\_\-Dispersion1}} has an 
  approximately natural glass dispersion. {\small\texttt{I\_\-Glass\_\-Dispersion2}} is exaggerated. 
 \end{list}

 \item 
   {\small\texttt{I\_\-Glass\_\-Caustics1, I\_\-Glass\_\-Caustics2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Glass interiors with caustics. 
 \end{list}

\end{description}

\subsection{Glass interior macros}

% reference/000390.html



   {\small\texttt{I\_\-Glass\_\-Exp(Distance)}} and {\small\texttt{I\_\-Glass\_\-Sqr(Distance)}}.\newline  These macros return an interior with either exponential or 
 fade\_\-power 2 falloff, and a fade\_\-distance of Distance. 


\subsection{glass\_\discretionary{old.}{}{old.}inc}

% reference/000350.html



   This file contains glass textures for POV-\discretionary{}{}{}Ray versions 3.1 and earlier. These textures do not take advantage of the new features introduced with POV-\discretionary{}{}{}Ray 3.5 
 and are included for backwards compatability, you will get better results with the materials in \discretionary{glass.}{}{glass.}inc. 



   These textures are designed to be used with the I\_\-Glass interior, also defined in this file. 


\subsubsection{Glass finishes}

% reference/000372.html



   {\small\texttt{F\_\-Glass1, ..., F\_\-Glass4}} 


\subsubsection{Glass textures}

% reference/000394.html


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Glass1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Simple clear glass. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Glass2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   More like an acrylic plastic. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Glass3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An excellent lead crystal glass. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Glass4}} 
 

 \item 
   {\small\texttt{T\_\-Old\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Winebottle\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Beerbottle\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Ruby\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Green\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Dark\_\-Green\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Yellow\_\-Glass}} 
 

 \item 
   {\small\texttt{T\_\-Orange\_\-Glass}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Orange/amber glass. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Vicksbottle\_\-Glass}} 
 

\end{description}

\section{\discretionary{math.}{}{math.}inc}

% reference/000371.html



   This file contains many general math functions and macros. 


\subsection{Float functions and macros}

% reference/000370.html

\index{even}

   {\small\texttt{even(N)}}. A function to test whether N is even, returns 1 when true, 0 when false.\newline  Parameters 


\begin{itemize}
 
 \item 
   {\small\texttt{N}} = Input value 
 

\end{itemize}
\index{odd}

   {\small\texttt{odd(N)}}. A function to test whether N is odd, returns 1 when true, 0 when false.\newline  Parameters 


\begin{itemize}
 
 \item 
   {\small\texttt{N}} = Input value 
 

\end{itemize}
\index{Interpolate! macro}

   {\small\texttt{Interpolate(GC, GS, GE, TS, TE, Method)}}. Interpolation macro, interpolates between the float values {\small\texttt{TS}} and {\small\texttt{TE}}. 
 The method of interpolation is cosine, linear or exponential. The position where to evaluate the interpolation is determined by the position of {\small\texttt{GC}} 
 in the range {\small\texttt{GS}} - {\small\texttt{GE}}. See example.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{GC}} = global current, float value within the range GS - GE 
 

 \item 
   {\small\texttt{GS}} = global start 
 

 \item 
   {\small\texttt{GE}} = global end 
 

 \item 
   {\small\texttt{TS}} = target start 
 

 \item 
   {\small\texttt{TE}} = target end 
 

 \item 
   {\small\texttt{Method}} = interpolation method, float value: 
  \begin{itemize}
   
   \item 
     {\small\texttt{Method}} $<$ 0 : exponential, using the value of Method as exponent. 
   

   \item 
     {\small\texttt{Method}} = 0 : cosine interpolation. 
   

   \item 
     {\small\texttt{Method}} $>$ 0 : exponential, using the value of Method as exponent. 
    \begin{itemize}
     
     \item 
       {\small\texttt{Method}} = 1 : linear interpolation, 
     

    \end{itemize}
     
   

  \end{itemize}
   
 

\end{itemize}


   Example: 


{\small\begin{verbatim}
  #declare A = Interpolate(0.5, 0, 1, 0, 10, 1);
  #debug str(A,0,2)
  // result A = 5.00

  #declare A = Interpolate(0.0,-2, 2, 0, 10, 1);
  #debug str(A,0,2)
  // result A = 5.00

  #declare A = Interpolate(0.5, 0, 1, 0, 10, 2);
  #debug str(A,0,2)  
  // result A = 2.50
\end{verbatim}}
\index{Mean}

   {\small\texttt{Mean(A)}}. A macro to compute the average of an array of values.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A}} = An array of float or vector values. 
 

\end{itemize}
\index{Std\_\-Dev}

   {\small\texttt{Std\_\-Dev(A, M)}}. A macro to compute the standard deviation.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A}} = An array of float values. 
 

 \item 
   {\small\texttt{M}} = Mean of the floats in the array. 
 

\end{itemize}
\index{GetStats}

   {\small\texttt{GetStats(ValArr)}}. This macro declares a global array named "{\small\texttt{StatisticsArray}}" containing: N, Mean, Min, Max, and 
 Standard Deviation\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A}} = An array of float values. 
 

\end{itemize}
\index{Histogram}

   {\small\texttt{Histogram(ValArr, Intervals)}}. This macro declares a global, 2D array named "{\small\texttt{HistogramArray}}". The first value in 
 the array is the center of the interval/bin, the second the number of values in that interval.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{ValArr}} = An array with values. 
 

 \item 
   {\small\texttt{Intervals}} = The desired number of intervals/bins. 
 

\end{itemize}
\index{sind}\index{cosd}\index{tand}\index{asind}\index{acosd}\index{atan2d}

   {\small\texttt{sind(v), cosd(v), tand(v), asind(v), acosd(v), atan2d(a, b)}}. These functions are versions of the trigonometric functions using degrees, 
 instead of radians, as the angle unit.\newline  Parameters:\newline  The same as for the analogous built-\discretionary{}{}{}in trig function. \index{max3} 



   {\small\texttt{max3(a, b, c)}}. A function to find the largest of three numbers.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{a, b, c}} = Input values. 
 

\end{itemize}
\index{min3}

   {\small\texttt{min3(a, b, c)}}. A function to find the smallest of three numbers.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{a, b, c}} = Input values. 
 

\end{itemize}
\index{f\_\-sqr}

   {\small\texttt{f\_\-sqr(v)}}. A function to square a number.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{v}} = Input value. 
 

\end{itemize}
\index{sgn}

   {\small\texttt{sgn(v)}}. A function to show the sign of the number. Returns -1 or 1 depending on the sign of v.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{v}} = Input value. 
 

\end{itemize}
\index{clip}

   {\small\texttt{clip(V, Min, Max)}}. A function that limits a value to a specific range, if it goes outside that range it is "clipped". Input values 
 larger than {\small\texttt{Max}} will return {\small\texttt{Max}}, those less than {\small\texttt{Min}} will return {\small\texttt{Min}}.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input value. 
 

 \item 
   {\small\texttt{Min}} = Minimum of output range. 
 

 \item 
   {\small\texttt{Max}} = Maximum of output range. 
 

\end{itemize}
\index{clamp}

   {\small\texttt{clamp(V, Min, Max)}}. A function that limits a value to a specific range, if it goes outside that range it is "clamped" to this 
 range, wrapping around. As the input increases or decreases outside the given range, the output will repeatedly sweep through that range, making a 
 "sawtooth" waveform.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input value. 
 

 \item 
   {\small\texttt{Min}} = Minimum of output range. 
 

 \item 
   {\small\texttt{Max}} = Maximum of output range. 
 

\end{itemize}
\index{adj\_\-range}

   {\small\texttt{adj\_\-range(V, Min, Max)}}. A function that adjusts input values in the range [0, 1] to a given range. An input value of 0 will return {\small\texttt{Min}}, 
 1 will return {\small\texttt{Max}}, and values outside the [0, 1] range will be linearly extrapolated (the graph will continue in a straight line).\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input value. 
 

 \item 
   {\small\texttt{Min}} = Minimum of output range. 
 

 \item 
   {\small\texttt{Max}} = Maximum of output range. 
 

\end{itemize}
\index{adj\_\-range2}

   {\small\texttt{adj\_\-range2(V, InMin, InMax, OutMin, OutMax)}}. Like {\small\texttt{f\_\-range()}}, but adjusts input values in the range {\small\texttt{[InMin, 
 InMax]}} to the range {\small\texttt{[OutMin, OutMax]}}.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input value. 
 

 \item 
   {\small\texttt{InMin}} = Minimum of input range. 
 

 \item 
   {\small\texttt{InMax}} = Maximum of input range. 
 

 \item 
   {\small\texttt{OutMin}} = Minimum of output range. 
 

 \item 
   {\small\texttt{OutMax}} = Maximum of output range. 
 

\end{itemize}

\subsection{Vector functions and macros}

% reference/000396.html



   These are all macros in the current version because functions can not take vector parameters, but this may change in the future.\index{VSqr} 



   {\small\texttt{VSqr(V)}}. Square each individual component of a vector, equivalent to {\small\texttt{V*V}}.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Vector to be squared. 
 

\end{itemize}
\index{VPow}\index{VPow5D}

   {\small\texttt{VPow(V, P), VPow5D(V, P)}}. Raise each individual component of a vector to a given power.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

 \item 
   {\small\texttt{P}} = Power. 
 

\end{itemize}
\index{VEq}

   {\small\texttt{VEq(V1, V2)}}. Tests for equal vectors, returns true if all three components of {\small\texttt{V1}}equal the respective components of {\small\texttt{V2}}.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = The vectors to be compared. 
 

\end{itemize}
\index{VEq5D}

   {\small\texttt{VEq5D(V1, V2)}}. A 5D version of {\small\texttt{VEq()}}. Tests for equal vectors, returns true if all 5 components of {\small\texttt{V1 }}equal 
 the respective components of {\small\texttt{V2}}.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = The vectors to be compared. 
 

\end{itemize}
\index{VZero}

   {\small\texttt{VZero(V)}}. Tests for a $<$ 0, 0, 0$>$ vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VZero5D}

   {\small\texttt{VZero5D(V)}}. Tests for a $<$ 0, 0, 0, 0, 0$>$ vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VLength5D}

   {\small\texttt{VLength5D(V)}}. Computes the length of a 5D vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VNormalize5D}

   {\small\texttt{VNormalize5D(V)}}. Normalizes a 5D vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VDot5D}

   {\small\texttt{VDot5D(V1, V2)}}. Computes the dot product of two 5D vectors. See vdot() for more information on dot products.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VCos\_\-Angle}

   {\small\texttt{VCos\_\-Angle(V1, V2)}}. Compute the cosine of the angle between two vectors.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = Input vectors. 
 

\end{itemize}
\index{VAngle}

   {\small\texttt{VAngle(V1, V2), VAngleD(V1, V2)}}. Compute the angle between two vectors. {\small\texttt{VAngle()}} returns the angle in radians, {\small\texttt{VAngleD()}} 
 in degrees.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = Input vectors. 
 

\end{itemize}
\index{VRotation}

   {\small\texttt{VRotation(V1, V2, Axis), VRotationD(V1, V2, Axis)}}.Compute the rotation angle from V1 to V2 around Axis. Axis should be perpendicular to both 
 V1 and V2. The output will be in the range between -pi and pi radians or between -180 degrees and 180 degrees if you are using the degree version. However, if 
 Axis is set to $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ the output will always be positive or zero, the same result you will get with the VAngle() macros.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = Input vectors. 
 

\end{itemize}
\index{VDist}

   {\small\texttt{VDist(V1, V2)}}. Compute the distance between two points.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = Input vectors. 
 

\end{itemize}
\index{VPerp\_\-To\_\-Vector}

   {\small\texttt{VPerp\_\-To\_\-Vector(V)}}. Find a vector perpendicular to the given vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VPerp\_\-To\_\-Plane}

   {\small\texttt{VPerp\_\-To\_\-Plane(V1, V2)}}. Find a vector perpendicular to both given vectors. In other words, perpendicular to the plane defined by the two 
 input vectors\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, V2}} = Input vectors. 
 

\end{itemize}
\index{VPerp\_\-Adjust}

   {\small\texttt{VPerp\_\-Adjust(V1, Axis)}}. Find a vector perpendicular to Axis and in the plane of V1 and Axis. In other words, the new vector is a version of 
 V1 adjusted to be perpendicular to Axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, Axis}} = Input vectors. 
 

\end{itemize}
\index{VProject\_\-Plane}

   {\small\texttt{VProject\_\-Plane(V1, Axis)}}. Project vector V1 onto the plane defined by Axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1}} = Input vectors. 
 

 \item 
   {\small\texttt{Axis}} = Normal of the plane. 
 

\end{itemize}
\index{VProject\_\-Axis}

   {\small\texttt{VProject\_\-Axis(V1, Axis)}}. Project vector V1 onto the axis defined by Axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V1, Axis}} = Input vectors. 
 

\end{itemize}
\index{VMin}

   {\small\texttt{VMin(V), VMax(V)}}. Find the smallest or largest component of a vector.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Input vector. 
 

\end{itemize}
\index{VWith\_\-Len}

   {\small\texttt{VWith\_\-Len(V, Len)}}. Create a vector parallel to a given vector but with a given length.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = Direction vector. 
 

 \item 
   {\small\texttt{Len}} = Length of desired vector. 
 

\end{itemize}

\subsection{Vector Analysis}

% reference/000395.html

\index{SetGradientAccuracy}

   {\small\texttt{SetGradientAccuracy(Value)}}: all below macros make use of a constant named '\_\_Gradient\_\-Fn\_\-Accuracy\_' for numerical approximation of the 
 derivatives. This constant can be changed with the macro, the default value is 0.001.\index{fn\_\-Gradient} 



   {\small\texttt{fn\_\-Gradient(Fn)}}: macro calculating the gradient of a function as a function. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fn}} = function to calculate the gradient from. 
 

\end{itemize}


   Output: the length of the gradient as a function. \index{fn\_\-Gradient\_\-Directional} 



   {\small\texttt{fn\_\-Gradient\_\-Directional(Fn, Dir)}}: macro calculating the gradient of a function in one direction as a function. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fn}} = function to calculate the gradient from. 
 

 \item 
   {\small\texttt{Dir}} = direction to calculate the gradient. 
 

\end{itemize}


   Output: the gradient in that direction as a function. \index{fn\_\-Divergence} 



   {\small\texttt{fn\_\-Divergence(Fnx, Fny, Fnz)}}: macro calculating the divergence of a (vector) function as a function. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fnx, Fny, Fnz}}= x, y and z components of a vector function. 
 

\end{itemize}


   Output: the divergence as a function. \index{vGradient} 



   {\small\texttt{vGradient(Fn, p0)}}: macro calculating the gradient of a function as a vector expression. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fn}} = function to calculate the gradient from. 
 

 \item 
   {\small\texttt{p0}} = point where to calculate the gradient. 
 

\end{itemize}


   Output: the gradient as a vector expression. \index{vCurl} 



   {\small\texttt{vCurl(Fnx, Fny, Fnz, p0)}}: macro calculating the curl of a (vector) function as a vector expression \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fnx, Fny, Fnz}} = x, y and z components of a vector function. 
 

 \item 
   {\small\texttt{p0}} = point where to calculate the gradient. 
 

\end{itemize}


   Output: the curl as a vector expression \index{Divergence} 



   {\small\texttt{Divergence(Fnx, Fny, Fnz, p0)}}: macro calculating the divergence of a (vector) function as a float expression \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fnx, Fny, Fnz}} = x, y and z components of a vector function. 
 

 \item 
   {\small\texttt{p0}} = point where to calculate the gradient. 
 

\end{itemize}


   Output: the divergence as a float expression. \index{Gradient\_\-Length} 



   {\small\texttt{Gradient\_\-Length(Fn, p0)}}: macro calculating the length of the gradient of a function as a float expression. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fn}} = function to calculate the gradient from. 
 

 \item 
   {\small\texttt{p0}} = point where to calculate the gradient. 
 

\end{itemize}


   Output: the length of the gradient as a float expression. \index{Gradient\_\-Directional} 



   {\small\texttt{Gradient\_\-Directional(Fn, p0, Dir)}}: macro calculating the gradient of a function in one direction as a float expression. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Fn}} = function to calculate the gradient from. 
 

 \item 
   {\small\texttt{p0}} = point where to calculate the gradient. 
 

 \item 
   {\small\texttt{Dir}} = direction to calculate the gradient. 
 

\end{itemize}


   Output: the gradient in that direction as a float expression 


\section{\discretionary{metals.}{}{metals.}inc, \discretionary{golds.}{}{golds.}inc}

% reference/000369.html



   These files define several metal textures. The file \discretionary{metals.}{}{metals.}inc contains copper, silver, chrome, and brass textures, and \discretionary{golds.}{}{golds.}inc contains the gold textures.\newline  
 Rendering the demo files will come in useful in using these textures. 


\subsection{\discretionary{metals.}{}{metals.}inc}

% reference/000368.html



   Colors: 


\begin{description}
 
 \item 
   {\small\texttt{P\_\-Brass1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark brown bronze. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Brass2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Somewhat lighter brown than Brass4. Old penny, in soft finishes. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Brass3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Used by Steve Anger's Polished\_\-Brass. Slightly coppery. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Brass4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A little yellower than Brass1. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Brass5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very light bronze, ranges from med tan to almost white. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{P\_\-Copper1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Bronze-\discretionary{}{}{}like. Best in finish \#C. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Copper2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Slightly brownish copper/bronze. Best in finishes \#B-\#D. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Copper3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Reddish-\discretionary{}{}{}brown copper. Best in finishes \#C-\#E. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Copper4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Pink copper, like new tubing. Best in finishes \#C-\#E. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Copper5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Bronze in softer finishes, gold in harder finishes. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{P\_\-Chrome1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   20\% Gray. Used in Steve Anger's Polished\_\-Chrome. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Chrome2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Slightly blueish 60\% gray. Good steel w/finish \#A. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Chrome3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   50\% neutral gray. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Chrome4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   75\% neutral gray. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Chrome5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   95\% neutral gray. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{P\_\-Silver1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Yellowish silverplate. Somewhat tarnished looking. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Silver2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Not quite as yellowish as Silver1 but more so than Silver3. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Silver3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Reasonably neutral silver. 
 \end{list}

 \item 
   {\small\texttt{P\_\-Silver4}} 
 

 \item 
   {\small\texttt{P\_\-Silver5}} 
 

\end{description}


   Finishes: 


\begin{description}
 
 \item 
   {\small\texttt{F\_\-MetalA}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very soft and dull. 
 \end{list}

 \item 
   {\small\texttt{F\_\-MetalB}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Fairly soft and dull. 
 \end{list}

 \item 
   {\small\texttt{F\_\-MetalC}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium reflectivity. Holds color well. 
 \end{list}

 \item 
   {\small\texttt{F\_\-MetalD}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very hard and highly polished. High reflectivity. 
 \end{list}

 \item 
   {\small\texttt{F\_\-MetalE}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very highly polished and reflective. 
 \end{list}

\end{description}


   Textures: 


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Brass\_\-1A to T\_\-Brass\_\-5E}} 
 

 \item 
   {\small\texttt{T\_\-Copper\_\-1A to T\_\-Copper\_\-5E}} 
 

 \item 
   {\small\texttt{T\_\-Chrome\_\-1A to T\_\-Chrome\_\-5E}} 
 

 \item 
   {\small\texttt{T\_\-Silver\_\-1A to T\_\-Silver\_\-5E}} 
 

\end{description}

\subsection{\discretionary{golds.}{}{golds.}inc}

% reference/000397.html



   This file has its own versions of {\small\texttt{F\_\-MetalA}} through {\small\texttt{F\_\-MetalB}}. 



   The gold textures themselves are {\small\texttt{T\_\-Gold\_\-1A}} through {\small\texttt{T\_\-Gold\_\-5E}}. 


\section{\discretionary{rand.}{}{rand.}inc}

% reference/000367.html



   A collection of macros for generating random numbers, as well as 4 predefined random number streams: {\small\texttt{RdmA, RdmB, RdmC,}} and {\small\texttt{RdmD}}. 
 There are macros for creating random numbers in a flat distribution (all numbers equally likely) in various ranges, and a variety of other distributions. 


\subsection{Flat Distributions}

% reference/000366.html

\index{SRand}

   {\small\texttt{SRand(Stream)}}. "Signed rand()", returns random numbers in the range [-1, 1]. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{RRand}

   {\small\texttt{RRand(Min, Max, Stream)}}. Returns random numbers in the range [Min, Max].\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Min}} = The lower end of the output range. 
 

 \item 
   {\small\texttt{Max}} = The upper end of the output range. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{VRand}

   {\small\texttt{VRand(Stream)}}. Returns random vectors in a box from $<$ 0, 0, 0$>$ to $<$ 1, 1, 1$>$\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{VRand\_\-In\_\-Box}

   {\small\texttt{VRand\_\-In\_\-Box(PtA, PtB, Stream)}}. Like VRand(), this macro returns a random vector in a box, but this version lets you specify the two corners 
 of the box.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA}} = Lower-\discretionary{}{}{}left-\discretionary{}{}{}bottom corner of box. 
 

 \item 
   {\small\texttt{PtB}} = Upper-\discretionary{}{}{}right-\discretionary{}{}{}top corner of box. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{VRand\_\-In\_\-Sphere}

   {\small\texttt{VRand\_\-In\_\-Sphere(Stream)}}. Returns a random vector in a unit-\discretionary{}{}{}radius sphere located at the origin.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{VRand\_\-On\_\-Sphere}

   {\small\texttt{VRand\_\-On\_\-Sphere(Stream)}}. Returns a random vector on the surface of a unit-\discretionary{}{}{}radius sphere located at the origin.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{VRand\_\-In\_\-Obj}

   {\small\texttt{VRand\_\-In\_\-Obj(Object, Stream)}} This macro takes a solid object and returns a random point that is inside it. It does this by randomly sampling 
 the bounding box of the object, and can be quite slow if the object occupies a small percentage of the volume of its bounding box (because it will take more 
 attempts to find a point inside the object). This macro is best used on finite, solid objects (non-\discretionary{}{}{}solid objects, such as meshes and bezier patches, do not 
 have a defined "inside", and will not work).\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object the macro chooses the points from. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}

\subsection{Other Distributions}

% reference/000401.html


\subsubsection{Continuous Symmetric Distributions}

% reference/000400.html

\index{Rand\_\-Cauchy}

   {\small\texttt{Rand\_\-Cauchy(Mu, Sigma, Stream)}}. Cauchy distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean. 
 

 \item 
   {\small\texttt{Sigma}} = Standard deviation. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Student}

   {\small\texttt{Rand\_\-Student(N, Stream)}}. Student's-\discretionary{}{}{}t distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{N}} = degrees of freedom. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Normal}

   {\small\texttt{Rand\_\-Normal(Mu, Sigma, Stream)}}. Normal distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean. 
 

 \item 
   {\small\texttt{Sigma}} = Standard deviation. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Gauss}

   {\small\texttt{Rand\_\-Gauss(Mu, Sigma, Stream)}}. Gaussian distribution. Like Rand\_\-Normal(), but a bit faster.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean. 
 

 \item 
   {\small\texttt{Sigma}} = Standard deviation. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}

\subsubsection{Continuous Skewed Distributions}

% reference/000399.html

\index{Rand\_\-Spline}

   {\small\texttt{Rand\_\-Spline(Spline, Stream)}}. This macro takes a spline describing the desired distribution. The T value of the spline is the output value, 
 and the .y value its chance of occuring.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Spline}} = A spline determining the distribution. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Gamma}

   {\small\texttt{Rand\_\-Gamma(Alpha, Beta, Stream)}}. Gamma distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Alpha}} = Shape parameter $>$ 0. 
 

 \item 
   {\small\texttt{Beta}} = Scale parameter $>$ 0. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Beta}

   {\small\texttt{Rand\_\-Beta(Alpha, Beta, Stream)}}. Beta variate.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Alpha}} = Shape Gamma1. 
 

 \item 
   {\small\texttt{Beta}} = Scale Gamma2. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Chi\_\-Square}

   {\small\texttt{Rand\_\-Chi\_\-Square(N, Stream)}}. Chi Square random variate.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{N}} = Degrees of freedom (integer). 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-F\_\-Dist}

   {\small\texttt{Rand\_\-F\_\-Dist(N, M, Stream)}}. F-\discretionary{}{}{}distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{N, M}} = Degrees of freedom. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Tri}

   {\small\texttt{Rand\_\-Tri(Min, Max, Mode, Stream)}}. Triangular distribution \newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Min, Max, Mode}}: Min $<$ Mode $<$ Max. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Erlang}

   {\small\texttt{Rand\_\-Erlang(Mu, K, Stream)}}. Erlang variate.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean $>$= 0. 
 

 \item 
   {\small\texttt{K}} = Number of exponential samples. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Exp}

   {\small\texttt{Rand\_\-Exp(Lambda, Stream)}}. Exponential distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Lambda}} = rate = 1/mean. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Lognormal}

   {\small\texttt{Rand\_\-Lognormal(Mu, Sigma, Stream)}}. Lognormal distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean. 
 

 \item 
   {\small\texttt{Sigma}} = Standard deviation. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Pareto}

   {\small\texttt{Rand\_\-Pareto(Alpha, Stream)}}. Pareto distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Alpha}} = ? 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Weibull}

   {\small\texttt{Rand\_\-Weibull(Alpha, Beta, Stream)}}. Weibull distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Alpha}} = ? 
 

 \item 
   {\small\texttt{Beta}} = ? 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}

\subsubsection{Discrete Distributions }

% reference/000398.html

\index{Rand\_\-Bernoulli}

   {\small\texttt{Rand\_\-Bernoulli(P, Stream)}} and {\small\texttt{Prob(P, Stream)}}. Bernoulli distribution. Output is true with probability equal to the value 
 of P and false with a probability of 1 - P.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{P}} = probability range (0-1). 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Binomial}

   {\small\texttt{Rand\_\-Binomial(N, P, Stream)}}. Binomial distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{N}} = Number of trials. 
 

 \item 
   {\small\texttt{P}} = Probability (0-1) 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Geo}

   {\small\texttt{Rand\_\-Geo(P, Stream)}}. Geometric distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{P}} = Probability (0-1). 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}
\index{Rand\_\-Poisson}

   {\small\texttt{Rand\_\-Poisson(Mu, Stream)}}. Poisson distribution.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mu}} = Mean. 
 

 \item 
   {\small\texttt{Stream}} = Random number stream. 
 

\end{itemize}

\section{\discretionary{shapes.}{}{shapes.}inc, shapes\_\discretionary{old.}{}{old.}inc, \discretionary{shapes2.}{}{shapes2.}inc, \discretionary{shapesq.}{}{shapesq.}inc}

% reference/000365.html



   These files contain predefined shapes and shape-\discretionary{}{}{}generation macros. 



   "\discretionary{shapes.}{}{shapes.}inc" includes "shapes\_\discretionary{old.}{}{old.}inc" and contains many macros for working with objects, and for creating special objects, such as 
 bevelled text, spherical height fields, and rounded shapes. 



   Many of the objects in "shapes\_\discretionary{old.}{}{old.}inc" are not very useful in the newer versions of POV-\discretionary{}{}{}Ray, and are kept for backwards compatability with old 
 scenes written for versions of POV-\discretionary{}{}{}Ray that lacked primitives like cones, disks, planes, etc. 



   The file "\discretionary{shapes2.}{}{shapes2.}inc" contains some more useful shapes, including regular polyhedrons, and "\discretionary{shapesq.}{}{shapesq.}inc" contains several quartic and 
 cubic shape definitions. 



   Some of the shapes in "\discretionary{shapesq.}{}{shapesq.}inc" would be much easier to generate, more flexible, and possibly faster rendering as isosurfaces, but are still 
 useful for two reasons: backwards compatability, and the fact that isosurfaces are always finite. 


\subsection{\discretionary{shapes.}{}{shapes.}inc}

% reference/000364.html

\index{Isect}

   {\small\texttt{Isect(Pt, Dir, Obj, OPt)}} and {\small\texttt{IsectN(Pt, Dir, Obj, OPt, ONorm)}}\newline  These macros are interfaces to the trace() function. 
 Isect() only returns the intersection point, IsectN() returns the surface normal as well. These macros return the point and normal information through their 
 parameters, and true or false depending on whether an intersection was found:\newline  If an intersection is found, they return true and set OPt to the 
 intersection point, and ONorm to the normal. Otherwise they return false, and do not modify OPt or ONorm.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Pt}} = The origin (starting point) of the ray. 
 

 \item 
   {\small\texttt{Dir}} = The direction of the ray. 
 

 \item 
   {\small\texttt{Obj}} = The object to test for intersection with. 
 

 \item 
   {\small\texttt{OPt}} = A declared variable, the macro will set this to the intersection point. 
 

 \item 
   {\small\texttt{ONorm}} = A declared variable, the macro will set this to the surface normal at the intersection point. 
 

\end{itemize}
\index{Extents}

   {\small\texttt{Extents(Obj, Min, Max)}}. This macro is a shortcut for calling both min\_\-extent() and max\_\-extent() to get the corners of the bounding box of an 
 object. It returns these values through the Min and Max parameters.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Obj}} = The object you are getting the extents of. 
 

 \item 
   {\small\texttt{Min}} = A declared variable, the macro will set this to the min\_\-extent of the object. 
 

 \item 
   {\small\texttt{Max}} = A declared variable, the macro will set this to the max\_\-extent of the object. 
 

\end{itemize}
\index{Center\_\-Object}

   {\small\texttt{Center\_\-Object(Object, Axis)}}. A shortcut for using the Center\_\-Trans() macro with an object.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object to be centered. 
 

 \item 
   {\small\texttt{Axis}} = See Center\_\-Trans() in the \discretionary{transforms.}{}{transforms.}inc documentation. 
 

\end{itemize}
\index{Align\_\-Object}

   {\small\texttt{Align\_\-Object(Object, Axis, Pt)}}. A shortcut for using the Align\_\-Trans() macro with an object.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object to be aligned. 
 

 \item 
   {\small\texttt{Axis}} = See Align\_\-Trans() in the \discretionary{transforms.}{}{transforms.}inc documentation. 
 

 \item 
   {\small\texttt{Point}} = The point to which to align the bounding box of the object. 
 

\end{itemize}
\index{Bevelled\_\-Text}

   {\small\texttt{Bevelled\_\-Text(Font, String, Cuts, BevelAng, BevelDepth, Depth, Offset, UseMerge)}}. This macro attempts to "bevel" the front edges 
 of a text object. It accomplishes this by making an intersection of multiple copies of the text object, each sheared in a different direction. The results are 
 no perfect, but may be entirely acceptable for some purposes. Warning: the object generated may render considerably more slowly than an ordinary text object.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Font}} = A string specifying the font to use. 
 

 \item 
   {\small\texttt{String}} = The text string the object is generated from. 
 

 \item 
   {\small\texttt{Cuts}} = The number of intersections to use in bevelling the text. More cuts give smoother results, but take more memory and are slower 
  rendering. 
 

 \item 
   {\small\texttt{BevelAng}} = The angle of the bevelled edge. 
 

 \item 
   {\small\texttt{BevelDepth}} = The thickness of the bevelled portion. 
 

 \item 
   {\small\texttt{Depth}} = The total thickness of the resulting text object. 
 

 \item 
   {\small\texttt{Offset}} = The offset parameter for the text object. The z value of this vector will be ignored, because the front faces of all the 
  letters need to be coplanar for the bevelling to work. 
 

 \item 
   {\small\texttt{UseMerge}} = Switch between merge (1) and union (0). 
 

\end{itemize}
\index{Text\_\-Space}

   {\small\texttt{Text\_\-Space(Font, String, Size, Spacing)}}. Computes the width of a text string, including "white space", it returns the advance 
 widths of all n letters. Text\_\-Space gives the space a text, or a glyph, occupies in regard to its surroundings.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Font}} = A string specifying the font to use. 
 

 \item 
   {\small\texttt{String}} = The text string the object is generated from. 
 

 \item 
   {\small\texttt{Size}} = A scaling value. 
 

 \item 
   {\small\texttt{Spacing}} = The amount of space to add between the characters. 
 

\end{itemize}
\index{Text\_\-Width}

   {\small\texttt{Text\_\-Width(Font, String, Size, Spacing)}}. Computes the width of a text string, it returns the advance widths of the first n-1 letters, plus 
 the glyph width of the last letter. Text\_\-Width gives the "physical" width of the text and if you use only one letter the "fysical" width 
 of one glyph. \newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Font}} = A string specifying the font to use. 
 

 \item 
   {\small\texttt{String}} = The text string the object is generated from. 
 

 \item 
   {\small\texttt{Size}} = A scaling value. 
 

 \item 
   {\small\texttt{Spacing}} = The amount of space to add between the characters. 
 

\end{itemize}


   {\small\texttt{Align\_\-Left, Align\_\-Right, Align\_\-Center}}. These constants are used by the {\small\texttt{Circle\_\-Text()}} macro. \index{Circle\_\-Text} 



   {\small\texttt{Circle\_\-Text(Font, String, Size, Spacing, Depth, Radius, Inverted, Justification, Angle)}}. Creates a text object with the bottom (or top) of 
 the character cells aligned with all or part of a circle. This macro should be used inside an {\small\texttt{object\{...\}}} block.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Font}} = A string specifying the font to use. 
 

 \item 
   {\small\texttt{String}} = The text string the object is generated from. 
 

 \item 
   {\small\texttt{Size}} = A scaling value. 
 

 \item 
   {\small\texttt{Spacing}} = The amount of space to add between the characters. 
 

 \item 
   {\small\texttt{Depth}} = The thickness of the text object. 
 

 \item 
   {\small\texttt{Radius}} = The radius of the circle the letters are aligned to. 
 

 \item 
   {\small\texttt{Inverted}} = Controls what part of the text faces "outside". If this parameter is nonzero, the tops of the letters will point 
  toward the center of the circle. Otherwise, the bottoms of the letters will do so. 
 

 \item 
   {\small\texttt{Justification}} = Align\_\-Left, Align\_\-Right, or Align\_\-Center. 
 

 \item 
   {\small\texttt{Angle}} = The point on the circle from which rendering will begin. The +x direction is 0 and the +y direction is 90 (\discretionary{i.}{}{i.}e. the angle 
  increases anti-\discretionary{}{}{}clockwise). 
 

\end{itemize}
\index{Wedge}

   {\small\texttt{Wedge(Angle)}}. This macro creates an infinite wedge shape, an intersection of two planes. It is mainly useful in CSG, for example to obtain a 
 specific arc of a torus. The edge of the wedge is positioned along the y axis, and one side is fixed to the zy plane, the other side rotates clockwise around 
 the y axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Angle}} = The angle, in degrees, between the sides of the wedge shape. 
 

\end{itemize}
\index{Spheroid}

   {\small\texttt{Spheroid(Center, Radius)}}. This macro creates an unevenly scaled sphere. Radius is a vector where each component is the radius along that 
 axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Center}} = Center of the spheroid. 
 

 \item 
   {\small\texttt{Radius}} = A vector specifying the radii of the spheroid. 
 

\end{itemize}
\index{Supertorus}

   {\small\texttt{Supertorus(MajorRadius, MinorRadius, MajorControl, MinorControl, Accuracy, MaxGradient)}}. This macro creates an isosurface of the torus 
 equivalent of a superellipsoid. If you specify a MaxGradient of less than 1, evaluate will be used. You will have to adjust MaxGradient to fit the parameters 
 you choose, a squarer supertorus will have a higher gradient. You may want to use the function alone in your own isosurface.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{MajorRadius, MinorRadius}} = Base radii for the torus. 
 

 \item 
   {\small\texttt{MajorControl, MinorControl}} = Controls for the roundness of the supertorus. Use numbers in the range [0, 1]. 
 

 \item 
   {\small\texttt{Accuracy}} = The accuracy parameter. 
 

 \item 
   {\small\texttt{MaxGradient}} = The max\_\-gradient parameter. 
 

\end{itemize}
\index{Supercone}

   {\small\texttt{Supercone(EndA, A, B, EndB, C, D)}}. This macro creates an object similar to a cone, but where the end points are ellipses. The actual object 
 is an intersection of a quartic with a cylinder.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{EndA}} = Center of end A. 
 

 \item 
   {\small\texttt{A, B}} = Controls for the radii of end A. 
 

 \item 
   {\small\texttt{EndB}} = Center of end B. 
 

 \item 
   {\small\texttt{C, D}} = Controls for the radii of end B. 
 

\end{itemize}
\index{Connect\_\-Spheres}

   {\small\texttt{Connect\_\-Spheres(PtA, RadiusA, PtB, RadiusB)}}. This macro creates a cone that will smoothly join two spheres. It creates only the cone object, 
 however, you will have to supply the spheres yourself or use the Round\_\-Cone2() macro instead.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA}} = Center of sphere A. 
 

 \item 
   {\small\texttt{RadiusA}} = Radius of sphere A. 
 

 \item 
   {\small\texttt{PtB}} = Center of sphere B. 
 

 \item 
   {\small\texttt{RadiusB}} = Radius of sphere B. 
 

\end{itemize}
\index{Wire\_\-Box\_\-Union}

   {\small\texttt{Wire\_\-Box\_\-Union(PtA, PtB, Radius),\newline  Wire\_\-Box\_\-Merge(PtA, PtB, Radius),\newline  Wire\_\-Box(PtA, PtB, Radius, UseMerge)}}. Creates a 
 wire-\discretionary{}{}{}frame box from cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA}} = Lower-\discretionary{}{}{}left-\discretionary{}{}{}front corner of box. 
 

 \item 
   {\small\texttt{PtB}} = Upper-\discretionary{}{}{}right-\discretionary{}{}{}back corner of box. 
 

 \item 
   {\small\texttt{Radius}} = The radius of the cylinders and spheres composing the object. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Round\_\-Box\_\-Union}

   {\small\texttt{Round\_\-Box\_\-Union(PtA, PtB, EdgeRadius),\newline  Round\_\-Box\_\-Merge(PtA, PtB, EdgeRadius),\newline  Round\_\-Box(PtA, PtB, EdgeRadius, UseMerge)}}. 
 Creates a box with rounded edges from boxes, cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points. 
 The result is slightly different from a superellipsoid, which has no truely flat areas.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA}} = Lower-\discretionary{}{}{}left-\discretionary{}{}{}front corner of box. 
 

 \item 
   {\small\texttt{PtB}} = Upper-\discretionary{}{}{}right-\discretionary{}{}{}back corner of box. 
 

 \item 
   {\small\texttt{EdgeRadius}} = The radius of the edges of the box. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Round\_\-Cylinder\_\-Union}

   {\small\texttt{Round\_\-Cylinder\_\-Union(PtA, PtB, Radius, EdgeRadius),\newline  Round\_\-Cylinder\_\-Merge(PtA, PtB, Radius, EdgeRadius),\newline  Round\_\-Cylinder(PtA, 
 PtB, Radius, EdgeRadius, UseMerge)}}. Creates a cylinder with rounded edges from cylinders and tori. The resulting object will fit entirely within a cylinder 
 object with the same end points and radius. The result is slightly different from a superellipsoid, which has no truely flat areas.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA, PtB}} = The end points of the cylinder. 
 

 \item 
   {\small\texttt{Radius}} = The radius of the cylinder. 
 

 \item 
   {\small\texttt{EdgeRadius}} = The radius of the edges of the cylinder. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Round\_\-Cone\_\-Union}

   {\small\texttt{Round\_\-Cone\_\-Union(PtA, RadiusA, PtB, RadiusB, EdgeRadius),\newline  Round\_\-Cone\_\-Merge(PtA, RadiusA, PtB, RadiusB, EdgeRadius),\newline  
 Round\_\-Cone(PtA, RadiusA, PtB, RadiusB, EdgeRadius, UseMerge)}} Creates a cone with rounded edges from cones and tori. The resulting object will fit 
 entirely within a cone object with the same end points and radii.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA, PtB}} = The end points of the cone. 
 

 \item 
   {\small\texttt{RadiusA, RadiusB}} = The radii of the cone. 
 

 \item 
   {\small\texttt{EdgeRadius}} = The radius of the edges of the cone. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Round\_\-Cone2\_\-Union}

   {\small\texttt{Round\_\-Cone2\_\-Union(PtA, RadiusA, PtB, RadiusB),\newline  Round\_\-Cone2\_\-Merge(PtA, RadiusA, PtB, RadiusB),\newline  Round\_\-Cone2(PtA, RadiusA, PtB, 
 RadiusB, UseMerge)}}. Creates a cone with rounded edges from a cone and two spheres. The resulting object will not fit entirely within a cone object with the 
 same end points and radii because of the spherical caps. The end points are not used for the conical portion, but for the spheres, a suitable cone is then 
 generated to smoothly join them.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA, PtB}} = The centers of the sphere caps. 
 

 \item 
   {\small\texttt{RadiusA, RadiusB}} = The radii of the sphere caps. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Round\_\-Cone3\_\-Union}

   {\small\texttt{Round\_\-Cone3\_\-Union(PtA, RadiusA, PtB, RadiusB),\newline  Round\_\-Cone3\_\-Merge(PtA, RadiusA, PtB, RadiusB)\newline  Round\_\-Cone3(PtA, RadiusA, PtB, 
 RadiusB, UseMerge)}}. Like Round\_\-Cone2(), this creates a cone with rounded edges from a cone and two spheres, and the resulting object will not fit entirely 
 within a cone object with the same end points and radii because of the spherical caps. The difference is that this macro takes the end points of the conical 
 portion and moves the spheres to be flush with the surface, instead of putting the spheres at the end points and generating a cone to join them.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{PtA, PtB}} = The end points of the cone. 
 

 \item 
   {\small\texttt{RadiusA, RadiusB}} = The radii of the cone. 
 

 \item 
   {\small\texttt{UseMerge}} = Whether or not to use a merge. 
 

\end{itemize}
\index{Quad}

   {\small\texttt{Quad(A, B, C, D)}} and {\small\texttt{Smooth\_\-Quad(A, NA, B, NB, C, NC, D, ND)}}. These macros create "quads", 4-sided polygonal 
 objects, using triangle pairs.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A, B, C, D}} = Vertices of the quad. 
 

 \item 
   {\small\texttt{NA, NB, NC, ND}} = Vertex normals of the quad. 
 

\end{itemize}

\subsubsection{The HF Macros}

% reference/000405.html



   There are several HF macros in \discretionary{shapes.}{}{shapes.}inc, which generate meshes in various shapes. All the HF macros have these things in common: 


\begin{itemize}
 
 \item 
   The HF macros do not directly use an image for input, but evaluate a user-\discretionary{}{}{}defined function. The macros deform the surface based on the function values. 
 

 \item 
   The macros can either write to a file to be included later, or create an object directly. If you want to output to a file, simply specify a filename. 
  If you want to create an object directly, specify "" as the file name (an empty string). 
 

 \item 
   The function values used for the heights will be taken from the square that goes from $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}0$>$ if UV height mapping is on. 
  Otherwise the function values will be taken from the points where the surface is (before the deformation). 
 

 \item 
   The texture you apply to the shape will be evaluated in the square that goes from $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ to $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}0$>$ if UV texture mapping is on. Otherwise 
  the texture is evaluated at the points where the surface is (after the deformation. 
 

\end{itemize}


   The usage of the different HF macros is described below.\index{HF\_\-Square} 



   {\small\texttt{HF\_\-Square (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, MnExt, MxExt)}}. This macro generates a mesh in the form of a square 
 height field, similar to the built-\discretionary{}{}{}in height\_\-field primitive. Also see the general description of the HF macros above.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Function}} = The function to use for deforming the height field. 
 

 \item 
   {\small\texttt{UseUVheight}} = A boolean value telling the macro whether or not to use UV height mapping. 
 

 \item 
   {\small\texttt{UseUVtexture}} = A boolean value telling the macro whether or not to use UV texture mapping. 
 

 \item 
   {\small\texttt{Res}} = A 2D vector specifying the resolution of the generated mesh. 
 

 \item 
   {\small\texttt{Smooth}} = A boolean value telling the macro whether or not to smooth the generated mesh. 
 

 \item 
   {\small\texttt{FileName}} = The name of the output file. 
 

 \item 
   {\small\texttt{MnExt}} = Lower-\discretionary{}{}{}left-\discretionary{}{}{}front corner of a box containing the height field. 
 

 \item 
   {\small\texttt{MxExt}} = Upper-\discretionary{}{}{}right-\discretionary{}{}{}back corner of a box containing the height field. 
 

\end{itemize}
\index{HF\_\-Sphere}

   {\small\texttt{HF\_\-Sphere(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Center, Radius, Depth)}}. This macro generates a mesh in the form of a 
 spherical height field. When UV-\discretionary{}{}{}mapping is used, the UV square will be wrapped around the sphere starting at +x and going anti-\discretionary{}{}{}clockwise around the y axis. 
 Also see the general description of the HF macros above. Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Function}} = The function to use for deforming the height field. 
 

 \item 
   {\small\texttt{UseUVheight}} = A boolean value telling the macro whether or not to use UV height mapping. 
 

 \item 
   {\small\texttt{UseUVtexture}} = A boolean value telling the macro whether or not to use UV texture mapping. 
 

 \item 
   {\small\texttt{Res}} = A 2D vector specifying the resolution of the generated mesh. 
 

 \item 
   {\small\texttt{Smooth}} = A boolean value telling the macro whether or not to smooth the generated mesh. 
 

 \item 
   {\small\texttt{FileName}} = The name of the output file. 
 

 \item 
   {\small\texttt{Center}} = The center of the height field before being displaced, the displacement can, and most likely will, make the object 
  off-\discretionary{}{}{}center. 
 

 \item 
   {\small\texttt{Radius}} = The starting radius of the sphere, before being displaced. 
 

 \item 
   {\small\texttt{Depth}} = The depth of the height field. 
 

\end{itemize}
\index{HF\_\-Cylinder}

   {\small\texttt{HF\_\-Cylinder(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, EndA, EndB, \discretionary{Radius,}{}{Radius,}Depth)}}. This macro generates a mesh in the form 
 of an open-\discretionary{}{}{}ended cylindrical height field. When UV-\discretionary{}{}{}mapping is used, the UV square will be wrapped around the cylinder. Also see the general description of the 
 HF macros above.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Function}} = The function to use for deforming the height field. 
 

 \item 
   {\small\texttt{UseUVheight}} = A boolean value telling the macro whether or not to use UV height mapping. 
 

 \item 
   {\small\texttt{UseUVtexture}} = A boolean value telling the macro whether or not to use UV texture mapping. 
 

 \item 
   {\small\texttt{Res}} = A 2D vector specifying the resolution of the generated mesh. 
 

 \item 
   {\small\texttt{Smooth}} = A boolean value telling the macro whether or not to smooth the generated mesh. 
 

 \item 
   {\small\texttt{FileName}} = The name of the output file. 
 

 \item 
   {\small\texttt{EndA, EndB}} = The end points of the cylinder. 
 

 \item 
   {\small\texttt{Radius}} = The (pre-\discretionary{}{}{}displacement) radius of the cylinder. 
 

 \item 
   {\small\texttt{Depth}} = The depth of the height field. 
 

\end{itemize}
\index{HF\_\-Torus}

   {\small\texttt{HF\_\-Torus (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Major, Minor, Depth)}}. This macro generates a mesh in the form of a 
 torus-\discretionary{}{}{}shaped height field. When UV-\discretionary{}{}{}mapping is used, the UV square is wrapped around similar to spherical or cylindrical mapping. However 
 the top and bottom edges of the map wrap over and under the torus where they meet each other on the inner rim. Also see the general description of the HF 
 macros above.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Function}} = The function to use for deforming the height field. 
 

 \item 
   {\small\texttt{UseUVheight}} = A boolean value telling the macro whether or not to use UV height mapping. 
 

 \item 
   {\small\texttt{UseUVtexture}} = A boolean value telling the macro whether or not to use UV texture mapping. 
 

 \item 
   {\small\texttt{Res}} = A 2D vector specifying the resolution of the generated mesh. 
 

 \item 
   {\small\texttt{Smooth}} = A boolean value telling the macro whether or not to smooth the generated mesh. 
 

 \item 
   {\small\texttt{FileName}} = The name of the output file. 
 

 \item 
   {\small\texttt{Major}} = The major radius of the torus. 
 

 \item 
   {\small\texttt{Minor}} = The minor radius of the torus. 
 

\end{itemize}

\subsection{shapes\_\discretionary{old.}{}{old.}inc}

% reference/000404.html


\begin{description}
 
 \item 
   {\small\texttt{Ellipsoid, Sphere}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Unit-\discretionary{}{}{}radius sphere at the origin. 
 \end{list}

 \item 
   {\small\texttt{Cylinder\_\-X, Cylinder\_\-Y, Cylinder\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Infinite cylinders. 
 \end{list}

 \item 
   {\small\texttt{QCone\_\-X, QCone\_\-Y, QCone\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Infinite cones. 
 \end{list}

 \item 
   {\small\texttt{Cone\_\-X, Cone\_\-Y, Cone\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Closed capped cones: unit-\discretionary{}{}{}radius at -1 and 0 radius at +1 along each axis. 
 \end{list}

 \item 
   {\small\texttt{Plane\_\-YZ, Plane\_\-XZ, Plane\_\-XY}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Infinite planes passing through the origin. 
 \end{list}

 \item 
   {\small\texttt{Paraboloid\_\-X, Paraboloid\_\-Y, Paraboloid\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y\^{}2 + z\^{}2 - x = 0 
 \end{list}

 \item 
   {\small\texttt{Hyperboloid, Hyperboloid\_\-Y}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y - x\^{}2 + z\^{}2 = 0 
 \end{list}

 \item 
   {\small\texttt{UnitBox, Cube}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A cube 2 units on each side, centered on the origin. 
 \end{list}

 \item 
   {\small\texttt{Disk\_\-X, Disk\_\-Y, Disk\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   "Capped" cylinders, with a radius of 1 unit and a length of 2 units, 
  centered on the origin. 
 \end{list}

\end{description}

\subsection{\discretionary{shapes2.}{}{shapes2.}inc}

% reference/000403.html


\begin{description}
 
 \item 
   {\small\texttt{Tetrahedron}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   4-sided regular polyhedron. 
 \end{list}

 \item 
   {\small\texttt{Octahedron}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   8-sided regular polyhedron. 
 \end{list}

 \item 
   {\small\texttt{Dodecahedron}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   12-sided regular polyhedron. 
 \end{list}

 \item 
   {\small\texttt{Icosahedron}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   20-sided regular polyhedron. 
 \end{list}

 \item 
   {\small\texttt{Rhomboid}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Three dimensional 4-sided diamond, basically a sheared box. 
 \end{list}

 \item 
   {\small\texttt{Hexagon}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   6-sided regular polygonal solid, axis along x. 
 \end{list}

 \item 
   {\small\texttt{HalfCone\_\-Y}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Convenient finite cone primitive, pointing up in the Y axis. 
 \end{list}

 \item 
   {\small\texttt{Pyramid}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   4-sided pyramid (union of triangles, can not be used in CSG). 
 \end{list}

 \item 
   {\small\texttt{Pyramid2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   4-sided pyramid (intersection of planes, can be used in CSG). 
 \end{list}

 \item 
   {\small\texttt{Square\_\-X, Square\_\-Y, Square\_\-Z}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Finite planes stretching 1 unit along each axis. In other words, 2X2 unit squares. 
 \end{list}

\end{description}

\subsection{\discretionary{shapesq.}{}{shapesq.}inc}

% reference/000402.html


\begin{description}
 
 \item 
   {\small\texttt{Bicorn}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This curve looks like the top part of a paraboloid, bounded from below by another 
  paraboloid. The basic equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y\^{}2 - (x\^{}2 + z\^{}2) y\^{}2 - (x\^{}2 + z\^{}2 + 2 y - 1)\^{}2 = 
 \end{list}

 \item 
   {\small\texttt{Crossed\_\-Trough}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This is a surface with four pieces that sweep up from the x-\discretionary{}{}{}z plane. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The equation is: y = x\^{}2 z\^{}2 
 \end{list}

 \item 
   {\small\texttt{Cubic\_\-Cylinder}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A drop coming out of water? This is a curve formed by using the equation: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y = 1/2 x\^{}2 (x + 1) 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   as the radius of a cylinder having the x-\discretionary{}{}{}axis as its central axis. The final form 
  of the equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y\^{}2 + z\^{}2 = 0.5 (x\^{}3 + x\^{}2) 
 \end{list}

 \item 
   {\small\texttt{Cubic\_\-Saddle\_\-1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A cubic saddle. The equation is: z = x\^{}3 - y\^{}3 
 \end{list}

 \item 
   {\small\texttt{Devils\_\-Curve}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Variant of a devil's curve in 3-space. This figure has a top and bottom part that 
  are very similar to a hyperboloid of one sheet, however the central region is pinched in the middle leaving two teardrop shaped holes. The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   x\^{}4 + 2 x\^{}2 z\^{}2 - 0.36 x\^{}2 - y\^{}4 + 0.25 y\^{}2 + z\^{}4 = 0 
 \end{list}

 \item 
   {\small\texttt{Folium}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This is a folium rotated about the x-\discretionary{}{}{}axis. The formula is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   2 x\^{}2 - 3 x y\^{}2 - 3 x z\^{}2 + y\^{}2 + z\^{}2 = 0 
 \end{list}

 \item 
   {\small\texttt{Glob\_\-5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Glob - sort of like basic teardrop shape. The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   y\^{}2 + z\^{}2 = 0.5 x\^{}5 + 0.5 x\^{}4 
 \end{list}

 \item 
   {\small\texttt{Twin\_\-Glob}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Variant of a lemniscate - the two lobes are much more teardrop-\discretionary{}{}{}like. 
 \end{list}

 \item 
   {\small\texttt{Helix, Helix\_\-1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Approximation to the helix z = arctan(y/x). The helix can be approximated with an 
  algebraic equation (kept to the range of a quartic) with the following steps: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   tan(z) = y/x =$>$ sin(z)/cos(z) = y/x =$>$\newline  (1) x sin(z) - y cos(z) = 0 
  Using the taylor expansions for sin, cos about z = 0,\newline  sin(z) = z - z\^{}3/3! + z\^{}5/5! - ...\newline  cos(z) = 1 - z\^{}2/2! + z\^{}6/6! - ...\newline  
  Throwing out the high order terms, the expression (1) can be written as:\newline  x (z - z\^{}3/6) - y (1 + z\^{}2/2) = 0, or\newline \newline  (2) -1/6 x z\^{}3 + x 
  z + 1/2 y z\^{}2 - y = 0\newline  This helix (2) turns 90 degrees in the range 0 $<$= z $<$= sqrt(2)/2. By using scale $<$2 2 2$>$, the helix defined below 
  turns 90 degrees in the range 0 $<$= z $<$= sqrt(2) = 1.4042. 
 \end{list}

 \item 
   {\small\texttt{Hyperbolic\_\-Torus}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Hyperbolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure 
  is generated by sweeping a circle along the arms of a hyperbola. The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   x\^{}4 + 2 x\^{}2 y\^{}2 - 2 x\^{}2 z\^{}2 - 104 x\^{}2 + y\^{}4 - 2 y\^{}2 z\^{}2 + 56 y\^{}2 + z\^{}4 + 104 z\^{}2 + 
  784 = 0 
 \end{list}

 \item 
   {\small\texttt{Lemniscate}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Lemniscate of Gerono. This figure looks like two teardrops with their pointed ends 
  connected. It is formed by rotating the Lemniscate of Gerono about the x-\discretionary{}{}{}axis. The formula is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   x\^{}4 - x\^{}2 + y\^{}2 + z\^{}2 = 0 
 \end{list}

 \item 
   {\small\texttt{Quartic\_\-Loop\_\-1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This is a figure with a bumpy sheet on one side and something that looks like a 
  paraboloid (but with an internal bubble). The formula is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   (x\^{}2 + y\^{}2 + a c x)\^{}2 - (x\^{}2 + y\^{}2)(c - a x)\^{}2 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   -99*x\^{}4+40*x\^{}3-98*x\^{}2*y\^{}2-98*x\^{}2*z\^{}2+99*x\^{}2+40*x*y\^{}2 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   +40*x*z\^{}2+y\^{}4+2*y\^{}2*z\^{}2-y\^{}2+z\^{}4-z\^{}2 
 \end{list}

 \item 
   {\small\texttt{Monkey\_\-Saddle}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This surface has three parts that sweep up and three down. This gives a saddle that 
  has a place for two legs and a tail... The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{z = c (x\^{}3 - 3 x y\^{}2)}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The value c gives a vertical scale to the surface - the smaller the value of c, the 
  flatter the surface will be (near the origin). 
 \end{list}

 \item 
   {\small\texttt{Parabolic\_\-Torus\_\-40\_\-12}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Parabolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure is 
  generated by sweeping a circle along the arms of a parabola. The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   x\^{}4 + 2 x\^{}2 y\^{}2 - 2 x\^{}2 z - 104 x\^{}2 + y\^{}4 - 2 y\^{}2 z + 56 y\^{}2 + z\^{}2 + 104 z + 784 = 
  0 
 \end{list}

 \item 
   {\small\texttt{Piriform}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This figure looks like a hersheys kiss. It is formed by sweeping a Piriform about 
  the x-\discretionary{}{}{}axis. A basic form of the equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   (x\^{}4 - x\^{}3) + y\^{}2 + z\^{}2 = 0. 
 \end{list}

 \item 
   {\small\texttt{Quartic\_\-Paraboloid}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Quartic parabola - a 4th degree polynomial (has two bumps at the bottom) that has 
  been swept around the z axis. The equation is: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   0.1 x\^{}4 - x\^{}2 - y\^{}2 - z\^{}2 + 0.9 = 0 
 \end{list}

 \item 
   {\small\texttt{Quartic\_\-Cylinder}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Quartic Cylinder - a Space Needle? 
 \end{list}

 \item 
   {\small\texttt{Steiner\_\-Surface}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Steiners quartic surface 
 \end{list}

 \item 
   {\small\texttt{Torus\_\-40\_\-12}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Torus having major radius sqrt(40), minor radius sqrt(12). 
 \end{list}

 \item 
   {\small\texttt{Witch\_\-Hat}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Witch of Agnesi. 
 \end{list}

 \item 
   {\small\texttt{Sinsurf}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very rough approximation to the sin-\discretionary{}{}{}wave surface z = sin(2 pi x y). 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   In order to get an approximation good to 7 decimals at a distance of 1 from the 
  origin would require a polynomial of degree around 60, which would require around \discretionary{200,}{}{200,}000 coefficients. For best results, scale by something like $<$1 1 
  0.2$>$. 
 \end{list}

\end{description}

\section{\discretionary{skies.}{}{skies.}inc, \discretionary{stars.}{}{stars.}inc}

% reference/000363.html



   These files contain some predefined skies for you to use in your scenes. 



   \discretionary{skies.}{}{skies.}inc:\newline  There are textures and pigment definitions in this file. All pigment definitions start with "P\_", all sky\_\-spheres start with 
 "S\_", all textures start with "T\_", and all objects start with "O\_". 



   \discretionary{stars.}{}{stars.}inc:\newline  This file contains predefined starfield textures. The starfields become denser and more colorful with the number, with Starfield6 being 
 the densest and most colorful. 


\subsection{\discretionary{skies.}{}{skies.}inc}

% reference/000362.html



   Pigments: 


\begin{description}
 
 \item 
   {\small\texttt{P\_\-Cloud1}} 
 

 \item 
   {\small\texttt{P\_\-Cloud2}} 
 

 \item 
   {\small\texttt{P\_\-Cloud3}} 
 

\end{description}


   Sky Spheres: 


\begin{description}
 
 \item 
   {\small\texttt{S\_\-Cloud1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This sky\_\-sphere uses P\_\-Cloud2 and P\_\-Cloud3. 
 \end{list}

 \item 
   {\small\texttt{S\_\-Cloud2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This sky\_\-sphere uses P\_\-Cloud4. 
 \end{list}

 \item 
   {\small\texttt{S\_\-Cloud3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This sky\_\-sphere uses P\_\-Cloud2. 
 \end{list}

 \item 
   {\small\texttt{S\_\-Cloud4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This sky\_\-sphere uses P\_\-Cloud3. 
 \end{list}

 \item 
   {\small\texttt{S\_\-Cloud5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This sky\_\-sphere uses a custom pigment. 
 \end{list}

\end{description}


   Textures: 


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Cloud1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   2-layer texture using P\_\-Cloud1 pigment, contains clear regions. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Cloud2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   1-layer texture, contains clear regions. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Cloud3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   2-layer texture, contains clear regions. 
 \end{list}

\end{description}


   Objects: 


\begin{description}
 
 \item 
   {\small\texttt{O\_\-Cloud1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Sphere, radius 10000 with T\_\-Cloud1 texture. 
 \end{list}

 \item 
   {\small\texttt{O\_\-Cloud2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Union of 2 planes, with T\_\-Cloud2 and T\_\-Cloud3. 
 \end{list}

\end{description}

\subsection{\discretionary{stars.}{}{stars.}inc}

% reference/000406.html


\begin{description}
 
 \item 
   {\small\texttt{Starfield1}} 
 

 \item 
   {\small\texttt{Starfield2}} 
 

 \item 
   {\small\texttt{Starfield3}} 
 

 \item 
   {\small\texttt{Starfield4}} 
 

 \item 
   {\small\texttt{Starfield5}} 
 

 \item 
   {\small\texttt{Starfield6}} 
 

\end{description}

\section{\discretionary{stones.}{}{stones.}inc, \discretionary{stones1.}{}{stones1.}inc, \discretionary{stones2.}{}{stones2.}inc, \discretionary{stoneold.}{}{stoneold.}inc}

% reference/000361.html



   The two files \discretionary{stones1.}{}{stones1.}inc and \discretionary{stones2.}{}{stones2.}inc contain lists of predefined stone textures. 



   The file "\discretionary{stones1.}{}{stones1.}inc" contains texture definitions for T\_\-Grnt0 to T\_\-Grnt29, T\_\-Grnt1a to T\_\-Grnt24a, and T\_\-Stone0 to T\_\-Stone24. 



   The T\_\-GrntXX, T\_\-GrntXXa, and CrackX textures are "building blocks that are used to create the final "usable" T\_\-StoneX textures (and other 
 textures that *you* design, of course!) 



   The T\_\-GrntXX textures generally contain no transparency, but the T\_\-GrntXXa textures do contain transparency. The CrackX textures are clear with thin opaque 
 bands, simulating cracks. 



   The file "\discretionary{stones2.}{}{stones2.}inc" provides additional stone textures, and contains texture definitions for T\_\-Stone25 to T\_\-Stone44. 



   The file "\discretionary{stones.}{}{stones.}inc" simply includes both "\discretionary{stones1.}{}{stones1.}inc" and "\discretionary{stones2.}{}{stones2.}inc", and the file "\discretionary{stoneold.}{}{stoneold.}inc" provides 
 backwards compatability for old scenes, the user is advised to use the textures in "\discretionary{stones1.}{}{stones1.}inc" instead. 


\subsection{\discretionary{stones1.}{}{stones1.}inc}

% reference/000360.html


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Grnt0}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray/Tan with Rose. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Creamy Whites with Yellow \& Light Gray. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Deep Cream with Light Rose, Yellow, Orchid, \& Tan. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Warm tans olive \& light rose with cream. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Orchid, Sand \& Mauve. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium Mauve \discretionary{Med.}{}{Med.}Rose \& Deep Cream. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt6}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Med. Orchid, Olive \& Dark Tan "mud pie". 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt7}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark Orchid, Olive \& Dark Putty. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt8}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Rose \& Light Cream Yellows 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt9}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light Steely Grays 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt10}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray Creams \& Lavender Tans 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt11}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Creams \& Grays Kahki 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt12}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Tan Cream \& Red Rose 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt13}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Cream Rose Orange 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt14}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Cream Rose \& Light Moss w/Light Violet 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt15}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Black with subtle chroma 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt16}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White Cream \& Peach 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt17}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Bug Juice \& Green 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt18}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Rose \& Creamy Yellow 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt19}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray Marble with White feather Viens 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt20}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White Marble with Gray feather Viens 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt21}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Green Jade 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt22}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Clear with White feather Viens (has some transparency) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt23}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light Tan to Mauve 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt24}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light Grays 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt25}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Moss Greens \& Tan 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt26}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Salmon with thin Green Viens 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt27}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark Green \& Browns 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt28}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Red Swirl 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt29}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White, Tan, w/ thin Red Viens 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{T\_\-Grnt0a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt0 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt1a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt1 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt2a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt2 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt3a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt3 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt4a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt4 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt5a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt5 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt6a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt6 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt7a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent T\_\-Grnt7 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt8a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Aqua Tints 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt9a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Creams With Cracks 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt10a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Cream Rose \& light yellow 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt11a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Light Grays 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt12a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Creams \& Tans 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt13a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Creams \& Grays 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt14a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Cream Rose \& light moss 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt15a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transmit Sand \& light Orange 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt16a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Cream Rose \& light moss (again?) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt17a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   ??? 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt18a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   ??? 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt19a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray Marble with White feather Viens with Transmit 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt20a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White Feather Viens 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt21a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Thin White Feather Viens 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt22a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   ??? 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt23a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Transparent Green Moss 
 \end{list}

 \item 
   {\small\texttt{T\_\-Grnt24a}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   ??? 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{T\_\-Crack1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   T\_\-Crack \& Red Overtint 
 \end{list}

 \item 
   {\small\texttt{T\_\-Crack2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Translucent Dark T\_\-Cracks 
 \end{list}

 \item 
   {\small\texttt{T\_\-Crack3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Overtint Green w/ Black T\_\-Cracks 
 \end{list}

 \item 
   {\small\texttt{T\_\-Crack4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Overtint w/ White T\_\-Crack 
 \end{list}

\end{description}


   The StoneXX textures are the complete textures, ready to use. 


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Stone1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Deep Rose \& Green Marble with large White Swirls 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light Greenish Tan Marble with Agate style veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Rose \& Yellow Marble with fog white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Tan Marble with Rose patches 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White Cream Marble with Pink veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone6}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Rose \& Yellow Cream Marble 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone7}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light Coffee Marble with darker patches 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone8}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray Granite with white patches 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone9}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White \& Light Blue Marble with light violets 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone10}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark Brown \& Tan swirl Granite with gray undertones 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone11}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Rose \& White Marble with dark tan swirl 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone12}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White \& Pinkish Tan Marble 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone13}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium Gray Blue Marble 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone14}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Tan \& Olive Marble with gray white veins 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone15}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Deep Gray Marble with white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone16}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Peach \& Yellow Marble with white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone17}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White Marble with gray veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone18}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Green Jade with white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone19}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Peach Granite with white patches \& green trim 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone20}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Brown \& Olive Marble with white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone21}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Red Marble with gray \& white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone22}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark Tan Marble with gray \& white veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone23}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Peach \& Cream Marble with orange veining 
 \end{list}

 \item 
   {\small\texttt{T\_\-Stone24}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Green \& Tan Moss Marble 
 \end{list}

\end{description}

\subsection{\discretionary{stones2.}{}{stones2.}inc}

% reference/000407.html



   {\small\texttt{T\_\-Stone25, ..., T\_\-Stone44}} 


\section{\discretionary{stdinc.}{}{stdinc.}inc}

% reference/000359.html



   This file simply includes the most commonly used include files, so you can get all of them with a single \#include. The files included are: 


\begin{itemize}
 
 \item 
   \discretionary{colors.}{}{colors.}inc 
 

 \item 
   \discretionary{shapes.}{}{shapes.}inc 
 

 \item 
   \discretionary{transforms.}{}{transforms.}inc 
 

 \item 
   \discretionary{consts.}{}{consts.}inc 
 

 \item 
   \discretionary{functions.}{}{functions.}inc 
 

 \item 
   \discretionary{math.}{}{math.}inc 
 

 \item 
   \discretionary{rand.}{}{rand.}inc 
 

\end{itemize}

\section{\discretionary{strings.}{}{strings.}inc}

% reference/000358.html



   This include contains macros for manipulating and generating text strings.\index{CRGBStr} 



   {\small\texttt{CRGBStr(C, MinLen, Padding)}} and {\small\texttt{CRGBFTStr(C, MinLen, Padding)}}\newline  These macros convert a color to a string. The format 
 of the output string is "rgb $<$ R, G, B$>$" or "rgbft $<$ R, G, B, F, T$>$", depending on the macro being called.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{C}} = The color to be turned into a string. 
 

 \item 
   {\small\texttt{MinLen}} = The minimum length of the individual components, analogous to the second parameter of str(). 
 

 \item 
   {\small\texttt{Padding}} = The padding to use for the components, see the third parameter of the str() function for details. 
 

\end{itemize}
\index{Str! \discretionary{strings.}{}{strings.}inc}

   {\small\texttt{Str(A)}}. This macro creates a string containing a float with the systems default precision. It is a shortcut for using the str() function.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A}} = The float to be converted to a string. 
 

\end{itemize}
\index{Vstr! \discretionary{strings.}{}{strings.}inc}\index{VStr2D! short form}

   {\small\texttt{VStr2D(V), VStr(V)}}. These macros create strings containing vectors using POV syntax ($<$\discretionary{X,}{}{X,}\discretionary{Y,}{}{Y,}Z$>$) with the default system precision. 
 VStr2D() works with 2D vectors, VStr() with 3D vectors. They are shortcuts for using the {\small\texttt{vstr()}} function.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = The vector to be converted to a string. 
 

\end{itemize}
\index{Vstr2D! long form}

   {\small\texttt{Vstr2D(\discretionary{V,}{}{V,}\discretionary{L,}{}{L,}P), Vstr(\discretionary{V,}{}{V,}\discretionary{L,}{}{L,}P)}}. These macros create strings containing vectors using POV syntax ($<$\discretionary{X,}{}{X,}\discretionary{Y,}{}{Y,}Z$>$) with user specified precision. 
 Vstr2D() works with 2D vectors, Vstr() with 3D vectors. They are shortcuts for using the vstr() function. The function of L and P is the same as in {\small\texttt{vstr}} 
 specified in String Functions.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{V}} = The vector to be converted to a string. 
 

 \item 
   {\small\texttt{L}} = Minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum. 
 

 \item 
   {\small\texttt{P}} = Number of digits after the decimal point." 
 

\end{itemize}
\index{Triangle\_\-Str}

   {\small\texttt{Triangle\_\-Str(A, B, C)}} and {\small\texttt{Smooth\_\-Triangle\_\-Str(A, NA, B, NB, C, NC)}}\newline  These macros take vertex and normal information 
 and return a string representing a triangle in POV-\discretionary{}{}{}Ray syntax. They are mainly useful for generating mesh files.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A, B, C}} = Triangle vertex points. 
 

 \item 
   {\small\texttt{NA, NB, NC}} = Triangle vertex normals (Smooth\_\-Triangle\_\-Str() only). 
 

\end{itemize}
\index{Parse\_\-String}

   {\small\texttt{Parse\_\-String(String)}}. This macro takes a string, writes it to a file, and then includes that file. This has the effect of parsing that 
 string: "{\small\texttt{Parse\_\-String("MyColor")}}" will be seen by POV-\discretionary{}{}{}Ray as "{\small\texttt{MyColor}}".\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{String}} = The string to be parsed. 
 

\end{itemize}

\section{\discretionary{textures.}{}{textures.}inc}

% reference/000357.html



   This file contains many predefined textures, including wood, glass, and metal textures, and a few texture/pattern generation macros. 


\subsection{Stones}

% reference/000356.html



   Stone Pigments: 


\begin{description}
 
 \item 
   {\small\texttt{Jade\_\-Map, Jade}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Drew Wells' superb Jade. Color map works nicely with other textures, too. 
 \end{list}

 \item 
   {\small\texttt{Red\_\-Marble\_\-Map, Red\_\-Marble}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Classic white marble with red veins. Over-\discretionary{}{}{}worked, like checkers. 
 \end{list}

 \item 
   {\small\texttt{White\_\-Marble\_\-Map, White\_\-Marble}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White marble with black veins. 
 \end{list}

 \item 
   {\small\texttt{Blood\_\-Marble\_\-Map, Blood\_\-Marble}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light blue and black marble with a thin red vein. 
 \end{list}

 \item 
   {\small\texttt{Blue\_\-Agate\_\-Map, Blue\_\-Agate}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A grey blue agate -- kind of purplish. 
 \end{list}

 \item 
   {\small\texttt{Sapphire\_\-Agate\_\-Map, Sapphire\_\-Agate}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Deep blue agate -- almost glows. 
 \end{list}

 \item 
   {\small\texttt{Brown\_\-Agate\_\-Map, Brown\_\-Agate}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Brown and white agate -- very pretty. 
 \end{list}

 \item 
   {\small\texttt{Pink\_\-Granite\_\-Map, Pink\_\-Granite}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Umm, well, pink granite. 
 \end{list}

\end{description}


   Stone textures: 


\begin{description}
 
 \item 
   {\small\texttt{PinkAlabaster}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Gray-\discretionary{}{}{}pink alabaster or marble. Layers are scaled for a unit object and relative to 
  each other. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   
  
    \textbf{Note:} This texture has very tiny dark blue specks that are often mistaken for rendering errors. They are not errors. Just a strange texture design. 
   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Underlying surface is very subtly mottled with bozo. 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Second layer texture has some transmit values, yet a fair amount of color. 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Veining is kept quite thin in color map and by the largish scale. 
   \end{list}

  

 \end{list}

\end{description}

\subsection{Skies}

% reference/000413.html



   Sky pigments: 


\begin{description}
 
 \item 
   {\small\texttt{Blue\_\-Sky\_\-Map, Blue\_\-Sky}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Basic blue sky with clouds. 
 \end{list}

 \item 
   {\small\texttt{Bright\_\-Blue\_\-Sky}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Bright blue sky with very white clouds. 
 \end{list}

 \item 
   {\small\texttt{Blue\_\-Sky2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Another sky. 
 \end{list}

 \item 
   {\small\texttt{Blue\_\-Sky3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Small puffs of white clouds. 
 \end{list}

 \item 
   {\small\texttt{Blood\_\-Sky}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Red sky with yellow clouds -- very surreal. 
 \end{list}

 \item 
   {\small\texttt{Apocalypse}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Black sky with red and purple clouds. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Try adding turbulence values from 0.1 - 5.0 -- CdW 
 \end{list}

 \item 
   {\small\texttt{Clouds}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   White clouds with transparent sky. 
 \end{list}

 \item 
   {\small\texttt{FBM\_\-Clouds}} 
 

 \item 
   {\small\texttt{Shadow\_\-Clouds}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A multilayered cloud texture (a real texture, not a pigment). 
 \end{list}

\end{description}

\subsection{Woods}

% reference/000412.html



   Wood pigments: 



   Several wooden pigments by Tom Price: 


\begin{description}
 
 \item 
   {\small\texttt{Cherry\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A light reddish wood. 
 \end{list}

 \item 
   {\small\texttt{Pine\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A light tan wood whiteish rings. 
 \end{list}

 \item 
   {\small\texttt{Dark\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark wood with \discretionary{a,}{}{a,}ish hue to it. 
 \end{list}

 \item 
   {\small\texttt{Tan\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Light tan wood with brown rings. 
 \end{list}

 \item 
   {\small\texttt{White\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A very pale wood with tan rings -- kind of balsa-\discretionary{}{}{}ish. 
 \end{list}

 \item 
   {\small\texttt{Tom\_\-Wood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Brown wood - looks stained. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   {\small\texttt{DMFWood1, DMFWood2, DMFWood3, DMFWood4, DMFWood5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The scaling in these definitions is relative to a unit-\discretionary{}{}{}sized object (radius 1). 
  
    \textbf{Note:} woods are functionally equivalent to a log lying along the z axis. For best results, think like a woodcutter trying to extract the nicest 
   board out of that log. A little tilt along the x axis will give elliptical rings of grain like you would expect to find on most boards. Experiment. 
  

 \end{list}

\end{description}


   Wood textures: 


\begin{description}
 
 \item 
   {\small\texttt{DMFWood6}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   This is a three-\discretionary{}{}{}layer wood texture. Renders rather slowly because of the 
  transparent layers and the two layers of turbulence, but it looks great. Try other colors of "varnish" for simple variations. 
 \end{list}

 \item 
   {\small\texttt{DMFLightOak}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Is this really oak? I dunno. Quite light, maybe more like spruce. 
 \end{list}

 \item 
   {\small\texttt{DMFDarkOak}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Looks like old desk oak if used correctly. 
 \end{list}

 \item 
   {\small\texttt{EMBWood1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Wood by Eric Barish 
 \end{list}

\end{description}


   Doug Otwell woods: 


\begin{description}
 
 \item 
   {\small\texttt{Yellow\_\-Pine}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Yellow pine, close grained. 
 \end{list}

 \item 
   {\small\texttt{Rosewood}} 
 

 \item 
   {\small\texttt{Sandalwood}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   makes a great burled maple, too 
 \end{list}

\end{description}

\subsection{Glass}

% reference/000411.html



   {\small\texttt{Glass\_\-Finish}} is a generic glass finish, {\small\texttt{Glass\_\-Interior}} is a generic glass interior, it just adds an ior of 1.5. 



   Glass materials: 


\begin{description}
 
 \item 
   {\small\texttt{M\_\-Glass}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Just glass. 
 \end{list}

 \item 
   {\small\texttt{M\_\-Glass2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Probably more of a "Plexiglas" than glass. 
 \end{list}

 \item 
   {\small\texttt{M\_\-Glass3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An excellent lead crystal glass! 
 \end{list}

 \item 
   {\small\texttt{M\_\-Green\_\-Glass}} 
 

\end{description}


   Glass textures contributed by Norm Bowler, of Richland WA. NBglass\_\-finish is used by these materials. 


\begin{description}
 
 \item 
   {\small\texttt{M\_\-NBglass}} 
 

 \item 
   {\small\texttt{M\_\-NBoldglass}} 
 

 \item 
   {\small\texttt{M\_\-NBwinebottle}} 
 

 \item 
   {\small\texttt{M\_\-NBbeerbottle}} 
 

\end{description}


   A few color variations on Norm's glass. 


\begin{description}
 
 \item 
   {\small\texttt{M\_\-Ruby\_\-Glass}} 
 

 \item 
   {\small\texttt{M\_\-Dark\_\-Green\_\-Glass}} 
 

 \item 
   {\small\texttt{M\_\-Yellow\_\-Glass}} 
 

 \item 
   {\small\texttt{M\_\-Orange\_\-Glass}} 
 

 \item 
   {\small\texttt{M\_\-Vicks\_\-Bottle\_\-Glass}} 
 

\end{description}

\subsection{Metals}

% reference/000410.html



   Metal finishes: 


\begin{description}
 
 \item 
   {\small\texttt{Metal}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Generic metal finish. 
 \end{list}

 \item 
   {\small\texttt{SilverFinish}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Basic silver finish 
 \end{list}

 \item 
   {\small\texttt{Metallic\_\-Finish}} 
 

\end{description}


   Metal textures: 


\begin{description}
 
 \item 
   {\small\texttt{Chrome\_\-Metal, Brass\_\-Metal, Bronze\_\-Metal, Gold\_\-Metal, Silver\_\-Metal, Copper\_\-Metal}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A series of metallic textures using the Metal finish (except for Chrome\_\-Metal, 
  which has a custom finish). There are identical textures ending in \_Texture instead of \_Metal, but use of those names is discouraged. 
 \end{list}

 \item 
   {\small\texttt{Polished\_\-Chrome}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A highly reflective Chrome texture. 
 \end{list}

 \item 
   {\small\texttt{Polished\_\-Brass}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A highly reflective brass texture. 
 \end{list}

 \item 
   {\small\texttt{New\_\-Brass}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Beautiful military brass texture! 
 \end{list}

 \item 
   {\small\texttt{Spun\_\-Brass}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Spun Brass texture for cymbals \& such 
 \end{list}

 \item 
   {\small\texttt{Brushed\_\-Aluminum}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Brushed aluminum (brushed along X axis) 
 \end{list}

 \item 
   {\small\texttt{Silver1}} 
 

 \item 
   {\small\texttt{Silver2}} 
 

 \item 
   {\small\texttt{Silver3}} 
 

 \item 
   {\small\texttt{Brass\_\-Valley}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Sort of a "Black Hills Gold", black, white, and orange specks or 
  splotches. 
 \end{list}

 \item 
   {\small\texttt{Rust}} 
 

 \item 
   {\small\texttt{Rusty\_\-Iron}} 
 

 \item 
   {\small\texttt{Soft\_\-Silver}} 
 

 \item 
   {\small\texttt{New\_\-Penny}} 
 

 \item 
   {\small\texttt{Tinny\_\-Brass}} 
 

 \item 
   {\small\texttt{Gold\_\-Nugget}} 
 

 \item 
   {\small\texttt{Aluminum}} 
 

 \item 
   {\small\texttt{Bright\_\-Bronze}} 
 

\end{description}

\subsection{Special textures}

% reference/000409.html


\begin{description}
 
 \item 
   {\small\texttt{Candy\_\-Cane}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Red \& white stripes - Looks best on a y axis Cylinder. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   It "spirals" because it's gradient on two axis. 
 \end{list}

 \item 
   {\small\texttt{Peel}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Orange and Clear stripes spiral around the texture to make an object look like it 
  was "Peeled". Now, you too can be \discretionary{M.}{}{M.}C. Escher! 
 \end{list}

 \item 
   {\small\texttt{Y\_\-Gradient}} 
 

 \item 
   {\small\texttt{X\_\-Gradient}} 
 

 \item 
   {\small\texttt{M\_\-Water}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Wavy water material. Requires a sub-\discretionary{}{}{}plane, and may require scaling to fit your 
  scene. 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   WARNING: Water texture has been changed to M\_\-Water material, see explanation in the 
  "glass" section of this file. 
 \end{list}

 \item 
   {\small\texttt{Cork}} 
 

 \item 
   {\small\texttt{Lightning\_\-CMap1, Lightning1, and Lightning\_\-CMap2, Lightning2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   These are just lightning textures, they look like arcing electricity...earlier 
  versions misspelled them as "Lightening". 
 \end{list}

 \item 
   {\small\texttt{Starfield}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A starfield texture by Jeff Burton 
 \end{list}

\end{description}

\subsection{Texture and pattern macros}

% reference/000408.html

\index{Irregular\_\-Bricks\_\-Ptrn}

   {\small\texttt{Irregular\_\-Bricks\_\-Ptrn (Mortar Thickness, X-\discretionary{}{}{}scaling, Variation, Roundness)}}. This function pattern creates a pattern of bricks of varying 
 lengths on the x-\discretionary{}{}{}y plane. This can be useful in building walls that do not look like they were built by a computer. Note that mortar thickness between bricks 
 can vary somewhat, too.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Mortar Thickness}} = Thickness of the mortar (0-1). 
 

 \item 
   {\small\texttt{X-\discretionary{}{}{}scaling}} = The scaling of the bricks (but not the mortar) in the x direction. 
 

 \item 
   {\small\texttt{Variation}} = The amount by which brick lengths will vary (0=none, 1=100\%). 
 

 \item 
   {\small\texttt{Roundness}} = The roundness of the bricks (0.01=almost rectangular, 1=very round). 
 

\end{itemize}
\index{Tiles\_\-Ptrn}

   {\small\texttt{Tiles\_\-Ptrn()}}. This macro creates a repeating box pattern on the x-\discretionary{}{}{}y plane. It can be useful for creating grids. The cells shade continuously 
 from the center to the edges.\newline  Parameters: None. \index{Hex\_\-Tiles\_\-Ptrn} 



   {\small\texttt{Hex\_\-Tiles\_\-Ptrn()}}. This macro creates a pattern that is a sort of cross between the hexagon pattern and a repeating box pattern. The 
 hexagonal cells shade continuously from the center to the edges.\newline  Parameters: None. \index{Star\_\-Ptrn} 



   {\small\texttt{Star\_\-Ptrn (Radius, Points, Skip)}}. This macro creates a pattern that resembles a star. The pattern is in the x-\discretionary{}{}{}y plane, centered around the 
 origin.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Radius}} = The radius of a circle drawn through the points of the star. 
 

 \item 
   {\small\texttt{Points}} = The number of points on the star. 
 

 \item 
   {\small\texttt{Skip}} = The number of points to skip when drawing lines between points to form the star. A normal 5-pointed star skips 2 points. A Star 
  of David also skips 2 points. Skip must be less than Points/2 and greater than 0. Integers are preferred but not required. Skipping 1 point makes a regular 
  polygon with Points sides. 
 

 \item 
   {\small\texttt{Pigment}} = The pigment to be applied to the star. 
 

 \item 
   {\small\texttt{Background}} = The pigment to be applied to the background. 
 

\end{itemize}

\section{\discretionary{transforms.}{}{transforms.}inc}

% reference/000355.html



   Several useful transformation macros. All these macros produce transformations, you can use them anywhere you can use scale, rotate, etc. The descriptions 
 will assume you are working with an object, but the macros will work fine for textures, etc.\index{Shear\_\-Trans} 



   {\small\texttt{Shear\_\-Trans(A, B, C)}}. This macro reorients and deforms an object so its original XYZ axes point along A, B, and C, resulting in a shearing 
 effect when the vectors are not perpendicular. You can also use vectors of different lengths to affect scaling, or use perpendicular vectors to reorient the 
 object.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A, B, C}} = Vectors representing the new XYZ axes for the transformation. 
 

\end{itemize}
\index{Matrix\_\-Trans}

   {\small\texttt{Matrix\_\-Trans(A, B, C, D)}}. This macro provides a way to specify a matrix transform with 4 vectors. The effects are very similar to that of 
 the Shear\_\-Trans() macro, but the fourth parameter controls translation.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{A, B, C, D}} = Vectors for each row of the resulting matrix. 
 

\end{itemize}
\index{Axial\_\-Scale\_\-Trans}

   {\small\texttt{Axial\_\-Scale\_\-Trans(Axis, Amt)}}. A kind of directional scale, this macro will "stretch" an object along a specified axis.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Axis}} = A vector indicating the direction to stretch along. 
 

 \item 
   Amt = The amount to stretch. 
 

\end{itemize}
\index{Axis\_\-Rotate\_\-Trans}

   {\small\texttt{Axis\_\-Rotate\_\-Trans(Axis, Angle)}}. This is equivalent to the transformation done by the vaxis\_\-rotate() function, it rotates around an arbitrary 
 axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Axis}} = A vector representing the axis to rotate around. 
 

 \item 
   {\small\texttt{Angle}} = The amount to rotate by. 
 

\end{itemize}
\index{Rotate\_\-Around\_\-Trans}

   {\small\texttt{Rotate\_\-Around\_\-Trans(Rotation, Point)}}. Ordinary rotation operates around the origin, this macro rotates around a specific point.\newline  
 Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Rotation}} = The rotation vector, the same as the parameter to the rotate keyword. 
 

 \item 
   {\small\texttt{Point}} = The point to rotate around. 
 

\end{itemize}
\index{Reorient\_\-Trans}

   {\small\texttt{Reorient\_\-Trans(Axis1, Axis2)}}. This aligns {\small\texttt{Axis1}} to {\small\texttt{Axis2}} by rotating the object around a vector 
 perpendicular to both axis1 and axis2. \newline Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Axis1}} = Vector to be rotated. 
 

 \item 
   {\small\texttt{Axis2}} = Vectors to be rotated towards. 
 

\end{itemize}
\index{Point\_\-At\_\-Trans}

   {\small\texttt{Point\_\-At\_\-Trans(YAxis)}}. This macro is similar to Reorient\_\-Trans(), but it points the y axis along Axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{YAxis}} = The direction to point the y axis in. 
 

\end{itemize}
\index{Center\_\-Trans}

   {\small\texttt{Center\_\-Trans(Object, Axis)}}. Calculates a transformation which will center an object along a specified axis. You indicate the axes you want 
 to center along by adding "x", "y", and "z" together in the Axis parameter. 



   \textbf{Note:} this macro actually computes the transform to center the bounding box of the object, which may not be entirely accurate. There is no way to 
 define the "center" of an arbitrary object. 



   Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object the center transform is being computed for. 
 

 \item 
   {\small\texttt{Axis}} = The axes to center the object on. 
 

\end{itemize}


   Usage: 


{\small\begin{verbatim}
object {MyObj Center_Trans(MyObj, x)} //center along x axis
 \end{verbatim}}


   You can also center along multiple axes: 


{\small\begin{verbatim}
object {MyObj Center_Trans(MyObj, x+y)} //center along x and y axis
 \end{verbatim}}
\index{Align\_\-Trans}

   {\small\texttt{Align\_\-Trans(Object, Axis, Pt)}}. Calculates a transformation which will align the sides of the bounding box of an object to a point. Negative 
 values on Axis will align to the sides facing the negative ends of the coordinate system, positive values will align to the opposite sides, 0 means not to do 
 any alignment on that axis.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object being aligned. 
 

 \item 
   {\small\texttt{Axis}} = A combination of +x, +y, +z, -x, -y, and -z, or a vector where each component is -1, 0, or +1 specifying the faces of the 
  bounding box to align to the point. 
 

 \item 
   {\small\texttt{Point}} = The point to which to align the bounding box of the object. 
 

\end{itemize}


   Usage: 


{\small\begin{verbatim}
  object {
     MyObj 
     Align_Trans(MyObj, x, Pt) //Align right side of object to be
                               //coplanar with Pt
     Align_Trans(MyObj,-y, Pt) //Align bottom of object to be
                               // coplanar with Pt
  } 
 \end{verbatim}}
\index{vtransform}

   {\small\texttt{vtransform(Vect, Trans)}} and {\small\texttt{vinv\_\-transform(Vect, Trans)}}.\newline  The {\small\texttt{vtransform()}} macro takes a 
 transformation (rotate, scale, translate, etc...) and a point, and returns the result of applying the transformation to the point. The {\small\texttt{vinv\_\-transform()}} 
 macro is similar, but applies the inverse of the transform, in effect "undoing" the transformation. You can combine transformations by enclosing 
 them in a transform block.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Vect}} = The vector to which to apply the transformation. 
 

 \item 
   {\small\texttt{Trans}} = The transformation to apply to Vect. 
 

\end{itemize}
\index{spline\_\-trans}

   {\small\texttt{Spline\_\-Trans(Spline, Time, SkyVector, ForeSight, Banking)}}. This macro aligns an object to a spline for a given time value. The Z axis of the 
 object will point in the forward direction of the spline and the Y axis of the object will point upwards.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Spline}} = The spline that the object is aligned to. 
 

 \item 
   {\small\texttt{Time}} = The time value to feed to the spline, for example clock. 
 

 \item 
   {\small\texttt{Sky}} = The vector that is upwards in your scene, usually y. 
 

 \item 
   {\small\texttt{Foresight}} = A positive value that controls how much in advance the object will turn and bank. Values close to 0 will give precise 
  results, while higher values give smoother results. It will not affect parsing speed, so just find the value that looks best. 
 

 \item 
   {\small\texttt{Banking}} = How much the object tilts when turning. The amount of tilting is equally much controlled by the ForeSight value. 
 

\end{itemize}


   Usage: 


{\small\begin{verbatim}
   object {MyObj Spline_Trans(MySpline, clock, y, 0.1, 0.5)}
\end{verbatim}}

\section{\discretionary{woodmaps.}{}{woodmaps.}inc, \discretionary{woods.}{}{woods.}inc}

% reference/000354.html



   The file \discretionary{woodmaps.}{}{woodmaps.}inc contains color\_\-maps designed for use in wood textures. The M\_\-WoodXA maps are intended to be used in the first layer of a multilayer 
 texture, but can be used in single-\discretionary{}{}{}layer textures. The M\_\-WoodXB maps contain transparent areas, and are intended to be used in upper texture layers. 



   The file \discretionary{woods.}{}{woods.}inc contains predefined wood textures and pigments. 



   The pigments are prefixed with P\_, and do not have color\_\-maps, allowing you to specify a color map from \discretionary{woodmaps.}{}{woodmaps.}inc or create your own. There are two 
 groups, "A" and "B": the A series is designed to work better on the bottom texture layer, and the B series is designed for the upper 
 layers, with semitransparent color maps. The pigments with the same number were designed to work well together, but you do not necessarily have to use them 
 that way. 



   The textures are prefixed with T\_, and are ready to use. They are designed with the major axis of the woodgrain "cylinder" aligned along the Z 
 axis. With the exception of the few of the textures which have a small amount of rotation built-\discretionary{}{}{}in, the textures will exhibit a very straight grain pattern 
 unless you apply a small amount of x-\discretionary{}{}{}axis rotation to them (generally 2 to 4 degrees seems to work well). 


\subsection{\discretionary{woodmaps.}{}{woodmaps.}inc}

% reference/000353.html



   Color maps: 


\begin{description}
 
 \item 
   {\small\texttt{M\_\-Wood1A, ..., M\_\-Wood19A}} 
 

 \item 
   {\small\texttt{M\_\-Wood1B, ..., M\_\-Wood19B}} 
 

\end{description}

\subsection{\discretionary{woods.}{}{woods.}inc}

% reference/000414.html



   Pigments: 


\begin{description}
 
 \item 
   {\small\texttt{P\_\-WoodGrain1A, ..., P\_\-WoodGrainA}} 
 

 \item 
   {\small\texttt{P\_\-WoodGrain1B, ..., P\_\-WoodGrainB}} 
 

\end{description}


   Textures: 


\begin{description}
 
 \item 
   {\small\texttt{T\_\-Wood1}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Natural oak (light) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood2}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark brown 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Bleached oak (white) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood4}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Mahogany (purplish-\discretionary{}{}{}red) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood5}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark yellow with reddish overgrain 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood6}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Cocabola (red) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood7}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Yellow pine (ragged grain) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood8}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Dark brown. Walnut? 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood9}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Yellowish-\discretionary{}{}{}brown burl (heavily turbulated) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood10}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Soft pine (light yellow, smooth grain) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood11}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Spruce (yellowish, very straight, fine grain) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood12}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Another very dark brown. Walnut-\discretionary{}{}{}stained pine, perhaps? 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood13}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Very straight grained, whitish 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood14}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Red, rough grain 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood15}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium brown 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood16}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium brown 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood17}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Medium brown 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood18}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Orange 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood19, ..., T\_\-Wood30}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Golden Oak. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood31}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A light tan wood - heavily grained (variable coloration) 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood32}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A rich dark reddish wood, like rosewood, with smooth-\discretionary{}{}{}flowing grain 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood33}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Similar to T\_\-WoodB, but brighter 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood34}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Reddish-\discretionary{}{}{}orange, large, smooth grain. 
 \end{list}

 \item 
   {\small\texttt{T\_\-Wood35}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Orangish, with a grain more like a veneer than a plank 
 \end{list}

\end{description}

\section{Other files}

% reference/000352.html



   There are various other files in the include collection, including font files, color maps, and images for use in height fields or image\_\-maps, and includes 
 that are too small to have their own section. 


\subsection{\discretionary{logo.}{}{logo.}inc}

% reference/000351.html



   The official POV-\discretionary{}{}{}Ray logo designed by Chris Colefax, in two versions 


\begin{description}
 
 \item 
   {\small\texttt{Povray\_\-Logo}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The POV-\discretionary{}{}{}Ray logo object 
 \end{list}

 \item 
   {\small\texttt{Povray\_\-Logo\_\-Prism}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The POV-\discretionary{}{}{}Ray logo as a prism 
 \end{list}

 \item 
   {\small\texttt{Povray\_\-Logo\_\-Bevel}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The POV-\discretionary{}{}{}Ray logo as a beveled prism 
 \end{list}

\end{description}

\subsection{rad\_\discretionary{def.}{}{def.}inc}

% reference/000423.html



   This file defines a macro that sets some common radiosity settings. These settings are extremely general and are intended for ease of use, and do not 
 necessarily give the best results. 



   Usage:\newline  


{\small\begin{verbatim}
 #include "rad_def.inc"
 global_settings {
    ...
    radiosity {
       Rad_Settings(Setting, Normal, Media)
    }
 }
\end{verbatim}}


   Parameters: 


\begin{itemize}
 
 \item 
   Setting = Quality setting. Use one of the predefined constants:\newline  
  \begin{itemize}
   
   \item 
     Radiosity\_\-Default 
   

   \item 
     Radiosity\_\-Debug 
   

   \item 
     Radiosity\_\-Fast 
   

   \item 
     Radiosity\_\-Normal 
   

   \item 
     Radiosity\_\-2Bounce 
   

   \item 
     Radiosity\_\-Final 
   

   \item 
     Radiosity\_\-OutdoorLQ 
   

   \item 
     Radiosity\_\-OutdoorHQ 
   

   \item 
     Radiosity\_\-OutdoorLight 
   

   \item 
     Radiosity\_\-IndoorLQ 
   

   \item 
     Radiosity\_\-IndoorHQ 
   

  \end{itemize}
   
 

 \item 
   Normal = Boolean value, whether or not to use surface normal modifiers for radiosity samples. 
 

 \item 
   Media = Boolean value, whether or not to calculate media for radiosity samples. 
 

\end{itemize}

\subsection{\discretionary{screen.}{}{screen.}inc}

% reference/000422.html



   \discretionary{Screen.}{}{Screen.}inc will enable you to place objects and textures right in front of the camera. When you move the camera, the objects placed with \discretionary{screen.}{}{screen.}inc will 
 follow the movement and stay in the same position on the screen. One use of this is to place your signature or a logo in the corner of the image. 



   You can only use \discretionary{screen.}{}{screen.}inc with the perspective camera. \discretionary{Screen.}{}{Screen.}inc will automatically create a default camera definition for you when it is included. All 
 aspects of the camera can than be changed, by invoking the appropriate 'Set\_\-Camera\_...' macros in your scene. After calling these setup macros you can use the 
 macros Screen\_\-Object and Screen\_\-Plane. 



   \textbf{Note:} even though objects aligned using \discretionary{screen.}{}{screen.}inc follow the camera, they are still part of the scene. That means that they will be affected by 
 perspective, lighting, the surroundings etc. 



   For an example of use, see the \discretionary{screen.}{}{screen.}pov demo file. 



   {\small\texttt{Set\_\-Camera\_\-Location(Loc)}} Changes the position of the default camera to a new location as specified by the {\small\texttt{Loc}} vector. 



   {\small\texttt{Set\_\-Camera\_\-Look\_\-At(LookAt)}} Changes the position the default camera looks at to a new location as specified by the {\small\texttt{LookAt}} 
 vector. 



   {\small\texttt{Set\_\-Camera\_\-Aspect\_\-Ratio(Aspect)}} Changes the default aspect ratio, {\small\texttt{Aspect}} is a float value, usually width divided by the 
 height of the image. 



   {\small\texttt{Set\_\-Camera\_\-Aspect(\discretionary{Width,}{}{Width,}Height)}} Changes the default aspect ratio of the camera. 



   {\small\texttt{Set\_\-Camera\_\-Sky(Sky)}} Sets a new Sky-\discretionary{}{}{}vector for the camera. 



   {\small\texttt{Set\_\-Camera\_\-Zoom(Zoom)}} The amount to zoom in or out, {\small\texttt{Zoom}} is a float. 



   {\small\texttt{Set\_\-Camera\_\-Angle(Angle)}} Sets a new camera angle. 



   {\small\texttt{Set\_\-Camera(Location, LookAt, Angle)}} Set {\small\texttt{location}}, {\small\texttt{look\_\-at}} and {\small\texttt{angle}} in one go. 



   {\small\texttt{Reset\_\-Camera()}} Resets the camera to its default values. 



   {\small\texttt{Screen\_\-Object (Object, Position, Spacing, Confine, Scaling)}} Puts an object in front of the camera.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Object}} = The object to place in front of the screen. 
 

 \item 
   {\small\texttt{Position}} = UV coordinates for the object. $<$\discretionary{0,}{}{0,}0$>$ is lower left corner of the screen and $<$\discretionary{1,}{}{1,}1$>$ is upper right corner. 
 

 \item 
   {\small\texttt{Spacing}} = Float describing minimum distance from object to the borders. UV vector can be used to get different horizontal and vertical 
  spacing. 
 

 \item 
   {\small\texttt{Confine}} = Set to true to confine objects to visible screen area. Set to false to allow objects to be outside visible screen area. 
 

 \item 
   {\small\texttt{Scaling}} = If the object intersects or interacts with the scene, try to move it closer to the camera by decreasing Scaling. 
 

\end{itemize}


   {\small\texttt{Screen\_\-Plane (Texture, Scaling, BLCorner, TRCorner)}} Screen\_\-Plane is a macro that will place a texture of your choice on a plane right in 
 front of the camera.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Texture }} = The texture to be displayed on the camera plane. $<$\discretionary{0,}{}{0,}\discretionary{0,}{}{0,}0$>$ is lower left corner and $<$\discretionary{1,}{}{1,}\discretionary{1,}{}{1,}0$>$ is upper right 
  corner. 
 

 \item 
   {\small\texttt{Scaling }} = If the plane intersects or interacts with the scene, try to move it closer to the camera by decreasing Scaling. 
 

 \item 
   {\small\texttt{BLCorner }} = The bottom left corner of the Screen\_\-Plane. 
 

 \item 
   {\small\texttt{TRCorner }} = The top right corner of the Screen\_\-Plane. 
 

\end{itemize}

\subsection{\discretionary{stdcam.}{}{stdcam.}inc}

% reference/000421.html



   This file simply contains a camera, a light\_\-source, and a ground plane. 


\subsection{\discretionary{stage1.}{}{stage1.}inc}

% reference/000420.html



   This file simply contains a camera, a light\_\-source, and a ground plane, and includes \discretionary{colors.}{}{colors.}inc, \discretionary{textures.}{}{textures.}inc, and \discretionary{shapes.}{}{shapes.}inc. 


\subsection{\discretionary{sunpos.}{}{sunpos.}inc}

% reference/000419.html



   This file only contains the sunpos() macro\index{sunpos} 



   {\small\texttt{sunpos(Year, Month, Day, Hour, Minute, Lstm, LAT, LONG)}}. The macro returns the position of the sun, for a given date, time, and location on 
 earth. The suns position is also globally declared as the vector {\small\texttt{SolarPosition}}. Two other declared vectors are the {\small\texttt{Az}} 
 (Azimuth) and {\small\texttt{Al}} (Altitude), these can be useful for aligning an object (media container) with the sunlight.\newline  Assumption: in the 
 scene north is in the +Z direction, south is -Z.\newline  Parameters: 


\begin{itemize}
 
 \item 
   {\small\texttt{Year}}= The year in four digits. 
 

 \item 
   {\small\texttt{Month}}= The month number (1-12). 
 

 \item 
   {\small\texttt{Day}}= The day number (1-31). 
 

 \item 
   {\small\texttt{Hour}}= The hour of day in 24 hour format (0-23). 
 

 \item 
   {\small\texttt{Minute}}= The minutes (0-59). 
 

 \item 
   {\small\texttt{Lstm}}= Meridian of your local time zone in degrees (+1 hour = +15 deg, east = positive, west = negative) 
 

 \item 
   {\small\texttt{LAT}}= Lattitude in \discretionary{degrees.}{}{degrees.}decimal, northern hemisphere = positive, southern = negative 
 

 \item 
   {\small\texttt{LONG}}= Longitude in \discretionary{degrees.}{}{degrees.}decimal, east = positive, west is negative 
 

\end{itemize}


   Use : 


{\small\begin{verbatim}
   #include "sunpos.inc"

   light_source {
      //Greenwich, noon on the longest day of 2000
      SunPos(2000, 6, 21, 12, 2, 0, 51.4667, 0.00) 
      rgb 1
   }

   cylinder{
      <-2,0,0>,<2,0,0>,0.1
      rotate <0, Az-90, Al>  //align cylinder with sun
      texture {...}
   }
\end{verbatim}}

\subsection{font files (*.ttf)}

% reference/000417.html



   The fonts \discretionary{cyrvetic.}{}{cyrvetic.}ttf and \discretionary{timrom.}{}{timrom.}ttf were donated to the POV-\discretionary{}{}{}Team by their creator, Ted Harrison (\discretionary{CompuServe:}{}{CompuServe:}\discretionary{70220,}{}{70220,}344) and were built using his FontLab for 
 Windows by SoftUnion, Ltd. of St. Petersburg, Russia. 



   The font \discretionary{crystal.}{}{crystal.}ttf was donated courtesy of Jerry Fitzpatrick, Red Mountain Corporation, redmtn [at] \discretionary{ix.}{}{ix.}\discretionary{netcom.}{}{netcom.}com 



   The font \discretionary{povlogo.}{}{povlogo.}ttf is created by Fabien Mosen and based on the POV-\discretionary{}{}{}Ray logo design by Chris Colefax. 


\begin{description}
 
 \item 
   {\small\texttt{\discretionary{crystal.}{}{crystal.}ttf}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A fixed space programmer's font. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{cyrvetic.}{}{cyrvetic.}ttf}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A proportional spaces sans-\discretionary{}{}{}serif font. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{timrom.}{}{timrom.}ttf}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A proportional spaces serif font. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{povlogo.}{}{povlogo.}ttf}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Only contains the POV-\discretionary{}{}{}Ray logo. 
 \end{list}

\end{description}

\subsection{color\_\-map files (*.map)}

% reference/000416.html



   These are 255-color color\_\-maps, and are in individual files because of their size. 


\begin{description}
 
 \item 
   {\small\texttt{\discretionary{ash.}{}{ash.}map}} 
 

 \item 
   {\small\texttt{\discretionary{benediti.}{}{benediti.}map}} 
 

 \item 
   {\small\texttt{\discretionary{bubinga.}{}{bubinga.}map}} 
 

 \item 
   {\small\texttt{\discretionary{cedar.}{}{cedar.}map}} 
 

 \item 
   {\small\texttt{\discretionary{marbteal.}{}{marbteal.}map}} 
 

 \item 
   {\small\texttt{\discretionary{orngwood.}{}{orngwood.}map}} 
 

 \item 
   {\small\texttt{\discretionary{pinkmarb.}{}{pinkmarb.}map}} 
 

 \item 
   {\small\texttt{\discretionary{rdgranit.}{}{rdgranit.}map}} 
 

 \item 
   {\small\texttt{\discretionary{teak.}{}{teak.}map}} 
 

 \item 
   {\small\texttt{\discretionary{whiteash.}{}{whiteash.}map}} 
 

\end{description}

\subsection{image files (*.png, *.pot, *.df3)}

% reference/000415.html


\begin{description}
 
 \item 
   {\small\texttt{bumpmap\_.png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A color mandelbrot fractal image, presumably intended for use as a bumpmap. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{fract003.}{}{fract003.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Some kind of fractal landscape, with color for blue water, brown land, and white 
  peaks. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{maze.}{}{maze.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A maze. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{mtmand.}{}{mtmand.}pot}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A grayscale mandelbrot fractal. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{mtmandj.}{}{mtmandj.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A 2D color julia fractal. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{plasma2.}{}{plasma2.}png, \discretionary{plasma3.}{}{plasma3.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   "Plasma fractal" images, mainly useful for landscape height fields. The 
  file \discretionary{plasma3.}{}{plasma3.}png is a smoother version of \discretionary{plasma2.}{}{plasma2.}png, \discretionary{plasma1.}{}{plasma1.}png does not exist. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{povmap.}{}{povmap.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The text "Persistance of Vision" in green on a blue background, framed in 
  black and red. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{test.}{}{test.}png}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A "test image", the image is divided into 4 areas of different colors 
  (magenta, yellow, cyan, red) with black text on them, and the text "POV-\discretionary{}{}{}Ray" is centered on the image in white. 
 \end{list}

 \item 
   {\small\texttt{\discretionary{spiral.}{}{spiral.}df3}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A 3D bitmap density file. A spiral, "galaxy" shape. 
 \end{list}

\end{description}

\clearpage \chapter{Quick Reference}

% reference/000424.html



   This is a consolidation of the entire syntax for the POV-\discretionary{}{}{}Ray's Scene Description Language. Note that the syntax conventions used here are slightly different 
 than those used in the user documentation.\index{quickref} 



   The following syntax conventions are used: 


\begin{description}
 
 \item 
   {\small\texttt{ITEM}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An item not in brackets indicates that it is a required item. 
 \end{list}

 \item 
   {\small\texttt{[ITEM]}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Brackets surround an optional item. If brackets are part of the item, that is noted 
  where applicable. 
 \end{list}

 \item 
   {\small\texttt{ITEM...}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An ellipsis indicates an item that may be used one or more times. 
 \end{list}

 \item 
   {\small\texttt{[ITEM...]}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An ellipsis within brackets indicates an item that may be used zero or more times. 
 \end{list}

 \item 
   {\small\texttt{ITEM ITEM}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Two or more juxtaposed items indicates that they should be used in the given order. 
 \end{list}

 \item 
   {\small\texttt{ITEM | ITEM}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A pipe separates two or more alternatives from which only one item should be used. 
 \end{list}

 \item 
   {\small\texttt{ITEM \& ITEM  }} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An ampersand separates two or more items that may be used in any order. 
 \end{list}

\end{description}


   Juxtaposition has precedence over the pipe or ampersand. In the following example, you would select one of the keyword and vector pairs. For that last pair, 
 the keyword itself is optional. 



   \textbf{{\small\texttt{rgb}}} 3D\_\-VECTOR | \textbf{{\small\texttt{rgbf}}} 4D\_\-VECTOR | \textbf{{\small\texttt{rgbt}}} 4D\_\-VECTOR | [\textbf{{\small\texttt{rgbft}}}] 5D\_\-VECTOR 
 



   Some item names are simply descriptive in nature. An indication of the item's type is given by a prefix on the item name, as follows: 


\begin{description}
 
 \item 
   {\small\texttt{F\_}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A FLOAT item 
 \end{list}

 \item 
   {\small\texttt{I\_}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An INT item 
 \end{list}

 \item 
   {\small\texttt{V\_}} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A VECTOR item 
 \end{list}

 \item 
   {\small\texttt{V4\_ }} 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A 4-D VECTOR item 
 \end{list}

\end{description}


   \textit{NOTE:} this document provides only the syntax of the Scene Description Language (SDL). The intent is to provide a single reference for all statements 
 and keywords. It does not provide definitions for the numerous keywords nor explain their usage. 


\section{Quick Reference Contents}

% reference/000425.html

\index{quickref! contents}\index{contents! quickref}

   


\begin{table} \centering\begin{tabular*}{410pt}[t]{@{} p{205pt}@{} p{205pt}@{} }
 
 
  
  {\raggedleft 
    
   \begin{description}
    
    \item 
      The Scene 
    

    \item 
      Language Basics 
    

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Floats 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Vectors 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Colors 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      User-\discretionary{}{}{}Defined Functions 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Strings 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Arrays 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Splines 
    \end{list}

    \item 
      Language Directives 
    

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      File Inclusion 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Identifier Declaration 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      File Input/Output 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Default Texture 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Version Compatibility 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Conditional Directives 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Message Streams 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Macros 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Embedded Directives 
    \end{list}

    \item 
      Transformations 
    

    \item 
      Camera 
    

    \item 
      Lights 
    

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Light Source 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Light Group 
    \end{list}

    \item 
      Objects 
    

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Finite Solid Objects 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Finite Patch Objects 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Infinite Solid Objects 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Isosurface 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Parametric 
    \end{list}

    \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
      Constructive Solid Geometry 
    \end{list}

   \end{description}
    
  } & 
{\raggedleft  
  \begin{description}
   
   \item 
     Object Modifiers 
   

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     UV Mapping 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Material 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Interior 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Interior Texture 
   \end{list}

   \item 
     Texture 
   

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Plain Texture 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Layered Texture 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Patterned Texture 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Pigment 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Normal 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Finish 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Pattern 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Pattern Modifiers 
   \end{list}

   \item 
     Media 
   

   \item 
     Atmospheric Effects 
   

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Background 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Fog 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Sky Sphere 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Rainbow 
   \end{list}

   \item 
     Global Settings 
   

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Radiosity 
   \end{list}

   \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
     Photons 
   \end{list}

  \end{description}
   } \\ 
 

\end{tabular*} \caption{Quick Reference Overview} \end{table}

\section{The Scene}

% reference/000441.html

\index{quickref! scene}\index{scene! quickref}\index{The scene! quickref}
\begin{description}
 
 \item 
   Describe a POV-\discretionary{}{}{}Ray scene: 
 

 \item 
   SCENE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{SCENE\_\-ITEM...}} 
 \end{list}

 \item 
   SCENE\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{LANGUAGE\_\-DIRECTIVE | CAMERA | LIGHT | OBJECT | ATMOSPHERIC\_\-EFFECT | 
  GLOBAL\_\-SETTINGS}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Language Basics}

% reference/000440.html

\index{quickref! language basics}\index{language basics! quickref}\index{language! basics, quickref}
\subsection{Floats}

% reference/000439.html

\index{quickref! floats}\index{float expressions! quickref}\index{floats! quickref}\index{float! quickref}
\begin{description}
 
 \item 
   Float Expressions 
 

 \item 
   FLOAT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{NUMERIC\_\-TERM [SIGN NUMERIC\_\-TERM]...}} 
 \end{list}

 \item 
   SIGN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{+} | \textbf{-}}} 
 \end{list}

 \item 
   NUMERIC\_\-TERM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{NUMERIC\_\-FACTOR [MULT NUMERIC\_\-FACTOR]...}} 
 \end{list}

 \item 
   MULT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{*} | \textbf{/}}} 
 \end{list}

 \item 
   NUMERIC\_\-EXPRESSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT\_\-LITERAL | FLOAT\_\-IDENTIFIER | SIGN NUMERIC\_\-EXPRESSION | 
  FLOAT\_\-FUNCTION | FLOAT\_\-BUILT\_\-IN\_\-IDENT | \textbf{(} FULL\_\-EXPRESSION \textbf{)} | \textbf{!} NUMERIC\_\-EXPRESSION | VECTOR\textbf{.}DOT\_\-ITEM | FLOAT\_\-FUNCTION\_\-INVOCATION}} 
  
 \end{list}

 \item 
   FLOAT\_\-LITERAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[DIGIT...][.]DIGIT...[EXP[SIGN]DIGIT...]}} 
 \end{list}

 \item 
   DIGIT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1} | \textbf{2} | \textbf{3} | \textbf{4} | \textbf{5} 
  | \textbf{6} | \textbf{7} | \textbf{8} | \textbf{9}}} 
 \end{list}

 \item 
   EXP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{e} | \textbf{E}}} 
 \end{list}

 \item 
   FLOAT\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{abs (}FLOAT\textbf{)} | \textbf{acos (}FLOAT\textbf{)} 
  | \textbf{acosh (}FLOAT\textbf{)} | \textbf{asc (}STRING\textbf{)} | \textbf{asin (}FLOAT\textbf{)} | \textbf{asinh (}FLOAT\textbf{)} | \textbf{atan (}FLOAT\textbf{)} 
  | \textbf{atanh (}FLOAT\textbf{)} | \textbf{atan2 (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT\textbf{)} | \textbf{ceil (}FLOAT\textbf{)} | \textbf{cos (}FLOAT\textbf{)} 
  | \textbf{cosh (}FLOAT\textbf{)} | \textbf{defined (}IDENTIFIER\textbf{)} | \textbf{degrees (}FLOAT\textbf{)} | \textbf{dimensions (}ARRAY\_\-IDENTIFIER\textbf{)} 
  | \textbf{dimension\_\-size (}ARRAY\_\discretionary{IDENTIFIER,}{}{IDENTIFIER,}INT\textbf{)} | \textbf{div (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT\textbf{)} | \textbf{exp (}FLOAT\textbf{)} | \textbf{file\_\-exists (}STRING\textbf{)} 
  | \textbf{floor (}FLOAT\textbf{)} | \textbf{int (}FLOAT\textbf{)} | \textbf{inside (}SOLID\_\-OBJECT\_\-IDENT, VECTOR\textbf{)} | \textbf{ln (}FLOAT\textbf{)} 
  | \textbf{log (}FLOAT\textbf{)} | \textbf{max (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT[,FLOAT]...\textbf{)} | \textbf{min (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT[,FLOAT]...\textbf{)} | \textbf{mod (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT\textbf{)} 
  | \textbf{pow (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT\textbf{)} | \textbf{radians (}FLOAT\textbf{)} | \textbf{rand (}FLOAT\textbf{)} | \textbf{seed (}FLOAT\textbf{)} 
  | \textbf{select (}\discretionary{FLOAT,}{}{FLOAT,}\discretionary{FLOAT,}{}{FLOAT,}FLOAT,[FLOAT]\textbf{)} | \textbf{sin (}FLOAT\textbf{)} | \textbf{sinh (}FLOAT\textbf{)} | \textbf{sqrt (}FLOAT\textbf{)} 
  | \textbf{strcmp (}\discretionary{STRING,}{}{STRING,}STRING\textbf{)} | \textbf{strlen (}STRING\textbf{)} | \textbf{tan (}FLOAT\textbf{)} | \textbf{tanh (}FLOAT\textbf{)} 
  | \textbf{val (}STRING\textbf{)} | \textbf{vdot (}\discretionary{VECTOR,}{}{VECTOR,}VECTOR\textbf{)} | \textbf{vlength (}VECTOR\textbf{)}}} 
 \end{list}

 \item 
   FLOAT\_\-BUILT\_\-IN\_\-IDENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{BOOLEAN\_\-KEYWORD | \textbf{clock} | \textbf{clock\_\-delta} | \textbf{clock\_\-on} 
  | \textbf{final\_\-clock} | \textbf{final\_\-frame} | \textbf{frame\_\-number} | \textbf{image\_\-height} | \textbf{image\_\-width} | \textbf{initial\_\-clock} | \textbf{initial\_\-frame} 
  | \textbf{pi} | \textbf{version}}} 
 \end{list}

 \item 
   BOOLEAN\_\-KEYWORD: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{true} | \textbf{yes} | \textbf{on} | \textbf{false} | \textbf{no} 
  | \textbf{off}}} 
 \end{list}

 \item 
   FULL\_\-EXPRESSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{LOGICAL\_\-EXPRESSION [\textbf{?} FULL\_\-EXPRESSION \textbf{:} 
  FULL\_\-EXPRESSION]}} 
 \end{list}

 \item 
   \index{quickref! logical\_\-expression}LOGICAL\_\-EXPRESSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{REL\_\-TERM [LOGICAL\_\-OPERATOR REL\_\-TERM]...}} 
 \end{list}

 \item 
   LOGICAL\_\-OPERATOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\&} | \textbf{|}}} 
 \end{list}

 \item 
   REL\_\-TERM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT [REL\_\-OPERATOR FLOAT]...}} 
 \end{list}

 \item 
   REL\_\-OPERATOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{$<$} | \textbf{$<$=} | \textbf{=} | \textbf{$>$=} | \textbf{$>$} 
  | \textbf{!=}}} 
 \end{list}

 \item 
   \index{quickref! dot\_\-item}DOT\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{x} | \textbf{y} | \textbf{z} | \textbf{t} | \textbf{u} | \textbf{v} 
  | \textbf{red} | \textbf{green} | \textbf{blue} | \textbf{filter} | \textbf{transmit} | \textbf{gray}}} 
 \end{list}

 \item 
   INT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Any fractional part is discarded. 
 \end{list}

 \item 
   BOOL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{BOOLEAN\_\-KEYWORD | LOGICAL\_\-EXPRESSION}} 
 \end{list}

 \item 
     
 

\end{description}


   Quick Reference Contents 


\subsection{Vectors}

% reference/000438.html

\index{quickref! vectors}
\begin{description}
 
 \item 
   Vector Expressions 
 

 \item 
   VECTOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VECTOR\_\-TERM [SIGN VECTOR\_\-TERM]...}} 
 \end{list}

 \item 
   VECTOR\_\-TERM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VECTOR\_\-EXPRESSION [MULT VECTOR\_\-EXPRESSION]...}} 
 \end{list}

 \item 
   VECTOR\_\-EXPRESSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VECTOR\_\-LITERAL | VECTOR\_\-IDENTIFIER | SIGN VECTOR\_\-EXPRESSION | 
  VECTOR\_\-FUNCTION | VECTOR\_\-BUILT\_\-IN\_\-IDENT | \textbf{!} VECTOR\_\-EXPRESSION | FLOAT | VECTOR\_\-FUNCTION\_\-INVOCATION | COLOR\_\-FUNCTION\_\-INVOCATION | SPLINE\_\-INVOCATION}} 
  
 \end{list}

 \item 
   VECTOR\_\-LITERAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{$<$} FLOAT, FLOAT [, FLOAT [, FLOAT [, FLOAT ]]] \textbf{$>$}}} 
  
 \end{list}

 \item 
   VECTOR\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{min\_\-extent (}OBJECT\_\-IDENTIFIER\textbf{)} | \textbf{max\_\-extent (}OBJECT\_\-IDENTIFIER\textbf{)} 
  | \textbf{trace (}OBJECT\_\discretionary{IDENTIFIER,}{}{IDENTIFIER,}\discretionary{VECTOR,}{}{VECTOR,}VECTOR[,VECTOR\_\-IDENTIFIER]\textbf{)} | \textbf{vaxis\_\-rotate (}\discretionary{VECTOR,}{}{VECTOR,}\discretionary{VECTOR,}{}{VECTOR,}FLOAT\textbf{)} | \textbf{vcross (}\discretionary{VECTOR,}{}{VECTOR,}VECTOR\textbf{)} 
  | \textbf{vrotate (}\discretionary{VECTOR,}{}{VECTOR,}VECTOR\textbf{)} | \textbf{vnormalize (}VECTOR\textbf{)} | \textbf{vturbulence (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT,\discretionary{FLOAT,}{}{FLOAT,}VECTOR\textbf{)}}} 
  
 \end{list}

 \item 
   VECTOR\_\-BUILT\_\-IN\_\-IDENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{x} | \textbf{y} | \textbf{z} | \textbf{t} | \textbf{u} | \textbf{v}}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Colors}

% reference/000437.html

\index{quickref! colors}\index{color! quickref}\index{colors! quickref}\index{colour! quickref}
\begin{description}
 
 \item 
   Color Expressions 
 

 \item 
   COLOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{color}] COLOR\_\-BODY | \textbf{colour} COLOR\_\-BODY}} 
 \end{list}

 \item 
   COLOR\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{COLOR\_\-VECTOR | COLOR\_\-KEYWORD\_\-GROUP | COLOR\_\-IDENTIFIER}} 
 \end{list}

 \item 
   COLOR\_\-VECTOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{rgb} 3D\_\-VECTOR | \textbf{rgbf} 4D\_\-VECTOR | \textbf{rgbt} 
  4D\_\-VECTOR | [\textbf{rgbft}] 5D\_\-VECTOR}} 
 \end{list}

 \item 
   COLOR\_\-KEYWORD\_\-GROUP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[COLOR\_\-IDENTIFIER] COLOR\_\-KEYWORD\_\-ITEMS}} 
 \end{list}

 \item 
   COLOR\_\-KEYWORD\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{red} FLOAT] \& [\textbf{green} FLOAT] \& [\textbf{blue} 
  FLOAT] \& [\textbf{filter} FLOAT] \& [\textbf{transmit} FLOAT]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{User defined Functions}

% reference/000436.html

\index{quickref! user-\discretionary{}{}{}defined functions}\index{user-\discretionary{}{}{}defined functions! quickref}
\begin{description}
 
 \item 
   User-\discretionary{}{}{}Defined Functions 
 

 \item 
   USER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT\_\-USER\_\-FUNCTION | VECTOR\_\-USER\_\-FUNCTION | COLOR\_\-USER\_\-FUNCTION}} 
 \end{list}

 \item 
   FLOAT\_\-USER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{function \{} FN\_\-FLOAT \textbf{\}} | \textbf{function (}IDENT\_\-LIST\textbf{) \{} FN\_\-FLOAT \textbf{\}} 
  | \textbf{function \{ pattern \{} PATTERN [PATTERN\_\-MODIFIERS]\textbf{\} \}}}} 
 \end{list}

 \item 
   IDENT\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{IDENT\_\-ITEM [, IDENT\_\-LIST]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The maximum number of parameter identifiers is 56. An identifier may not be 
  repeated in the list. 
 \end{list}

 \item 
   IDENT\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{x} | \textbf{y} | \textbf{z} | \textbf{u} | \textbf{v} | 
  PARAM\_\-IDENTIFIER}} 
 \end{list}

 \item 
   PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{MAP\_\-PATTERN | \textbf{brick} [BRICK\_\-ITEM] | \textbf{checker} | \textbf{hexagon} 
  | \textbf{object \{} LIST\_\-OBJECT \textbf{\}}}} 
 \end{list}

 \item 
   VECTOR\_\-USER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{function \{} SPECIAL\_\-VECTOR\_\-FUNCTION \textbf{\}}}} 
  
 \end{list}

 \item 
   SPECIAL\_\-VECTOR\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TRANSFORM | SPLINE}} 
 \end{list}

 \item 
   COLOR\_\-USER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{function \{} PIGMENT \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Specify a float expression in a user-\discretionary{}{}{}defined function: 
 

 \item 
   FN\_\-FLOAT 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{LOGIC\_\-AND [OR LOGIC\_\-AND]}} 
 \end{list}

 \item 
   OR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{|}}} 
 \end{list}

 \item 
   LOGIC\_\-AND: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{REL\_\-TERM [AND REL\_\-TERM]}} 
 \end{list}

 \item 
   AND: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\&}}} 
 \end{list}

 \item 
   REL\_\-TERM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TERM [REL\_\-OPERATOR TERM]}} 
 \end{list}

 \item 
   REL\_\-OPERATOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{$<$} | \textbf{$<$=} | \textbf{=} | \textbf{$>$=} | \textbf{$>$} 
  | \textbf{!=}}} 
 \end{list}

 \item 
   TERM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FACTOR [SIGN FACTOR]}} 
 \end{list}

 \item 
   SIGN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{+} | \textbf{-}}} 
 \end{list}

 \item 
   FACTOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{EXPRESSION [MULT EXPRESSION]}} 
 \end{list}

 \item 
   MULT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{*} | \textbf{/}}} 
 \end{list}

 \item 
   EXPRESSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT\_\-LITERAL | FLOAT\_\-IDENTIFIER | FN\_\-FLOAT\_\-FUNCTION | 
  FLOAT\_\-BUILT\_\-IN\_\-IDENT | \textbf{(} FN\_\-FLOAT \textbf{)} | IDENT\_\-ITEM | SIGN EXPRESSION | VECTOR\_\-FUNCTION\_\-INVOCATION\textbf{.}FN\_\-DOT\_\-ITEM 
  | COLOR\_\-FUNCTION\_\-INVOCATION\textbf{.}FN\_\-DOT\_\-ITEM | FLOAT\_\-FUNCTION\_\-INVOCATION}} 
 \end{list}

 \item 
   FN\_\-DOT\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{DOT\_\-ITEM | \textbf{hf}}} 
 \end{list}

 \item 
   FN\_\-FLOAT\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{abs (}FN\_\-FLOAT\textbf{)} | \textbf{acos (}FN\_\-FLOAT\textbf{)} 
  | \textbf{acosh (}FN\_\-FLOAT\textbf{)} | \textbf{asin (}FN\_\-FLOAT\textbf{)} | \textbf{asinh (}FN\_\-FLOAT\textbf{)} | \textbf{atan (}FN\_\-FLOAT\textbf{)} 
  | \textbf{atanh (}FN\_\-FLOAT\textbf{)} | \textbf{atan2 (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT\textbf{)} | \textbf{ceil (}FN\_\-FLOAT\textbf{)} | \textbf{cos (}FN\_\-FLOAT\textbf{)} 
  | \textbf{cosh (}FN\_\-FLOAT\textbf{)} | \textbf{degrees (}FN\_\-FLOAT\textbf{)} | \textbf{exp (}FN\_\-FLOAT\textbf{)} | \textbf{floor (}FN\_\-FLOAT\textbf{)} 
  | \textbf{int (}FN\_\-FLOAT\textbf{)} | \textbf{ln (}FN\_\-FLOAT\textbf{)} | \textbf{log (}FN\_\-FLOAT\textbf{)} | \textbf{max (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT[,FN\_\-FLOAT]...\textbf{)} 
  | \textbf{min (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT[,FN\_\-FLOAT]...\textbf{)} | \textbf{mod (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT\textbf{)} | \textbf{pow (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT\textbf{)} 
  | \textbf{prod (}IDENTIFIER, FN\_\-FLOAT, FN\_\-FLOAT, FN\_\-FLOAT\textbf{)} | \textbf{radians (}FN\_\-FLOAT\textbf{)} | \textbf{sin (}FN\_\-FLOAT\textbf{)} 
  | \textbf{sinh (}FN\_\-FLOAT\textbf{)} | \textbf{sqrt (}FN\_\-FLOAT\textbf{)} | \textbf{sum (}IDENTIFIER, FN\_\-FLOAT, FN\_\-FLOAT, FN\_\-FLOAT\textbf{)} |\textbf{tan (}FN\_\-FLOAT\textbf{)} 
  | \textbf{tanh (}FN\_\-FLOAT\textbf{)} | \textbf{select (}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\discretionary{FLOAT,}{}{FLOAT,}FN\_\-FLOAT [,FN\_\-FLOAT]\textbf{)}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Create an identifier for a user-\discretionary{}{}{}defined function: 
 

 \item 
   USER\_\-FUNCTION\_\-DECLARATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#declare} FLOAT\_\-FUNCTION\_\-IDENTIFIER \textbf{=} 
  FLOAT\_\-USER\_\-FUNCTION |\newline  \textbf{\#local} FLOAT\_\-FUNCTION\_\-IDENTIFIER \textbf{=} FLOAT\_\-USER\_\-FUNCTION |\newline  \textbf{\#declare} 
  VECTOR\_\-FUNCTION\_\-IDENTIFIER \textbf{=} VECTOR\_\-USER\_\-FUNCTION |\newline  \textbf{\#local} VECTOR\_\-FUNCTION\_\-IDENTIFIER \textbf{=} VECTOR\_\-USER\_\-FUNCTION |\newline  
  \textbf{\#declare} COLOR\_\-FUNCTION\_\-IDENTIFIER \textbf{=} COLOR\_\-USER\_\-FUNCTION |\newline  \textbf{\#local} COLOR\_\-FUNCTION\_\-IDENTIFIER \textbf{=} COLOR\_\-USER\_\-FUNCTION}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   \index{quickref! function\_\-invocation}Reference a user-\discretionary{}{}{}defined function: 
 

 \item 
   FLOAT\_\-FUNCTION\_\-INVOCATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT\_\-FUNCTION\_\-IDENTIFIER \textbf{(}FN\_\-PARAM\_\-LIST\textbf{)}}} 
 \end{list}

 \item 
   VECTOR\_\-FUNCTION\_\-INVOCATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VECTOR\_\-FUNCTION\_\-IDENTIFIER \textbf{(}FN\_\-PARAM\_\-LIST\textbf{)}}} 
 \end{list}

 \item 
   COLOR\_\-FUNCTION\_\-INVOCATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{COLOR\_\-FUNCTION\_\-IDENTIFIER \textbf{(}FN\_\-PARAM\_\-LIST\textbf{)}}} 
 \end{list}

 \item 
   FN\_\-PARAM\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FN\_\-PARAM\_\-ITEM [, FN\_\-PARAM\_\-LIST]}} 
 \end{list}

 \item 
   FN\_\-PARAM\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{x} | \textbf{y} | \textbf{z} | \textbf{u} | \textbf{v} | 
  FLOAT}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Strings}

% reference/000435.html

\index{quickref! strings}\index{strings! quickref}\index{string! quickref}
\begin{description}
 
 \item 
   String Expressions 
 

 \item 
   STRING: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{STRING\_\-FUNCTION | STRING\_\-IDENTIFIER | STRING\_\-LITERAL}} 
 \end{list}

 \item 
   STRING\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{chr (}INT\textbf{)} | \textbf{concat (}\discretionary{STRING,}{}{STRING,}STRING[,STRING]...\textbf{)} 
  | \textbf{str (}\discretionary{FLOAT,}{}{FLOAT,}\discretionary{INT,}{}{INT,}INT\textbf{)} | \textbf{strlwr (}STRING\textbf{)} | \textbf{strupr (}STRING\textbf{)} | \textbf{substr (}\discretionary{STRING,}{}{STRING,}\discretionary{INT,}{}{INT,}INT\textbf{)} 
  | \textbf{vstr (}\discretionary{INT,}{}{INT,}VECTOR,\discretionary{STRING,}{}{STRING,}\discretionary{INT,}{}{INT,}INT\textbf{)}}} 
 \end{list}

 \item 
   STRING\_\-LITERAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{QUOTE [CHARACTER...] QUOTE}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Limited to 256 characters. 
 \end{list}

 \item 
   QUOTE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{"}}} 
 \end{list}

 \item 
   CHARACTER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Any ASCII or Unicode character, depending on the \textbf{charset} setting in \textbf{global\_\-settings}. 
  The following escape sequences might be useful when writing to files or message streams: 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   \textbf{{\small\texttt{$\backslash$a}}} - alarm\newline  \textbf{{\small\texttt{$\backslash$b}}} - 
  backspace\newline  \textbf{{\small\texttt{$\backslash$f}}} - form feed\newline  \textbf{{\small\texttt{$\backslash$n}}} - new line\newline  \textbf{{\small\texttt{$\backslash$r}}} - carriage 
  return\newline  \textbf{{\small\texttt{$\backslash$t}}} - horizontal tab\newline  \textbf{{\small\texttt{$\backslash$u}}}{\small\texttt{\textit{NNNN}}} - unicode character 
  four-\discretionary{}{}{}digit code\newline  \textbf{{\small\texttt{$\backslash$v}}} - vertical tab\newline  \textbf{{\small\texttt{$\backslash$$\backslash$}}} - backslash\newline  \textbf{{\small\texttt{$\backslash$'}}} 
  - single quote\newline  \textbf{{\small\texttt{$\backslash$"}}} - double quote\newline  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Arrays}

% reference/000434.html

\index{quickref! arrays}\index{arrays! quickref}\index{array! quickref}
\begin{description}
 
 \item 
   Define an array: 
 

 \item 
   ARRAY\_\-DECLARATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#declare} ARRAY\_\-IDENTIFIER \textbf{= array} DIMENSION... 
  [ARRAY\_\-INITIALIZER] |\newline  \textbf{\#local} ARRAY\_\-IDENTIFIER \textbf{= array} DIMENSION... [ARRAY\_\-INITIALIZER]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Limited to five dimensions. 
 \end{list}

 \item 
   DIMENSION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} INT \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the dimension specification. The integer must be 
  greater than zero. 
 \end{list}

 \item 
   ARRAY\_\-INITIALIZER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\{} ARRAY\_\-INITIALIZER [, ARRAY\_\-INITIALIZER]... \textbf{\}} |\newline  
  \textbf{\{} RVALUE [, RVALUE]... \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Place a value into an array: 
 

 \item 
   ARRAY\_\-ELEMENT\_\-ASSIGNMENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#declare} ARRAY\_\-REFERENCE \textbf{=}RVALUE [\textbf{;}] |\newline  
  \textbf{\#local} ARRAY\_\-REFERENCE \textbf{=} RVALUE [\textbf{;}]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The semicolon is required for a FLOAT, VECTOR or COLOR assignment. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Reference an array: 
 

 \item 
   ARRAY\_\-REFERENCE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{ARRAY\_\-IDENTIFIER ELEMENT...}} 
 \end{list}

 \item 
   ELEMENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} INT \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the element specification. 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Splines}

% reference/000433.html

\index{quickref! splines}\index{splines! quickref}\index{spline! quickref}
\begin{description}
 
 \item 
   Define a spline: 
 

 \item 
   SPLINE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{spline \{} SPLINE\_\-ITEMS \textbf{\}}}} 
 \end{list}

 \item 
   SPLINE\_\-ITEMS 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[SPLINE\_\-TYPE] PATH\_\-LIST | SPLINE\_\-IDENTIFIER [SPLINE\_\-TYPE][PATH\_\-LIST]}} 
  
 \end{list}

 \item 
   SPLINE\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{linear\_\-spline} | \textbf{quadratic\_\-spline} | \textbf{cubic\_\-spline} 
  | \textbf{natural\_\-spline}}} 
 \end{list}

 \item 
   PATH\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT, VECTOR [[,] PATH\_\-LIST]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Reference a spline: 
 

 \item 
   SPLINE\_\-INVOCATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{SPLINE\_\-IDENTIFIER \textbf{(} FLOAT [, SPLINE\_\-TYPE] \textbf{)}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Language Directives}

% reference/000432.html

\index{quickref! language directives}\index{language! directives, quickref}\index{language directives! quickref}
\begin{description}
 
 \item 
   Control the parsing of sections of the scene file: 
 

 \item 
   LANGUAGE\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{INCLUDE\_\-DIRECTIVE | IDENTIFIER\_\-DECLARATION | UNDEF\_\-DIRECTIVE | 
  FOPEN\_\-DIRECTIVE | FCLOSE\_\-DIRECTIVE | READ\_\-DIRECTIVE | WRITE\_\-DIRECTIVE | DEFAULT\_\-DIRECTIVE | VERSION\_\-DIRECTIVE | IF\_\-DIRECTIVE | IFDEF\_\-DIRECTIVE | 
  IFNDEF\_\-DIRECTIVE | SWITCH\_\-DIRECTIVE | WHILE\_\-DIRECTIVE | TEXT\_\-STREAM\_\-DIRECTIVE | MACRO\_\-DEFINITION}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{File Inclusion}

% reference/000431.html

\index{quickref! file inclusion}\index{file inclusion! quickref}
\begin{description}
 
 \item 
   Insert content of another scene file: 
 

 \item 
   INCLUDE\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#include} FILE\_\-NAME}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   File inclusion may be nested at most 10 levels deep. 
 \end{list}

 \item 
   FILE\_\-NAME: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{STRING}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Identifier Declaration}

% reference/000430.html

\index{quickref! identifier declaration}\index{identifier! declaration, quickref}
\begin{description}
 
 \item 
   Create an identifier for a value, object, etc. 
 

 \item 
   IDENTIFIER\_\-DECLARATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#declare} IDENTIFIER \textbf{=} RVALUE [\textbf{;}] |\newline  
  \textbf{\#local} IDENTIFIER \textbf{=} RVALUE [\textbf{;}]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Up to 127 characters, starting with a letter, consisting of letters, digits and/or 
  the underscore. The semicolon is required for a FLOAT, VECTOR or COLOR declaration. 
 \end{list}

 \item 
   RVALUE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT | VECTOR | COLOR | USER\_\-FUNCTION | STRING | ARRAY\_\-REFERENCE | 
  SPLINE | TRANSFORM | CAMERA | LIGHT | OBJECT | MATERIAL | INTERIOR | TEXTURE | TEXTURE\_\-MAP | PIGMENT | COLOR\_\-MAP | PIGMENT\_\-MAP | NORMAL | SLOPE\_\-MAP | 
  NORMAL\_\-MAP | FINISH | MEDIA | DENSITY | DENSITY\_\-MAP | FOG | RAINBOW | SKY\_\-SPHERE}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Destroy an identifier: 
 

 \item 
   UNDEF\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#undef} IDENTIFIER}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{File Input/Output}

% reference/000429.html

\index{quickref! file i/o}\index{file i/o! quickref}
\begin{description}
 
 \item 
   Open a text file: 
 

 \item 
   FOPEN\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#fopen} FILE\_\-HANDLE\_\-IDENTIFIER FILE\_\-NAME OPEN\_\-TYPE}} 
 \end{list}

 \item 
   OPEN\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{read} | \textbf{write} | \textbf{append}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Close a text file: 
 

 \item 
   FCLOSE\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#fclose} FILE\_\-HANDLE\_\-IDENTIFIER}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Read string, float and/or vector values from a text file: 
 

 \item 
   READ\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#read (} FILE\_\-HANDLE\_\-IDENTIFIER, DATA\_\-IDENTIFIER [, 
  DATA\_\-IDENTIFIER]... \textbf{)}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Use \textbf{defined(}FILE\_\-HANDLE\_\-IDENTIFIER\textbf{)} to detect end-\discretionary{}{}{}of-\discretionary{}{}{}file after a 
  read. 
 \end{list}

 \item 
   DATA\_\-IDENTIFIER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{UNDECLARED\_\-IDENTIFIER | FLOAT\_\-IDENTIFIER | VECTOR\_\-IDENTIFIER | 
  STRING\_\-IDENTIFIER | ARRAY\_\-REFERENCE}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   May read a value into an array reference if the array element's type has already 
  been established. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Write string, float and/or vector values to a text file: 
 

 \item 
   WRITE\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#write (} FILE\_\-HANDLE\_\-IDENTIFIER, DATA\_\-ITEM [, DATA\_\-ITEM]... \textbf{)}}} 
  
 \end{list}

 \item 
   DATA\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FLOAT | VECTOR | STRING}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Default Texture}

% reference/000428.html

\index{quickref! default texture}\index{default texture! quickref}
\begin{description}
 
 \item 
   Specify a default texture, pigment, normal or finish: 
 

 \item 
   DEFAULT\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#default \{} DEFAULT\_\-ITEM \textbf{\}}}} 
 \end{list}

 \item 
   DEFAULT\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PLAIN\_\-TEXTURE | PIGMENT | NORMAL | FINISH}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Version Identfier}

% reference/000427.html

\index{quickref! version}\index{version! quickref}\index{version identfier! quickref}
\begin{description}
 
 \item 
   Specify the POV-\discretionary{}{}{}Ray compatibility version number: 
 

 \item 
   VERSION\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#version} FLOAT\textbf{;}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Control Flow Directives}

% reference/000426.html

\index{quickref! conditional directives}\index{conditional directives! quickref}
\begin{description}
 
 \item 
   Conditionally parse a section of the scene file, depending on a boolean expression: 
 

 \item 
   IF\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#if (} BOOL \textbf{)} TOKENS [\textbf{\#else} TOKENS] \textbf{\#end}}} 
  
 \end{list}

 \item 
   TOKENS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Any number of POV-\discretionary{}{}{}Ray keywords, identifiers, values and/or punctuation. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Conditionally parse a section of the scene file, depending on the existence of an identifier: 
 

 \item 
   IFDEF\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#ifdef (} IDENTIFIER \textbf{)} TOKENS [\textbf{\#else} TOKENS] 
  \textbf{\#end}}} 
 \end{list}

 \item 
   IFNDEF\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#ifndef (} IDENTIFIER \textbf{)} TOKENS [\textbf{\#else} TOKENS] 
  \textbf{\#end}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Conditionally parse a section of the scene file, depending on the value of a float expression: 
 

 \item 
   SWITCH\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#switch (} FLOAT \textbf{)} SWITCH\_\-CLAUSE... [\textbf{\#else} TOKENS] 
  \textbf{\#end}}} 
 \end{list}

 \item 
   SWITCH\_\-CLAUSE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#case (} FLOAT \textbf{)} TOKENS [\textbf{\#break}] |\newline  
  \textbf{\#range (} F\_\-LOW, F\_\-HIGH \textbf{)} TOKENS [\textbf{\#break}]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Repeat a section of the scene file while a boolean condition is true: 
 

 \item 
   WHILE\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#while (} LOGICAL\_\-EXPRESSION \textbf{)} TOKENS \textbf{\#end}}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Message Streams}

% reference/000442.html

\index{quickref! message streams}\index{message streams! quickref}
\begin{description}
 
 \item 
   Send a message to a text stream: 
 

 \item 
   TEXT\_\-STREAM\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#debug} STRING | \textbf{\#error} STRING | \textbf{\#warning} 
  STRING}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Macro}

% reference/000459.html

\index{quickref! macros}\index{macro! quickref}\index{macros! quickref}
\begin{description}
 
 \item 
   Define a macro: 
 

 \item 
   MACRO\_\-DEFINITION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{\#macro} MACRO\_\-IDENTIFIER \textbf{(} [PARAM\_\-IDENTIFIER [, 
  PARAM\_\-IDENTIFIER]...] \textbf{)} TOKENS \textbf{\#end}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A parameter identifier may not be repeated in the list. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Invoke a macro: 
 

 \item 
   MACRO\_\-INVOCATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{MACRO\_\-IDENTIFIER \textbf{(} [ACTUAL\_\-PARAM [, ACTUAL\_\-PARAM]...] \textbf{)}}} 
  
 \end{list}

 \item 
   ACTUAL\_\-PARAM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{IDENTIFIER | RVALUE}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Embedded Directives}

% reference/000458.html

\index{quickref! embedded directives}
\begin{description}
 
 \item 
   Some directives may be embedded in CAMERA, LIGHT, OBJECT and ATMOSPHERIC\_\-EFFECT statements. However, the directives should only include items (if any) 
  that are valid for a given statement. Also, they should not disrupt the required order of items, where applicable. 
 

 \item 
   EMBEDDED\_\-DIRECTIVE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{IDENTIFIER\_\-DECLARATION | UNDEF\_\-DIRECTIVE | READ\_\-DIRECTIVE | 
  WRITE\_\-DIRECTIVE | IF\_\-DIRECTIVE | IFDEF\_\-DIRECTIVE | IFNDEF\_\-DIRECTIVE | SWITCH\_\-DIRECTIVE | WHILE\_\-DIRECTIVE | TEXT\_\-STREAM\_\-DIRECTIVE}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Transformations}

% reference/000457.html

\index{quickref! transformations}\index{transformations! quickref}\index{matrix}\index{rotate}\index{scale}\index{transform}\index{translate}
\begin{description}
 
 \item 
   Rotate, resize, move, or otherwise manipulate the coordinates of an object or texture 
 

 \item 
   TRANSFORMATION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{rotate} VECTOR | \textbf{scale} VECTOR | \textbf{translate} VECTOR 
  | TRANSFORM | MATRIX}} 
 \end{list}

 \item 
   TRANSFORM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{transform} TRANSFORM\_\-IDENTIFIER | \textbf{transform \{} 
  [TRANSFORM\_\-ITEM...] \textbf{\}}}} 
 \end{list}

 \item 
   TRANSFORM\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TRANSFORM\_\-IDENTIFIER | TRANSFORMATION | \textbf{inverse}}} 
 \end{list}

 \item 
   MATRIX: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{matrix $<$} F\_\-VAL00, F\_\-VAL01, F\_\-VAL02, F\_\-VAL10, F\_\-VAL11, 
  F\_\-VAL12, F\_\-VAL20, F\_\-VAL21, F\_\-VAL22, F\_\-VAL30, F\_\-VAL31, F\_\-VAL32 \textbf{$>$}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Camera}

% reference/000456.html

\index{quickref! camera}
\begin{description}
 
 \item 
   Describe the position, projection type and properties of the camera viewing the scene 
 

 \item 
   CAMERA: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{camera \{} [CAMERA\_\-TYPE] [CAMERA\_\-ITEMS] [CAMERA\_\-MODIFIERS] \textbf{\}} 
  |}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{camera \{} CAMERA\_\-IDENTIFIER [TANSFORMATIONS ...] \textbf{\}}}} 
  
 \end{list}

 \item 
   CAMERA\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{perspective} | \textbf{orthographic} | \textbf{fisheye} | \textbf{ultra\_\-wide\_\-angle} 
  | \textbf{omnimax} | \textbf{panoramic} | \textbf{spherical} | \textbf{cylinder} CYLINDER\_\-TYPE}} 
 \end{list}

 \item 
   CYLINDER\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2} | \textbf{3} | \textbf{4}}} 
 \end{list}

 \item 
   CAMERA\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{location} VECTOR] \& [\textbf{right} VECTOR] 
  \& [\textbf{up} VECTOR] \& [\textbf{direction} VECTOR] \& [\textbf{sky} VECTOR]}} 
 \end{list}

 \item 
   CAMERA\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{ [\textbf{angle} [angle F\_\-HORIZONTAL] [,F\_\-VERTICAL]] \& [\textbf{look\_\-at} VECTOR] 
  \& [FOCAL\_\-BLUR] \& [NORMAL] \& [TRANSFORMATION...]}} 
 \end{list}

 \item 
   FOCAL\_\-BLUR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{aperture} FLOAT \& \textbf{blur\_\-samples} INT 
  \& [\textbf{focal\_\-point} VECTOR] \& [\textbf{confidence} FLOAT] \& [\textbf{variance} FLOAT]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Lights}

% reference/000454.html

\index{quickref! lights}\index{lights! quickref}
\begin{description}
 
 \item 
   Specify light sources for the scene or for specific objects 
 

 \item 
   LIGHT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{LIGHT\_\-SOURCE | LIGHT\_\-GROUP}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Describe the position, type and properties of a light source for the scene: 
 

 \item 
   LIGHT\_\-SOURCE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{light\_\-source \{} V\_\-LOCATION, COLOR [LIGHT\_\-SOURCE\_\-ITEMS] \textbf{\}}}} 
  
 \end{list}

 \item 
   LIGHT\_\-SOURCE\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[LIGHT\_\-TYPE] \& [AREA\_\-LIGHT\_\-ITEMS] \& [LIGHT\_\-MODIFIERS]}} 
 \end{list}

 \item 
   LIGHT\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{spotlight} [SPOTLIGHT\_\-ITEMS] | \textbf{cylinder} [SPOTLIGHT\_\-ITEMS]}} 
  
 \end{list}

 \item 
   SPOTLIGHT\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{radius} FLOAT] \& [\textbf{falloff} FLOAT] 
  \& [\textbf{tightness} FLOAT] \& [\textbf{point\_\-at} VECTOR]}} 
 \end{list}

 \item 
   AREA\_\-LIGHT\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{area\_\-light} V\_\-AXIS1, V\_\-AXIS2, I\_\-SIZE1, I\_\-SIZE2 
  [AREA\_\-LIGHT\_\-MODIFIERS]}} 
 \end{list}

 \item 
   AREA\_\-LIGHT\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{adaptive} INT] \& [\textbf{jitter}] \& [\textbf{circular}] 
  \& [\textbf{orient}]}} 
 \end{list}

 \item 
   LIGHT\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[LIGHT\_\-PHOTONS] \& [\textbf{looks\_\-like \{} OBJECT \textbf{\}}] 
  \& [TRANSFORMATION...] \& [\textbf{fade\_\-distance} FLOAT] \& [\textbf{fade\_\-power} FLOAT] \& [\textbf{media\_\-attenuation} [BOOL]] \& [\textbf{media\_\-interaction} [BOOL]] 
  \& [\textbf{shadowless}] \& [\textbf{projected\_\-through \{} OBJECT\_\-IDENTIFIER \textbf{\}}] \& [\textbf{parallel} [\textbf{point\_\-at} VECTOR]]}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Specify how a light source should interact with photons: 
 

 \item 
   LIGHT\_\-PHOTONS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{photons \{} LIGHT\_\-PHOTON\_\-ITEMS \textbf{\}}}} 
 \end{list}

 \item 
   LIGHT\_\-PHOTON\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{refraction} BOOL] \& [\textbf{reflection} BOOL] 
  \& [\textbf{area\_\-light}]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Lightgroup}

% reference/000453.html

\index{quickref! lightgroup}\index{lightgroup! quickref}
\begin{description}
 
 \item 
   Assign objects to specific light sources: 
 

 \item 
   LIGHT\_\-GROUP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{light\_\-group \{} LIGHT\_\-GROUP\_\-ITEM... [LIGHT\_\-GROUP\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   LIGHT\_\-GROUP\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{LIGHT\_\-SOURCE | OBJECT | LIGHT\_\-GROUP}} 
 \end{list}

 \item 
   LIGHT\_\-GROUP\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{global\_\-lights} BOOL] \& [TRANSFORMATION...]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Objects}

% reference/000452.html

\index{quickref! objects}\index{objects! quickref}
\begin{description}
 
 \item 
   Describe an object in the scene 
 

 \item 
   OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FINITE\_\-SOLID\_\-OBJECT | FINITE\_\-PATCH\_\-OBJECT | INFINITE\_\-SOLID\_\-OBJECT | 
  ISOSURFACE | PARAMETRIC | CSG\_\-OBJECT | OBJECT\_\-STATEMENT}} 
 \end{list}

 \item 
   OBJECT\_\-STATEMENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{object \{} OBJECT\_\-IDENTIFIER [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Finite Solid Objects}

% reference/000451.html

\index{quickref! finite solid objects}\index{objects! finite solid, quickref}
\begin{description}
 
 \item 
   Describe a solid finite shape: 
 

 \item 
   FINITE\_\-SOLID\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{BLOB | BOX | CONE | CYLINDER | HEIGHT\_\-FIELD | JULIA\_\-FRACTAL | LATHE 
  | PRISM | SPHERE | SPHERE\_\-SWEEP | SUPERELLIPSOID | SOR | TEXT | TORUS}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The blob object: 
 

 \item 
   BLOB: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{blob \{} [\textbf{threshold} FLOAT] BLOB\_\-ITEM... 
  [BLOB\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   BLOB\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sphere \{} V\_\-CENTER, F\_\-RADIUS, [\textbf{strength}] F\_\-STRENGTH 
  [COMPONENT\_\-MODIFIERS] \textbf{\}} |\newline  \textbf{cylinder \{} V\_\-END1, V\_\-END2, F\_\-RADIUS, [\textbf{strength}] F\_\-STRENGTH [COMPONENT\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   COMPONENT\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[TEXTURE] \& [PIGMENT] \& [NORMAL] \& [FINISH] \& 
  [TRANSFORMATION...]}} 
 \end{list}

 \item 
   BLOB\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{hierarchy} [BOOL]] \& [\textbf{sturm} [BOOL]] 
  \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The box object: 
 

 \item 
   BOX: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{box \{} V\_\-CORNER1, V\_\-CORNER2 [BOX\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   BOX\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The cone object: 
 

 \item 
   CONE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{cone \{} V\_\-BASE\_\-CENTER, F\_\-BASE\_\-RADIUS, V\_\-CAP\_\-CENTER, 
  F\_\-CAP\_\-RADIUS [\textbf{open}] [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The cylinder object: 
 

 \item 
   CYLINDER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{cylinder \{} V\_\-BASE\_\-CENTER, V\_\-CAP\_\-CENTER, F\_\-RADIUS [\textbf{open}] 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The height field object: 
 

 \item 
   HEIGHT\_\-FIELD: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{height\_\-field \{} HF\_\-IMAGE [HF\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   HF\_\-IMAGE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FUNCTION\_\-IMAGE | [HF\_\-TYPE] FILE\_\-NAME}} 
 \end{list}

 \item 
   HF\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{gif} | \textbf{tga} | \textbf{pot} | \textbf{png} | \textbf{pgm} 
  | \textbf{ppm} | \textbf{jpeg} | \textbf{tiff} | \textbf{sys}}} 
 \end{list}

 \item 
   HF\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{hierarchy} [BOOL]] \& [\textbf{smooth}] \& [\textbf{water\_\-level} FLOAT] 
  \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The Julia fractal object: 
 

 \item 
   JULIA\_\-FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{julia\_\-fractal \{} 4D\_\-VECTOR [JF\_\-ITEMS] [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   JF\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[ALGEBRA\_\-ITEM] \& [\textbf{max\_\-iteration} INT] \& [\textbf{precision} FLOAT] 
  \& [\textbf{slice} V4\_\-NORMAL, F\_\-DISTANCE]}} 
 \end{list}

 \item 
   ALGEBRA\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{quaternion} [QUATER\_\-FUNCTION] | \textbf{hypercomplex} [HYPER\_\-FUNCTION]}} 
  
 \end{list}

 \item 
   QUATER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sqr} | \textbf{cube}}} 
 \end{list}

 \item 
   HYPER\_\-FUNCTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sqr} | \textbf{cube} | \textbf{exp} | \textbf{reciprocal} | \textbf{sin} 
  | \textbf{asin} | \textbf{sinh} | \textbf{asinh} | \textbf{cos} | \textbf{acos} | \textbf{cosh} | \textbf{acosh} | \textbf{tan} | \textbf{atan} | \textbf{tanh} 
  | \textbf{atanh} | \textbf{ln} | \textbf{pwr (}\discretionary{FLOAT,}{}{FLOAT,}FLOAT\textbf{)}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The lathe object: 
 

 \item 
   LATHE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{lathe \{} [LATHE\_\-SPLINE\_\-TYPE] I\_\-NUM\_\-POINTS, POINT\_\-LIST 
  [LATHE\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   LATHE\_\-SPLINE\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{linear\_\-spline} | \textbf{quadratic\_\-spline} | \textbf{cubic\_\-spline} 
  | \textbf{bezier\_\-spline}}} 
 \end{list}

 \item 
   POINT\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{2D\_\-VECTOR [, 2D\_\-VECTOR]...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The quantity of 2D\_\-VECTORs is specified by the I\_\-NUM\_\-POINTS value. 
 \end{list}

 \item 
   LATHE\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{sturm} [BOOL]] \& [UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The prism object: 
 

 \item 
   PRISM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{prism \{} [PRISM\_\-ITEMS] F\_\-HEIGHT1, F\_\-HEIGHT2, I\_\-NUM\_\-POINTS, 
  POINT\_\-LIST [\textbf{open}] [PRISM\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   PRISM\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PRISM\_\-SPLINE\_\-TYPE] \& [PRISM\_\-SWEEP\_\-TYPE]}} 
 \end{list}

 \item 
   PRISM\_\-SPLINE\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{linear\_\-spline} | \textbf{quadratic\_\-spline} | \textbf{cubic\_\-spline} 
  | \textbf{bezier\_\-spline}}} 
 \end{list}

 \item 
   PRISM\_\-SWEEP\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{linear\_\-sweep} | \textbf{conic\_\-sweep}}} 
 \end{list}

 \item 
   PRISM\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{sturm} [BOOL]] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The sphere object: 
 

 \item 
   SPHERE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sphere \{} V\_\-CENTER, F\_\-RADIUS [SPHERE\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   SPHERE\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The sphere sweep object: 
 

 \item 
   SPHERE\_\-SWEEP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sphere\_\-sweep \{} SWEEP\_\-SPLINE\_\-TYPE I\_\-NUM\_\-SPHERES, SPHERE\_\-LIST 
  [\textbf{tolerance} F\_\-DEPTH\_\-TOLERANCE] [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   SWEEP\_\-SPLINE\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{linear\_\-spline} | \textbf{b\_\-spline} | \textbf{cubic\_\-spline}}} 
 \end{list}

 \item 
   SPHERE\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{V\_\-CENTER, F\_\-RADIUS [, SPHERE\_\-LIST]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The quantity of V\_\-CENTER, F\_\-RADIUS pairs is specified by the I\_\-NUM\_\-SPHERES value. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The superquadric ellipsoid object: 
 

 \item 
   SUPERELLIPSOID: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{superellipsoid \{} $<$ FLOAT, FLOAT $>$ 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The surface of revolution object: 
 

 \item 
   SOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sor \{} I\_\-NUM\_\-POINTS, POINT\_\-LIST [\textbf{open}] 
  [SOR\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   SOR\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{sturm} [BOOL]] \& [UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The text object: 
 

 \item 
   TEXT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{text \{ ttf} FILE\_\-NAME STRING F\_\-THICKNESS, V\_\-OFFSET 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The torus object: 
 

 \item 
   TORUS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{torus \{} F\_\-MAJOR\_\-RADIUS, F\_\-MINOR\_\-RADIUS [TORUS\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   TORUS\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{sturm} [BOOL]] \& [UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Finite Patch Objects}

% reference/000450.html

\index{quickref! finite patch objects}\index{objects! finite patch, quickref}
\begin{description}
 
 \item 
   Describe a totally thin, finite shape: 
 

 \item 
   FINITE\_\-PATCH\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{BICUBIC\_\-PATCH | DISC | MESH | MESH2 | POLYGON | TRIANGLE | 
  SMOOTH\_\-TRIANGLE}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The bicubic patch object: 
 

 \item 
   BICUBIC\_\-PATCH: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{bicubic\_\-patch \{} PATCH\_\-ITEMS [PATCH\_\-UV\_\-VECTORS] 
  CONTROL\_\-POINTS [BICUBIC\_\-PATCH\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   PATCH\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{type} PATCH\_\-TYPE \& [\textbf{u\_\-steps} INT] 
  \& [\textbf{v\_\-steps} INT] \& [\textbf{flatness} FLOAT]}} 
 \end{list}

 \item 
   PATCH\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1}}} 
 \end{list}

 \item 
   PATCH\_\-UV\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{uv\_\-vectors} V2\_\-CORNER1, V2\_\-CORNER2, V2\_\-CORNER3, V2\_\-CORNER4}} 
 \end{list}

 \item 
   CONTROL\_\-POINTS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   16 VECTORs, optionally separated by commas. 
 \end{list}

 \item 
   BICUBIC\_\-PATCH\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The disc object: 
 

 \item 
   DISC: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{disc \{} V\_\-CENTER, V\_\-NORMAL, F\_\-RADIUS [, F\_\-HOLE\_\-RADIUS] 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The mesh object: 
 

 \item 
   MESH: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{mesh \{} MESH\_\-TRIANGLE... [MESH\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   MESH\_\-TRIANGLE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{triangle \{} V\_\-CORNER1, V\_\-CORNER2, V\_\-CORNER3 
  [MESH\_\-UV\_\-VECTORS] [MESH\_\-TEXTURE] \textbf{\}} |\newline  \textbf{smooth\_\-triangle \{} V\_\-CORNER1, V\_\-NORMAL1, V\_\-CORNER2, V\_\-NORMAL2, V\_\-CORNER3, V\_\-NORMAL3 
  [MESH\_\-UV\_\-VECTORS] [MESH\_\-TEXTURE] \textbf{\}}}} 
 \end{list}

 \item 
   MESH\_\-UV\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{uv\_\-vectors} V2\_\-CORNER1, V2\_\-CORNER2, V2\_\-CORNER3}} 
 \end{list}

 \item 
   MESH\_\-TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture \{} TEXTURE\_\-IDENTIFIER \textbf{\}} |\newline  \textbf{texture\_\-list 
  \{} TEXTURE\_\-IDENTIFIER TEXTURE\_\-IDENTIFIER TEXTURE\_\-IDENTIFIER \textbf{\}}}} 
 \end{list}

 \item 
   MESH\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{inside\_\-vector} V\_\-DIRECTION] \& [\textbf{hierarchy} 
  [BOOL]] \& [UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The mesh2 object: 
 

 \item 
   MESH2: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{mesh2 \{} MESH2\_\-VECTORS [TEXTURE\_\-LIST] MESH2\_\-INDICES 
  [MESH2\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   MESH2\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VERTEX\_\-VECTORS [NORMAL\_\-VECTORS] [UV\_\-VECTORS]}} 
 \end{list}

 \item 
   VERTEX\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{vertex\_\-vectors \{} I\_\-NUM\_\-VERTICES, VECTOR [, VECTOR]... \textbf{\}}}} 
  
 \end{list}

 \item 
   NORMAL\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{normal\_\-vectors \{} I\_\-NUM\_\-NORMALS, VECTOR [, VECTOR]... \textbf{\}}}} 
  
 \end{list}

 \item 
   UV\_\-VECTORS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{uv\_\-vectors \{} I\_\-NUM\_\-UV\_\-VECTORS, 2D\_\-VECTOR 
  [, 2D\_\-VECTOR]... \textbf{\}}}} 
 \end{list}

 \item 
   TEXTURE\_\-LIST: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture\_\-list \{} I\_\-NUM\_\-TEXTURES, TEXTURE [, TEXTURE]... \textbf{\}}}} 
  
 \end{list}

 \item 
   MESH2\_\-INDICES: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FACE\_\-INDICES [NORMAL\_\-INDICES] [UV\_\-INDICES]}} 
 \end{list}

 \item 
   FACE\_\-INDICES: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{face\_\-indices \{} I\_\-NUM\_\-FACES, FACE\_\-INDICES\_\-ITEM 
  [, FACE\_\-INDICES\_\-ITEM]... \textbf{\}}}} 
 \end{list}

 \item 
   FACE\_\-INDICES\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{VECTOR [, I\_\-TEXTURE\_\-INDEX [, I\_\-TEXTURE\_\-INDEX, 
  I\_\-TEXTURE\_\-INDEX ]]}} 
 \end{list}

 \item 
   NORMAL\_\-INDICES: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{normal\_\-indices \{} I\_\-NUM\_\-FACES, VECTOR [, VECTOR]... \textbf{\}}}} 
  
 \end{list}

 \item 
   UV\_\-INDICES: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{uv\_\-indices \{} I\_\-NUM\_\-FACES, VECTOR [, VECTOR]... \textbf{\}}}} 
  
 \end{list}

 \item 
   MESH2\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{inside\_\-vector} V\_\-DIRECTION] \& [UV\_\-MAPPING] \& 
  [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The polygon object: 
 

 \item 
   POLYGON: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{polygon \{} I\_\-NUM\_\-POINTS, V\_\-POINT [, V\_\-POINT]... 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The quantity of V\_\-POINTs is specified by the I\_\-NUM\_\-POINTS value. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The triangle object: 
 

 \item 
   TRIANGLE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{triangle \{} V\_\-CORNER1, V\_\-CORNER2, V\_\-CORNER3 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The smooth triangle object: 
 

 \item 
   SMOOTH\_\-TRIANGLE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{smooth\_\-triangle \{} V\_\-CORNER1, V\_\-NORMAL1, V\_\-CORNER2, 
  V\_\-NORMAL2, V\_\-CORNER3, V\_\-NORMAL3 [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Infinite Solid Objects}

% reference/000449.html

\index{quickref! infinite solid objects}\index{objects! infinite solid, quickref}
\begin{description}
 
 \item 
   Describe a solid, possibly infinite, shape: 
 

 \item 
   INFINITE\_\-SOLID\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PLANE | POLY | CUBIC | QUARTIC | QUADRIC}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The plane object: 
 

 \item 
   PLANE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{plane \{} V\_\-NORMAL, F\_\-DISTANCE [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The poly object: 
 

 \item 
   POLY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{poly \{} ORDER, $<$ POLY\_\-COEFFICIENTS $>$ 
  [POLY\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   ORDER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   An integer value between 2 and 15 inclusive. 
 \end{list}

 \item 
   POLY\_\-COEFFICIENTS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   A quantity \textbf{n} of FLOATs separated by commas, where \textbf{n} is {\small\texttt{((ORDER+1)*(ORDER+2)*(ORDER+3))/6.}} 
  
 \end{list}

 \item 
   POLY\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{sturm} [BOOL]] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The cubic object: 
 

 \item 
   CUBIC: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{cubic \{} $<$ CUBIC\_\-COEFFICIENTS $>$ 
  [POLY\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   CUBIC\_\-COEFFICIENTS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   20 FLOATs separated by commas. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The quartic object: 
 

 \item 
   QUARTIC: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{quartic \{} $<$ QUARTIC\_\-COEFFICIENTS $>$ 
  [POLY\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   QUARTIC\_\-COEFFICIENTS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   35 FLOATs separated by commas. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   The quadric object: 
 

 \item 
   QUADRIC: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{quadric \{} $<$ FLOAT, FLOAT, FLOAT $>$, 
  $<$ FLOAT, FLOAT, FLOAT $>$, $<$ FLOAT, FLOAT, FLOAT $>$, FLOAT [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Isosurface}

% reference/000448.html

\index{quickref! isosurface objects}\index{objects! isosurface, quickref}
\begin{description}
 
 \item 
   Describe a surface via a mathematical function: 
 

 \item 
   ISOSURFACE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{isosurface \{} FLOAT\_\-USER\_\-FUNCTION [ISOSURFACE\_\-ITEMS] 
  [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   ISOSURFACE\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{contained\_\-by \{} CONTAINER \textbf{\}}] \& [\textbf{threshold} FLOAT] 
  \& [\textbf{accuracy} FLOAT] \& [\textbf{max\_\-gradient} FLOAT [\textbf{evaluate} F\_\-MIN\_\-ESTIMATE, F\_\-MAX\_\-ESTIMATE, F\_\-ATTENUATION]] 
  \& [\textbf{open}] \& [INTERSECTION\_\-LIMIT]}} 
 \end{list}

 \item 
   CONTAINER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sphere \{ }V\_\-CENTER, F\_\-RADIUS \textbf{\}} | \textbf{box \{ }V\_\-CORNER1, 
  V\_\-CORNER2 \textbf{\}}}} 
 \end{list}

 \item 
   INTERSECTION\_\-LIMIT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{max\_\-trace} INT | \textbf{all\_\-intersections}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Parametric}

% reference/000447.html

\index{quickref! parametric objects}\index{objects! parametric, quickref}
\begin{description}
 
 \item 
   Describe a surface using functions to locate points on the surface: 
 

 \item 
   PARAMETRIC: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{parametric \{} FLOAT\_\-USER\_\-FUNCTION, FLOAT\_\-USER\_\-FUNCTION, 
  FLOAT\_\-USER\_\-FUNCTION 2D\_\-VECTOR, 2D\_\-VECTOR [PARAMETRIC\_\-ITEMS] [UV\_\-MAPPING] \& [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   PARAMETRIC\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{contained\_\-by \{} CONTAINER \textbf{\}}] \& [\textbf{max\_\-gradient} FLOAT] 
  \& [\textbf{accuracy} FLOAT] \& [\textbf{precompute} I\_\-DEPTH, \textbf{x, y, z}]}} 
 \end{list}

 \item 
   CONTAINER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sphere \{ }V\_\-CENTER, F\_\-RADIUS \textbf{\}} | \textbf{box \{ }V\_\-CORNER1, 
  V\_\-CORNER2 \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{CSG}

% reference/000446.html

\index{quickref! csg objects}\index{objects! csg, quickref}\index{Constructive Solid Geometry! quickref}
\begin{description}
 
 \item 
   Describe one complex shape from multiple shapes: 
 

 \item 
   CSG\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{UNION | INTERSECTION | DIFFERENCE | MERGE}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Combine multiple shapes into one: 
 

 \item 
   UNION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{union \{} UNION\_\-OBJECT UNION\_\-OBJECT... [UNION\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   UNION\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{OBJECT | LIGHT}} 
 \end{list}

 \item 
   UNION\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{split\_\-union} BOOL] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Create a new shape from the overlapping portions of multiple shapes: 
 

 \item 
   INTERSECTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{intersection \{} SOLID\_\-OBJECT SOLID\_\-OBJECT... 
  [INTERSECTION\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   SOLID\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FINITE\_\-SOLID\_\-OBJECT | INFINITE\_\-SOLID\_\-OBJECT | ISOSURFACE | CSG\_\-OBJECT}} 
  
 \end{list}

 \item 
   INTERSECTION\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{cutaway\_\-textures}] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Subtract one or more shapes from another: 
 

 \item 
   DIFFERENCE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{difference \{} SOLID\_\-OBJECT SOLID\_\-OBJECT... 
  [DIFFERENCE\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   DIFFERENCE\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{cutaway\_\-textures}] \& [OBJECT\_\-MODIFIERS]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Combine multiple shapes into one, removing internal surfaces: 
 

 \item 
   MERGE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{merge \{} SOLID\_\-OBJECT SOLID\_\-OBJECT... [OBJECT\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Object Modifiers}

% reference/000445.html

\index{quickref! object modifiers}\index{object modifiers! quickref}\index{object! modifiers, quickref}
\begin{description}
 
 \item 
   Manipulate the appearance of an object 
 

 \item 
   OBJECT\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[OBJECT\_\-PHOTONS] \& [CLIPPED\_\-BY] \& [BOUNDED\_\-BY] \& 
  [MATERIAL] \& [INTERIOR] \& [INTERIOR\_\-TEXTURE] \& [TEXTURE] \& [PIGMENT] \& [NORMAL] \& [FINISH] \& [TRANSFORMATION...] \& [\textbf{no\_\-shadow}] 
  \& [\textbf{no\_\-image}[BOOL]] \& [\textbf{no\_\-reflection}\{BOOL]] \& [\textbf{inverse}] \& [\textbf{double\_\-illuminate}[BOOL]] \& [\textbf{hollow} [BOOL]]}} 
  
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Specify how an object should interact with photons: 
 

 \item 
   OBJECT\_\-PHOTONS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{photons \{} OBJECT\_\-PHOTON\_\-ITEMS \textbf{\}}}} 
 \end{list}

 \item 
   OBJECT\_\-PHOTON\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{target} [F\_\-SPACING\_\-MULT]] \& [\textbf{refraction} BOOL] 
  \& [\textbf{reflection} BOOL] \& [\textbf{collect} BOOL] \& [\textbf{pass\_\-through} [BOOL]]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Slice a portion of a shape: 
 

 \item 
   CLIPPED\_\-BY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{clipped\_\-by \{} UNTEXTURED\_\-SOLID\_\-OBJECT... \textbf{\}} |\newline  
  \textbf{clipped\_\-by \{ bounded\_\-by \}}}} 
 \end{list}

 \item 
   UNTEXTURED\_\-SOLID\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FINITE\_\-SOLID\_\-OBJECT | INFINITE\_\-SOLID\_\-OBJECT}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Note, neither with a texture applied. 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Specify a bounding shape for an object: 
 

 \item 
   BOUNDED\_\-BY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{bounded\_\-by \{} UNTEXTURED\_\-SOLID\_\-OBJECT... \textbf{\}} |\newline  
  \textbf{bounded\_\-by \{ clipped\_\-by \}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{UV Mapping}

% reference/000444.html

\index{quickref! uv\_\-mapping}\index{uv\_\-mapping! quickref}
\begin{description}
 
 \item 
   Map a texture to an object using surface coordinates: 
 

 \item 
   UV\_\-MAPPING: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{uv\_\-mapping} PIGMENT | \textbf{pigment \{ uv\_\-mapping} PIGMENT\_\-BODY \textbf{\}} 
  |\newline  \textbf{uv\_\-mapping} NORMAL | \textbf{normal \{ uv\_\-mapping} NORMAL\_\-BODY \textbf{\}} |\newline  \textbf{uv\_\-mapping} TEXTURE | \textbf{texture \{ uv\_\-mapping} TEXTURE\_\-BODY \textbf{\}}}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Material}

% reference/000469.html

\index{quickref! material}\index{material! quickref}
\begin{description}
 
 \item 
   Group together surface textures and interior properties: 
 

 \item 
   MATERIAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{material \{} [MATERIAL\_\-IDENTIFIER] [MATERIAL\_\-ITEM ...] \textbf{\}}}} 
  
 \end{list}

 \item 
   MATERIAL\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TEXTURE | INTERIOR\_\-TEXTURE | INTERIOR | TRANSFORMATION}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Interior}

% reference/000474.html

\index{quickref! interior}\index{interior! quickref}
\begin{description}
 
 \item 
   Describe the interior of an object: 
 

 \item 
   INTERIOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{interior \{} [INTERIOR\_\-IDENTIFIER] [INTERIOR\_\-ITEMS] \textbf{\}}}} 
  
 \end{list}

 \item 
   INTERIOR\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{ior} FLOAT] \& [\textbf{dispersion} FLOAT] \& [\textbf{dispersion\_\-samples} INT] 
  \& [\textbf{caustics} FLOAT] \& [\textbf{fade\_\-distance} FLOAT] \& [\textbf{fade\_\-power} FLOAT] \& [\textbf{fade\_\-color} COLOR] 
  \& [MEDIA...]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Interior Texture}

% reference/000473.html

\index{quickref! interior texture}\index{interior texture}
\begin{description}
 
 \item 
   Describe the interior surface of an object: 
 

 \item 
   INTERIOR\_\-TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{interior\_\-texture \{} TEXTURE\_\-BODY \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Texture}

% reference/000472.html

\index{quickref! texture}\index{texture! quickref}
\begin{description}
 
 \item 
   Describe the surface of an object 
 

 \item 
   TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PLAIN\_\-TEXTURE | LAYERED\_\-TEXTURE | PATTERNED\_\-TEXTURE}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Plain Texture}

% reference/000471.html

\index{quickref! plain texture}\index{plain texture! quickref}\index{texture! plain, quickref}
\begin{description}
 
 \item 
   Describe a texture consisting of a single pigment, normal and finish: 
 

 \item 
   PLAIN\_\-TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture \{} PLAIN\_\-TEXTURE\_\-BODY \textbf{\}}}} 
 \end{list}

 \item 
   PLAIN\_\-TEXTURE\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PLAIN\_\-TEXTURE\_\-IDENT] [PNF\_\-IDENTIFIERS] [PNF\_\-ITEMS]}} 
 \end{list}

 \item 
   PNF\_\-IDENTIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PIGMENT\_\-IDENTIFIER] \& [NORMAL\_\-IDENTIFIER] \& 
  [FINISH\_\-IDENTIFIER]}} 
 \end{list}

 \item 
   PNF\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PIGMENT] \& [NORMAL] \& [FINISH] \& [TRANSFORMATION...]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Layered Texture}

% reference/000470.html

\index{quickref! layered texture}\index{layered texture! quickref}\index{texture! layered, quickref}
\begin{description}
 
 \item 
   Describe a texture consisting of two or more semi-\discretionary{}{}{}transparent layers: 
 

 \item 
   LAYERED\_\-TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture \{} LAYERED\_\-TEXTURE\_\-IDENT \textbf{\}} |\newline  
  PLAIN\_\-TEXTURE PLAIN\_\-TEXTURE...}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Patterned Texture}

% reference/000468.html

\index{quickref! patterned texture}\index{patterned texture! quickref}\index{texture! patterned, quickref}
\begin{description}
 
 \item 
   Describe a texture using a pattern or blending function: 
 

 \item 
   PATTERNED\_\-TEXTURE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture \{} PATTERNED\_\-TEXTURE\_\-BODY \textbf{\}}}} 
 \end{list}

 \item 
   PATTERNED\_\-TEXTURE\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PATTERNED\_\-TEXTURE\_\-IDENT [TRANSFORMATION...] | TEXTURE\_\-PATTERN 
  [PATTERN\_\-MODIFIERS] | MATERIAL\_\-MAP [TRANSFORMATION...]}} 
 \end{list}

 \item 
   TEXTURE\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TEXTURE\_\-LIST\_\-PATTERN | MAP\_\-PATTERN TEXTURE\_\-MAP}} 
 \end{list}

 \item 
   TEXTURE\_\-LIST\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{brick} TEXTURE, TEXTURE [BRICK\_\-ITEMS] |\newline  \textbf{checker} 
  TEXTURE, TEXTURE |\newline  \textbf{hexagon} TEXTURE, TEXTURE, TEXTURE |\newline  \textbf{object \{} LIST\_\-OBJECT TEXTURE, TEXTURE \textbf{\}}}} 
 \end{list}

 \item 
   \index{quickref! brick\_\-item}BRICK\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{brick\_\-size} VECTOR] \& [\textbf{mortar} FLOAT]}} 
  
 \end{list}

 \item 
   \index{quickref! list\_\-object}LIST\_\-OBJECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{UNTEXTURED\_\-SOLID\_\-OBJECT | UNTEXTURED\_\-SOLID\_\-OBJECT\_\-IDENT}} 
 \end{list}

 \item 
   TEXTURE\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{texture\_\-map \{} TEXTURE\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS]}} 
  
 \end{list}

 \item 
   TEXTURE\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{TEXTURE\_\-MAP\_\-IDENTIFIER | TEXTURE\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   TEXTURE\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT TEXTURE\_\-BODY \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

 \item 
   TEXTURE\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PLAIN\_\-TEXTURE\_\-BODY | LAYERED\_\-TEXTURE\_\-IDENT | PATTERNED\_\-TEXTURE\_\-BODY}} 
  
 \end{list}

 \item 
   MATERIAL\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{material\_\-map \{} BITMAP\_\-IMAGE [BITMAP\_\-MODIFIERS] TEXTURE... \textbf{\}}}} 
  
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Pigment}

% reference/000467.html

\index{quickref! pigment}\index{pigment! quickref}
\begin{description}
 
 \item 
   Describe a color or pattern of colors for a texture: 
 

 \item 
   PIGMENT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{pigment \{} PIGMENT\_\-BODY \textbf{\}}}} 
 \end{list}

 \item 
   PIGMENT\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PIGMENT\_\-IDENTIFIER] [PIGMENT\_\-TYPE] [PIGMENT\_\-MODIFIERS]}} 
 \end{list}

 \item 
   PIGMENT\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{COLOR | COLOR\_\-LIST\_\-PATTERN | PIGMENT\_\-LIST\_\-PATTERN | IMAGE\_\-MAP | 
  MAP\_\-PATTERN [COLOR\_\-MAP] | MAP\_\-PATTERN PIGMENT\_\-MAP}} 
 \end{list}

 \item 
   COLOR\_\-LIST\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{brick} [COLOR [, COLOR]] [BRICK\_\-ITEMS] |\newline  \textbf{checker} 
  [COLOR [, COLOR]] |\newline  \textbf{hexagon} [COLOR [, COLOR [, COLOR]]] |\newline  \textbf{object \{} LIST\_\-OBJECT [COLOR [, COLOR]] \textbf{\}}}} 
 \end{list}

 \item 
   PIGMENT\_\-LIST\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{brick} PIGMENT, PIGMENT [BRICK\_\-ITEMS] |\newline  \textbf{checker} 
  PIGMENT, PIGMENT |\newline  \textbf{hexagon} PIGMENT, PIGMENT, PIGMENT |\newline  \textbf{object \{} LIST\_\-OBJECT PIGMENT, PIGMENT \textbf{\}}}} 
 \end{list}

 \item 
   IMAGE\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{image\_\-map \{}BITMAP\_\-IMAGE [IMAGE\_\-MAP\_\-MODIFIER...] 
  [BITMAP\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   IMAGE\_\-MAP\_\-MODIFIER: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{filter} I\_\-PALETTE, F\_\-AMOUNT | \textbf{filter all} F\_\-AMOUNT 
  | \textbf{transmit} I\_\-PALETTE, F\_\-AMOUNT | \textbf{transmit all} F\_\-AMOUNT}} 
 \end{list}

 \item 
   COLOR\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{color\_\-map \{} COLOR\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS] 
  |\newline  \textbf{colour\_\-map \{} COLOR\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS]}} 
 \end{list}

 \item 
   COLOR\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{COLOR\_\-MAP\_\-IDENTIFIER | COLOR\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   COLOR\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT COLOR \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

 \item 
   PIGMENT\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{pigment\_\-map \{} PIGMENT\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS]}} 
  
 \end{list}

 \item 
   PIGMENT\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PIGMENT\_\-MAP\_\-IDENTIFIER | PIGMENT\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   PIGMENT\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT PIGMENT\_\-BODY \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

 \item 
   PIGMENT\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[QUICK\_\-COLOR] \& [PATTERN\_\-MODIFIERS]}} 
 \end{list}

 \item 
   QUICK\_\-COLOR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{quick\_\-color} COLOR | \textbf{quick\_\-colour} COLOR}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Normal}

% reference/000466.html

\index{quickref! normal}\index{normal! quickref}
\begin{description}
 
 \item 
   Simulate the visual or tactile surface characteristics of a texture: 
 

 \item 
   NORMAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{normal \{} NORMAL\_\-BODY \textbf{\}}}} 
 \end{list}

 \item 
   NORMAL\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[NORMAL\_\-IDENTIFIER] [NORMAL\_\-TYPE] [NORMAL\_\-MODIFIERS]}} 
 \end{list}

 \item 
   NORMAL\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{NORMAL\_\-PATTERN | BUMP\_\-MAP}} 
 \end{list}

 \item 
   NORMAL\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{NORMAL\_\-LIST\_\-PATTERN |\newline  MAP\_\-PATTERN [F\_\-DEPTH] [SLOPE\_\-MAP] |\newline  
  MAP\_\-PATTERN NORMAL\_\-MAP}} 
 \end{list}

 \item 
   NORMAL\_\-LIST\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{brick} NORMAL, NORMAL [BRICK\_\-ITEMS] | \textbf{brick} [F\_\-DEPTH] [BRICK\_\-ITEMS] 
  |\newline  \textbf{checker} NORMAL, NORMAL | \textbf{checker} [F\_\-DEPTH] |\newline  \textbf{hexagon} NORMAL, NORMAL, NORMAL | \textbf{hexagon} [F\_\-DEPTH] 
  |\newline  \textbf{object \{} LIST\_\-OBJECT NORMAL, NORMAL \textbf{\}} | \textbf{object \{} LIST\_\-OBJECT \textbf{\}} [F\_\-DEPTH]}} 
 \end{list}

 \item 
   NORMAL\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{normal\_\-map \{} NORMAL\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS]}} 
  
 \end{list}

 \item 
   NORMAL\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{NORMAL\_\-MAP\_\-IDENTIFIER | NORMAL\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   NORMAL\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT NORMAL\_\-BODY \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

 \item 
   SLOPE\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{slope\_\-map \{} SLOPE\_\-MAP\_\-BODY \textbf{\}} [BLEND\_\-MAP\_\-MODIFIERS]}} 
  
 \end{list}

 \item 
   SLOPE\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{SLOPE\_\-MAP\_\-IDENTIFIER | SLOPE\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   SLOPE\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT, $<$ F\_\-HEIGHT, F\_\-SLOPE $>$ \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

 \item 
   BUMP\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{bump\_\-map \{} BITMAP\_\-IMAGE [BUMP\_\-MAP\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   BUMP\_\-MAP\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[BITMAP\_\-MODIFIERS] \& [BUMP\_\-METHOD] \& [\textbf{bump\_\-size} FLOAT]}} 
  
 \end{list}

 \item 
   BUMP\_\-METHOD: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{use\_\-index} | \textbf{use\_\-color} | \textbf{use\_\-colour}}} 
 \end{list}

 \item 
   NORMAL\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[PATTERN\_\-MODIFIERS] \& [\textbf{bump\_\-size} FLOAT] \& [\textbf{no\_\-bump\_\-scale} [BOOL]] 
  \& [\textbf{accuracy} FLOAT]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Finish}

% reference/000443.html

\index{quickref! finish}\index{finish! quickref}
\begin{description}
 
 \item 
   Describe the reflective properties of a surface: 
 

 \item 
   FINISH: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{finish \{} [FINISH\_\-IDENTIFIER] [FINISH\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   FINISH\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{ambient} COLOR] \& [\textbf{diffuse} FLOAT] \& [\textbf{brilliance} FLOAT] 
  \& [PHONG] \& [SPECULAR] \& [REFLECTION] \& [IRID] \& [\textbf{crand} FLOAT] \& [\textbf{conserve\_\-energy} [BOOL]]}} 
 \end{list}

 \item 
   PHONG: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{phong} FLOAT \& [\textbf{phong\_\-size} FLOAT] \& [\textbf{metallic} [FLOAT]]}} 
  
 \end{list}

 \item 
   SPECULAR: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{specular} FLOAT \& [\textbf{roughness} FLOAT] \& [\textbf{metallic} [FLOAT]]}} 
  
 \end{list}

 \item 
   REFLECTION: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{reflection} COLOR [\textbf{reflection\_\-exponent} FLOAT] |\newline  
  \textbf{reflection \{} [COLOR,] COLOR [REFLECTION\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   REFLECTION\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{fresnel} BOOL] \& [\textbf{falloff} FLOAT] \& [\textbf{exponent} FLOAT] 
  \& [\textbf{metallic} [FLOAT]]}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Must also use {\small\texttt{\textbf{interior \{ior} FLOAT\textbf{\}}}} in 
  the object when \textbf{{\small\texttt{fresnel}}} is used. 
 \end{list}

 \item 
   IRID: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{irid \{} F\_\-AMOUNT [IRID\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   IRID\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{thickness} FLOAT] \& [\textbf{turbulence} FLOAT]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Pattern}

% reference/000460.html

\index{quickref! pattern}\index{pattern! quickref}
\begin{description}
 
 \item 
   Specify a pattern function for a texture, pigment, normal or density: 
 

 \item 
   MAP\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{AGATE | \textbf{average} | \textbf{boxed} | \textbf{bozo} | \textbf{bumps} 
  | \textbf{cells} | CRACKLE | \textbf{cylindrical} | DENSITY\_\-FILE | \textbf{dents} | FACETS | FRACTAL | \textbf{function \{} FN\_\-FLOAT \textbf{\}} | \textbf{gradient} VECTOR 
  | \textbf{granite} | IMAGE\_\-PATTERN | \textbf{leopard} | \textbf{marble} | \textbf{onion} | \textbf{pigment\_\-pattern \{} PIGMENT\_\-BODY \textbf{\}} 
  | \textbf{planar} | QUILTED | \textbf{radial} | \textbf{ripples} | SLOPE | \textbf{spherical} | \textbf{spiral1} I\_\-NUM\_\-ARMS | \textbf{spiral2} I\_\-NUM\_\-ARMS 
  | \textbf{spotted} | \textbf{waves} | \textbf{wood} | \textbf{wrinkles}}} 
 \end{list}

 \item 
   AGATE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{agate} [\textbf{agate\_\-turb} FLOAT]}} 
 \end{list}

 \item 
   CRACKLE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{crackle} [CRACKLE\_\-TYPES]}} 
 \end{list}

 \item 
   CRACKLE\_\-TYPES: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{form} VECTOR] \& [\textbf{metric} FLOAT] \& [\textbf{offset} FLOAT] 
  \& [\textbf{solid}]}} 
 \end{list}

 \item 
   DENSITY\_\-FILE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{density\_\-file df3} FILE\_\-NAME [\textbf{interpolate} DENSITY\_\-INTERPOLATE]}} 
  
 \end{list}

 \item 
   DENSITY\_\-INTERPOLATE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1} | \textbf{2}}} 
 \end{list}

 \item 
   FACETS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{facets} FACETS\_\-TYPE}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Note, {\small\texttt{\textbf{facets}}} can only be used as a {\small\texttt{\textbf{normal}}} 
  pattern. 
 \end{list}

 \item 
   FACETS\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{coords} F\_\-SCALE | \textbf{size} F\_\-SIZE\_\-FACTOR}} 
 \end{list}

 \item 
   FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{MANDELBROT\_\-FRACTAL | JULIA\_\-FRACTAL | MAGNET\_\-MANDEL\_\-FRACTAL | 
  MAGNET\_\-JULIA\_\-FRACTAL}} 
 \end{list}

 \item 
   MANDELBROT\_\-FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{mandel} I\_\-ITERATIONS [\textbf{exponent} INT] [\textbf{exterior} EXTERIOR\_\-TYPE, F\_\-FACTOR] 
  [\textbf{interior} INTERIOR\_\-TYPE, F\_\-FACTOR]}} 
 \end{list}

 \item 
   JULIA\_\-FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{julia} V2\_\-COMPLEX, I\_\-ITERATIONS [\textbf{exponent} INT] 
  [\textbf{exterior} EXTERIOR\_\-TYPE, F\_\-FACTOR] [\textbf{interior} INTERIOR\_\-TYPE, F\_\-FACTOR]}} 
 \end{list}

 \item 
   MAGNET\_\-MANDEL\_\-FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{magnet} MAGNET\_\-TYPE \textbf{mandel} I\_\-ITERATIONS [\textbf{exterior} EXTERIOR\_\-TYPE, F\_\-FACTOR] 
  [\textbf{interior} INTERIOR\_\-TYPE, F\_\-FACTOR]}} 
 \end{list}

 \item 
   MAGNET\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2}}} 
 \end{list}

 \item 
   MAGNET\_\-JULIA\_\-FRACTAL: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{magnet} MAGNET\_\-TYPE \textbf{julia} V2\_\-COMPLEX, I\_\-ITERATIONS [\textbf{exterior} EXTERIOR\_\-TYPE, F\_\-FACTOR] 
  [\textbf{interior} INTERIOR\_\-TYPE, F\_\-FACTOR]}} 
 \end{list}

 \item 
   EXTERIOR\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1} | \textbf{2} | \textbf{3} | \textbf{4} | \textbf{5} 
  | \textbf{6}}} 
 \end{list}

 \item 
   INTERIOR\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1} | \textbf{2} | \textbf{3} | \textbf{4} | \textbf{5} 
  | \textbf{6}}} 
 \end{list}

 \item 
   IMAGE\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{image\_\-pattern \{}BITMAP\_\-IMAGE [IMAGE\_\-PATTERN\_\-MODIFIERS] \textbf{\}}}} 
  
 \end{list}

 \item 
   IMAGE\_\-PATTERN\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[BITMAP\_\-MODIFIERS] \& [\textbf{use\_\-alpha}]}} 
 \end{list}

 \item 
   QUILTED: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{quilted} [\textbf{control0} FLOAT] [\textbf{control1} FLOAT]}} 
  
 \end{list}

 \item 
   SLOPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{slope \{} V\_\-DIRECTION [, F\_\-LOW\_\-SLOPE, F\_\-HIGH\_\-SLOPE ] [\textbf{altitude} VECTOR 
  [, F\_\-LOW\_\-ALT, F\_\-HIGH\_\-ALT ]] \textbf{\}}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The {\small\texttt{\textbf{slope}}} pattern does not work in media densities. 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Pattern Modifiers}

% reference/000465.html

\index{quickref! pattern modifiers}\index{pattern modifiers! quickref}
\begin{description}
 
 \item 
   Modify the evaluation of a pattern function: 
 

 \item 
   PATTERN\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[TURBULENCE] \& [WARP...] \& [TRANSFORMATION...] \& [\textbf{noise\_\-generator} NG\_\-TYPE]}} 
  
 \end{list}

 \item 
   NG\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2} | \textbf{3}}} 
 \end{list}

 \item 
   TURBULENCE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{turbulence} VECTOR \& [\textbf{octaves} INT] \& [\textbf{omega} FLOAT] 
  \& [\textbf{lambda} FLOAT]}} 
 \end{list}

 \item 
   WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{warp \{} WARP\_\-ITEM \textbf{\}}}} 
 \end{list}

 \item 
   WARP\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{REPEAT\_\-WARP | BLACK\_\-HOLE\_\-WARP | TURBULENCE | CYLINDRICAL\_\-WARP | 
  SPHERICAL\_\-WARP | TOROIDAL\_\-WARP | PLANAR\_\-WARP}} 
 \end{list}

 \item 
   REPEAT\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{repeat} VECTOR [\textbf{offset} VECTOR] [\textbf{flip} VECTOR]}} 
  
 \end{list}

 \item 
   BLACK\_\-HOLE\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{black\_\-hole} V\_\-LOCATION, F\_\-RADIUS [BLACK\_\-HOLE\_\-ITEMS]}} 
 \end{list}

 \item 
   BLACK\_\-HOLE\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{strength} FLOAT] \& [\textbf{falloff} FLOAT] \& [\textbf{inverse}] 
  \& [\textbf{repeat} VECTOR [\textbf{turbulence} VECTOR]]}} 
 \end{list}

 \item 
   CYLINDRICAL\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{cylindrical} [\textbf{orientation} VECTOR] [\textbf{dist\_\-exp} FLOAT]}} 
  
 \end{list}

 \item 
   SPHERICAL\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{spherical} [\textbf{orientation} VECTOR] [\textbf{dist\_\-exp} FLOAT]}} 
  
 \end{list}

 \item 
   TOROIDAL\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{toroidal} [\textbf{orientation} VECTOR] [\textbf{dist\_\-exp} FLOAT] 
  [\textbf{major\_\-radius} FLOAT]}} 
 \end{list}

 \item 
   PLANAR\_\-WARP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{planar} [V\_\-NORMAL, F\_\-DISTANCE]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   \index{quickref! blend\_\-map\_\-modifiers}Modify the usage of a blend map: 
 

 \item 
   BLEND\_\-MAP\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   [\textbf{frequency} FLOAT] \& [\textbf{phase} FLOAT] \& [WAVEFORM] 
 \end{list}

 \item 
   WAVEFORM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{ramp\_\-wave} | \textbf{triangle\_\-wave} | \textbf{sine\_\-wave} | \textbf{scallop\_\-wave} 
  | \textbf{cubic\_\-wave} | \textbf{poly\_\-wave} [F\_\-EXPONENT]}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   \index{quickref! bitmap}Specify a two-\discretionary{}{}{}dimensional bitmap image for a pattern: 
 

 \item 
   BITMAP\_\-IMAGE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FUNCTION\_\-IMAGE | BITMAP\_\-TYPE FILE\_\-NAME}} 
 \end{list}

 \item 
   FUNCTION\_\-IMAGE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{function} I\_\-WIDTH, I\_\-HEIGHT \textbf{\{} FUNCTION\_\-IMAGE\_\-BODY \textbf{\}}}} 
  
 \end{list}

 \item 
   FUNCTION\_\-IMAGE\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PIGMENT | FN\_\-FLOAT | \textbf{pattern \{} PATTERN 
  [PATTERN\_\-MODIFIERS] \textbf{\}}}} 
 \end{list}

 \item 
   PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{MAP\_\-PATTERN | \textbf{brick} [BRICK\_\-ITEMS] | \textbf{checker} | \textbf{hexagon} 
  | \textbf{object \{} LIST\_\-OBJECT \textbf{\}}}} 
 \end{list}

 \item 
   BITMAP\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{gif} | \textbf{tga} | \textbf{iff} | \textbf{ppm} | \textbf{pgm} 
  | \textbf{png} | \textbf{jpeg} | \textbf{tiff} | \textbf{sys}}} 
 \end{list}

\end{description}

\begin{description}
 
 \item 
   Modify how a 2-D bitmap is to be applied to a 3-D surface: 
 

 \item 
   BITMAP\_\-MODIFIERS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{once}] \& [\textbf{map\_\-type} MAP\_\-TYPE] \& [\textbf{interpolate} INTERPOLATE\_\-TYPE]}} 
  
 \end{list}

 \item 
   MAP\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{0} | \textbf{1} | \textbf{2} | \textbf{5}}} 
 \end{list}

 \item 
   INTERPOLATE\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{2} | \textbf{4}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Media}

% reference/000464.html

\index{quickref! media}\index{media! quickref}
\begin{description}
 
 \item 
   Describe particulate matter 
 

 \item 
   MEDIA: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{media \{} [MEDIA\_\-IDENTIFIER] [MEDIA\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   MEDIA\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{method} METHOD\_\-TYPE] \& [\textbf{intervals} INT] 
  \& [\textbf{samples} I\_\-MIN, I\_\-MAX] \& [\textbf{confidence} FLOAT] \& [\textbf{variance} FLOAT] \& [\textbf{ratio} FLOAT] 
  \& [\textbf{absorption} COLOR] \& [\textbf{emission} COLOR] \& [\textbf{aa\_\-threshold} FLOAT] \& [\textbf{aa\_\-level} INT] \& 
  [SCATTERING] \& [DENSITY...] \& [TRANSFORMATION...] \& [\textbf{collect} BOOL]}} 
 \end{list}

 \item 
   METHOD\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2} | \textbf{3}}} 
 \end{list}

 \item 
   SCATTERING: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{scattering \{} SCATTERING\_\-TYPE, COLOR [\textbf{eccentricity} FLOAT] 
  [\textbf{extinction} FLOAT] \textbf{\}}}} 
 \end{list}

 \item 
   SCATTERING\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2} | \textbf{3} | \textbf{4} | \textbf{5}}} 
 \end{list}

 \item 
   DENSITY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{density \{} DENSITY\_\-BODY \textbf{\}}}} 
 \end{list}

 \item 
   DENSITY\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[DENSITY\_\-IDENTIFIER] [DENSITY\_\-TYPE] [PATTERN\_\-MODIFIERS]}} 
 \end{list}

 \item 
   DENSITY\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{COLOR | COLOR\_\-LIST\_\-PATTERN | DENSITY\_\-LIST\_\-PATTERN | MAP\_\-PATTERN [COLOR\_\-MAP] 
  | MAP\_\-PATTERN DENSITY\_\-MAP}} 
 \end{list}

 \item 
   DENSITY\_\-LIST\_\-PATTERN: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{brick} DENSITY, DENSITY [BRICK\_\-ITEMS] |\newline  \textbf{checker} 
  DENSITY, DENSITY |\newline  \textbf{hexagon} DENSITY, DENSITY, DENSITY |\newline  \textbf{object \{} LIST\_\-OBJECT DENSITY, DENSITY \textbf{\}}}} 
 \end{list}

 \item 
   DENSITY\_\-MAP: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{density\_\-map \{} DENSITY\_\-MAP\_\-BODY \textbf{\}} 
  [BLEND\_\-MAP\_\-MODIFIERS]}} 
 \end{list}

 \item 
   DENSITY\_\-MAP\_\-BODY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{DENSITY\_\-MAP\_\-IDENTIFIER | DENSITY\_\-MAP\_\-ENTRY...}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   There may be from 2 to 256 map entries. 
 \end{list}

 \item 
   DENSITY\_\-MAP\_\-ENTRY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{[} FLOAT DENSITY\_\-BODY \textbf{]}}} 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   The brackets here are part of the map entry. 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Atmospheric Effects}

% reference/000463.html

\index{quickref! atmospheric effects}\index{atmospheric effects! quickref}
\begin{description}
 
 \item 
   Describe various background and atmospheric features 
 

 \item 
   ATMOSPHERIC\_\-EFFECT: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{MEDIA | BACKGROUND | FOG | SKY\_\-SPHERE | RAINBOW}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Background}

% reference/000462.html

\index{quickref! background}\index{background! quickref}
\begin{description}
 
 \item 
   Specify a background color for the scene: 
 

 \item 
   BACKGROUND: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{background \{} COLOR \textbf{\}}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Fog}

% reference/000461.html

\index{quickref! fog}\index{fog! quickref}
\begin{description}
 
 \item 
   Simulate a hazy or foggy atmosphere: 
 

 \item 
   FOG: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{CONSTANT\_\-FOG | GROUND\_\-FOG}} 
 \end{list}

 \item 
   CONSTANT\_\-FOG: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{fog \{} [FOG\_\-IDENTIFIER] [\textbf{fog\_\-type 1}] FOG\_\-ITEMS \textbf{\}}}} 
  
 \end{list}

 \item 
   FOG\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{distance} FLOAT \& COLOR \& [TURBULENCE [\textbf{turb\_\-depth} FLOAT]]}} 
  
 \end{list}

 \item 
   GROUND\_\-FOG: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{fog \{} [FOG\_\-IDENTIFIER] \textbf{fog\_\-type 2} 
  GROUND\_\-FOG\_\-ITEMS \textbf{\}}}} 
 \end{list}

 \item 
   GROUND\_\-FOG\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{FOG\_\-ITEMS \& \textbf{fog\_\-offset} FLOAT \& \textbf{fog\_\-alt} FLOAT 
  \& [\textbf{up} VECTOR [TRANSFORMATION...]]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Sky Sphere}

% reference/000475.html

\index{quickref! sky sphere}\index{sky sphere! quickref}
\begin{description}
 
 \item 
   Specify a sky pigment: 
 

 \item 
   SKY\_\-SPHERE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{sky\_\-sphere \{} [SKY\_\-SPHERE\_\-IDENTIFIER] [SKY\_\-SPHERE\_\-ITEM...] \textbf{\}}}} 
  
 \end{list}

 \item 
   SKY\_\-SPHERE\_\-ITEM: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{PIGMENT | TRANSFORMATION}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Rainbow}

% reference/000477.html

\index{quickref! rainbow}\index{rainbow! quickref}
\begin{description}
 
 \item 
   Specify a rainbow arc: 
 

 \item 
   RAINBOW: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{rainbow \{} [RAINBOW\_\-IDENTIFIER] [RAINBOW\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   RAINBOW\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{direction} VECTOR \& \textbf{angle} FLOAT \& \textbf{width} FLOAT 
  \& \textbf{distance} FLOAT \& COLOR\_\-MAP \& [\textbf{jitter} FLOAT] \& [\textbf{up} VECTOR] \& [\textbf{arc\_\-angle} FLOAT] 
  \& [\textbf{falloff\_\-angle} FLOAT]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\section{Global Settings}

% reference/000478.html

\index{quickref! global settings}\index{global settings! quickref}
\begin{description}
 
 \item 
   Specify various settings that apply to the entire scene 
 

 \item 
   GLOBAL\_\-SETTINGS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{global\_\-settings \{} GLOBAL\_\-SETTING\_\-ITEMS \textbf{\}}}} 
 \end{list}

 \item 
   GLOBAL\_\-SETTING\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{adc\_\-bailout} FLOAT] \& [\textbf{ambient\_\-light} COLOR] 
  \& [\textbf{assumed\_\-gamma} FLOAT] \& [\textbf{hf\_\-gray\_\-16} [BOOL]] \& [\textbf{irid\_\-wavelength} COLOR] \& [\textbf{charset} GLOBAL\_\-CHARSET] 
  \& [\textbf{max\_\-intersections} INT] \& [\textbf{max\_\-trace\_\-level} INT] \& [\textbf{number\_\-of\_\-waves} INT] \& [\textbf{noise\_\-generator} NG\_\-TYPE] 
  \& [RADIOSITY] \& [PHOTONS]}} 
 \end{list}

 \item 
   GLOBAL\_\-CHARSET: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{ascii} | \textbf{utf8} | \textbf{sys}}} 
 \end{list}

 \item 
   NG\_\-TYPE: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{1} | \textbf{2} | \textbf{3}}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Radiosity}

% reference/000479.html

\index{quickref! radiosity}\index{radiosity! quickref}
\begin{description}
 
 \item 
   Enable radiosity to compute diffuse inter-\discretionary{}{}{}reflection of light: 
 

 \item 
   RADIOSITY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{radiosity \{} [RADIOSITY\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   RADIOSITY\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{adc\_\-bailout} FLOAT] \& [\textbf{always\_\-sample} BOOL] 
  \& [\textbf{brightness} FLOAT] \& [\textbf{count} INT] \& [\textbf{error\_\-bound} FLOAT] \& [\textbf{gray\_\-threshold} FLOAT] \& [\textbf{load\_\-file} FILE\_\-NAME] 
  \& [\textbf{low\_\-error\_\-factor} FLOAT] \& [\textbf{max\_\-sample} FLOAT] \& [\textbf{media} BOOL] \& [\textbf{minimum\_\-reuse} FLOAT] 
  \& [\textbf{nearest\_\-count} INT] \& [\textbf{normal} BOOL] \& [\textbf{pretrace\_\-end} FLOAT] \& [\textbf{pretrace\_\-start} FLOAT] 
  \& [\textbf{recursion\_\-limit} INT] \& [\textbf{save\_\-file} FILE\_\-NAME]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\subsection{Photons}

% reference/000183.html

\index{quickref! photons}\index{photons! quickref}
\begin{description}
 
 \item 
   Enable photon mapping to render reflective and refractive caustics: 
 

 \item 
   PHOTONS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   Jump to SDL 
 \end{list}

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{photons \{} PHOTON\_\-QUANTITY [PHOTON\_\-ITEMS] \textbf{\}}}} 
 \end{list}

 \item 
   PHOTON\_\-QUANTITY: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{\textbf{spacing} FLOAT | \textbf{count} INT}} 
 \end{list}

 \item 
   PHOTON\_\-ITEMS: 
 

 \begin{list}{}{\setlength{\parskip}{-8pt}\setlength{\itemsep}{-2pt}}\item 
   {\small\texttt{[\textbf{gather} I\_\-MIN, I\_\-MAX] \& [\textbf{media} I\_\-MAX\_\-STEPS [, F\_\-FACTOR]] 
  \& [\textbf{jitter} FLOAT] \& [\textbf{max\_\-trace\_\-level} INT] \& [\textbf{adc\_\-bailout} FLOAT] \& [\textbf{save\_\-file} FILE\_\-NAME] 
  \& [\textbf{load\_\-file} FILE\_\-NAME] \& [\textbf{autostop} FLOAT] \& [\textbf{expand\_\-thresholds} F\_\-INCREASE, F\_\-MIN] \& [\textbf{radius} [FLOAT, 
  FLOAT, FLOAT, FLOAT]]}} 
 \end{list}

\end{description}


   Quick Reference Contents 


\cleardoublepage

\printindex

\end{document}
