From POV-Wiki
Revision as of 13:00, 23 September 2018 by Jholsenback (talk | contribs) (sub-section additions)
Jump to navigation Jump to search

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


Persistence Of Vision Raytracer™


Welcome to the POV-Ray documentation repository ... if you're looking for the most up to date documentation, you've found it! This content is used to generate the documentation included with the distribution, so occasionally it can get ahead of the current release.

The content has been divided into the following five major sections:

  1. Introduction to POV-Ray
  2. POV-Ray Reference
  3. POV-Ray for Windows
  4. POV-Ray for Mac OS
  5. POV-Ray for Unix

New to POV-Ray? You'd most likely want to begin with the tutorial section. Need to locate something quickly? The list of identifiers and keywords is a good place to start. See the changes and new features summary for what's new with this release.

Introduction to POV-Ray

1.1 Introduction
1.1.1 Program Description
1.1.2 What is Ray-Tracing?
1.1.3 What is POV-Ray?
1.1.4 Features Changes and New Features Summary Version 3.8 Version 3.7
1.1.5 Trademarks
1.1.6 The Early History of POV-Ray The Original Creation Message The Name A Historic 'Version History'
1.1.7 How Do I Begin?
1.1.8 Notation and Basic Assumptions
1.2 Getting Started
1.2.1 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
1.2.2 Basic Shapes Box Object Cone Object Cylinder Object Plane Object Torus Object
1.2.3 CSG Objects What is CSG? CSG Union CSG Intersection CSG Difference CSG Merge CSG Pitfalls Co-incident Surfaces
1.2.4 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
1.2.5 Simple Texture Options Surface Finishes Adding Bumpiness Creating Color Patterns Pre-defined Textures
1.2.6 Using the Camera Using Focal Blur
1.2.7 POV-Ray Coordinate System Transformations Translate Scale Rotate Matrix Transformation Order Inverse Transform Transform Identifiers Transforming Textures and Objects
1.2.8 Setting POV-Ray Options Command Line Switches Using INI Files Using the POVINI Environment Variable
1.3 Advanced Features
1.3.1 Spline Based Shapes Lathe Object Understanding The Concept of Splines Surface of Revolution Object Prism Object Teaching An Old Spline New Tricks Smooth Transitions Multiple Sub-Shapes Conic Sweeps And The Tapering Effect Sphere Sweep Object Bicubic Patch Object Text Object
1.3.2 Polygon Based Shapes Mesh Object Mesh2 Object Smooth triangles and mesh2 UV mapping and mesh2 A separate texture per triangle Polygon Object
1.3.3 Other Shapes Blob Object Component Types and Other New Features Complex Blob Constructs and Negative Strength Height Field Object Isosurface Object Simple functions Several surfaces Non-linear functions Specifying functions Internal functions Combining isosurface functions Noise and pigment functions Conditional directives and loops Transformations on functions Improving Isosurface Speed Poly Object Creating the polynomial function Writing the polynomial vector Polynomial made easy Superquadric Ellipsoid Object
1.3.4 Gamma Handling Setting Up Your Display Setting Up POV-Ray Gamma in Output Images Setting Up Your Scene Gamma in Literal Colors Gamma in Input Images Gamma in Legacy Scenes
1.3.5 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 Slope Map Tutorial Slopes, what are they? Syntax of a slope map Examples of slope maps Finishes Using Ambient Using Emission Using Surface Highlights Using Reflection, Metallic 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
1.3.6 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
1.3.7 Simple Media Tutorial Types of media Some media concepts Simple media examples Emitting media Absorbing media Scattering media Multiple medias inside the same object Media and transformations A more advanced example of scattering media Media and photons
1.3.8 Radiosity Introduction Radiosity with conventional lighting Radiosity without conventional lighting Normals and Radiosity Performance considerations
1.3.9 Making Animations 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
1.3.10 While-loop tutorial What a while-loop is and what it is not How does a single while-loop work? How do I make a while-loop? What is a condition and how do I make one? What about loop types other than simple for-loops? What about nested loops? Mixed-type nested loops Other things to note
1.3.11 SDL tutorial: A raytracer Introduction The idea and the code Short introduction to raytracing Global settings Scene definition Initializing the raytracer Ray-sphere intersection Inner workings of a macro The ray-sphere intersection macro The Trace macro Calculating the closest intersection If the ray doesn't hit anything Initializing color calculations Going through the light sources Shadow test Diffuse lighting Specular lighting Reflection Calculation Calculating the image Creating the colored mesh The structure of the mesh Creating the mesh Creating the vertex points Creating the textures Creating the triangles The Camera-setup
1.4 Questions and Tips
1.5 Appendices
1.5.1 Contacting the Authors
1.5.2 POV-Ray License
1.5.3 Contact Information
1.5.4 Support Library Licenses OpenEXR
1.5.5 Citing POV-Ray in Academic Publications
1.5.6 Contributors to POV-Ray
1.5.7 Thanks
1.5.8 What to do if you don't have POV-Ray Which Version of POV-Ray should you use? Microsoft Windows Apple Macintosh Linux/Unix All Versions Where to Find POV-Ray Files World Wide Website
1.5.9 Suggested Reading

