This document is a reference to the file format used inpbrt-v3, the version of the system correspondingto the third edition of Physically Based Rendering; it serves as acomprehensive reference. The pbrt User'sGuide documents how to use pbrt with morefocus on how to achieve certain tasks or how to address various issues inthe results it renders.
The scene description files used by pbrt areplain text files. The file format was designed so that it would be botheasy to parse and easy for applications to generate from their own internalrepresentations of scenes.
A pbrt scene file consists of a series ofstatements; different statements specify the geometry and lightsources in the scene and set overall rendering parameters (such as whichlight transport algorithm to use or the image resolution). Each statementin these files corresponds directly to a pbrt APIfunction from Appendix B in the Physically Based Rendering book.For example, when the WorldBegin statement appearsin the input, the pbrtWorldBegin() function iscalled. To best understand this document, you should already be familiarwith the concepts introduced in Appendix B, though we will try tore-introduce some key concepts from that appendix here.
We tried to minimize changes to the file format in order to make it aseasy as possible to use existing scene description fileswith pbrt-v3. A number of changes were necessaryfor new functionality or changes in the system's implementation. Thebiggest resulting change to input files is thatthe Renderer, SurfaceIntegrator,and VolumeIntegrator directives have all beenunified under Integrator; only a singleintegrator now needs to be specified.
Some functionality was removed:
- Accelerator "grid": use "bvh" or "kdtree"instead.
- Material "measured": the new "fourier"material should now be used for measured BRDFs. Note that it uses adifferent representation of BRDFs than "measured" did.
- Material "shinymetal": use the "uber"material in place of "shinymetal".
- VolumeRegion: use the new participatingmedia representation: NamedMedium and MediumInterface.
- SurfaceIntegrator: the "photonmap","irradiancecache", "igi", "dipolesubsurface", "ambientocclusion","useprobes", "diffuseprt" and "glossyprt" integrators have been removed.
- Use "sppm" for the "photonmap".
- The "path" integrator now handles subsurface scattering directly.
- The others aren't as good as path tracing anyway. :-)
- VolumeIntegrator"single"and emission: use the "volpath" path tracingintegrator.
- Sampler "bestcandidate": use any other sampler.
- Renderer: use Integrator, as described above.
- Texture "image" "float gamma": image maptextures now take a "bool" value to enable or disable conversion fromsRGB to linear texture values; it is true by default for 8-bit textureformats like TGA and false by default for floating-point formats likeOpenEXR.
The documentation on the pbrt-v2 fileformat is still available.
Here is a short example of a pbrt input file:Between the start of the file and the WorldBeginstatement, overall options for rendering the scene are specified, includingthe camera type and position, the sampler definition, and information aboutthe image to be generated. AfterWorldBegin, the lights, geometry, and scatteringvolumes (if any) in the scene are defined, up untilthe WorldEnd statement, which causes the image tobe rendered.
LookAt 3 4 1.5 # eye .5 .5 0 # look at point 0 0 1 # up vectorCamera "perspective" "float fov" 45Sampler "halton" "integer pixelsamples" 128Integrator "path"Film "image" "string filename" "simple.png" "integer xresolution" [400] "integer yresolution" [400]WorldBegin# uniform blue-ish illumination from all directionsLightSource "infinite" "rgb L" [.4 .45 .5]# approximate the sunLightSource "distant" "point from" [ -30 40 100 ] "blackbody L" [3000 1.5]AttributeBegin Material "glass" Shape "sphere" "float radius" 1AttributeEndAttributeBegin Texture "checks" "spectrum" "checkerboard" "float uscale" [8] "float vscale" [8] "rgb tex1" [.1 .1 .1] "rgb tex2" [.8 .8 .8] Material "matte" "texture Kd" "checks" Translate 0 0 -1 Shape "trianglemesh" "integer indices" [0 1 2 0 2 3] "point P" [ -20 -20 0 20 -20 0 20 20 0 -20 20 0 ] "float st" [ 0 0 1 0 1 1 0 1 ]AttributeEndWorldEnd
When rendered with pbrt, this image isgenerated:
A scene description file starts with a series of directives thatdescribe the camera, film, and sampling and light transport algorithms touse in rendering the scene. These are followed bythe WorldBegin directive;after WorldBegin, the world definition blockstarts, and it is no longer legal to specify different definitions of anyof the objects defined in the initial section of the file. However,lights, materials, textures, shapes, and volumetric scattering regions canbe defined inside the world block (and can only be defined inside the worldblock). The world block ends with the WorldEnddirective; when this is encountered, theIntegrator defined takes control and does therequired rendering computation.
The hash character # denotes that the rest ofthe line is a comment and should be ignored by the parser.
The followingsection, Scene-widerendering options, documents the directives that are valid outside ofthe world definition block. The subsequentsection, Describing the scene,documents the directives for defining the shapes, materials, lights, etc.,that define the scene.
Some of the statements in the input file, such as WorldBegin,AttributeEnd, and so on, have no additional arguments. Others, such asthose related to specifying transformations, such as Rotate andLookAt, take a predetermined number of argumentsof predetermined type. (For example, Translateis followed by three floating-point values that give the x, y, and zcomponents of the translation vector.) The remainder of the statements takea variable number of arguments and are of the form
identifier "type" parameter-list
For example, the Shape identifier describes a shape to be added to thescene, where the type of shape to create is given by a string(e.g. "sphere") and is followed a list of shape-specific parameters thatdefine the shape. For example,
Shape "sphere" "float radius" [5]
defines a sphere of radius 5. (See Shapes for documentation of theparameters taken by the various shapes implemented in pbrt.)
Here, the "type" string gives the name of the particular shape, etc.,implementation to use, and parameter-list gives the parameters to pass tothe implementation. With this design, the parser doesn't need to know anythingabout the semantics of the parameters; it just needs to know how to parseparameter lists and how to initialize a ParamSet from them (TheParamSet class is described starting on page 1105of the third edition of the Physically Based Rendering book).
Almost all directives in a pbrt input file have a direct correspondencewith a function in the pbrt API, defined in the files core/api.hand core/api.cpp. The only input file directive that does not directlycorrespond to a function in the API is the Include statement, whichallows other input files to be parsed. Include behaves similarly tothe #include directive in C++, except that only the directory that thecurrently-being-processed input file is searched for matching filenames.Of course, a complete pathname or a path relative to the current directorycan be specified if appropriate.
Include "geometry/car.pbrt"
Parameter Lists
Variable-length lists of named parameters and their values are the keymeeting ground between the parsing system and the objects that are createdto represent the scene. Each of these lists holds an arbitrary number ofname/value pairs, with the name in quotation marks and the value or valuesin square brackets:
"type name" [ value or values ]
For example,
"float fov" [30]
specifies a parameter "fov" that is a single floating-pointvalue, with value 30. Or,
"float cropwindow" [0 .5 0 .25]
specifies that "cropwindow" is a floating-point array with the given fourvalues. Notice that values are enclosed in square brackets. Single values(such as the "30" in the "fov" example above) may be provided with orwithout square brackets enclosing them, though arrays of values always mustbe enclosed in square brackets.
The type of each parameter must always be given along with its name;pbrt has no built-in knowledge of any parameter names. This simplifiesthe parsing system, although it does create a small burden for thecreator of the input file.
pbrt supports nine basic parameter types: integer, float,point2, vector2,point3, vector3,normal3, spectrum, bool,and string. Alternatively, point, vector,normal, can be used as synonyms for theirthree-dimensional equivalents.
The point2and vector2 types take two floating-point valuesto specify each value (and similarly for their 3Dequivalents). string parameters must be insidequotation marks, and bool parameters are set withthe strings"true" and "false", quotation marks included.
"string filename" "foo.exr""point origin" [ 0 1 2 ]"normal N" [ 0 1 0 0 0 1 ] # array of 2 normal values"bool renderquickly" "true"
pbrt provides a number of ways of specifying spectral values in scenedescription files. RGB values are commonly used, though see the discussionin Section 5.2.2on page 325 of the third edition of "Physically Based Rendering" fordiscussion of the shortcomings of this representation. RGB color valuescan be specified with the rgb type. (color is also supported as asynonym for this):
"rgb Kd" [ .2 .5 .3 ]
specifies the RGB color with red equal to 0.2 and so forth. TheFromRGB() method of the Spectrum implementation being used is usedto convert the given RGB colors to the current spectral representation.
Alternatively, XYZ colors can be used to specify a spectrum:
"xyz Kd" [ .4 .6 .7 ]
General sampled SPDs are specified with a series of (wavelength, value)pairs, where wavelengths are specified in nm. These SPDs are resampled tothe current spectral representation with its FromSampled() method. Forexample,
"spectrum Kd" [ 300 .3 400 .6 410 .65 415 .8 500 .2 600 .1 ]
specifies a piecewise-linear SPD with a value of 0.3 at 300nm, 0.6 and400nm, and so forth. Since complex sampled SPDs may have many values, theycan also be provided through a separate file:
"spectrum Kd" "filename"
Where the filename specifies the path to a plain text file with pairs offloating-point (wavelength, value) as above. The parser for these filesallows uses # to denote a comment that goes to the end of the currentline. See the directory scenes/spds in thepbrt scenes distribution forexamples.
Finally, SPDs of blackbody emitters can be specified with twofloating-point values, one giving the blackbody temperature in Kelvin, andthe second giving a scale factor. (Blackbody emitters are discussed inSection 12.1.1 of the book.)
"blackbody L" [ 6500 1 ] # daylight, approximately
Transformations
A series of directives modify the current transformation matrix (CTM).(See Section B.2.2 on page 1111 for more information about how the CTM ismaintained during scene description.) When the scene's camera is specifiedwith a Camera directive, the CTM defines theworld to camera transformation; when a light or shape is created, the CTMspecifies the transformation from object space to world space.
When parsing begins, the CTM is the identity transformation; furthermore,it is is reset to the identity when the WorldBegin directive isencountered. The following directives change the CTM; they are shown withthe corresponding pbrt API call:
Input File Syntax | API Call |
---|---|
Identity | pbrtIdentity() |
Translate x y z | pbrtTranslate() |
Scale x y z | pbrtScale() |
Rotate angle x y z | pbrtRotate() |
LookAt eye_x eye_y eye_z look_x look_y look_z up_x up_y up_z | pbrtLookAt() |
CoordinateSystem "name" | pbrtCoordinateSystem() |
CoordSysTransform "name" | pbrtCoordSysTransform() |
Transform m00 ... m33 | pbrtTransform() |
ConcatTransform m00 .. m33 | pbrtConcatTransform() |
For example, Translate takes three floating-point values, x, y, andz, and the corresponding values are passed to the pbrtTranslate() APIcall, which in turn modifies the CTM by setting it to the product of theCTM with the matrix representing the given translation.
pbrt supports animated transformations by allowing two transformationmatrices to be specified at different times. The TransformTimesdirective, which must be outside of the world definition block, defines thesetwo times with floating-point values:
TransformTimes start end
Then, the ActiveTransform directive indicates whether subsequentdirectives that modify the CTM should apply to the transformation at thestarting time, the transformation at the ending time, or both. The defaultis that both matrices should be updated:
Translate 1 0 0 # applies to both, by defaultActiveTransform StartTimeRotate 90 1 0 0ActiveTransform EndTimeRotate 120 0 1 0ActiveTransform All
This section describes rendering options that must be specified before theWorldBegin statement.
Cameras
The Camera directive specifies the camera usedfor viewing the scene.
The default camera is a PerspectiveCamera witha 90 degree field of view:
Camera "perspective" "float fov" [90]
When the Camera directive is encountered in an input file, the currenttransformation matrix is used to initialize the world-to-cameratransformation.
pbrt provides four camera implementations:
Name | Implementation Class |
---|---|
"environment" | EnvironmentCamera |
"orthographic" | OrthographicCamera |
"perspective" | PerspectiveCamera |
"realistic" | RealisticCamera |
Two parameters that set the camera's shutter open times are common toall cameras in pbrt.
Type | Name | Default Value | Description |
---|---|---|---|
float | shutteropen | 0 | The time at which the virtual camera shutter opens. |
float | shutterclose | 1 | The time at which the virtual camera shutter closes. |
The PerspectiveCamera,OrthographicCamera,and EnvironmentCamera share two additionalparameters that describe the imaging area:
Type | Name | Default Value | Description |
---|---|---|---|
float | frameaspectratio | (see description) | The aspect ratio of the film. By default, this is computed fromthe x and y resolutions of the film, but it can be overridden if desired. |
float | screenwindow | (see description) | The bounds of the film plane in screen space. By default, thisis [-1,1] along the shorter image axis and is set proportionally along thelonger axis. |
PerspectiveCameraand OrthographicCamera support images rendered withdepth of field. They both use the following two parameters to setparameters related to lens focus.
Type | Name | Default Value | Description |
---|---|---|---|
float | lensradius | 0 | The radius of the lens. Used to render scenes with depth of fieldand focus effects. The default value yields a pinhole camera. |
float | focaldistance | 10^30 | The focal distance of the lens. If "lensradius" is zero, this hasno effect. Otherwise, it specifies the distance from the camera originto the focal plane. |
The perspective camera has two (semi-redundant) parameters forsetting the camera's field of view.
Type | Name | Default Value | Description |
---|---|---|---|
float | fov | 90 | Specifies the field of view for the perspective camera. This isthe spread angle of the viewing frustum along the narrower of theimage's width and height. |
float | halffov | n/a | For convenience to some programs that export from modeling systems, thecamera's field of view can also be specified via the half-angle betweenthe view direction and the edge of the viewing frustum. If this parameterisn't provided, then fov is used to set the field of view instead. |
The RealisticCamera simulates imaging from light rays passing throughcomplex lens systems. It takes a number of additional parameters.
Type | Name | Default Value | Description |
---|---|---|---|
string | lensfile | "" | Specifies the name of a lens description file that gives the collectionof lens elements in the lens system. A number of such lenses areavailable in the lenses directory in thepbrt-v3 scenes distribution. |
float | aperturediameter | 1.0 | Diameter of the lens system's aperture, specified in mm. The smallerthe aperture, the less light reaches the film plane, but the greater therange of distances that are in focus. |
float | focusdistance | 10.0 | Distance in meters at which the lens system is focused. |
bool | simpleweighting | true | Indicates whether incident radiance at the film plane should just beweighted by the cosine-to-the-4th term, or whether it should alsoinclude the additional weighting terms that account for the shutter opentime and the projected area of the exit pupil are included so that theimage records incident energy on the film plane. |
Samplers
The Sampler generates samples for the image,time, lens, and Monte Carlo integration. A number of implementations areprovided; the default "halton"—is an instance ofthe HaltonSampler that takes 16 samples perpixel.
Name | Implementation Class |
---|---|
"02sequence" (or, for backwards compatibility, "lowdiscrepancy") | ZeroTwoSequenceSampler |
"halton" | HaltonSampler |
"maxmindist" | MaxMinDistSampler |
"random" | RandomSampler |
"sobol" | SobolSampler |
"stratified" | StratifiedSampler |
The HaltonSamplerand SobolSampler are generally the mosteffective samplers for Monte Carlointegration. The RandomSampler generatesparticularly ineffective sampling patterns and is really only useful forcomparison against more sophisticated approaches and shouldn't otherwisebe used.
The ZeroTwoSequenceSampler, HaltonSampler, MaxMinDistSampler, RandomSampler,and SobolSampler all take a single parameter, "pixelsamples",which sets the number of samples to take in each pixel area. (ForZeroTwoSequenceSampler, MaxMinDistSampler,and SobolSampler, this value must be a power oftwo. If a non-power-of-two value is provided, it is rounded up to thenext power of two.)
Type | Name | Default Value | Description |
---|---|---|---|
integer | pixelsamples | 16 | The number of samples to take, per pixel. Note that thenumber of samples is taken per pixel on average; depending onthe actual sampling algorithm being used, individualpixel areas may have slightly more or slightly fewer. |
The StratifiedSampler has three parametersthat control its behavior.
Type | Name | Default Value | Description |
---|---|---|---|
bool | jitter | "true" | Whether or not the generated samples should be jittered inside each stratum;this is generally only worth setting to "false" for comparisonsbetween jittered and uniform sampling—uniform sampling willalmost always give a worse result. |
integer | xsamples | 2 | The number of samples per pixel to take in the x direction. |
integer | ysamples | 2 | The number of samples per pixel to take in the y direction.In general, "xsamples" and "ysamples" should be set to thesame value for best results. |
Film
The Film directive specifies the characteristics of the image being generated by the renderer.
The only Film implementation currentlyavailable in pbrt isImageFilm which is specified as "image" in input files. For example:
Film "image" "string filename" ["out.exr"] "float cropwindow" [ .2 .5 .3 .8 ]
The "image" film takes a handful of parameters:
Type | Name | Default Value | Description |
---|---|---|---|
integer | xresolution | 640 | The number of pixels in the x direction. |
integer | yresolution | 480 | The number of pixels in the y direction. |
float[4] | cropwindow | [ 0 1 0 1 ] | The subregion of the image to render. The four values specifiedshould be fractions in the range [0,1], and they represent x_min,x_max, y_min, and y_max, respectively.These values are in normalized device coordinates, with (0,0) in theupper-left corner of the image. |
float | scale | 1 | Scale factor to apply to film pixel values before saving the image. |
float | maxsampleluminance | infinite | Image sample values with luminance greater than this value are clampedto have this luminance. (This is a hack, but can be useful foreliminating large variance spikes in scenes with difficult light transport.) |
float | diagonal | 35 | Diagonal length of the film, in mm. (This value is only used when theRealisticCamera is used.) |
string | filename | "pbrt.exr" | The output filename. |
The ImageFilm uses the suffix of the givenoutput filename to determine the image file format to use.pbrt supportsPFM andEXR for storing images with pixel valuesstored directly as floating-point values;TGA andPNG can also be used, thoughthese only provide 8 bits per color channel of precision.
Filters
The implementation of ImageFilm uses an instance of the abstractFilter class to filter sample values to computefinal pixel values. The filter is specified withthe PixelFilter directive.pbrt provides a number of filter implementations,listed below. The default is "box".
Name | Implementation Class |
---|---|
"box" | BoxFilter |
"gaussian" | GaussianFilter |
"mitchell" | MitchellFilter |
"sinc" | LanczosSincFilter |
"triangle" | TriangleFilter |
All filter implementations take two parameters that set the filter width in each direction. Typically,these two parameters will have the same value.
Type | Name | Default Value | Description |
---|---|---|---|
float | xwidth | 2 (0.5 for box, 4 for sinc) | The width of the filter in the x direction. |
float | ywidth | 2 (0.5 for box, 4 for sinc) | The width of the filter in the y direction. |
The "gaussian" filter takes an additional parameter that adjusts the rateof Gaussian falloff; see page 478 for more information.
Type | Name | Default Value | Description |
---|---|---|---|
float | alpha | 2 | alpha controls the falloff rate of the Gaussian filter. Smallervalues give a blurrier image. |
Two parameters set the shape of the "mitchell" filter; see the equation on the top of page 481.
Type | Name | Default Value | Description |
---|---|---|---|
float | B | 1/3 | |
float | C | 1/3 | These parameters control the shape of the Mitchell filter. The bestresults are generally obtained when B+2C=1. |
Finally the sinc filter takes a value tau that sets the number of cycles of the sinc function.
Type | Name | Default Value | Description |
---|---|---|---|
float | tau | 3 | tau controls how many cycles the sinc function passes through beforeit is clamped to zero by the windowing function. |
Integrators
The integrator implements the light transport algorithm thatcomputes radiance arriving at the film plane from surfaces andparticipating media in the scene. The default integrator is thePathIntegrator:
Integrator "path" "integer maxdepth" [5]
The PathIntegrator takes a handful ofparameters:
Type | Name | Default Value | Description |
---|---|---|---|
integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. |
integer[4] | pixelbounds | (Entire image) | Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.) |
float | rrthreshold | 1 | Determines when Russian roulette is applied to paths: when the maximumspectral component of the path contribution falls beneath this value,Russian roulette starts to be used. |
string | lightsamplestrategy | "spatial" | Technique used for sampling light sources. Options include "uniform",which samples all light sources uniformly, "power", which samples lightsources according to their emitted power, and "spatial", which computeslight contributions in regions of the scene and samples from a relateddistribution. |
A number of other surface integrators are available in the system.
Name | Implementation Class |
---|---|
"bdpt" | BDPTIntegrator |
"directlighting" | DirectLightingIntegrator |
"mlt" | MLTIntegrator |
"path" | PathIntegrator |
"sppm" | SPPMIntegrator |
"volpath" | VolPathIntegrator |
"whitted" | WhittedIntegrator |
The DirectLightingIntegrator takes anadditional parameter that controls the light source samplingstrategy.
Type | Name | Default Value | Description |
---|---|---|---|
string | strategy | "all" | The strategy to use for sampling direct lighting. Valid options are"all", which samples all the lights uniformly and averages theircontributions, and "one", which chooses a single light uniformly at random. |
integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. |
integer[4] | pixelbounds | (Entire image) | Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.) |
These are the parameters that the BDPTIntegrator takes:
Type | Name | Default Value | Description |
---|---|---|---|
integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. |
integer[4] | pixelbounds | (Entire image) | Subset of image to sample during rendering; in order, values givenspecify the starting and ending x coordinates and then starting andending y coordinates. (This functionality is primarily useful fornarrowing down to a few pixels for debugging.) |
string | lightsamplestrategy | "power" | Technique used for sampling light sources. Options include "uniform",which samples all light sources uniformly, "power", which samples lightsources according to their emitted power, and "spatial", which computeslight contributions in regions of the scene and samples from a relateddistribution. |
bool | visualizestrategies | false | If true, an image is saved for each (s,t) bidirectional path generationstrategy used by the integrator. These images can be helpful forunderstanding which sampling strategies are effective for samplingvarious types of light transport paths. |
bool | visualizeweights | false | If true, an image is saved with the multiple importance samplingweights for each (s,t) bidirectional path generation strategy. Theseimages can be helpful for understanding which sampling strategies areeffective for sampling various types of light transport paths. |
The MLTIntegrator, which implementsthe multiplexed Metropolis light transport algorithm described in Section16.5, takes a number of parameters.
Type | Name | Default Value | Description |
---|---|---|---|
integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. |
integer | bootstrapsamples | 100000 | Number of samples to take during the "bootstrap" phase; some of thesesamples are used for initial light-carrying paths for the Metropolis algorithm. |
integer | chains | 1000 | Number of unique Markov chains chains to follow with the Metropolisalgorithm. (Each chain starts with a new path from the bootstrap phase.) |
integer | mutationsperpixel | 100 | Number of path mutations to apply per pixel in the image. (Note thateach pixel will generally receive more or fewer path contributions,depending on how bright the pixel is. For the most part, this is themost effective parameter to increase to improve image quality. |
float | largestepprobability | 0.3 | Probability of discarding the current path and generating a new randompath (versus applying a small mutation to the current path). For sceneswith very difficult-to-sample light transport paths, reducing thisprobability may be worthwhile. |
float | sigma | 0.01 | Standard deviation of the perturbation applied to random samples in[0,1] used for small path mutations. |
Finally, the SPPMIntegrator integrator takes anumber of parameters to control the stochastic progressive photon mappingalgorithm.
Type | Name | Default Value | Description |
---|---|---|---|
integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. |
integer | iterations | 64 | Total number of iterations of photon shooting from lightsources. (After each iteration, photon statistics are updated.) |
integer | photonsperiteration | -1 | Number of photons to shoot from light sources in each iteration. Withthe default value, -1, the number is automatically set to be equal tothe number of pixels in the image. |
integer | imagewritefrequency | 2^31 | Frequency at which to write out the current image, in photon shootingiterations. (The default value means that the image will effectivelyonly be written once when rendering has finished.) |
float | radius | 1 | Initial photon search radius. (This value will be reduced as photonsare accumulated at each pixel.) |
Accelerators
The type of aggregate to use for efficiently finding ray-shapeintersections is defined with the Accelerator directive:
Accelerator "kdtree" "float emptybonus" [0.1]
The default accelerator, "bvh", is generally a good choice; it is rarelyworthwhile to specify a different accelerator or to need to change theaccelerator's parameters to improve performance.
Two accelerator implementations are available in pbrt:
Name | Implementation Class |
---|---|
"bvh" | BVHAccel |
"kdtree" | KdTreeAccel |
The "bvh" accelerator, the default, takes just two parameters. Thisaccelerator is efficiently constructed when the scene description isprocessed, while still providing highly efficient ray-shape intersectiontests.
Type | Name | Default Value | Description |
---|---|---|---|
integer | maxnodeprims | 4 | Maximum number of primitives to allow in a node in the tree. Once the primitives have been split to groups ofthis size or smaller, a leaf node is created. |
string | splitmethod | "sah" | Method to use to partition the primitives when building the tree. The default, "sah", denotes the surfacearea heuristic; the default should almost certainly be used. The other options—"middle", which splits eachnode at its midpoint along the split axis, "equal", which splits the current group of primitives intotwo equal-sized sets, and "hlbvh", which selects the HLBVHalgorithm, which parallelizes well—are slightly more efficient to evaluate at tree construction time, but lead tosubstantially lower-quality hierarchies. |
The "kdtree" accelerator takes a number of parameters that controlits construction. This accelerator takes substantially longer to createthan "bvh" at scene definition time, but it can be marginally faster atfinding ray-shape intersections. It tends to require less memory than"bvh".
See page 291 of the third edition of the book for the details of the costfunction used for building kd-trees (and thus the use of some of the thevarious parameters below.)
Type | Name | Default Value | Description |
---|---|---|---|
integer | intersectcost | 80 | The value of the cost function that estimates the expected cost of performing a ray-objectintersection, for use in building the kd-tree. |
integer | traversalcost | 1 | Estimated cost for traversing a ray through a kd-tree node. |
float | emptybonus | 0.2 | "Bonus" factor for kd-tree nodes that represent empty space. |
integer | maxprims | 1 | Maximum number of primitives to store in kd-tree node. (Not a hard limit; more may be stored if the kd-treecan't find splitting planes that reduce the number of primitives when refining a node.) |
integer | maxdepth | -1 | Maximum depth of the kd-tree. If negative, the kd-tree chooses a maximum depth based on the number ofprimitives to be stored in it. |
The MakeNamedMediumand MediumInterface directives are allowed bothin the initial options before WorldBegin aswell as after WorldBegin. See thedocumentation of participating media in"Describing the scene" for more information. When media specifiedin the scene-wide options, the "outside" medium is used for the mediumthat camera rays start out in.
After the camera, film, and rendering options have been set, theWorldBegin directive marks the start of the scenedefinition (the "world block"). In the world block, the lights,materials, and geometric shapes that make up the scene are defined.After WorldBegin, nearly all of the directivesdescribed in the Scene-widerendering options section are illegal; an error message will be printedif one is encountered. Similarly, nearly all of the directives documentedin this section are illegal outside of the world block. (The twoexceptions are the MakeNamedMediumand MediumInterface directives, which are legalin both places.) The end of the world block is denoted bythe WorldEnd directive; when it is encountered,the chosen Integrator takes over and does therequested rendering computation.
Attributes
A number of directives modify the current graphics state—examples includethe transformation directives (Transformations), and thedirective that sets the current material. The current graphics state(including the current transformation matrix) can be saved and restoredusing the AttributeBegin and AttributeEnd directives:
Material "matte"AttributeBegin Material "plastic" Shape "sphere"AttributeEnd # back to the "matte" materialShape "cone"
The transformation matrix can be saved and restored independently of thegraphics state using TransformBegin and TransformEnd.
Scale 2 2 2TransformBegin Translate 1 0 1 Shape "sphere"TransformEnd # Translate no longer applies here
In addition to the current transformation matrix and material, thereverse-orientation setting, specified by the ReverseOrientationdirective, is part of the graphics state. This directive, when active,flips the surface normal of the shapes that follow it; it can be usefulwhen specifying area light sources, which only emit light from the sidetheir surface normal points from, and when specifying transparentmaterials, where the surface normal is used to determine whether rays areentering or exiting the refractive medium.
Shapes
Shapes are specified with the Shape directive; it takes the name of ashape implementation and a parameter list used to define the shape'sproperties:
Shape "name" parameter-list
For example,
Shape "sphere" "float radius" [0.25]
When a Shape directive is encountered, the current transformationmatrix is used to set the object to world transformation for the shape.
A number of shapes are provided by pbrt; this list shows the mappingfrom shape names to implementation class in the system.
Name | Implementation Class |
---|---|
"cone" | Cone |
"curve" | Curve |
"cylinder" | Cylinder |
"disk" | Disk |
"hyperboloid" | Hyperboloid |
"paraboloid" | Paraboloid |
"sphere" | Sphere |
"trianglemesh" | Triangle |
A few additional shapes are available for convenience; these immediatelyconvert themselves to instances of the Triangleshape when the scene description is loaded.
Name |
---|
"heightfield" |
"loopsubdiv" |
"nurbs" |
"plymesh" |
The extent of the "cone" shape is defined by three parameters; note thatthe cone is oriented along the z axis in object space; the currenttransformation matrix can be used to orient it differently in the scene'sworld space.
Type | Name | Default Value | Description |
---|---|---|---|
float | radius | 1 | The cone's radius. |
float | height | 1 | The height of the cone along the z axis. |
float | phimax | 360 | The maximum extent of the cone in phi (in spherical coordinates). |
The "curve" shape, described in Section 3.7 of the book, is useful formodeling thin objects like hair, fur, and grass. It has a few variants,including a ribbon that's always oriented toward the incident ray, a flatribbon with orientation given by a pair of surface normals, and an(apparent) thin cylinder, where shading normals give the illusion of acurved surface.
After the book's publication, support for degree 2 curves was added, aswas support for curves spcified in the b-spline basis.
Type | Name | Default Value | Description |
---|---|---|---|
point[4] | P | (none) | Control points for the cubic Bezier spline that goes along the centerof the curve shape. |
string | basis | "bezier" | Curve spline basis. "bspline" is the only other option currentlysupported. |
int | degree | 3 | Degree of the curve's spline. The only other valid option is 2. |
string | type | "flat" | Which curve variant is used. The other options are "ribbon" and"cylinder". (Figure 3.18 on page 170 shows the differences betweenthem.) |
normal[2] | N | (none) | For "ribbon" curves, these normals are respectively used at the startand end of the curve. Intermediate normals are interpolated usingspherical linear interpolation. |
float | width | 1 | Width of the curve. |
float | width0/width1 | 1 | Width of the curve at the start and end points. If specified, theseoverride the "width" parameter. |
integer | splitdepth | 3 | Number of times the curve is split in half into sub-curves at startuptime. Splitting curves increases memory use but can improve rayintersection performance, as the sub-curves generally have tighterbounding boxes than the entire curve extent. |
Similarly, "cylinder" is oriented along the z axis as well. It takesfour parameters.
Type | Name | Default Value | Description |
---|---|---|---|
float | radius | 1 | The cylinder's radius. |
float | zmin | -1 | The height of the cylinder's bottom along the z axis. |
float | zmax | 1 | The height of the cylinder's top along the z axis. |
float | phimax | 360 | The maximum extent of the cylinder in phi (in spherical coordinates). |
The "disk" is perpendicular to the z axis, with its center at x=0 andy=0.
Type | Name | Default Value | Description |
---|---|---|---|
float | height | 0 | The location of the disk along the z axis. |
float | radius | 1 | The outer radius of the disk. |
float | innerradius | 0 | The inner radius of the disk (if nonzero, the disk is an annulus). |
float | phimax | 360 | The maximum extent of the disk in phi (in spherical coordinates). |
The "heightfield" shape isn't described in the pbrt book text; it'sessentially a compact way to describe a regular triangulated mesh. Theuser provides resolutions in the u and v directions and then a seriesof height values. The height values give the z values for a series ofvertices over [0,1]^2 in (x,y).
Type | Name | Default Value | Description |
---|---|---|---|
int | nu, nv | none | Number of sample values in each direction. The total numberof triangles in the mesh is 2 * (nu-1) * (nv-1). |
float[nu*nv] | Pz | none | Array of height values to specify the heightfield. |
"hyperboloid" takes two points to define the line of revolution that sweeps out its surface.
Type | Name | Default Value | Description |
---|---|---|---|
point | p1 | 0 0 0 | The first end point of the hyperboloid's line of revolution. |
point | p2 | 1 1 1 | The second end point of the hyperboloid's line of revolution. |
float | phimax | 360 | The maximum extent of the hyperboloid in phi (in spherical coordinates). |
"loopsubdiv" corresponds to a subdivision surface evaluated with Loop's subdivision rules.
Type | Name | Default Value | Description |
---|---|---|---|
integer | levels | 3 | The number of levels of refinement to compute in the subdivision algorithm. |
integer[n] | indices | required—no default | Indices for the base mesh. Indexing is the same as for the triangle mesh primitive.(See "trianglemesh" below). |
point[n] | P | required—no default | Vertex positions for the base mesh. This is the same as for the triangle mesh primitive.(See "trianglemesh" below). |
"nurbs" can be used to define a NURBS surface. Theimplementation in pbrt does a fixed-rate tessellation, with tessellationrate provided directly by the user.
Type | Name | Default Value | Description |
---|---|---|---|
integer | nu, nv | none—must be specified | Number of control points for NURBS patch in the u and v parametric directions. |
integer | uorder, vorder | see description | Order of NURBS surface in u and v directions. (Order is equal to one plus the surface's degree.) |
float[nu+uorder] | uknots | none—must be specified | Knot vector for NURBS in the u direction. |
float[nv+vorder] | vknots | none—must be specified | Knot vector for NURBS in the v direction. |
float | u0, v0 | none—must be specified | Starting u and v parametric coordinates at which to evaluate NURBS. |
float | u1, v1 | none—must be specified | Ending u and v parametric coordinates at which to evaluate NURBS. |
point[nu*nv] | P | none | Either the P or Pw parameter must be specified to give the surface's controlpoints. P gives regular control points. |
float[4*nu*nv] | Pw | none | Specifies rational control points, with an additional per-vertex weight value. |
Here are the parameters for "paraboloid".
Type | Name | Default Value | Description |
---|---|---|---|
float | radius | 1 | The paraboloid's radius. |
float | zmin | 0 | The height of the lower clipping plane along the z axis. |
float | zmax | 1 | The height of the upper clipping plane along the z axis. |
float | phimax | 360 | The maximum extent of the paraboloid along phi (in spherical coordinates). |
And these are the "sphere" parameters.
Type | Name | Default Value | Description |
---|---|---|---|
float | radius | 1 | The sphere's radius. |
float | zmin | -radius | The height of the lower clipping plane along the z axis. |
float | zmax | radius | The height of the upper clipping plane along the z axis. |
float | phimax | 360 | The maximum extent of the sphere in phi (in spherical coordinates). |
An arbitrary triangle mesh is defined by the "trianglemesh" shape. Themesh's topology is defined by the indices parameter, which is an arrayof integer indices into the vertex arrays. Each successive triplet ofindices defines the offsets to the three vertices of one triangle; thus,the length of the indices array must be a multiple of three.
Here is an example of a small triangle mesh:
Shape "trianglemesh" "integer indices" [0 2 1 0 3 2 ] "point P" [550 0 0 0 0 0 0 0 560 550 0 560 ]
Here, we have an array of four vertices in the P parameter. Theindices array defines two triangles that use these vertices—the firstone has vertex positions (550,0,0), (0,0,560), and (0,0,0). Note that bothtriangles use vertices 0 and 2. Because the triangle mesh is specified ina way that makes this vertex reuse explicit, the in-memory representationof the triangle mesh can be more compact than if each triangle had toexplicitly and privately store all of its per-vertex data.
Type | Name | Default Value | Description |
---|---|---|---|
integer[n] | indices | required—no default | The array of integer offsets into the per-vertex data arrays(P, and any of N, S, or uv that are present.) |
point[n] | P | required—no default | The vertex positions of the triangle mesh. |
normal[n] | N | none—optional | Per-vertex normals. If present, shading normals will be computedfrom these values. |
vector[n] | S | none—optional | Per-vertex tangents. |
float[2*n] | uv | none—optional | Per-vertex texture coordinates. |
float texture | alpha | none | Optional "alpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,at any point on the triangle where the alpha texture evaluatesto have the value zero, the triangle is cut away and anyray intersection is ignored. |
float texture | shadowalpha | none | Optional "shadowalpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,intersections at any points on the triangle where the alpha texture evaluatesto zero are ignored. |
pbrt can also directly read triangle meshes specified inthe PLY meshfile format, via the "plymesh" shape. The following parameters aresupported:
Type | Name | Default Value | Description |
---|---|---|---|
string | filename | required—no default | File from which the PLY-format mesh is loaded. |
float texture | alpha | none | Optional "alpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,at any point on the triangle where the alpha texture evaluatesto have the value zero, the triangle is cut away and anyray intersection is ignored. |
float texture | shadowalpha | none | Optional "shadowalpha" texture. (See the Textures section formore information about textures in pbrt.) When provided,intersections at any points on the triangle where the alpha texture evaluatesto zero are ignored. |
Object Instancing
If a complex object is used repeatedly in a scene, object instancing may bedesirable; this lets the system store a single instance of the object inmemory and just record multiple transformations to place it in the scene.Object instances are created via named objects.
To create a named object, its definition should be placed within anObjectBegin/ObjectEnd pair:
ObjectBegin "name" Shape ... Shape ...ObjectEnd
When a named object is defined, the current transformation matrix definesthe transformation from object space to the instance's coordinate space.
After a named object has been defined, it can be instantiated with theObjectInstance directive. The current transformation matrix then definesthe instance space to world space transformation; thus, the finaltransformation for a shape in an object instance definition is thecomposition of the CTM when the instance was defined and the CTM when theinstance was instantiated.
Thus, two instances of an object named "foo" are instantiated in thefollowing:
ObjectInstance "foo"Translate 1 0 0ObjectInstance "foo"
Lights
Light sources cast illumination in the scene.pbrt provides two types of lights: lights that exist in the scenewithout any geometry associated with them, and lights that describeemission from one or more shapes in the scene (area lights).
The first type of light is defined with the LightSource directive.There are 6 light sources of this type that are currently available inpbrt.
Name | Implementation Class |
---|---|
"distant" | DistantLight |
"goniometric" | GonioPhotometricLight |
"infinite" | InfiniteAreaLight |
"point" | PointLight |
"projection" | ProjectionLight |
"spot" | SpotLight |
For example, the following defines a point light source with RGB intensityof (0.5, 0.5, 0.5):
LightSource "point" "rgb I" [ .5 .5 .5 ]
When a light source definition is encountered, the current transformationmatrix is used to define the light-to-world transformation. Many of thelight sources also take parameters to place it in the scene; using either atransformation matrix or an explicit position or direction to place alight can be useful.
All lights support a spectrum"scale" parameter that scales the amount of light that the lightemits.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | scale | rgb (1 1 1) | Scale factor that modulates the amount of light that the light sourceemits into the scene. |
Distant
The "distant" light source represents a directional light source "atinfinity"; in other words, it illuminates the scene with light arrivingfrom a single direction. It takes these parameters:
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | L | rgb (1 1 1) | The radiance emitted from the light source. |
point | from | (0,0,0) | "from" and "to" define the direction vector along which illuminationfrom the light arrives at the scene. The defaults give a light that shinesalong the z axis. |
point | to | (0,0,1) |
Goniometric
The "goniometric" light represents a point light source withdirectionally-varying emission, where the emission distribution isrepresented by a texture map. This representation can be useful formodeling many real-world light sources, where measurements of thisdistribution may be available.
Given a normalized outgoing direction w from the goniometriclight source to a point in the scene, the image coordinates in thegoniometric diagram file are found using a (theta, phi) parameterization inspherical coordinates. Here, the theta angle is measured with respect tothe y axis, and x and z define phi. (Elsewherein pbrt, the z axis is generally used tomeasure theta.) The light-to-world transformation matrix can be used toposition and orient the light.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | I | rgb (1 1 1) | A radiant intensity scale-factor; the radiant intensity in aparticular direction is computed as the product of this valueand the appropriate value from the goniometric diagram table. |
string | mapname | required—no default | The filename of the image file that stores a goniometricdiagram to use for the lighting distribution. |
Infinite
The "infinite" light represents an infinitely far away light source thatpotentially casts illumination from all directions. It is useful formodeling incident light in complex real environments ("HDR lighting"). Ittakes an environment map with a "latitude-longitude" parameterization,where given a direction vector w, the spherical (theta, phi) coordinatesare found, and then the u coordinate of the environment map is indexed bythe phi value and v is indexed by theta. (If needed, the environment mapcan be reoriented with the light to world transformation.)
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | L | rgb (1 1 1) | A radiance scale factor for the light; final emitted radiancevalues for a particular direction are computed as the productof this value and the radiance value found from the environment map. |
integer | samples | 1 | Suggested number of shadow samples to take when computing illumination from the light.Depending on the number of pixel samples being taken, this valuemay need to be increased to reduce noise in the illuminationcomputation for the light. (Note that this value is used only whenthe DirectLightingIntegrator is used.) |
string | mapname | none | The environment map to use for the infinite area light. If this is notprovided, the light will be a constant color. |
Point
"point" defines a simple point light that casts the same amount ofillumination in all directions. It takes two parameters:
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | I | rgb (1 1 1) | The light's emitted radiant intensity. |
point | from | 0 0 0 | The location of the light. |
Projection
The "projection" light acts like a slide projector; the given image is usedto define a 2D emission distribution that is projected with a center ofprojection at the light's position. Directions outside the frustum oflight projection receive no emitted illumination. It is positioned usingthe light-to-world transformation matrix.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | I | rgb (1 1 1) | Radiant intensity scale factor; the intensity in a given directionis the product of this value and the value from the image mapfor the corresponding direction. |
float | fov | 45 | The spread angle of the projected light, along the shorter image axis. |
string | mapname | required—no default | The image to project into the scene. |
Spotlight
A spotlight is defined by the "spot" light source. The spotlight isdefined by a lighting direction and then two angles that specify a cone ofdirections in which light is emitted.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | I | rgb (1 1 1) | Maximum radiant intensity of the light; this is the emitted radiant intensityin the center of the illumination cone. It falls off to zero outside of thecone. |
point | from, to | see description | Two points defining the lighting vector. The defaults are(0,0,0) and (0,0,1), respectively. This gives a light that ispointing down the z axis. |
float | coneangle | 30 | The angle that the spotlight's cone makes with its primary axis. For directionsup to this angle from the main axis, the full radiant intensity given by "I"is emitted. After this angle and up to "coneangle" + "conedeltaangle",illumination falls off until it is zero. |
float | conedeltaangle | 5 | The angle at which the spotlight intensity begins to fall off at the edges. |
Area lights have geometry associated with them; the shape and size ofthe emitting shapes have a substantial effect on the resulting emittedradiance distribution. After an AreaLightSourcedirective, all subsequent shapes emit light from their surfaces accordingto the distribution defined by the given area light implementation.Note that area lights can currently only be used with triangle, sphere,cylinder, and disk shapes; a runtime error is issued if an area light isbound to any other type of shape.
The current area light is saved and restored inside attribute blocks;typically area light definitions are insidean AttributeBegin/AttributeEndpair in order to control the shapes that they are applied to.
AttributeBegin AreaLightSource "diffuse" "rgb L" [ .5 .5 .5 ] Translate 0 10 0 Shape "sphere" "float radius" [.25]AttributeEnd# area light is out of scope, subsequent shapes aren't emitters
pbrt currently only includes a single area light implementation, "diffuse".
Name | Implementation Class |
---|---|
"diffuse" | DiffuseAreaLight |
The "diffuse" area light defines an emitter that emitsradiance uniformly over all directions in the hemisphere around the surfacenormal at each point on the surface. Thus, the orientation of the surfacenormal is meaningful; by default, an emitting sphere emits in thedirections outside the sphere and there's no illumination inside of it. Ifthis is not the desired behavior,the ReverseOrientation directive can be used toflip the orientation of the surface normal of subsequent shapes, or the"twosided" option, described in the list of options below, can beenabled.
AttributeBegin AreaLightSource "diffuse" ReverseOrientation # illuminate inside the sphere Shape "sphere"AttributeEnd
The "diffuse" area light takes these parameters.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | L | rgb (1 1 1) | The amount of emitted radiance at each point and emitted direction.. |
bool | twosided | false | Determines whether the light source emits light from just the side ofthe surface where the surface normal points or both sides. |
integer | samples | 1 | Suggested number of shadow samples to take when computing illuminationfrom the light. (As with the InfintieAreaLight,this value is used only whenthe DirectLightingIntegrator is used.) |
Materials
Materials specify the light scattering properties of surfaces in the scene.The Material directive specifies the current material, which thenapplies for all subsequent shape definitions (until the end of the currentattribute scope or until a new material is defined:
Material "matte" "rgb Kd" [ .7 .2 .2 ]
Parameters to materials are distinctive in that textures can be usedto specify spatially-varying values for the parameters. For example, theabove material definition defines diffuse surface with the same reddishcolor at all points. Alternatively, we might want to use an image map todefine the color as a function of (u,v) on the surface. This is done bydefining a texture with a user-defined name (below, "lines-tex"), and thenbinding that to the desired parameter of the material.
For example, thefollowing sets the "Kd" parameter of the "matte" material to be computedvia lookups to the "lines.exr" image map.
Texture "lines-tex" "spectrum" "imagemap" "string filename" "textures/lines.exr"Material "matte" "texture Kd" "lines-tex"
Note that for each parameter (for example, "Kd" in the above), a value forthe parameter can either be bound with a constant value, in which case thegiven type of the parameter should be "float", "rgb", "spectrum", etc., asappropriate, or a texture value, in which case the given type of theparameter should be "texture" and the parameter value bound is the name ofa texture. (The next section of this document, Textures, describes thetextures available in pbrt as well as their parameters.)
Parameters to materials can be overridden by the shapes that they areapplied to. For example, the sphere in the following would be green, not red.
Material "matte" "rgb Kd" [ 1 0 0 ]Shape "sphere" "float radius" [ .5 ] "rgb Kd" [ 0 1 0 ]
Finally, it is sometimes useful to name a material. A named material is amaterial and a set of parameter bindings (to constant values or totextures). It is defined with the MakeNamedMaterial directive. Anamed material can be set to be the current material with theNamedMaterial directive.
MakeNamedMaterial "myplastic" "string type" "plastic" "float roughness" [0.1]Material "matte" # current material is "matte"NamedMaterial "myplastic" # current material is "plastic" as above
This table lists the materials available in pbrt and the correspondingclass in the source code distribution that implements each of them.
Name | Implementation Class |
---|---|
disney | DisneyMaterial |
fourier | FourierMaterial |
glass | GlassMaterial |
hair | HairMaterial |
kdsubsurface | KdSubsurfaceMaterial |
matte | MatteMaterial |
metal | MetalMaterial |
mirror | MirrorMaterial |
mix | MixMaterial |
none | A special material that signifies that the surface it is associatedwith should be ignored for ray intersections. (This is useful forspecifying regions of space associated withparticipating media.) |
plastic | PlasticMaterial |
substrate | SubstrateMaterial |
subsurface | SubsurfaceMaterial |
translucent | TranslucentMaterial |
uber | UberMaterial |
All of the above materials take a texture that can be used to specify abump map.
Type | Name | Default Value | Description |
---|---|---|---|
float texture | bumpmap | None | The floating-point texture to be used as a bump map. |
Disney
The "disney" material was after the book's publication. Itimplements the "Disney BSDF with subsurface scattering", as described inExtendingthe Disney BRDF to a BSDF with Integrated Subsurface Scattering. (Itbuilds on the model describedin PhysicallyBased Shading at Disney. See those documents for more details about theparameters.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | color | 0.5 | Base color of the material. |
float texture | anisotropic | 0 | Controls degree of anisotropy in the specular highlight. Default,0, is none. Range: [0,1]. |
float texture | clearcoat | 0 | Contribution of the clearcoat, which gives isotropic specular highlight thattakes on the light's color. Range: [0,1]. |
float texture | clearcoatgloss | 1 | Glossiness of the clearcoat. Larger values give tighterhighglights. Range: [0,1]. |
float texture | eta | 1.5 | Object's index of refraction. |
float texture | metallic | 0 | Controls how "metal" the object appears. Higher values reducediffuse scattering and shift the highlight color towards the material'scolor. Range: [0,1]. |
float texture | roughness | 0.5 | Material's roughness. Affects specular reflection andtransmission. Range: [0,1]. |
spectrum texture | scatterdistance | 0 | Distance that light travels in the object before scattering. Ifgreater than zero, subsurface scattering is used in place ofdiffuse reflection. |
float texture | sheen | 0 | Contribution of the "sheen" term, which adds retro-reflection atobject edges. Mostly useful for cloth. Range: [0,1]. |
float texture | sheentint | 0.5 | Controls how much the sheen term's color is tinted by the basecolor. Range: [0,1]. |
float texture | spectrans | 0 | Controls contribution of glossy specular transmission. Range: [0,1]. |
float texture | speculartint | 0 | Controls how much the specular highlight's color is tinted by thebase color. Range: [0,1].. |
The Disney BSDF also has a mode for thin surfaces that aren't closedgeometric models (e.g. a sheet of paper). The "thin" parameter to thematerial can be used to enable it.
Type | Name | Default Value | Description |
---|---|---|---|
boolean | thin | false | Controls whether the thin is enabled surface model. |
spectrum texture | difftrans | 1 | Controls how much of the diffuse scattering is reflected versustransmitted. Zero causes only diffuse reflection and no diffusetransmission, 1 gives an even split between both, and 2 gives onlydiffuse transmission. Range: [0,2]. |
spectrum texture | flatness | 0 | Base color of the material. |
Fourier
The "fourier" material is used for the Fourier Basis BSDFsdescribed in Section 8.6 of Physically Based Rendering, startingon page 552. This representation is useful both for measured BSDF dataas well as for BSDFs computed through simulation of scattering inlayered surfaces. (A number of such BSDFs are available in thebsdfs directory in thepbrt scenesdistribution.)
Type | Name | Default Value | Description |
---|---|---|---|
string | bsdffile | none | File that stores the Fourier BSDF description. |
Glass
The "glass" material has parameters that specify the reflectivity andtransmissivity. These values are both modulated by the Fresnel equationsfor dielectric materials, which also ensure energy conservation (as long asneither "Kr" nor "Kt" is ever greater than one.)
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kr | 1 | The reflectivity of the surface. |
spectrum texture | Kt | 1 | The transmissivity of the surface. |
float texture | eta | 1.5 | The index of refraction of the inside of the object.(pbrt implicitly assumes that the exterior of objectsis a vacuum, with IOR of 1.) |
float texture | uroughness | 0 | Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled. |
float texture | vroughness | 0 | Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Hair
The "hair" material models reflection and transmission fromcylindrical fibers like hair and fur. It's generally only useful with the"curve" shape. Its implementation is described in the supplementaryImplementation of a Hair Scattering Model document.
The color of the hair material can be specified in one of a number ofdifferent ways.
Type | Name | Description |
---|---|---|
spectrum texture | sigma_a | Absorption coefficient of the medium inside the hair. This absorptioncoefficient is normalized such that the value provided should be withrespect to the diameter of the hair. |
spectrum texture | color | If specified, a value of the absorption coefficient is computed usingan approximation that leads to the hair having roughly this color, aftermultiple scattering in the hair during rendering. |
float texture | eumelanin | Concentration of the eumelanin pigment in the hair. Blonde hair hasconcentrations around 0.3, brown around 1.3, and black around 8. |
float texture | pheomelanin | Concentration of the pheomelanin pigment in the hair. Pheomelaninmakes red hair red. |
If "sigma_a" is specified, then all other parameters related to haircolor are ignored, if present. Otherwise, if "color" is specified, theeumelanin and pheomelanin parameters are ignored, if present. If no haircolor parameters are specified, a eumelanin concentration of 1.3 is used,giving brown hair.
A number of additional parameters are available to control the hair'sappearance.
Type | Name | Default Value | Description |
---|---|---|---|
float texture | eta | 1.55 | Index of refraction of the hair medium. |
float texture | beta_m | 0.3 | Longitudinal roughness of the hair. Should be between 0 and 1. Thisroughness controls the size and shape of the hair highlight. |
float texture | beta_n | 0.3 | Azimuthal roughness of the hair. Should be between 0 and 1. |
float texture | alpha | 2 | Angle of scales on the hair surface, in degrees. |
KdSubsurface
The "kdsubsurface" material provides a convenient way to specify thescattering materials of a material that exhibits subsurface scattering.(The parameters to the "subsurface" material, below, are often difficult toset to achieve a desired visual result.) Here, the user can specify adiffuse reflection color, "Kd", and the mean free path—the averagedistance that light travels in the medium before scattering. (The smallerthe mean free path, the thicker the medium is.) These two values are thenused to derive scattering coefficients for the medium.)
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.5 | Diffuse scattering coefficient used to derive scattering properties. |
float texture | mfp | 1 | The mean free path--the average distance light travels in the mediumbefore scattering. |
float texture | eta | 1.3 | The index of refraction inside the object. |
spectrum texture | Kr | 1 | Reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofreflection. |
spectrum texture | Kt | 1 | Transmission term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount oftransmission. |
float texture | uroughness | 0 | Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled. |
float texture | vroughness | 0 | Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Matte
The "matte" material defines an object with simple Lambertian scattering. It takes two parameters.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.5 | The diffuse reflectivity of the surface. |
float texture | sigma | 0 | The sigma parameter for the Oren-Nayar model, in degrees.If this is zero, the surface exhibits pure Lambertian reflection. |
Metal
The "metal" material describes scattering from metals, where the index ofrefraction (eta) and the absorption coefficient (k) describe metals'reflectance spectra. These and a roughness parameter, which adjusts themicrofacet distributions roughness, describe the overall material. See thescenes/spds/metals directory inthe pbrt distribution for spectra of the IOR andabsorption coefficients of a variety of metals.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | eta | (copper) | Index of refraction to use in computing the material's reflectance. |
spectrum texture | k | (copper) | Absorption coefficient to use in computing the material's reflectance. |
float texture | roughness | 0.01 | Roughness of the material's microfacet distribution. Smaller valuesbecome increasingly close to perfect specular reflection.This value should be between zero and one. |
float texture | uroughness | n/a | Microfacet roughness in the u direction. If unspecified, the"roughness" parameter is used. |
float texture | vroughness | n/a | Microfacet roughness in the v direction. If unspecified, the"roughness" parameter is used. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Mirror
The "mirror" material is a simple specular reflector. The amount ofreflection isn't modified by the Fresnel equations.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kr | 0.9 | The reflectivity of the mirror. This value can be used to makecolored or dim reflections. |
Mixture
The "mix" material interpolates between two previously-named materialsusing a texture. This allows spatially-varying variation between twomaterials.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | amount | 0.5 | Weighting factor for the blend between materials. A valueof one corresponds to just "namedmaterial1", a value of zerocorresponds to just "namedmaterial2", and values in betweeninterpolate linearly. |
string | namedmaterial1 | (none) | Name of first material to be interpolated between. |
string | namedmaterial2 | (none) | Name of second material to be interpolated between. |
Plastic
"plastic" defines a simple plastic material, described by diffuse andspecular reflection coefficients as well as a roughness value thatdescribes how much variation there is in the microfacet distribution thatmodels glossy specular reflection.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.25 | The diffuse reflectivity of the surface. |
spectrum texture | Ks | 0.25 | The specular reflectivity of the surface. |
float texture | roughness | 0.1 | The roughness of the surface, from 0 to 1. Larger valuesresult in larger, more blurry highlights. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Substrate
The "substrate" material mixes between diffuse and glossy reflection basedon the viewing angle—this models many realistic materials, which becomeincreasingly specular as the viewing angle approaches grazing. It alsosupports anisotropic microfacet models, with two roughness parameters.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.5 | The coefficient of diffuse reflection. |
spectrum texture | Ks | 0.5 | The coefficient of specular reflection. |
float texture | uroughness | 0.1 | The roughness of the surface in the u direction. |
float texture | vroughness | 0.1 | The roughness of the surface in the v direction. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Subsurface
The "subsurface" material is another material that describes subsurfacescattering. It allows directly setting the absorption coefficient andreduced scattering coefficient. (These values are generally difficult toset manually to achieve a desired look; the "kdsubsurface" material isusually better for that. However, if measured data is available, thismaterial is the appropriate one.) This material also supports setting thescattering properties using values that have been measured by variousresearchers.
Type | Name | Default Value | Description |
---|---|---|---|
string | name | none | Name of measured subsurface scattering coefficients. See thefile src/core/media.cppin the pbrt distribution for all of themeasurements that are available. |
spectrum texture | sigma_a | (.0011, .0024, .014) | Absorption coefficient of the volume, measured in mm^-1. |
spectrum texture | sigma_prime_s | (2.55, 3.12, 3.77) | Reduced scattering coefficient of the volume, measured in mm^-1. |
float | scale | 1 | Scale factor that is applied to sigma_a and sigma_prime_s.This is particularly useful when the scene is not measured inmm and the coefficients need to be scaled accordingly. For example,if the scene is modeled in meters, then a scale factor of 0.001would be appropriate. |
float texture | eta | 1.33 | Index of refraction of the scattering volume. |
spectrum texture | Kr | 1 | Specular reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofspecular reflection. |
spectrum texture | Kt | 1 | Specular reflection term; this coefficient is modulatedwith the dielectric Fresnel equation to give the amount ofspecular reflection. |
float texture | uroughness | 0 | Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled. |
float texture | vroughness | 0 | Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Translucent
The "translucent" material models transmission through thin objects (like leaves).
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.25 | The coefficient of diffuse reflection and transmission. |
spectrum texture | Ks | 0.25 | The coefficient of specular reflection and transmission. |
spectrum texture | reflect | 0.5 | Fraction of light reflected. |
spectrum texture | transmit | 0.5 | Fraction of light transmitted. |
float texture | roughness | 0.1 | The roughness of the surface. (This value should be between0 and 1). |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Uber
Finally, the "uber" material is a "kitchen sink" material that supportsdiffuse, glossy specular, and specular reflection.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum texture | Kd | 0.25 | The coefficient of diffuse reflection. |
spectrum texture | Ks | 0.25 | The coefficient of glossy reflection. |
spectrum texture | Kr | 0 | The coefficient of specular reflection. |
spectrum texture | Kt | 0 | The coefficient of specular transmission. |
float texture | roughness | 0.1 | The roughness of the surface. |
float texture | uroughness | 0 | Microfacet roughness in the u direction. If zero, perfect specularreflection is modeled. |
float texture | vroughness | 0 | Microfacet roughness in the v direction. If zero, perfect specularreflection is modeled. |
float texture | eta | 1.5 | Index of refraction of the surface. This value is used inboth the microfacet model for specular reflection as well as forcomputing a Fresnel reflection term for perfect specular reflection. |
spectrum texture | opacity | 1 | The opacity of the surface. Note that when less than one,the uber material transmits light without refracting it. |
bool | remaproughness | true | If true, roughness values are expected to be in the range [0,1], andare remapped to microfacet distribution function parameter values thatrange from near-perfect-specular at 0 to very rough at 1. Otherwise theroughness parameters are used directly for the alpha parameters of themicrofacet distribution function. |
Textures
The Texture statement creates a named texture of a particular type.Currently, the only types that are supported are spectrum (colorcan be used a synonym) and float.
Texture "name" "type" "class" [ parameter-list ]
For example,
Texture "mydiffuse" "spectrum" "imagemap" "string filename" "image.tga"Material "matte" "texture Kd" "mydiffuse"
pbrt provides the following texture implementations:
Name | Implementation Class |
---|---|
"bilerp" | BilerpTexture |
"checkerboard" | Checkerboard2DTexture |
"checkerboard" | Checkerboard3DTexture |
"constant" | ConstantTexture |
"dots" | DotsTexture |
"fbm" | FBmTexture |
"imagemap" | ImageTexture |
"marble" | MarbleTexture |
"mix" | MixTexture |
"scale" | ScaleTexture |
"uv" | UVTexture |
"windy" | WindyTexture |
"wrinkled" | WrinkledTexture |
In the below, note that a number of textures (e.g. "mix") themselves taketextures as parameters; thus, one can build up small "trees" of computationto compose a series of texture functions.
Textures can be separated into three categories: any-D, 2D, and 3D.Any-D texturesare ConstantTexture, ScaleTexture,and MixTexture. These kinds of textures do nothave a specific dimensionality and have no common arguments.
2D textures use the (u,v) parametric coordinates on a surfacefor evaluation. Theyare BilerpTexture, ImageTexture, UVTexture,CheckerboardTexture, and DotsTexture. 2D textures have thefollowing common parameters:
Type | Name | Default Value | Description |
---|---|---|---|
string | mapping | "uv" | A string specifying the kind of texture coordinate mapping to use.Legal values are: "uv", "spherical", "cylindrical", or "planar". |
float | uscale, vscale | 1 | Scaling factors to be applied to the u and v texture coordinates, respectively.These parameters are only meaningful if the texture coordinate mapping typehas been set to "uv". |
float | udelta, vdelta | 0 | An offset to be applied to the u and v texture coordinates, respectively.These parameters are only meaningful if the texture coordinate mapping type has beenset to "uv" or "planar". |
vector | v1, v2 | see description | v1 and v2 are two vectors that define a planar mapping. The defaults are(1,0,0) and (0,1,0), respectively. These parameters are only meaningful if thetexture coordinate mapping type has been set to "planar". |
3D textures use a texture space point location to evaluate themselves. Thecurrent transformation matrix at the time they are created gives thetransformation from object space. They are CheckerboardTexture,FBmTexture, WrinkledTexture,MarbleTexture, andWindyTexture. Notethat CheckerboardTexture is the only texture thatcan be either a 2D or 3D texture (see its plug-in specific parametersettings in the following). 3D textures have no common parameters.
Most of the provided textures can generate either Spectrum orfloat values, which is why many of the followingdescriptions have the spectrum/float type.
Constant
The "constant" texture is just a convenience that always returns a givenconstant value.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum/float texture | value | 1 | The constant value of this texture. |
Scale
"scale" takes two textures as parameters, evaluates each of them, andreturns their product. It is often convenient to scale a texture used as abump map by a constant float value to modulate the perceived height ofthe bumps, for example.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum/float texture | tex1, tex2 | 1 | These two textures will be multiplied together by the ScaleTexture. |
Mix
"mix" takes two textures and linearly interpolates between their valuesaccording to the "amount" parameter (which may itself be a texture).
Type | Name | Default Value | Description |
---|---|---|---|
spectrum/float texture | tex1 | 0 | One of the two textures to be mixed. |
spectrum/float texture | tex2 | 1 | The other texture to be mixed. These two textures must be of the same type. |
float texture | amount | 0.5 | The amount to use when linearly interpolating between the two mix textures. |
Bilinear Interpolation
"bilerp" bilinearly interpolates between the four textures using the(u,v) parametric coordinate. The v00 parameter represents thetexture to use at (0,0), and so forth.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum/float texture | v00, v01, v10, v11 | see description | The four values to be bilinearly interpolated between.They default to 0, 1, 0, and 1, respectively. |
Image Map
Image maps can be provided with the "imagemap" texture.
Type | Name | Default Value | Description |
---|---|---|---|
string | filename | required—no default | The filename of the image to load. Currently pbrt supportsTGA, PFM, and EXR format images. |
string | wrap | "repeat" | What to do with texture coordinates that fall outside the legal [0,1] range.Legal values are "repeat", which simply tiles the texture; "black", whichreturns black when outside the legal range; and "clamp", which always returns thenearest border texel. |
float | maxanisotropy | 8 | The maximum elliptical eccentricity for the EWA algorithm. |
bool | trilinear | false | If true, perform trilinear interpolation when looking up pixel values.Otherwise, pbrt uses the EWA algorithm for texture filtering. EWAgives much better results, but is slower. |
float | scale | 1 | Scale factor to apply to value looked up in texture. |
bool | gamma | (depends) | Indicates whether texel values should be converted from sRGB gammaspace to linear space. This parameter is "true" by default for texturesstored in 8-bit formats like TGA and PNG, and "false" for floating-pointformats like EXR and PFM. |
Checkerboard
The "checkerboard" texture is a simple texture that alternates between two other textures.
Type | Name | Default Value | Description |
---|---|---|---|
integer | dimension | 2 | Sets the dimension of the checkerboard texture. Legal values are 2 and 3. |
spectrum/float texture | tex1 | 1 | The texture to use for even checks. |
spectrum/float texture | tex2 | 0 | The texture to use for odd checks. |
string | aamode | "closedform" | Set the antialiasing mode for the checkerboard texture. Legal valuesare "closedform" or "none". This parameter is only legal for 2D checkerboards. |
Dots
The "dots" texture generates a random collection of polka dots.
Type | Name | Default Value | Description |
---|---|---|---|
spectrum/float texture | inside, outside | see description | The textures to use for coloring the dots and the background. The defaultsare 1 and 0, respectively. |
Fbm and Wrinkled
"fbm" and "wrinkled" are two textures based on the Perlin noise function.They are 3D textures, so the scale of the features of the texture can beadjusted by setting accordingly the CTM when the texture is defined.
Type | Name | Default Value | Description |
---|---|---|---|
integer | octaves | 8 | The maximum number of octaves of noise to use in spectral synthesis. |
float | roughness | 0.5 | The "bumpiness" of the resulting texture. |
Marble
Finally, "marble" is a simple approximation to a layered marble texture,based on using Perlin noise to create stochastic variation in the result.
Type | Name | Default Value | Description |
---|---|---|---|
integer | octaves | 8 | The maximum number of octaves of noise to use in spectral synthesis. |
float | roughness | 0.5 | The "bumpiness" of the resulting texture. |
float | scale | 1 | A scaling factor to apply to the noise function inputs. |
float | variation | 0.2 | A scaling factor to apply to the noise function output. |
Participating media can be associated with regions of space in thescene using the MakedNamedMediumand MediumInterface directives. First,MakedNamedMedium associates a user-specified namewith medium scattering characteristics.
MakeNamedMedium "mymedium" "string type" "homogeneous" "rgb sigma_s" [100 100 100]
There are two representations of participating media available in pbrt.One represents spatially-uniform media, and the other represents mediawith varying density specified by a 3D grid of floating-point values.
Name | Implementation Class |
---|---|
"homogeneous" | HomogeneousMedium |
"heterogeneous" | GridDensityMedium |
Both take a few common parameters. (And for the "homogeneous"medium, these are the only parameters available.)
Type | Name | Default Value | Description |
---|---|---|---|
spectrum | sigma_a | rgb (0.0011, 0.0024, 0.014) | The absorption cross section. |
spectrum | sigma_s | rgb (2.55, 3.21, 3.77) | The scattering cross section. |
string | preset | none | If specified, a named measured scattering medium; see thefile src/core/media.cppin the pbrt distribution for all of themeasurements that are available. |
float | g | 0 | The phase function asymmetry parameter. |
float | scale | 1 | Scale factor applied to the absorption and scattering crosssections. |
The "heterogeneous" allows specification of a sampled volumedensity on a regular grid. Final scattering properties at points insidethe volume are computed by trilinearly interpolating the adjacent samplevalues and then scaling the sigma_a and sigma_s parameter values by theresult.
Type | Name | Default Value | Description |
---|---|---|---|
point | p0, p1 | (0,0,0), (1,1,1) | The two corners of the bounding box that gives the maximum extent ofthe medium. (It may be smaller depending on the shape or shapes that themedium is enclosed in.) |
integer | nx,ny,nz | 1 | The number of voxels in the x, y, and z directions, respectively. |
float[nx*ny*nz] | density | 0 | The array of density values. |
Given named media, the MediumInterfacedirective can be used to specify the current "interior" and "exterior"media. A vacuum—no participating media—is represented byempty string "".
MakeNamedMedium "mymedium" "homogeneous" "rgb sigma_s" [100 100 100]MediumInterface "" "mymedium"
Before the world block, the interior medium is ignored, but the exteriormedium specifies the medium that camera rays start out in.
Inside the world block, the current medium interface is maintained likeother attributes; it's saved and restored insideAttributeBegin/AttributeEndblocks, and so forth. When a light source is created, the current exteriormedium is used for rays leaving the light when bidirectional lighttransport algorithms are used. (The user is responsible for specifyingmedia in a way such that rays reaching lights are in the same medium asrays leaving those lights.)
Shapes can be used to determine the spatial extent of participating mediain the scene. When a shape is created, the current interior medium isassumed to be the medium inside the shape (where "inside" is on the sideopposite the one the surface normal is pointing), and the current exteriormedium is assumed to be the medium outside the shape. As with lights, theuser is responsible for defining these consistently. (For example, media'sspatial extents should always be enclosed by closed shapes.)
Depending on the application, it can be useful to use a shape purely todetermine the spatial extent of media, but to not want the shape toappear in the scene. In this case, if "none" is specified for theshape's material, it will be ignored in ray intersection calculations(except for allowing the current medium to be updated.)