Persistence of Vision ™ Ray-Tracer
POV-Ray ™ Version 3.1
User's Documentation
August 1998
Copyright 1998 POV-Team ™
POV-Ray ™ is based on DKBTrace 2.12 by David K. Buck and Aaron A. Collins.
POV-Ray, POV-Help, POV-Team, and Persistence of Vision are trademarks of the POV-Team.
Table of Contents
Introduction
Program Description
What is Ray-Tracing?
What is POV-Ray?
How Do I Begin?
Notation and Basic Assumptions
What's New in POV-Ray 3.1?
Media Replaces Halo & Atmosphere
New #macro Feature
Arrays Added
File I/O and other Directives
Additional New Features
Beginning Tutorial
Our First Image
Understanding POV-Ray's Coordinate System
Adding Standard Include Files
Adding a Camera
Describing an Object
Adding Texture to an Object
Defining a Light Source
Simple Shapes
Box Object
Cone Object
Cylinder Object
Plane Object
CSG Objects
What is CSG?
CSG Union
CSG Intersection
CSG Difference
CSG Merge
CSG Pitfalls
Coincidence Surfaces
Advanced Shapes
Bicubic Patch Object
Blob Object
Component Types and Other New Features
Complex Blob Constructs and Negative Strength
Height Field Object
Lathe Object
Understanding The Concept of Splines
Mesh Object
Polygon Object
Prism Object
Teaching An Old Spline New Tricks
Smooth Transitions
Multiple Sub-Shapes
Conic Sweeps And The Tapering Effect
Superquadric Ellipsoid Object
Surface of Revolution Object
Text Object
Torus Object
The Light Source
The Pointlight Source
The Spotlight Source
The Cylindrical Light Source
The Area Light Source
The Ambient Light Source
Light Source Specials
Using Shadowless Lights
Assigning an Object to a Light Source
Using Light Fading
Simple Texture Options
Surface Finishes
Adding Bumpiness
Creating Color Patterns
Pre-defined Textures
Advanced Texture Options
Pigments
Using Color List Pigments
Using Pigment and Patterns
Using Pattern Modifiers
Using Transparent Pigments and Layered Textures
Using Pigment Maps
Normals
Using Basic Normal Modifiers
Blending Normals
Finishes
Using Ambient
Using Surface Highlights
Using Reflection and Metallic
Using Iridescence
Working With Pigment Maps
Working With Normal Maps
Working With Texture Maps
Working With List Textures
What About Tiles?
Average Function
Working With Layered Textures
Declaring Layered Textures
Another Layered Textures Example
When All Else Fails: Material Maps
Limitations Of Special Textures
Using the Camera
Using Focal Blur
Using Atmospheric Effects
The Background
The Sky Sphere
Creating a Sky with a Color Gradient
Adding the Sun
Adding Some Clouds
The Fog
A Constant Fog
Setting a Minimum Translucency
Creating a Filtering Fog
Adding Some Turbulence to the Fog
Using Ground Fog
Using Multiple Layers of Fog
Fog and Hollow Objects
The Rainbow
Starting With a Simple Rainbow
Increasing the Rainbow's Translucency
Using a Rainbow Arc
Animation
The Clock Variable: Key To It All
Clock Dependant Variables And Multi-Stage Animations
The Phase Keyword
Do Not Use Jitter Or Crand
INI File Settings
POV-Ray Options
Setting POV-Ray Options
Command Line Switches
Using INI Files
Using the POVINI Environment Variable
Options Reference
Animation Options
External Animation Loop
Internal Animation Loop
Subsets of Animation Frames
Cyclic Animation
Field Rendering
Output Options
General Output Options
Height and Width of Output
Partial Output Options
Interrupting Options
Resuming Options
Display Output Options
Display Hardware Settings
Display Related Settings
Mosaic Preview
File Output Options
Output File Type
Output File Name
Output File Buffer
CPU Utilization Histogram
File Type
File Name
Grid Size
Scene Parsing Options
Input File Name
Library Paths
Language Version
Shell-out to Operating System
String Substitution in Shell Commands
Shell Command Sequencing
Shell Command Return Actions
Text Output
Text Streams
Console Text Output
Directing Text Streams to Files
Help Screen Switches
Tracing Options
Quality Settings
Radiosity Setting
Automatic Bounding Control
Removing User Bounding
Anti-Aliasing Options
Scene Description Language
Language Basics
Identifiers and Keywords
Comments
Float Expressions
Float Literals
Float Identifiers
Float Operators
Built-in Float Identifiers
Boolean Keywords
Float Functions
Vector Expressions
Vector Literals
Vector Identifiers
Vector Operators
Operator Promotion
Built-in Vector Identifiers
Vector Functions
Specifying Colors
Color Vectors
Color Keywords
Color Identifiers
Color Operators
Common Color Pitfalls
Strings
String Literals
String Identifiers
String Functions
Array Identifiers
Declaring Arrays
Array Initalizers
Language Directives
Include Files and the #include Directive.
The #declare and #local Directives
Declaring identifiers
#declare vs. #local
Identifier Name Collisions
Destroying Identifiers with #undef
File I/O Directives
The #fopen Directive
The #fclose Directive
The #read Directive
The #write Directive
The #default Directive
The #version Directive
Conditional Directives
The #if...#else...#end Directives
The #ifdef and #ifndef Directives
The #switch, #case, #range and #break Directives
The #while...#end Directive
User Message Directives
Text Message Streams
Text Formatting
User Defined Macros
The #macro Directive
Invoking Macros
Are POV-Ray Macros a Function or a Macro?
Returning a Value Like a Function
Returning Values Via Parameters
POV-Ray Coordinate System
Transformations
Translate
Scale
Rotate
Matrix Keyword
Transformation Order
Transform Identifiers
Transforming Textures and Objects
Camera
Placing the Camera
Location and Look_At
The Sky Vector
Angle
The Direction Vector
Up and Right Vectors
Aspect Ratio
Handedness
Transforming the Camera
Types of Projection
Focal Blur
Camera Ray Perturbation
Camera Identifiers
Objects
Finite Solid Primitives
Blob
Box
Cone
Cylinder
Height Field
Julia Fractal
Lathe
Prism
Sphere
Superquadric Ellipsoid
Surface of Revolution
Text
Torus
Finite Patch Primitives
Bicubic Patch
Disc
Mesh
Polygon
Triangle and Smooth Triangle
Infinite Solid Primitives
Plane
Poly, Cubic and Quartic
Quadric
Constructive Solid Geometry
Inside and Outside
Union
Intersection
Difference
Merge
Light Sources
Point Lights
Spotlights
Cylindrical Lights
Area Lights
Shadowless Lights
Looks_like
Light Fading
Atmospheric Media Interaction
Atmospheric Attenuation
Object Modifiers
Clipped_By
Bounded_By
Material
Inverse
Hollow
No_Shadow
Sturm
Interior
Why are Interior and Media Necessary?
Empty and Solid Objects
Refraction
Attenuation
Faked Caustics
Object Media
Textures
Pigment
Solid Color Pigments
Color List Pigments
Color Maps
Pigment Maps and Pigment Lists
Image Maps
Specifying an Image Map
The Filter and Transmit Bitmap Modifiers
Using the Alpha Channel
Quick Color
Normal
Slope Maps
Normal Maps and Normal Lists
Bump Maps
Specifying a Bump Map
Bump_Size
Use_Index and Use_Color
Finish
Ambient
Diffuse Reflection Items
Diffuse
Brilliance
Crand Graininess
Highlights
Phong Highlights
Specular Highlight
Metallic Highlight Modifier
Specular Reflection
Iridescence
Halo
Patterned Textures
Texture Maps
Tiles
Material Maps
Specifying a Material Map
Layered Textures
Patterns
Agate
Average
Boxed
Bozo
Brick
Bumps
Checker
Crackle
Cylindrical
Density_File
Dents
Gradient
Granite
Hexagon
Leopard
Mandel
Marble
Onion
Planar
Quilted
Radial
Ripples
Spherical
Spiral1
Spiral2
Spotted
Waves
Wood
Wrinkles
Pattern Modifiers
Transforming Patterns
Frequency and Phase
Waveforms
Turbulence
Octaves
Lambda
Omega
Warps
Black Hole Warp
Repeat Warp
Turbulence Warp
Bitmap Modifiers
The once Option
The map_type Option
The interpolate Option
Media
Media Types
Absorption
Emission
Scattering
Sampling Parameters
Density
General Density Modifiers
Density with color_map
Density Maps and Density Lists
Multiple Density vs. Multiple Media
Atmospheric Effects
Atmospheric Media
Background
Fog
Sky Sphere
Rainbow
Global Settings
ADC_Bailout
Ambient Light
Assumed_Gamma
Monitor Gamma
Image File Gamma
Scene File Gamma
HF_Gray_16
Irid_Wavelength
Max_Trace_Level
Max_Intersections
Number_Of_Waves
Radiosity
How Radiosity Works
Adjusting Radiosity
brightness
count
distance_maximum
error_bound
gray_threshold
low_error_factor
minimum_reuse
nearest_count
recursion_limit
Tips on Radiosity
APPENDICES
Copyright, Legal Information and License -- POVLEGAL.DOC
General License Agreement -- POVLEGAL.DOC
Usage Provisions
General Rules For All Distribution
Definition Of "Full Package"
Conditions For Shareware/Freeware Distribution Companies
Conditions For On-Line Services And Bbs's Including Internet
Online Or Remote Execution Of POV-Ray
Permitted Modification And Custom Versions
Conditions For Distribution Of Custom Versions
Conditions For Commercial Bundling
POV-Team Endorsement Prohibitions
Retail Value Of This Software
Other Provisions
Revocation Of License
Disclaimer
Technical Support
Authors
Contacting the Authors
What to do if you don't have POV-Ray
Which Version of POV-Ray should you use?
Microsoft Windows 95/98/NT
MS-Dos & Windows 3.x
Linux for Intel x86
Apple Macintosh
Amiga
SunOS
Generic Unix
All Versions
Where to Find POV-Ray Files
POV-Ray Forum on CompuServe
World Wide Website www.povray.org
Books, Magazines and CD-ROMs
Compiling POV-Ray
Directory Structure
Configuring POV-Ray Source
Conclusion
Suggested Reading