POV-Ray Reference

2.1 Introduction
2.2 Command-line Options
2.2.1 Animation Options External Animation Loop Internal Animation Loop Subsets of Animation Frames Cyclic Animation Field Renderings
2.2.2 General Output Options Height and Width of Output Max Image Buffer Memory Partial Output Options Interrupting Options Resuming Options
2.2.3 Display Output Options Display Hardware Settings Setting your Display Gamma Display Related Settings Mosaic Preview
2.2.4 File Output Options Output File Type Output File Name Output File Buffer Output File Dithering Output File Gamma CPU Utilization Histogram
2.2.5 Scene Parsing Options Constant Include File Name Library Paths Language Version
2.2.6 Shell Command Options String Substitution in Shell Commands Shell Command Sequencing Shell Command Return Actions
2.2.7 Text Output Options Text Streams Console Text Output Directing Text Streams to Files Warning Levels Help Screen Switches
2.2.8 Tracing Options Symmetric MultiProcessing Render Block Size Render Pattern Render Block Step Quality Settings Automatic Bounding Control Removing User Bounding BSP Bounding Stochastic Seed Anti-Aliasing Options Sampling Methods Synopsis Sampling Method 1 Sampling Method 2 Sampling Method 3 Common Properties Radiosity Options Radiosity High Reproducibility Radiosity Load and Save Radiosity Vain Pretrace
2.3 Scene Description Language
2.3.1 Language Basics Notation and Basic Assumptions Keywords Identifiers Comments Numeric Expressions Literals Identifiers Operators Functions Built-in Constants Built-in Variables Vector Expressions Literals Identifiers Operators Operator Promotion Functions Built-in Constants Dot Item Access for Vectors Color Expressions Color Vectors sRGB Colors Color Keywords Color Identifiers Color Operators Dot Item Access for Colors Common Color Pitfalls Function Sum and Product functions Functions and Macros Declaring User-Defined Float Functions Declaring User-Defined Vector Functions Declaring User-Defined Color Functionss Internal Pre-Defined Functions Strings String Literals String Identifiers String Relational Operators String Functions Built-in Variables Array Declaring Arrays Array Initializers Spline Splines and Macros Transformations Translate Scale Rotate Matrix
2.3.2 Language Directives Include Directive Declare and Local Directives Declaring identifiers declare vs. local Identifier Name Collisions Destroying Identifiers with undef Deprecation Support File I/O Directives The fopen Directive The fclose Directive The read Directive The write Directive Default Directive Version Directive Conditional Directives The if...else...end Directives The ifdef and ifndef Directives The for Directive 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 Optional Parameters Macro Caching
2.4 Scene File Basics
2.4.1 Global Settings ADC_Bailout Ambient_Light Assumed_Gamma HF_Gray_16 Irid_Wavelength Charset Max_Trace_Level Max_Intersections Mm_Per_Unit Number_Of_Waves Noise_generator Subsurface
2.4.2 Camera Placing the Camera Location and Look_At The Sky Vector Angles The Direction Vector Up and Right Vectors Aspect Ratio Handedness Transforming the Camera Types of Projection Perspective projection Orthographic projection Mesh projection Rays Per Pixel Distribution Type Max Distance Mesh Object About the Location Vector About the Direction Vector The Smooth Modifier Fisheye projection Ultra wide angle projection Omnimax projection Panoramic projection Cylindrical projection Spherical projection User defined projection Focal Blur Camera Ray Perturbation Camera Identifiers
2.4.3 Lighting Types Light Source Point Lights Spotlights Cylindrical Lights Parallel Lights Area Lights Shadowless Lights Looks Like Projected Through Light Fading Atmospheric Media Interaction Atmospheric Attenuation Light Group Radiosity Radiosity Basics How Radiosity Works Adjusting Radiosity adc_bailout always_sample brightness count error_bound gray_threshold low_error_factor max_sample maximum_reuse minimum_reuse nearest_count pretrace_start and pretrace_end recursion_limit Configuring Radiosity Importance Media and Radiosity No Radiosity Normal and Radiosity Save and Load Radiosity Data Subsurface and Radiosity Tips on Radiosity Photons Examples Using Photon Mapping in Your Scene Photon Global Settings Shooting Photons at an Object Photons and Light Sources Photons and Media Photons FAQ Photon Tips Advanced Techniques Autostop Adaptive Search Radius Photons and Dispersion Saving and Loading Photon Maps
2.5 The Object Zoo
2.5.1 Object Finite Solid Primitives Blob Box Cone Cylinder Height Field Isosurface Julia Fractal Lathe Lemon Ovus Parametric Prism Sphere Sphere Sweep Superquadric Ellipsoid Surface of Revolution Text Torus Finite Patch Primitives Bicubic Patch Disc Mesh Solid Mesh Mesh2 Smooth and Flat triangles in the same mesh Mesh Triangle Textures Polygon Triangle Smooth Triangle Infinite Solid Primitives Plane Poly Cubic Quartic Polynomial Quadric Constructive Solid Geometry Inside and Outside Union Split Union Intersection Difference Merge Object Modifiers Clipped By Object Modifier Bounded By Object Modifier Material Hollow Object Modifier Inverse Object Modifier No Shadow Object Modifier No Image Object Modifier No Reflection Object Modifier Double Illuminate Object Modifier No Radiosity Object Modifier Sturm Object Modifier
2.6 Embellishments
2.6.1 Texture Pigment Solid Color Pigments Color Map Pigment Map Color List Pigments Quick Color Normal Normal Map Slope Map Normals, Accuracy Bump Map Specifying a Bump Map Bump_Size Use_Index and Use_Color Scaling normals Finish Ambient Emission Diffuse Reflection Items Diffuse Brilliance Crand Graininess Subsurface Light Transport Highlights Phong Highlights Specular Highlight Metallic Highlight Modifier Specular Reflection Conserve Energy for Reflection Iridescence Halo Patterned Textures Texture Maps Tiles Material Maps Specifying a Material Map Layered Textures UV Mapping Supported Objects UV Vectors Triangle Texture Interpolation Interior Texture Cutaway Textures
2.6.2 Pattern General Patterns Agate Pattern Boxed Pattern Bozo Pattern Brick Pattern Bumps Pattern Cubic Pattern Cylindrical Pattern Density File Pattern df3 file format Dents Pattern Facets Pattern Fractal Pattern Function Pattern What can be used Function Image Gradient Pattern Granite Pattern Leopard Pattern Marble Pattern Onion Pattern Pavement Pattern Pigment Pattern Planar Pattern Quilted Pattern Radial Pattern Ripples Pattern Spherical Pattern Spiral1 Pattern Spiral2 Pattern Spotted Pattern Tiling Pattern Waves Pattern Wood Pattern Wrinkles Pattern Discontinuous Patterns Cells Pattern Checker Pattern Crackle Pattern Hexagon Pattern Object Pattern Square Pattern Triangular Pattern Normal-Dependent Patterns Aoi Pattern Slope Pattern Special Patterns Average Pattern Image Pattern Potential Pattern User Defined Pattern Pattern Modifiers Transforming Patterns Frequency and Phase Waveforms Noise Generators Warp Black Hole Warp Repeat Warp Turbulence Warp Octaves Lambda Omega Mapping using warps Turbulence versus Turbulence Warp Turbulence Image Map Specifying an Image Map The Gamma Option The Filter and Transmit Bitmap Modifiers Using the Alpha Channel Bitmap Modifiers The once Option The map_type Option The interpolate Option
2.7 Special Effects
2.7.1 Atmospheric Effects Atmospheric Media Background Fog Sky Sphere Rainbow
2.7.2 Media Interior Why are Interior and Media Necessary? Empty and Solid Objects Scaling objects with an interior Refraction Dispersion Dispersion & Caustics Attenuation Simulated Caustics Object Media Media Types Absorption Emission Scattering Sampling Parameters & Methods Density General Density Modifiers Density with color_map Density Maps and Density Lists Multiple Density vs. Multiple Media
2.8 Scene File Extras
2.8.1 Include Files Main Files Predefined colors Color macros Vector constants Map type constantss Interpolation type constants Fog type constants Focal blur hexgrid constants IORs Dispersion amounts Scattering media type constants Common Parameters Cross Section Type Field Strength Field Limit SOR Switch SOR Offset SOR Angle Invert Isosurface Internal Functions Pre defined functions Pattern functions Glass colors (with transparency) Glass colors (without transparency, for fade_color) Glass finishes Glass interiors Glass interior macros Float functions and macros Vector functions and macros Vector Analysis Flat Distributions Other Distributions Continuous Symmetric Distributions Continuous Skewed Distributions Discrete Distributions The HF Macros Stones Skies Woods Glass Metals Special textures Texture and pattern macros Old Files Glass finishes Glass textures Other Files Font Files Color Map Files Image Files

