A POV-Ray scene is plain text. One main file (a .pov file) holds the scene, and it can read other text files with #include and binary files such as images, density grids and fonts. This page lists the file types, shows how a scene file is laid out, and explains what the tokenizer accepts (characters, line ends, the UTF-8 signature) and how a file name is turned into a file on disk.
File types
The program groups files by type. For each type it knows up to four extensions (the upper-case form of the first one is tried too). Where a name is given without an extension, the program appends the extensions of the wanted type one after the other (see Finding files).
| Extension | Content | Used by the language? |
|---|---|---|
.pov | scene file (text) | The main file, set with +Iname or Input_File_Name. The language reads it from the first character to the end; it is also the only extension that makes a bare command-line argument a scene file. |
.inc | include file (text, same language as a scene) | Read by #include "name" at the point where the directive stands. Any name works: .mac and .mcr are also used for files of macros, and the Windows editor lists them with .inc; the program treats them like any other include file when the full name is written. |
.map | text file; in the standard library each one holds a single #declare M_Name = color_map { ... } | Read with #include (the file is ordinary scene text). See Include files. |
.ini | options file (Name=value lines) | No. The front end reads it before the scene is parsed. See INI options and switches. |
.png, .gif, .tga, .iff (.lbm), .jpg (.jpeg), .tif (.tiff), .bmp, .exr, .hdr, .ppm, .pgm | raster images | Read by image_map, bump_map, material_map, height_field, an image pigment, and the image_pattern and image_map function forms. The image type keyword (png, gif, tga, iff, jpeg, tiff, bmp, exr, hdr, ppm, pgm, sys) chooses the decoder; the file extension is not used to guess it. |
.pot | Fractint potential file: a GIF-like file with a 16-bit palette (up to 65536 values) | Read as the pot image type, mainly for height_field. |
.df3 | density file: three big-endian 16-bit sizes (x, y, z), then x*y*z unsigned values of 8, 16 or 32 bits (the width follows from the file size) | Read by density_file df3 "name" in a pattern or in media. |
.ttf | TrueType font | Read by text { ttf "name" ... }. The 3.8 distribution carries crystal.ttf, cyrvetic.ttf, timrom.ttf and povlogo.ttf in its include folder. |
ttffonts.cat | plain text note about the three sample fonts and their donors | No. It is not a catalogue that any program reads. |
.obj | Wavefront OBJ geometry | Read by the experimental obj object (it makes the render report an experimental feature). |
.rca | radiosity cache | Written and read through the options Radiosity_To_File, Radiosity_From_File and Radiosity_File_Name (INI options and switches). The save_file and load_file words of radiosity are ignored in a 3.7 or later scene. |
.txt, any name | text and data files for #fopen, #read and #write | Opened by name with #fopen Id "file" read|write|append. Data written by a scene goes through the same path. |
.log, .csv, .bak | render logs, CPU histogram, backup of a replaced file | Written by the program, not read by a scene. |
The image decoders, the maps and the data files are covered where they are used (Textures and pigments, Patterns and maps, Implicit objects). The Tooling page lists the formats the program writes.
Layout of a scene file
A scene is a sequence of items: directives, a camera, light sources, objects, atmospheric effects and the global settings. The grammar lets them appear in any order and none is required. A directive (a word that starts with #) may even stand between two tokens of another statement. In practice a scene follows this order:
| Part | Example | Notes |
|---|---|---|
| language version | #version 3.8; | First non-comment statement of the main file. It sets the defaults that depend on the version (see Versions 3.0 to 3.8). |
| includes | #include "colors.inc" | The names must be declared before they are used, so the includes come early. |
global_settings | global_settings { assumed_gamma 1.0 } | Settings for the whole scene (Global settings). In a 3.7 or later scene write assumed_gamma here, or the parser warns. |
| declarations | #declare Wall = texture { ... } | Names, macros and functions. They may also appear later, but only after the point where they are needed. |
camera | camera { location <0, 1, -4> look_at 0 } | The last camera parsed is the one used. See Cameras. |
light_source | light_source { <5, 8, -6> color rgb 1 } | See Lights. |
| objects | sphere { 0, 1 pigment { color rgb 1 } } | Each object statement at the top level becomes part of the scene. |
| atmosphere | fog, background, sky_sphere, rainbow | See Media and interior. |
#version 3.8;
#include "colors.inc"
global_settings { assumed_gamma 1.0 }
camera { location <0, 1, -4> look_at <0, 0.5, 0> }
light_source { <5, 8, -6> color White }
sphere { <0, 0.5, 0>, 0.5 pigment { color Red } }
plane { y, 0 pigment { checker color White color Blue } }What a scene needs
Nothing is mandatory to parse. A file that holds only #version 3.8; global_settings { assumed_gamma 1.0 } parses, and the parser warns “No objects in scene.” and renders an empty image. A scene without a camera uses the default one: location <0, 0, 0>, looking along +z, up <0, 1, 0>, a perspective view of 90 degrees. A scene without light sources gets no diffuse or specular light; only the ambient term (0 by default for #version 3.8, 0.1 for older versions) and the background remain. For a picture you want at least one object, one light source and usually a camera.
The #version rule
The first statement of the main file that is not a comment should be #version number;. What the parser does depends on what it finds:
| Situation | Result |
|---|---|
#version is the first statement | The version sets the defaults (Versions 3.0 to 3.8). |
| another statement comes first and the version is 3.8 or higher | Parse error: “As of POV-Ray v3.7, the '#version' directive must be the first non-comment statement in the scene file.” This test applies to the main file only; an include file may set a version later in its text. |
| another statement comes first and the version is lower than 3.8 | Parsing goes on and the parser warns at the end that the scene had declarations before the first #version. |
no #version at all | Warning at the end that a version should be given. The scene is read as version 3.62, unless the Version option (+MV) set another one. |
#version version; | Uses the version of the running program. The scene adapts to whatever program renders it. |
| a number higher than the program's version | Error “Your scene file requires POV-Ray version ... or later!”. |
#version 3.71; | Warning: the release that was developed as 3.7.1 is called 3.8, so use #version 3.8. |
#version unofficial 3.8; | The word unofficial is accepted after #version; an official build refuses such a scene. |
global_settings { assumed_gamma 1.0 }
#version 3.8;
sphere { 0, 1 pigment { color rgb 1 } }global_settings statement stands before #version, so the parser stops with the error above at line 2.Characters, encoding and line ends
| Topic | Behaviour |
|---|---|
| Characters outside strings and comments | Only printable ASCII (codes 0x20 to 0x7E) plus white space is accepted. Any other character there is an “invalid character” error. |
| White space | Space, tab, line feed, carriage return and the DOS end-of-file character (0x1A) separate tokens. |
| Strings and comments | May hold any character the encoding can decode. In a string, a line break is kept as one line feed. |
| Encoding, no signature | The tokenizer is in an automatic mode. At the first byte above 0x7F it tries to decode the bytes as UTF-8; if that works it stays in UTF-8, and if not it rewinds and reads the rest as Windows-1252. |
| UTF-8 signature | A file that begins with the byte order mark (the bytes EF BB BF) is read as UTF-8 from the start. The signature is taken as a token of its own at the very start of the main file and of every include file, so it does no harm in front of #version. |
| Line ends | A line feed (Unix), a carriage return (old Mac) or both together (Windows) end a line. The first style met in a file is the one that counts for line numbers in messages; the other character is then treated as white space. |
| Comments | // to the end of the line; /* ... */, which may be nested. |
charset in global_settings | Still read (ascii, utf8, sys) but the parser warns that it is no longer supported. For versions below 3.8 it decides how the text of a text object is mapped to the font; for 3.8 and later it is ignored. |
Write scenes in UTF-8 if text objects need characters beyond ASCII. The font side (the cmap and the character set used to pick glyphs) is part of the text object, described under Finite objects.
Finding files
Every file the scene names (include files, images, fonts, density files, #fopen files) is looked up the same way:
- The program builds a list of file names. If the name has an extension that belongs to the wanted type (for instance
.incfor an include), that exact name is tried first and then the extension variants; otherwise the variants are tried first (name plus.inc, name plus.INC) and the exact name last. So#include "colors"findscolors.inc. - Each name is tried relative to the current directory of the program (or as the full path, when it is absolute). The directory of the scene file is not added automatically: relative names are resolved from where
povraywas started. - If the name is not absolute and was not found, each library path is tried in the order given, joined with the name. Library paths come from
Library_Pathin the INI files and+Ldiron the command line (repeated paths are dropped), and, on Unix, from the environment variablePOVINC, which is added last. When no INI file at all is found,<POVLIBDIR>/includeof the installation is the one library path. - If nothing is found, the parser reports “Cannot find file 'name', even after trying to append file type extension.” (for an include file: “Cannot open include file”).
An absolute path that does not exist is not searched in the library paths. The input scene itself is found the same way, with the .pov type. File read and write rights can be limited with povray.conf (see Tooling).
Nesting
An #include opens the file as if its text stood at that place. Each include gets its own symbol table, so #local names are private to that file and #declare names stay available afterwards (Include files). The include stack and the brace and condition stacks are checked when a file ends: a file must not leave a { or #if open.
What a render does with the scene
The program works in two phases. First the parser reads the whole scene file and the files it includes, runs the directives, macros and loops, and builds the scene in memory: objects, textures, lights, the camera and the settings. Messages of this phase (warnings, errors, #debug and #warning text) are printed with the line and column. If parsing fails, nothing is rendered. Then the tracer computes the image: it shoots primary rays from the camera, finds the nearest intersection, adds lighting, reflection, refraction and radiosity, and writes the pixels to the display and the output file. Which options steer these steps is on INI options and switches. With Clock and the animation options the same scene is parsed again for every frame, with the built-in clock variable changed.
Not described
Known, not yet covered
- Reference: the exact list of image types the
syskeyword can read depends on the platform build (it is empty in the Unix build read here); the interplay ofInclude_Headerwith the#versionrule is marked as a known gap in the parser source itself (aTODO FIXMEinParse_Version).
Unknown
- Reference: whether a
.ttcor OpenType font works was not tested; only.ttffiles are named by the program as the font type.