An include file is a text file in the scene language that a scene reads with #include "name". The program ships a folder of them (the include folder of the installation) that holds colours, finishes and textures, shapes, macros for mathematics, strings, arrays, random numbers and meshes, and a few data files. This page explains how include files are written and read, then lists every file of the folder: the 40 .inc files with what each declares, and the 26 other files (colour maps, images, a density file, a potential file and fonts).
How include files work
| Topic | Rule |
|---|---|
| The directive | #include "file" reads the file at that point as if its text stood there. The name is a string. An extension of .inc may be left out (#include "colors" finds colors.inc); any other name must be written in full. The file may itself include other files. |
| Where files are found | First the current directory of the program, then each library path in order (Library_Path or +L). The standard folder is normally listed in povray.ini. The directory of the scene file is not searched. See File types and structure and INI options and switches. |
| The header | Each standard file starts with comment lines: its name, the version it was written for and a description. Then comes the guard. |
| Include guard | The files avoid doing their work twice with a marker name. The usual form is #ifndef(Colors_Inc_Temp) at the top and a matching #end at the bottom. Including a file a second time then does nothing. (debug.inc uses the marker DEBUG_MCR.) |
| Version handling | Inside the guard the file saves the scene's version in the marker (#declare Colors_Inc_Temp = version;), switches to the version it was written for (#version 3.5;) and restores the saved one at the end (#version Colors_Inc_Temp;). So an old include file reads the same way in a 3.8 scene, and the scene keeps its own version afterwards. The #version rule for a scene file does not apply to include files. |
| Include stack trace | Most files contain #ifdef(View_POV_Include_Stack) #debug "including colors.inc\n" #end. If a scene declares View_POV_Include_Stack (the macro Debug_Inc_Stack() of debug.inc does it), every include announces itself in the debug stream. |
#declare and #local | An include file has its own table of local names. A name made with #declare stays after the file ends and is seen by the whole scene; a name made with #local is private to the file (and to macros defined in it). Include files use #local for helper values and #declare for the names they publish. Names are case-sensitive, and a library name can be overridden by declaring it again later in the scene. |
| Macros | Most of the logic is in #macros, which are also defined at the point of inclusion. A macro keeps working after the include ends. A macro defines its own names with #local. |
| Names that cost time | Files such as textures.inc and stones.inc declare hundreds of textures, so reading them takes a moment. Include only what the scene needs. |
| Deprecated names | Some files declare a name with #declare deprecated once "text" Name = ...; using that name prints the text as a warning (once). glass_old.inc does this. |
stdinc.inc, rad_def.inc and the groups
stdinc.inc is a convenience: it includes the seven files used most, in this order: colors.inc, shapes.inc, transforms.inc, consts.inc, functions.inc, math.inc and rand.inc. It does not read the texture, finish, glass, metal or sky files. rad_def.inc declares a macro for radiosity presets (Global settings, radiosity and photons). stones.inc is only the pair stones1.inc and stones2.inc read together.
Some files read others, so a scene does not need to list them: glass.inc reads glass_old.inc and consts.inc; shapes.inc reads shapes_old.inc, consts.inc, transforms.inc, strings.inc and math.inc; shapes3.inc reads shapes.inc, transforms.inc, math.inc and strings.inc; logo.inc reads shapes.inc; math.inc reads functions.inc; transforms.inc reads math.inc; rand.inc reads consts.inc; metals.inc reads golds.inc; textures.inc reads finish.inc; woods.inc reads woodmaps.inc; stoneold.inc reads stones1.inc; colors_ral.inc reads colors.inc. textures.inc does not read the stone, wood or metal files.
#version 3.8;
#include "colors.inc"
#include "finish.inc"
#include "shapes.inc"
#include "woods.inc"
global_settings { assumed_gamma 1.0 }
camera { location <0, 2, -5> look_at <0, 0.3, 0> }
light_source { <5, 8, -6> color White }
plane { y, -0.01 pigment { checker color White color Gray50 } }
object {
Round_Box(<-1.2, 0, -0.8>, <1.2, 0.6, 0.8>, 0.1, false)
texture { T_Wood10 }
}
sphere { <0, 1.0, 0>, 0.4 pigment { color Gold } finish { Shiny } }colors.inc, the finish Shiny from finish.inc, the macro Round_Box from shapes.inc and the texture T_Wood10 from woods.inc.// inc_a.inc: a small include file with a guard
#ifndef (Inc_A_Temp)
#declare Inc_A_Temp = version;
#version 3.5;
#local Scale_Private = 2;
#declare Wall_Height = 3 * Scale_Private;
#macro Post(P) cylinder { P, P + y*Wall_Height, 0.1 } #end
#version Inc_A_Temp;
#endWall_Height and Post are visible in the scene that includes it; Scale_Private is not, and the scene's version is back after the file. Including it twice defines everything once. Checked by a scene that includes it twice and tests all three facts with #ifdef and #if (version != 3.8).The .inc files
Names are as the files declare them; a family such as T_Grnt0 to T_Grnt29 is written as a range. Colours are written in the gamma space of the scene; a scene needs assumed_gamma 1.0 for the physically correct look.
| File | Declares | Main names |
|---|---|---|
stdinc.inc | nothing of its own; reads other files | includes colors.inc, shapes.inc, transforms.inc, consts.inc, functions.inc, math.inc, rand.inc |
colors.inc | colours and colour conversion macros | Red, Green, Blue, Yellow, Cyan, Magenta, White, Black, Clear (rgbf 1); Gray05 to Gray95 in steps of 5 percent; Gray, DimGray, LightGray, VLightGray (each also with the spelling Grey); the X11 style names Aquamarine, Coral, Gold, Khaki, Orange, Pink, Plum, Salmon, SkyBlue, Tan, Turquoise, Violet, Wheat and others; metal and material colours Brass, Copper, Bronze, Silver, BrightGold, Quartz, Mica; wood and chocolate tones LightWood, MediumWood, DarkWood, SemiSweetChoc, BakersChoc; macros CHSL2RGB, CRGB2HSL, CHSV2RGB, CRGB2HSV, CXYZ2RGB, CRGB2XYZ, CLab2RGB, CRGB2Lab (and the _D65 forms), CH2RGB, CRGB2H |
colors_ral.inc | 213 colours of the German RAL Classic collection | RAL_1000 to RAL_9023 (four-digit RAL numbers); built with CLab2RGB_D65 from colors.inc, which it includes. Needs assumed_gamma 1.0. The values differ slightly from the official ones. |
consts.inc | constants and aliases | e; the vectors o, xy, yz, xz; Plane_Map, Sphere_Map, Cylinder_Map, Torus_Map; Bi, Norm; Uniform_Fog, Ground_Fog; Hex_Blur1 to Hex_Blur3 (7, 19, 37); refraction indices Water_Ior, Crown_Glass_Ior, Flint_Glass_Ior, Diamond_Ior, Air_Ior and about 30 more; dispersion values Water_Dispersion, Diamond_Dispersion and others; FoV_15 to FoV_165 (the length of the camera vector for a view angle); scattering types ISOTROPIC_SCATTERING, MIE_HAZY_SCATTERING, MIE_MURKY_SCATTERING, RAYLEIGH_SCATTERING, HENYEY_GREENSTEIN_SCATTERING |
ior.inc | refraction index and dispersion data (187 declarations of pairs) | names of the form iorDiamond and dispDiamond, declared as pairs with the syntax #declare (ior, disp) = ...; glasses (iorGlassBK7, iorGlassSF11, iorSodaLimeGlass, aliases iorCrownGlass, iorFlintGlass, iorWindowGlass, iorGlass), plastics (iorPMMA, iorPC, iorPlexiglas and trade names), and many gemstones and minerals; helper macros IorData_n_disp, IorData_n_disp_Range, IorData_G_D_B and variants (the macros are removed at the end of the file). Some old names are declared deprecated. |
finish.inc | eight finishes | Dull, Shiny, Phong_Dull, Phong_Shiny, Glossy, Phong_Glossy, Luminous (ambient 1 diffuse 0), Mirror (reflection 1, no diffuse) |
glass.inc | glass colours, finishes and interiors | about 108 colours Col_Glass_* and Col_* (Col_Glass_Ruby, Col_Glass_Bluish, Col_Red_01 to Col_Red_04, Col_Amethyst_01, Col_Emerald_01 and many gem colours); finishes F_Glass5 to F_Glass10; interiors I_Glass1 to I_Glass4, I_Glass_Fade_Sqr1, I_Glass_Fade_Exp1 to I_Glass_Fade_Exp3, I_Glass_Dispersion1, I_Glass_Dispersion2, I_Glass_Caustics1, I_Glass_Caustics2 (use with material and interior) |
glass_old.inc | the glass of version 3.1 (deprecated) | I_Glass, F_Glass1 to F_Glass4, and the textures T_Glass1 to T_Glass4, T_Old_Glass and others declared with deprecated once, so each use gives a warning |
golds.inc | gold pigments, finishes and textures | pigments P_Gold1 to P_Gold5; finishes F_MetalA to F_MetalE; textures T_Gold_1A to T_Gold_5E (five colours times five finishes); the short names T01 to T25; the helpers GoldBase and CVect1 to CVect5 |
metals.inc | brass, copper, chrome and silver | pigments P_Brass1 to P_Brass5, P_Copper1 to P_Copper5, P_Chrome1 to P_Chrome5, P_Silver1 to P_Silver5; finishes F_MetalA to F_MetalE; textures T_Brass_1A to T_Brass_5E, T_Copper_1A to T_Copper_5E, T_Chrome_1A to T_Chrome_5E, T_Silver_1A to T_Silver_5E |
textures.inc | the large general texture collection (stone, sky, wood, glass, metal, misc.) | stone: Jade, Red_Marble, White_Marble, Blood_Marble, Blue_Agate, Sapphire_Agate, Brown_Agate, Pink_Granite, PinkAlabaster (each with a _Map colour map where one exists); sky: Blue_Sky, Bright_Blue_Sky, Blue_Sky2, Blue_Sky3, Blood_Sky, Apocalypse, Clouds, FBM_Clouds, Shadow_Clouds; wood: Cherry_Wood, Pine_Wood, Dark_Wood, Tan_Wood, White_Wood, Tom_Wood, DMFWood1 to DMFWood6, DMFLightOak, DMFDarkOak, EMBWood1, Yellow_Pine, Rosewood, Sandalwood; glass: Glass, Glass2, Glass3, Green_Glass, Ruby_Glass, Yellow_Glass and so on with M_ material forms (M_Glass, M_Ruby_Glass); metal: Metal, Chrome_Texture, Brass_Texture, Gold_Texture, Bronze_Texture, Copper_Texture, Silver_Texture, Polished_Chrome, Brushed_Aluminum, Rusty_Iron; other: Candy_Cane, Peel, Water, Cork, Lightning1, Lightning2, Starfield, X_Gradient, Y_Gradient; macros Irregular_Bricks_Ptrn, Hex_Tiles_Ptrn, Tiles_Ptrn, Star_Ptrn |
stones1.inc | stone textures, first part | T_Grnt0 to T_Grnt29, T_Grnt0a to T_Grnt24a, T_Crack1 to T_Crack4, T_Stone1 to T_Stone24 |
stones2.inc | stone textures, second part | T_Stone25 to T_Stone44 |
stones.inc | both stone files | includes stones1.inc and stones2.inc and declares nothing else; slower to read |
stoneold.inc | stone pigments of version 3.1 (old) | the pigments Grnt0 to Grnt29, Grnt0a to Grnt2a, Crack1 to Crack4, Stone1 to Stone24 |
woods.inc | wood pigments and textures | pigments P_WoodGrain1A to P_WoodGrain19B (19 grains, two variants each) and textures T_Wood1 to T_Wood35; it uses the colour maps of woodmaps.inc |
woodmaps.inc | colour maps for woods | M_Wood1A, M_Wood1B to M_Wood19A, M_Wood19B |
skies.inc | skies and clouds | pigment layers P_Cloud1 to P_Cloud4 (they have clear regions: use with a background); sky spheres S_Cloud1 to S_Cloud5; textures T_Cloud1 to T_Cloud3 and objects O_Cloud1, O_Cloud2 (cloud layers on a plane) |
stars.inc | star fields | textures Starfield1 to Starfield6, denser one after the other |
shapes.inc | macros for working with objects, and shape macros | geometry: Isect, IsectN, Extents, Center_Object, Align_Object (with Align_Left, Align_Right, Align_Center); text: Bevelled_Text, Text_Space, Text_Width, Circle_Text; shapes: Wedge, Spheroid, Supertorus, Supercone, Connect_Spheres, Quad, Smooth_Quad; wire and rounded forms in pairs of union, merge and chosen form: Wire_Box, Round_Box, Round_Cylinder, Round_Cone, Round_Cone2, Round_Cone3 (each also as _Union and _Merge); height field helpers HF_Square, HF_Sphere, HF_Cylinder, HF_Torus |
shapes2.inc | polyhedra and flat shapes (declared objects) | Tetrahedron, Octahedron, Dodecahedron, Icosahedron, HalfCone_Y, Hexagon, Rhomboid, Pyramid, Pyramid2, Square_X, Square_Y, Square_Z |
shapes3.inc | macros for tubes, columns, pyramids and egg shapes | Segment_of_Object, Segment_of_CylinderRing, Segment_of_Torus, Round_N_Tube_Polygon, Pyramid_N, Pyramid_N_AB, Column_N, Column_N_AB, Egg_Shape, Egg, Facetted_Sphere, Facetted_Egg, Ring_Sphere, Round_Pyramid_N_in, Round_Pyramid_N_out, Rounded_Tube, Rounded_Tube_AB, Round_Cylinder_Tube, Round_Conic_Torus, Round_Conic_Prism, Half_Hollowed_Rounded_Cylinder1, Half_Hollowed_Rounded_Cylinder2 |
shapesq.inc | quartic and cubic surfaces (declared objects) | Bicorn, Crossed_Trough, Cubic_Cylinder, Cubic_Saddle_1, Devils_Curve, Folium, Glob_5, Twin_Glob, Helix, Helix_1, Hyperbolic_Torus_40_12, Lemniscate, Quartic_Loop_1, Monkey_Saddle, Parabolic_Torus_40_12, Piriform, Quartic_Paraboloid, Quartic_Cylinder, Steiner_Surface, Torus_40_12, Witch_Hat, Sinsurf |
shapes_old.inc | the shapes of version 3.1 (declared objects) | Ellipsoid, Sphere, Cylinder_X, Cylinder_Y, Cylinder_Z, QCone_X, Cone_X, Plane_YZ, Plane_XZ, Plane_XY, Paraboloid_X, Hyperboloid, UnitBox, Cube, Disk_X, Disk_Y, Disk_Z (and the Y and Z forms of the others) |
chars.inc | letters as objects, each 4 by 5 by 1 units with the bottom centre at the origin | char_A to char_Z, char_0 to char_9, char_Dash, char_Plus, char_ExclPt, char_AtSign, char_Num, char_Dol, char_Perc, char_Hat, char_Amps, char_Astr, char_LPar, char_RPar, char_LSqu, char_RSqu |
logo.inc | the POV-Ray logo | Povray_Logo, Povray_Logo_Prism, Povray_Logo_Bevel |
functions.inc | named isosurface and pattern functions | about 100 function identifiers: algebraic surfaces f_algbr_cyl1, f_bicorn, f_boy_surface, f_cushion, f_ellipsoid, f_heart, f_helix1, f_klein_bottle, f_paraboloid, f_sphere, f_torus, f_superellipsoid, f_rounded_box; noise: f_noise3d, f_snoise3d, f_noise_generator, f_hetero_mf, f_ridged_mf; the patterns as functions f_agate, f_bozo, f_bumps, f_checker, f_granite, f_marble, f_wood, f_wrinkles and others; waves f_sine_wave, f_scallop_wave; and the macro eval_pigment. See Functions and constants |
math.inc | mathematics macros and functions | statistics: Mean, Std_Dev, GetStats, Histogram; degree trigonometry sind, cosd, tand, asind, acosd, atand, atan2d; max3, min3, even, odd, sgn, clip, clamp, adj_range, adj_range2, f_sqr, Interpolate; vector macros VSqr, VPow, VEq, VZero, VDist, VAngle, VAngleD, VRotation, VPerp_To_Vector, VPerp_To_Plane, VProject_Plane, VProject_Axis, VMin, VMax, VWith_Len and 5D forms; gradient and field macros SetGradientAccuracy, fn_Gradient, vGradient, vCurl, Divergence, Gradient_Length |
rand.inc | random number helpers (every macro takes a seed stream) | SRand, RRand, VRand, VRand_In_Box, VRand_In_Sphere, VRand_On_Sphere, VRand_In_Obj, Prob; distributions Rand_Normal, Rand_Gauss, Rand_Cauchy, Rand_Student, Rand_Gamma, Rand_Beta, Rand_Chi_Square, Rand_F_Dist, Rand_Triangle, Rand_Erlang, Rand_Exp, Rand_Lognormal, Rand_Pareto, Rand_Weibull, Rand_Bernoulli, Rand_Binomial, Rand_Geo, Rand_Poisson, Rand_Spline |
arrays.inc | array macros | Rand_Array_Item, Resize_Array, Reverse_Array, Sort_Array, Sort_Partial_Array (with the hooks Sort_Compare and Sort_Swap_Data), ARRAYS_WriteDF3 (writes a one-, two- or three-dimensional array to a density file) |
strings.inc | macros that turn values into strings | Str, VStr, VStr2D, Vstr, Vstr2D, CRGBStr, CRGBFTStr, Triangle_Str, Smooth_Triangle_Str, Parse_String |
transforms.inc | transform macros | Shear_Trans, Matrix_Trans, Axial_Scale_Trans, Axis_Rotate_Trans, Rotate_Around_Trans, Reorient_Trans, Point_At_Trans, Center_Trans, Align_Trans, Spline_Trans, vtransform, vinv_transform |
meshmaker.inc | macros that build mesh2 objects | Parametric, Prism, Prism1, Lathe, Coons, TwoVarSurf, SweepSpline1, SweepSpline2, MSM, BuildSpline, FromU, ToU, FromV, ToV, FindPoint, CheckFileName. Each takes a file name; with a non-empty name the macro writes the mesh to that file and reads it back with an #include of the name. |
makegrass.inc | macros for grass (meshes) | MakeBlade (one blade), MakeGrassPatch (a patch of blades, optionally saved to a file), MakePrairie (patches side by side); example parameter values posBlade, lBlade, segBlade are declared at the top |
sunpos.inc | position of the sun | SunPos(Year, Month, Day, Hour, Minute, Lstm, LAT, LONG) returns the position of the sun as a vector, to be used as light_source { SunPos(...) rgb 1 }. North is +z. It also declares the vector SolarPosition and the angles Az (azimuth) and Al (altitude) |
rad_def.inc | radiosity presets | Radiosity_Default to Radiosity_IndoorHQ (0 to 10) and the macro Rad_Settings; see Global settings, radiosity and photons |
debug.inc | debugging macros | Debug_Inc_Stack, Set_Debug, Debug_Message, Debug, Warning, Error (each takes a condition and a message and calls #debug, #warning or #error); the flag DEBUG. Do not reuse these macro names in a scene that includes the file. |
screen.inc | objects and textures placed in front of the camera | Set_Camera_Location, Set_Camera_Look_At, Set_Camera_Aspect_Ratio, Set_Camera_Aspect, Set_Camera_Sky, Set_Camera_Zoom, Set_Camera_Angle, Set_Camera, Update_Camera, Reset_Camera, Screen_Object, Screen_Plane. It creates the camera itself when included, so use it only with the perspective camera and do not add another one. |
stdcam.inc | a sample scene fragment, not declarations | a camera (location <-2, 1.75, -5>, angle 70), a light_source and a plane with the pigment Plum. Including it adds these objects to the scene. It expects colors.inc to have been read. |
stage1.inc | a sample scene fragment, not declarations | reads colors.inc, textures.inc and shapes.inc, declares Camera1 and makes it the camera, adds a light source and a hollow checkered plane at z = 1.01. Including it adds these objects. |
The other files of the folder
These are read by name from a scene (images by their image type, maps with #include), not as include files, except where noted.
| File | Kind | Content and use |
|---|---|---|
ash.map | colour map (text) | declares M_Ash, a color_map of 255 entries |
benediti.map | colour map | M_Benediti |
bubinga.map | colour map | M_Bubinga |
cedar.map | colour map | M_Cedar |
marbteal.map | colour map | M_MarbTeal |
orngwood.map | colour map | M_Orangewood |
pinkmarb.map | colour map | M_PinkMarb |
rdgranit.map | colour map | M_RedGranite |
teak.map | colour map | M_Teak |
whiteash.map | colour map | M_WhiteAsh |
bumpmap_.png | image, 320 by 200, palette | a colour Mandelbrot picture, meant for a bump map |
fract003.png | image, 320 by 200, palette | a fractal landscape in blue, brown and white (for a height field) |
Mount1.png | image, 250 by 250, grey scale | a grey-scale image, usable as a height field |
Mount2.png | image, 250 by 250, grey scale | a second grey-scale image of the same size |
mtmandj.png | image, 320 by 200, palette | a Julia fractal in colour |
plasma2.png | image, 100 by 100, palette | a plasma fractal, for landscapes |
plasma3.png | image, 100 by 100, palette | a smoother version of plasma2.png |
povmap.png | image, 320 by 200, 4-bit palette | the text “Persistence of Vision” in a frame |
test.png | image, 320 by 200, 4-bit palette | a test picture of four coloured areas with the word “POV-Ray” |
mtmand.pot | Fractint potential file, 42207 bytes | a grey-scale Mandelbrot set, for height fields (pot image type) |
spiral.df3 | density file, 12506 bytes | a spiral galaxy shape, 50 by 50 by 5 voxels of 8 bits; use with density_file df3 "spiral.df3" |
crystal.ttf | TrueType font | a fixed-width programmer's font |
cyrvetic.ttf | TrueType font | a proportional sans-serif font |
timrom.ttf | TrueType font | a proportional serif font |
povlogo.ttf | TrueType font | a font that holds only the POV-Ray logo |
ttffonts.cat | text note | describes the sample fonts and their donors; no program reads it |
#version 3.8;
#include "teak.map"
#include "rand.inc"
global_settings { assumed_gamma 1.0 }
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
#declare Seed = seed(7);
#declare I = 0;
#while (I < 5)
sphere { VRand_In_Box(<-1,-1,-1>, <1,1,1>, Seed), 0.2
pigment { wood color_map { M_Teak } scale 0.05 }
}
#declare I = I + 1;
#end
box { <-3, -1.3, -3>, <3, -1.2, 3>
pigment { image_map { png "test.png" } rotate x*90 translate -y*1.2 scale 5 }
}M_Teak), a random macro from rand.inc and an image from the folder used as an image map.Not described
Known, not yet covered
- Reference: the folder of this distribution holds 40
.incfiles, not more; the parameter lists of the long macros (the texture helpers,MakeGrassPatch,Parametricand the others inmeshmaker.incandshapes3.inc) are not spelled out here, and neither are the values returned bySunPos. The manual's file list also names amaze.pngthat is not in the folder, and omitsMount1.pngandMount2.png, which are.