POV-Ray for Windows

3.1 Introduction
3.1.1 What is POV-Ray for Windows?
3.1.2 ... And What Is It Not?
3.1.3 Who Can Use POV-Ray for Windows?
3.1.4 System Requirements
3.1.5 System Specific Features What's new in POV-Ray for Windows SYS File Type System Specific Charset
3.1.6 Spelling
3.1.7 Reporting Bugs
3.1.8 Trademarks
3.1.9 Real-Time Raytracing Clockless Animation Video Capture Options Video Source
3.2 Getting Started
3.2.1 The Demo
3.2.2 Starting a Render Job
3.2.3 Dragging and Dropping Files
3.2.4 File Associations
3.2.5 Tutorials
3.2.6 Understanding File Types POV Files INI Files INI File Sections
3.2.7 Using the Internal Editor The Editor Feature Set Turning the Internal Editor On or Off Preventing File Restore Switching between Editor windows Keyword Expansion and CodeList A Quick Example How Keyword Expansion Works CodeList Using CodeList Summary Configuring the Internal Editor Important Editor Notes Default Key Mappings Setting Key Mappings Reserved Keys Using the Mouse Hints for Match Brace The Language Setting The Font Setting
3.2.8 I/O Restrictions High-Level Configuration Overall Options No Restrictions Restrict Write but Allow Read Restrict Read/Write Restrictions Affect all Core File I/O Additional Options Permit Read/Write in Current Directory Disable Starting other Programs Low-Level Configuration Overall Concept Implicitly Permitted Locations Adding or Changing Allowed Directories For Those Who use an Image Output Directory
3.3 Command-Line Options
3.3.1 POV-Ray Documents Directory
3.3.2 Special Command-Line Options
3.3.3 The Benchmark Command-line Option
3.3.4 Non-Standard Installations Background The /INSTALL and /QINSTALL switches Publishing via Group Policy System Admins / Lab Techs
3.3.5 Adding New Resolutions
3.4 Windows
3.4.1 The Main Window
3.4.2 The Toolbar Preset Rendering Options Toolbar Command Line
3.4.3 The Status Bar
3.4.4 The Tab Control
3.4.5 The Message Window
3.4.6 The Editor Window
3.4.7 The Render Window
3.5 Menus
3.5.1 File Menu New File Open File Close Close All Print Exit MRU List Older Files sub-menu
3.5.2 Edit Menu Copy Pane Clear Messages Undo Redo Cut Copy Paste Delete Select All Selection sub-menu Indent Indent To Previous Undent Uppercase Lowercase Convert Spaces To Tabs Convert Tabs To Spaces
3.5.3 Search Menu Find dialog Match Whole Word Only Match Case Wildcard Search Replace Find Next Match Brace
3.5.4 Text Menu Show White Space Set Repeat Count Tab Size Indent sub-menu Auto-Indent Style sub-menu None Language Scope Copy From Previous Line Bookmarks sub-menu Clear All First Last Next Previous Toggle
3.5.5 Editor Menu Auto-Load Error File Auto-Show Parse Messages Auto-Save Delay Create Backups Allow Undo After Manual Save Click Beyond EOL Constrain Caret To Text Overlay Keyword Expansion On Tab Key Show Message Window Editor Preferences dialog Record Macro/Play Macro Auto-Reload sub-menu Scroll Bars sub-menu Color Scheme sub-menu Editor Preferences Color/Font Item Color Background Font Language/Tabs Auto Indentation Style Tabs Language Keyboard Misc Smooth Scrolling Show Left Margin Line Tooltips on Scroll Allow Drag and Drop Allow Column Selection Confine Caret to Text Color Syntax Highlighting Show Horizontal/Vertical Scrollbar Allow Horizontal/Vertical Splitting Line Numbering Max Undoable Actions
3.5.6 Insert Menu Physical Layout Sorting the Insert Menu Adding a Separator Using the Insert Menu
3.5.7 Render Menu Edit Settings/Render dialog Select File and Render dialog Start Rendering (Go!)/Stop Rendering Run Demo Run Benchmark File Queue dialog Clear Queue Render Priority sub-menu Duty Cycle sub-menu Thread Count dialog Prevent Sleep Sound Settings dialog On Completion sub-menu Do Nothing Display Message Exit POV-Ray for Windows File List
3.5.8 Options Menu Keep Single Instance Show Toolbar Place in System Tray Script I/O Restrictions Drag'N'Drop Destination sub-menu Update Checks sub-menu Periodically Check for Updates Include System Information Check for Update Now Other Settings sub-menu Video Source sub-menu Use Editor Show Tips of the Day Show Tooltips Preserve Messages Save Settings on Exit Hide New User Help Show Next Tip Re-Render Insert Menu Bitmaps Message Window sub-menu Select Plain Background Text Font Text Color Background Color Tiling Options Render Window sub-menu Force 8 Bit Display Preserve Contents During Animation Re-Display Autoclose Close Keep Above Main Get Focus on Creation Hide When Main Minimized Editor Window sub-menu
3.5.9 Tools Menu PVTOOLS.INI Syntax Reload Tool Menu Edit PVTOOLS.INI Example PVTOOLS.INI
3.5.10 Window Menu
3.5.11 Context Menus The Message Window context menu Minimize to System Tray Show Tip The Render Window context menu The Editor Window context menu Show or Hide Messages Context Help Open Filename Copy ... to Command-Line
3.6 Bug Reports
3.6.1 Bugs and GUI Extensions
3.6.2 Crash Upload Utility
3.6.3 Bug Reporting via Email
3.6.4 Bug Reporting via our Bug Tracking System
3.7 Speed Considerations
3.7.1 Render Priority
3.7.2 Render Window
3.7.3 Memory
3.7.4 Scene Features
3.7.5 Render Quality

POV-Ray for Mac OS

4.1 Introduction
4.1.1 What's new in POV-Ray for Mac OS
4.1.2 Requirements
4.1.3 Installation
4.1.4 Bug Reporting via our Bug Tracking System
4.2 Getting Started
4.3 Tips and Tricks
4.3.1 How to use TrueType fonts with the text object
4.3.2 Known Problems

POV-Ray for Unix

5.1 Introduction
5.1.1 What is POV-Ray?
5.1.2 What is POV-Ray for Unix?
5.1.3 ... And What Is It Not?
5.1.4 Who Can Use POV-Ray for Unix?
5.1.5 Spelling
5.1.6 Reporting Bugs
5.1.7 Trademarks
5.2 Features
5.2.1 New Features
5.2.2 Display Options
5.2.3 Benchmark Mode
5.2.4 Sample scene render scripts
5.2.5 KDE Integration
5.3 Getting Started
5.3.1 Available distributions
5.3.2 Configuration The I/O Restrictions configuration file The main POV-Ray INI file
5.3.3 Starting a Render Job X Window display SVGAlib display Output file formats
5.3.4 Interrupting POV-Ray
5.3.5 Tutorials
5.3.6 Rendering the Sample Scenes
5.3.7 POV-Ray for Unix Tips Automated execution Post-processing Images
5.4 I/O Restrictions
5.4.1 Configuration file format
5.4.2 File I/O Security
5.4.3 Shellout Security
5.4.4 Permitted Paths Examples for path settings
5.4.5 Example configuration file
5.5 Understanding File Types
5.5.1 POV Files
5.5.2 INI Files INI File Sections
5.6 Understanding POV-Ray Options
5.6.1 Special Command-Line Options
5.6.2 Benchmark Rendering Mode
5.7 Bug Reports
5.7.1 Known Bugs
5.7.2 Bug Reporting via Email
5.7.3 Bug Reporting via our Bug Tracking System
5.8 Speed Considerations
5.8.1 Render Priority
5.8.2 Render Window
5.8.3 Memory
5.8.4 Scene Features
5.8.5 Render Quality

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