This document is a reference to the file format used inpbrt-v4, the version of the system correspondingto the forthcoming fourth edition of Physically Based Rendering;it serves as a comprehensive reference. Thepbrt-v4 User's Guide documents how touse pbrt with more focus on how to achievevarious tasks.
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. However, pbrt supportsa variety of efficient binary encodings for scene data such as PLY filesfor meshes and various image formats for textures; thus, the size of thetext input files is often not too large.
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 APImethod defined in theParserTargetclass in pbrt-v4. (See also Appendix C in thefourth edition of the Physically Based Rendering book.) Forexample, when the WorldBegin statement appears inthe input, an implementation ofthe ParserTarget::WorldBegin() method iscalled.
We have tried to minimize changes to the file format in order to make it aseasy as possible to use existing scene description fileswith pbrt-v4.However, a number of changes were necessaryfor new functionality or changes in the system's implementation.
To make it easier to bringpbrt-v3 scenesto pbrt-v4, pbrt now providesan --upgrade command-line option:
$ pbrt --upgrade scene.pbrt > scene-v4.pbrtIn some cases, it may not be possible toupgrade pbrt-v3 scenes automatically; pbrt willthen issue an error indicating which part of the scene description requiresmanual attention.
Major changes to the scene description include:
- Environment maps used for image-based lighting should nowuse Clarberg'sequal-area mapping. pbrt's imgtool utilityprovides a makeequiarea operation that convertsequirectangular environment maps (as used in pbrt-v3) to thisparameterization.
- The WorldEnd directive has been removed. WorldBegin is stillused to separate rendering options from the scene specification butrendering then begins when the end of the input files is reached. Thischange means that multiple images can no longer be rendered from a singleinvocation of pbrt, though that feature was both rarely used andbuggy.
- The TransformBeginand TransformEnd directives have also beenremoved. AttributeBeginand AttributeEnd should be used instead. (Inpbrt, they have nearly the same semantics.)
- The parser has become more strict about types in parameter lists.For example, "point P" will now give anerror; "point3 P" must be usedinstead. (Previously, both were allowed.)
- The set of materials provided by pbrt is nearly all new and betterreflects modes of physical scattering at surfaces. (Thus, for example,materials like "mirror" and "plastic" are no longer available, havingbeen replaced with "conductor" and "coateddiffuse", which providefunctionality that is a superset of those.)
- Various parameter names have been changed to improve clarity orconsistency. (For example, the xwidthparameter to various pixel reconstruction filters is now namedxradius.) Refer to thethe pbrt-v4 File Format documentationfor further details.
- The rarely-used and occasionally-buggy "cone", "hyperboloid", and "paraboloid"Shapes have been removed.
- The "image" Film is gone; use "rgb" instead.
- The "fourier" material is no longer supported and has been replacedwith "measured", which is based on aparameterization that better matches measured BRDF data.
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.
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 "volpath"Film "rgb" "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" "point3 from" [ -30 40 100 ] "blackbody L" 3000 "float scale" 1.5AttributeBegin Material "dielectric" Shape "sphere" "float radius" 1AttributeEndAttributeBegin Texture "checks" "spectrum" "checkerboard" "float uscale" [16] "float vscale" [16] "rgb tex1" [.1 .1 .1] "rgb tex2" [.8 .8 .8] Material "diffuse" "texture reflectance" "checks" Translate 0 0 -1 Shape "bilinearmesh" "point3 P" [ -20 -20 0 20 -20 0 -20 20 0 20 20 0 ] "point2 uv" [ 0 0 1 0 1 1 0 1 ]AttributeEnd
When this input file is rendered with pbrt-v4,this image is generated:
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, and shapes, can be defined inside the worldblock (and can only be defined inside the world block). Participatingmedia can be specified before orafter WorldBegin, as it can be associated withcameras, lights, and shapes.
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.
When there is nothing left to parse, rendering begins. At this point,the Integrator defined takes control andperforms the required rendering computation.
The hash character # denotes that the rest ofthe line is a comment and should be ignored by the parser.
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.)
For these statements, the "type" string gives the name of the particularshape, light., etc., and parameter-list gives the parameters topass to the implementation. With this design, pbrt's parser doesn't needto know anything about the semantics of the parameters; it just needs toknow how to parse parameter lists and store the parameter names and valuesthat it finds in a structure for later processing.
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 ]
If there is only a single value, the brackets areoptional. For example,
"float fov" 30
specifies a parameter "fov" that is a single floating-pointvalue, with value 30.
Alternatively,
"float cropwindow" [0 .5 0 .25]
specifies that "cropwindow" is a floating-point array with the given fourvalues.
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 eleven parametertypes: integer, float,point2, vector2,point3, vector3,normal3, spectrum,rgb, blackbody, bool,and string.
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 valuestrue and false.
"string filename" "foo.exr""point3 origin" [ 0 1 2 ]"normal N" [ 0 1 0 0 0 1 ] # array of 2 normals"bool renderquickly" true
Colors and Spectra
pbrt provides three different 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.(They are interpreted as being with respect to the current RGB colorspace, which can be specified usingthe ColorSpace directive, which is described below):
"rgb reflectance" [ .2 .5 .3 ]
specifies the RGB color with red equal to 0.2 and so forth.
Alternatively, a normalized blackbody spectral distribution with maximumvalue of 1 can be specifiedusing blackbody.
"blackbody emission" 6500
General spectral distributions can be specified with a series of (wavelength, value)pairs, where wavelengths are specified in nm:
"spectrum reflectance" [ 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 using a file on disk:
"spectrum reflectance" "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 tothe end of the current line.
A number of useful spectral distributions are also built into pbrt; if the following names areprovided as string values to spectrum parameters,the corresponding spectral distribution is used:
| String | Description |
|---|---|
| "glass-BK7" | Index of refraction for BK7 glass |
| "glass-BAF10" | Index of refraction for BAF10 glass |
| "glass-FK51A" | Index of refraction for FK51A glass |
| "glass-LASF9" | Index of refraction for LASF9 glass |
| "glass-F5" | Index of refraction for F5 glass |
| "glass-F10" | Index of refraction for F10 glass |
| "glass-F11" | Index of refraction for F11 glass |
| "metal-Ag-eta" / "metal-Ag-k" | Index of refraction and extinction coefficient for silver. |
| "metal-Al-eta" / "metal-Al-k" | Index of refraction and extinction coefficient for aluminum. |
| "metal-Au-eta" / "metal-Au-k" | Index of refraction and extinction coefficient for gold. |
| "metal-Cu-eta" / "metal-Cu-k" | Index of refraction and extinction coefficient for copper. |
| "metal-CuZn-eta" / "metal-CuZn-k" | Index of refraction and extinction coefficient for copper zinc alloy. |
| "metal-MgO-eta" / "metal-MgO-k" | Index of refraction and extinction coefficient for magnesium oxide. |
| "metal-TiO2-eta" / "metal-TI02-k" | Index of refraction and extinction coefficient for titanium dioxide. |
| "stdillum-A" | CIE standard illuminant A. |
| "stdillum-D50" | CIE standard illuminant D50. |
| "stdillum-D65" | CIE standard illuminant D65. |
| "stdillum-F1" – "stdillum-F12" | CIE standard illuminants F1 through F12. |
| "illum-acesD60" | D60 illuminant fromACES. |
Transformations
A series of directives modify the current transformation matrix (CTM).When the scene's camera is specified witha Camera directive, the CTM defines thetransformation from world space to camera space; when a light or shape iscreated, the CTM specifies the transformation from object space to worldspace.
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 modify the CTM:
| Input File Syntax |
|---|
| Identity |
| Translate x y z |
| Scale x y z |
| Rotate angle x y z |
| LookAt eye_x eye_y eye_z look_x look_y look_z up_x up_y up_z |
| CoordinateSystem "name" |
| CoordSysTransform "name" |
| Transform m00 ... m33 |
| ConcatTransform m00 .. m33 |
For example, Translate takes three floating-point values, x, y, andz, and cause the CTM to be set it to its product of with thematrix representing the given translation. An arbitrary transformation tomultiply the CTM with can be specifiedusing ConcatTransform;alternatively, Transform resets the CTM to thespecified matrix.
A name can be associated with the CTM usingthe CoordinateSystem directive. In turn, theCTM can later be reset to the recorded transformationusing CoordSysTransform.pbrt automatically records the cameratransformation matrix in the "camera" named coordinate system; this canbe useful for placing light sources with respect to the camera, forexample.
pbrt supports animated transformations byallowing two transformation matrices to be specified at different times.The TransformTimes directive, which must beoutside of the world definition block, defines these two times withfloating-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
Including Files
Two statements make it possible to specify other files to be parsed.The first of them is Include, which behavessimilarly to the #include directive in C++:parsing of the current file is suspended, the specified file isparsed in its entirety, and only then does parsing of the current fileresume. Its effect is equivalent to direct text substitution of theincluded file.
Include "geometry/car.pbrt"
Included files may be compressed using gzip. If a scene file name has a".gz" suffix, then pbrt will automatically decompress it asit is read from disk.
Include "geometry/bigcar.pbrt.gz"
The Import directive can also be used tospecify a file to be parsed. It is similarto Include in that it takes a single filenameargument and that the file may be gzip-compressed, but its semantics arethat the definitions of any named objects—object instances, namedtextures, named materials, or named participating media—may not bereferenced in the initial file with the Importstatement. Thus, Import does not correspond todirect text substitution. In return for this restriction, it is possibleto parse imported files in parallel; judicious useof Import can thus significantlyimprove pbrt's startup time when renderingcomplex scenes.
Import "geometry/complex-car.pbrt"
If the filename given to a Includeor Import statement is not an absolute path,its path is interpreted as being relative to the directory of theinitial file being parsed as specifiedwith pbrt's command-line arguments.
This section describes rendering options that must be specified before theWorldBegin statement.
General Options
A number of general options that control rendering can be specifiedusing the Option directive. Many of these canalso be specified via command-line arguments.
Option "type name" value
The following options can be specified:
| Type | Name | Default Value | Description |
|---|---|---|---|
| bool | disablepixeljitter | false | Forces all pixel samples to be through the center of the pixelarea. Enabling this can be useful when computing reference images and thencomputing error with respect to them in that it eliminatesdifferences due to geometric sampling that may not be of interest. |
| bool | disabletexturefiltering | false | Forces point sampling at the finest MIP level for all texturelookups. (Rarely useful.) |
| bool | disablewavelengthjitter | false | Forces all samples within each pixel to sample the samewavelengths. RGB images will generally have objectionable color error butthis can also be useful when computing error with respect toreference images when error due to random wavelength samplingshouldn't be included. |
| float | displacementedgescale | 1 | Global scale factor applied to triangle edge lengths beforeevaluating the edge length test for refinement when applyingdisplacement mapping. Increasing this value will generally reducememory use and startup time when rendering scenes with displacementmapping. |
| string | msereferenceimage | (none) | Specifies the filename of an image to use when computingmean squared error versus the number of pixel samples taken (see"msereferenceout" below). |
| string | msereferenceout | (none) | Filename for per-sample mean squared error results. When boththis and "msereferenceimage" are specified, the mean squared errorof the current image and the reference image is computed after eachsample is taken and the results are stored in text format in this file. |
| string | rendercoordsys | "cameraworld" | Specifies the coordinate system to use for renderingcomputation. The default, "cameraworld" translates the scene so thatthe camera is at the origin. "camera" uses camera space (performancemay suffer due to the scene being rotated) and "world" uses worldspace (accuracy may suffer due to floating-point precision). |
| integer | seed | 0 | Seed to use for pseudo-random number generation duringrendering. Rendering a scene with different seed values will giveindependent results, which can be useful for statistical analysis. |
| bool | forcediffuse | false | Force all materials to be diffuse. (Note: not currently supported with the--wavefrontand --gpuintegrators.) |
| bool | pixelstats | false | Write out images after rendering that encode per-pixelstatistics including time spent rendering each pixel and any otherper-pixel statistics addedusing STAT_PIXEL_COUNTER orSTAT_PIXEL_RATIO in the pbrt source code. |
| bool | wavefront | false | Enables the "wavefront" integrator (i.e., the integrator used forGPU rendering, but running on the CPU.) |
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 camera-from-worldtransformation.
pbrt provides four camera implementations:
| Name | Implementation Class |
|---|---|
| "orthographic" | OrthographicCamera |
| "perspective" | PerspectiveCamera |
| "realistic" | RealisticCamera |
| "spherical" | SphericalCamera |
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 andOrthographicCamera 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 also support images thatinclude defocus blur due to finite camera apertures. Both use thefollowing two parameters to set parameters related to lens focus.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | lensradius | 0 | The radius of the lens. 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 a parameter for setting the camera's field ofview.
| 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. |
The SphericalCamera captures light arriving atthe camera from all directions. It takes a parameter that describes themapping to use from directions to 2D points on the image.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | mapping | "equalarea" | By default, an area-preserving mapping based on an octahedral encodingof the unit sphere is used. Alternatively, an equirectangular mappingcan be specified using "equirectangular". |
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-v4 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. |
| string | aperture | (unspecified) | Allows specifying the shape of the camera aperture, which is circularby default. The values of "gaussian", "square", "pentagon",and "star" are associated with built-in aperture shapes; other valuesare interpreted as filenames specifying an image to be used to specifythe shape. |
Samplers
The Sampler generates samples for the image,time, lens, and Monte Carlo integration. A number of implementations areprovided; the default "zsobol"—is an instance ofthe ZSobolSampler that takes 16 samples perpixel.
| Name | Implementation Class |
|---|---|
| "halton" | HaltonSampler |
| "independent" | IndependentSampler |
| "paddedsobol" | PaddedSobolSampler |
| "sobol" | SobolSampler |
| "stratified" | StratifiedSampler |
| "zsobol" | ZSobolSampler |
Note that the IndependentSampler is the leasteffective of the samplers and is mostly included only for comparison withmore sophisticated approaches.
For samplers that use pseudorandom values (either directly whenjittering sample positions or for scrambling), a seed for thepseudorandom number generator can be specified. Specifying differentseeds makes it possible to do independent runsof pbrt, which can be useful for analysis ofconvergence or error of various sampling algorithms.
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer | seed | (See description) | A seed to use for the pseudorandom number generator. The default seedvalue is zero, though the --seed command-lineargument can be used to specify a different seed. If a seed is specifiedin the scene description file, it overrides a value specified on thecommand-line. |
All of the samplers other thanthe StratifiedSampler take a "pixelsamples"parameter that sets the number of samples to take in each pixelarea. ForPaddedSobolSampler, SobolSampler,and ZSobolSampler, this value must be a powerof two. For those, if a non-power-of-two value is provided, it is roundedup to the next power of two.
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer | pixelsamples | 16 | The number of samples to take in each pixel. |
The four Samplers that are based on low-discrepancy sample points(HaltonSampler, PaddedSobolSampler, SobolSampler,and ZSobolSampler) provide an option thatchooses among algorithms that randomize the sample points while stillpreserving their low-discrepancy properties.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | randomization | "fastowen" ("permutedigits" for the HaltonSampler). | Specifies a randomization algorithm to use. "none" disablesrandomization; "permutedigits" applies a random permutation to the digitsof the sample; "owen" applies Owen scrambling; "fastowen" (not availablewith the the HaltonSampler) applies anefficient approximation to Owen scrambling. |
The StratifiedSampler takes separatespecifications of the number of pixel samples in each of the twodimensions and also provides control of whether samples are jittered.
| 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 | 4 | The number of samples per pixel to take in the x direction. |
| integer | ysamples | 4 | 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. |
Color Spaces
RGB colors specified in the scene description are interpreted withrespect to the current color space when the RGB value is encountered. (Forimages used as texture maps, the current color space is not used; RGBimages are interpreted as being sRGB unless they are stored in an imageformat like OpenEXR that allows encoding the color space and another colorspace is specified in the image's metadata.)
The ColorSpace directive specifies the currentcolor space.
ColorSpace "rec2020"
Four color spaces are currently available. sRGB is the default.
| Name | Description |
|---|---|
| aces2065-1 | The standard color space defined in the AcademyColor Encoding System. |
| rec2020 | The ITU-R Recommendation BT.2020 color space. |
| dci-p3 | The DCI-P3 color space, widely used in current displays. |
| srgb | The venerable sRGB color space; it has the smallest gamutof pbrt-v4's color spaces, but is still widelyused. |
Film
The Film directive specifies the characteristics of the image being generated by the renderer.Three Film implementations are available:
- "rgb", corresponding to RGBFilm: thedefault film if none is specified; stores RGB images using the currentcolor space when the Film directive isencountered.
- "gbuffer", corresponding to GBufferFilm: inaddition to RGB, stores multiple additional channels that encodeinformation about the visible geometry in each pixel. Images must bewritten in OpenEXR format with this film. The User's Guidehas furtherdocumentation about the format of the information stored by this filmimplementation.
- "spectral", corresponding toSpectralFilm:stores a discretized spectral distribution at each pixel, in addition toRGB (for convenience when viewing images.) Images must bewritten in OpenEXR format with this film. Spectral data is stored using theformat described by Fichet et al..
A number of parameters common to all Film implementations specify theresolution of the image, an optional subset of it to be rendered, and howto save it when it is complete:
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer | xresolution | 1280 | The number of pixels in the x direction. |
| integer | yresolution | 720 | The number of pixels in the y direction. |
| float[4] | cropwindow | [ 0 1 0 1 ] | The sub-region 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. |
| integer[4] | pixelbounds | [ 0 xres 0 yres ] | A sub-region of the image to render, specified using pixel coordinates. |
| 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. |
| bool | savefp16 | true | Whether 16-bit floating point values (as opposed to 32-bit floatingpoint values) should be used when saving images in OpenEXR format. |
All Film implementations also take a number of parameters that affecthow the image is recorded:
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | iso | 100 | Film sensitivity to light; final pixel values are scaled by the "iso"value divided by 100. |
| float | whitebalance | 0 | If non-zero, this gives a temperature in degrees kelvin that is usedas the reference color temperature used for whitebalancing. |
| string | sensor | "cie1931" | Characterizes the sensor's response for red, green, and blue colors.The default corresponds to using the CIE 1931 spectral response curves.Alternatively, the measured response curves are available for thefollowing cameras:"canon_eos_100d","canon_eos_1dx_mkii","canon_eos_200d","canon_eos_200d_mkii","canon_eos_5d","canon_eos_5d_mkii","canon_eos_5d_mkiii","canon_eos_5d_mkiv","canon_eos_5ds","canon_eos_m","hasselblad_l1d_20c","nikon_d810","nikon_d850","sony_ilce_6400","sony_ilce_7m3","sony_ilce_7rm3", and"sony_ilce_9". |
| float | maxcomponentvalue | 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.) |
The GBufferFilm takes a parameter that specifies the coordinate system thatper-pixel geometric data (positions, normals, etc.) is stored in:
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | coordinatesystem | "camera" | Geometric data is stored in camera space by default. Alternatively,"world" can be specified for world space. |
Finally, the SpectralFilm takes a number of parameters that control howspectra are stored at each pixel:
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer | nbuckets | 16 | Number of buckets that the spectral range is discretized into. |
| float | lambdamin | 360 | Minimum wavelength for spectral range. |
| float | lambdamax | 830 | Maximum wavelength for spectral range. |
The RGBFilm uses the suffix of the givenoutput filename to determine the image file format to use.pbrt supportsPFM andOpenEXR for storing images with pixel valuesstored directly as floating-point values;QOI andPNG can also be used, thoughthese only provide 8 bits per color channel of precision.
Both GBufferFilmand SpectralFilm require that theOpenEXR format be used for output, as itprovides capabilities that both of them require for storing multi-channelimages with arbitrary semantics.
Filters
The Film implementations use an instance oftheFilter 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 along with the respective default filter radii. The defaultfilter is "gaussian".
| Name | Implementation Class | Default Radius |
|---|---|---|
| "box" | BoxFilter | 0.5 |
| "gaussian" | GaussianFilter | 1.5 |
| "mitchell" | MitchellFilter | 2 |
| "sinc" | LanczosSincFilter | 4 |
| "triangle" | TriangleFilter | 2 |
All filter implementations take two parameters for manually setting thefilter radius. The default values for these parameters vary according towhich filter is used, as listed in the table above.
| Type | Name | Description |
|---|---|---|
| float | xradius | The width of the filter in the x direction. |
| float | yradius | The width of the filter in the y direction. |
The "gaussian" filter takes an additional parameter that adjusts the rateof Gaussian falloff.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | sigma | 0.5 | Standard deviation of the Gaussian distribution. Larger values give afilter with broader support. |
Two parameters set the shape of the "mitchell" filter.
| 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 theVolPathIntegrator, which implements volumetricpath tracing:
Integrator "volpath" "integer maxdepth" [5]
Note that if GPU rendering is being used or if the CPU-based wavefrontintegrator is enabled using the --wavefrontcommand-line option, then the Integratorstatement is ignored and an integrator corresponding tothe VolPathIntegrator is used.
The following integrators are available:
| Name | Implementation Class | Algorithm Used |
|---|---|---|
| "ambientocclusion" | AOIntegrator | Ambient occlusion (accessibility over the hemisphere) |
| "bdpt" | BDPTIntegrator | Bidirectional path tracing |
| "lightpath" | LightPathIntegrator | Path tracing starting from the light sources |
| "mlt" | MLTIntegrator | Metropolis light transport using bidirectional path tracing |
| "path" | PathIntegrator | Path tracing |
| "randomwalk" | RandomWalkIntegrator | Rendering using a simple random walk without any explicit light sampling |
| "simplepath" | SimplePathIntegrator | Path tracing with very basic sampling algorithms |
| "simplevolpath" | SimpleVolPathIntegrator | Volumetric path tracing with very basic sampling algorithms |
| "sppm" | SPPMIntegrator | Stochastic progressive photon mapping |
| "volpath" | VolPathIntegrator | Volumetric path tracing |
Many of these integrators are present only for pedagogical purposes orfor use in debugging more complex integrators through computing imagesusing much simpler integration algorithms. For rendering high qualityimages, one should almost always use one of "bdpt", "mlt", "sppm", or"volpath".
For scenes that include volumetric effects, the "volpath" integratorshould almost always be used. Other than it (and "simplevolpath"), theonly other integrators that support volumetric effects are "bdpt" and"mlt". Although those offer bidirectional sampling algorithms, theiralgorithms for sampling volumetric effects are not as good as the"volpath" integrator, especially for scenes with chromatic media.
A number of parameters are accepted by multiple integrators:
| Type | Name | Default Value | Description | Integrators |
|---|---|---|---|---|
| integer | maxdepth | 5 | Maximum length of a light-carrying path sampled by the integrator. | All but "ambientocclusion" |
| string | lightsampler | "bvh" | Light sampling algorithm to be used. The default is a BVH over thelights. Other options include "uniform" for uniform light sampling and"power" for sampling lights according to their power. | "path", "volpath", wavefront/GPU |
| bool | regularize | false | Controls whether "path regularization" is performed. (i.e., aroughening of specular vertices after a non-specular scattering eventwhich can reduce high-variance error in tricky lighting situations.) | "bdpt", "mlt", path", "volpath", wavefront/GPU |
Some of the other integrators take specialized parameters for theirunderlying integration algorithms:
| Integrator | Type | Name | Default Value | Description |
|---|---|---|---|---|
| "ambientocclusion" | bool | cossample | true | Controls whether uniform hemisphere sampling or cosine-weightedsampling should be used for ambient occlusion sample rays |
| "ambientocclusion" | float | maxdistance | (infinite) | Distance after which occlusion should be ignored. |
| "bdpt" | 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. |
| "bdpt" | 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. |
| "mlt" | 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. |
| "mlt" | 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.) |
| "mlt" | 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. |
| "mlt" | 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. |
| "mlt" | float | sigma | 0.01 | Standard deviation of the perturbation applied to random samples in[0,1] used for small path mutations. |
| "simplepath" | bool | samplebsdf | true | Use the BSDFs' importance sampling routines to sample raydirections. (Uniform spherical sampling is used otherwise.) |
| "simplepath" | bool | samplelights | true | Use the lights' importance sampling routines for direct lightingcalculations. (No light sampling is used otherwise and lights must berandomly intersected by rays for illumination to be found.) |
| "sppm" | 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. |
| "sppm" | float | radius | 1 | Initial photon search radius. (This value will be reduced as photonsare accumulated at each pixel.) |
| "sppm" | integer | seed | 0 | Seed for random number generator used to randomize samplegeneration for photon rays. |
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, "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 implementations are available in pbrt-v4:
| Name | Implementation Class |
|---|---|
| "bvh" | BVHAggregate |
| "kdtree" | KdTreeAggregate |
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. |
| 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 though it tends to require less memory than"bvh".
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer | intersectcost | 5 | 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.5 | "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.)
Attributes
A number of directives modify the current graphics state—examplesinclude the transformation directives(Transformations), and the directive thatsets the current material. The current graphics state can be saved andrestored using the AttributeBeginand AttributeEnd directives:
Material "diffuse"AttributeBegin Material "conductor" Shape "sphere"AttributeEnd # back to the "diffuse" materialShape "cone"
In addition to the current transformation matrix and material, thereverse-orientation setting, specified bythe ReverseOrientation directive, is part of thegraphics state. This directive, when active, flips the surface normal ofthe shapes that follow it; it can be useful when specifying area lightsources, which only emit light from the side their surface normal pointsfrom, and when specifying transparent materials, where the surface normalis used to determine whether rays are entering or exiting the refractivemedium.
pbrt-v4 also providesan Attribute directive that makes it possibleto specify parameter values for shapes, lights, textures, materials, andparticipating media once and have subsequent instantiations of thoseobjects inherit the specified value. Its syntax is:
Attribute"target" parameter-list
"target" must be one of "shape", "light", "material", "medium",or "texture". The following block shows an example of its use; thefirst two spheres have a radius of 5 (rather than the default sphereradius of 1), while the third one has a radius of 2.
Attribute "shape" "float radius" 5Shape "sphere"Translate 10 0 0Shape "sphere"Translate 10 0 0Shape "sphere" "float radius" 2 # this one has radius 2
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, the following specifies a sphere with radius 0.25.
Shape "sphere" "float radius" [0.25]
When a Shape directive is encountered, the current transformationmatrix is used to set the world from object 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 |
|---|---|
| "bilinearmesh" | BilinearPatch |
| "curve" | Curve |
| "cylinder" | Cylinder |
| "disk" | Disk |
| "sphere" | Sphere |
| "trianglemesh" | Triangle |
The "loopsubdiv" and "plymesh" shapes are available for convenience;both immediately convert themselves to instances ofthe Triangle shape when the scene description isloaded. Their parameters are also documented in the following.
All shapes take an optional "alpha" parameter that can be used to definea mask that cuts away regions of a surface. (For example, a leaf might bemodeled with a single triangle but with a texture that cuts away theedges to make the outline of a leaf.) It can be specified in twodifferent ways:
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | alpha | 1 | A constant "alpha" value across the entire surface. A value of 1has no effect and a value of 0 causes the surface to entirelydisappear. Intermediate values cause the surface to be partiallytransparent. |
| texture | alpha | (none) | A spatially-varying "alpha" value specified using a texture. Seethe Textures section below for informationabout how textures are specified. |
The "curve" shape is useful for modeling thin objects like hair, fur,and grass. It has a few variants, including a ribbon that is alwaysoriented toward the incident ray, a flat ribbon with orientation given bya pair of surface normals, and an (apparent) thin cylinder, where shadingnormals give the illusion of a curved surface.
| Type | Name | Default Value | Description |
|---|---|---|---|
| point3[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 "flat" curve is always oriented to facethe incident ray. The "cylinder" alternative includes a shading normalthat causes the curve to appear to have a cylindrical cross section.Finally, the "ribbon" curve has a fixed orientation. |
| normal[2] | N | (none) | For "ribbon" curves, these normals are respectively used at endpointsof the curve to orient the surface there. Intermediate normals areinterpolated using spherical 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. |
The "cylinder" is always oriented along the z axis. Ittakes four 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 in the xyplane, with its object space center at x=0 andy=0.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | height | 0 | The position 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). |
Spheres are always at the origin in object space. These are the "sphere"shape's 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). |
A triangle mesh is defined by the "trianglemesh" shape. The mesh'stopology is defined by the indices parameter,which is an array of integer indices into the vertex arrays. Eachsuccessive triplet of indices defines the offsets to the three vertices ofone triangle; thus, the length of the indicesarray 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 ] "point3 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.
For convenience, a single triangle can be specified withoutthe indices parameter. If justthree P vertices are specifiedwithout indices, then the indices are assumedto be "[0 1 2]".
Triangle meshes are specified using the following parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| integer[n] | indices | (none) | The array of integer offsets into the per-vertex data arrays(P, and anyof N, S,or uv that are present.) Required, unlessexactly three vertices are specified. |
| point3[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. |
| vector3[n] | S | none—optional | Per-vertex tangents. |
| point2[n] | uv | none—optional | Per-vertex texture coordinates. |
pbrt can also directly read triangle meshes specified inthe PLY meshfile format, via the "plymesh" shape. Unlike all of the othershapes, the "plymesh" shape supports displacement mapping, where auser-specified texture is used to offset the base surface. It takes thefollowing parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | filename | required—no default | File from which the PLY-format mesh is loaded. If the file name'sextension is ".gz", the file will be decompressed from gzip format as itis read. |
| texture | displacement | (none) | Specifies a texture used to displace the vertices of the mesh. Themesh will be adaptively tessellated so that all edges are below aspecified length. (See the Textures sectionbelow for information about how textures are specified.) |
| float | edgelength | 1 | Maximum length (in world space) of an edge of a triangle mesh thatis being displaced. Edges are recursively split until shorter than thislength. |
"loopsubdiv" corresponds to a subdivision surface evaluated with Loop'ssubdivision rules. It takes the following parameters:
| 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. |
| point[n] | P | required—no default | Vertex positions for the base mesh. This is the same as for the triangle mesh primitive. |
Object Instancing
If a complex object is used repeatedly in a scene, object instancing may beworthwhile; 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 world from instance 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"
Note that the materials that are active when a shape is specified in aninstance definition are used when the instance is used; it is notpossibility specify different materials for different uses of the sameinstance.
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 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 blackbodyemission of 5,500 kelvin:
LightSource "point" "blackbody I" [ 5500 ]
When a light source definition is encountered in the scene description,the current transformation matrix is used to define the world from lighttransformation. Many of the light sources also take parameters to place itin the scene; using either a transformation matrix or an explicit positionor direction to place a light can be useful.
All lights support a float "scale" parameterthat scales the amount of light that the light emits. Further, most lightstake an optional float "power" parameter thatspecifies the total power emitted by the light. The "distant" and"infinite" lights instead take an optional float"illuminance" parameter that specifies the light's total illuminance.Specifying the power (or illuminance) of lights in the scene can be aneffective way to adjust the lighting in the scene if multiple types oflights are being used.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | power / illuminance | (no default) | Total luminous power or illuminance emitted by the light. |
| float | scale | 1 | Scale factor that modulates the amount of light that the light sourceemits into the scene. |
If both "scale" and "power" (or, respectively, "illuminance") are specified, then the light's power isscaled by the given scale.
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 | Current color space's illuminant | Spectral distribution of the radiance emitted by 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 an image. This representation can be useful for modelingmany real-world light sources, where measurements of this distribution maybe available.
The image representing emission should be stored in the octahedral equalarea parameterization used by pbrt-v4. Thesource code that implements themappings fromthe unit square to the sphereand fromthe sphere to the unit square may be useful references. Furthermore,for convenience, imgtool makeequiarea can be usedto convert an image stored in an equirectangular mapping (as was used inprevious versions of pbrt) to the mapping usedin pbrt-v4. The default "up" direction for thislight is the y axis, though the world from light transformationmatrix can be used to position and orient the light.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | filename | required—no default | The filename of the image file that stores a goniometricdiagram to use for the lighting distribution. |
| spectrum | I | The current color space's illuminant | The spectral distribution of emission from the light; the radiantintensity in a particular direction is computed as the product ofthis value, the "scale" parameter, the appropriate value from thegoniometric diagram table, and the light's power, if specified. |
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").Like the "goniometric" light, the y axis is the default "up"direction, but the environment map can be reoriented using the world fromlight transformation.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | filename | (none) | The environment map to use for the infinite area light. If nofilename is provided, the light will emit the same amount of radiancefrom every direction. Environment maps should be specified using thesame equal-area mapping as is used for the goniometric light; seeabove for information about this parameterization and how to convertenvironment maps into this representation. |
| portal | point3[4] | (none) | If provided, these points should specify a planar quadrilateralthrough with the light source is visible (e.g., a window, or a quadthat bounds multiple windows on a wall.) This information is used toonly sample regions of the light that are visible from the point beingshaded and generally gives lower error when it is applicable. |
| spectrum | L | The current color space's illuminant | The spectral distribution of emission from the light; the radianceintensity in a particular direction is computed as the product ofthis value, the "scale" parameter, and the light's power, ifspecified. Note that both "L" and "filename" may not be specified. |
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 | The current color space's illuminant | Spectral distribution of 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 world from light transformation matrix.
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum | I | The current color space's illuminant | Spectral distribution of the light's emitted radiant intensity. |
| float | fov | 90 | The spread angle of the projected light, along the shorter image axis. |
| string | filename | 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 | The current color space's illuminant | Spectral distribution of the light's emitted radiant intensity. |
| 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. Notethat area lights can currently only be used with triangle, bilinear patch,sphere, cylinder, and disk shapes; a runtime error is issued if an arealight is bound 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" "blackbody L" [ 6500 ] "float power" [ 100 ] 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 emits radianceuniformly over all directions in the hemisphere around the surface normalat each point on the surface. Thus, the orientation of the surface normalis meaningful; by default, an emitting sphere emits in the directionsoutside the sphere and there's no illumination inside of it. If this isnot the desired behavior, the ReverseOrientationdirective can be used to flip the orientation of the surface normal ofsubsequent shapes, or the "twosided" option, described in the list ofoptions below, can be enabled.
AttributeBegin AreaLightSource "diffuse" ReverseOrientation # illuminate inside the sphere Shape "sphere"AttributeEnd
The "diffuse" area light takes these parameters.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | filename | (none) | Filename for an image that describes spatially-varying emissionover the surface of the emitter. The emitting shape's default (u,v)parameterization is used to map the image to the surface. |
| spectrum | L | The current color space's illuminant | Spectral distribution of the light's emitted radiance. |
| bool | twosided | false | Determines whether the light source emits light from just the side ofthe surface where the surface normal points or both sides. |
Materials
Materials specify the light scattering properties of surfaces in thescene. The Material directive specifies thecurrent material, which then applies for all subsequent shape definitions(until the end of the current attribute scope or until a new material isdefined:
Material "diffuse" "rgb reflectance" [ .7 .2 .2 ]
Parameters to materials are distinctive in that textures can beused to specify spatially-varying values for the parameters. For example,the above material definition defines a diffuse surface with the samereddish color at all points. Alternatively, we might want to use an imagemap to define the color as a function of (u,v) on the surface.This is done by defining a texture with a user-defined name (below,"lines-tex"), and then binding that to the appropriate parameter of thematerial.
For example, the following sets the "reflectance" parameter of the"diffuse" material to be computed via lookups to the "lines.exr" imagemap.
Texture "lines-tex" "spectrum" "imagemap" "string filename" "textures/lines.exr"Material "diffuse" "texture reflectance" "lines-tex"
Note that for each parameter (for example, "reflectance" in the above),a value for the parameter can either be bound with a constant value, inwhich case the given type of the parameter should be "float","spectrum", etc., as appropriate, or a texture value, in which case thegiven type of the parameter should be "texture" and the parameter valuebound is the name of a texture. (The next section of thisdocument, Textures, describes the texturesavailable in pbrt as well as theirparameters.)
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 withthe MakeNamedMaterial directive. The currentmaterial can be set to a preexisting named material using theNamedMaterial directive.
MakeNamedMaterial "mydiffuse" "string type" "diffuse" "rgb reflectance" [ 0.1 0.5 0.2 ]Material "conductor" # current material is "conductor"NamedMaterial "mydiffuse" # current material is "mydiffuse" 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 |
|---|---|
| coateddiffuse | CoatedDiffuseMaterial |
| coatedconductor | CoatedConductorMaterial |
| conductor | ConductorMaterial |
| dielectric | DielectricMaterial |
| diffuse | DiffuseMaterial |
| diffusetransmission | DiffuseTransmissionMaterial |
| hair | HairMaterial |
| interface | 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.) This material takesno parameters. |
| measured | MeasuredMaterial |
| mix | MixMaterial |
| subsurface | SubsurfaceMaterial |
| thindielectric | ThinDielectricMaterial |
All of the materials except for "interface" and "mix" can either take atexture that specifies a bump map or an image that specifies a normalmap.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float texture | displacement | None | Float-valued texture specifying surface height offsets that areused for bump mapping. |
| string | normalmap | None | Filename for an image to use to specify a normal map. |
Specifying Surface Roughness
Many of the following materials are based on models of light scatteringfrom rough surfaces modeled using microfacets; for example, a metal mightbe polished to be very smooth, or it might be roughened due to wear overtime. For all such materials, the following parameters are used todescribe the surface roughness.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float texture | roughness | 0 | Overall surface roughness, modeled using the Trowbridge-Reitz (GGX)microfacet distribution. If zero, the surface is perfectly smooth and perfect specularreflection (and possibly transmission) occurs. Larger valuescorrespond to greater roughness. |
| float texture | uroughness | 0 | For surfaces with anisotropic roughness distributions, microfacetroughness in the u direction. |
| float texture | vroughness | 0 | For surfaces with anisotropic roughness distributions, microfacetroughness in the v direction. |
| bool | remaproughness | true | If true, roughness values are expected to be between 0 and 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 parameter of theTrowbridge-Reitz microfacet distribution function. Using this remappinggives a more intuitive control of roughness than specifying alpha. |
CoatedConductor and CoatedDiffuse
The "coatedconductor" and "coateddiffuse" materials model scattering dueto a dielectric interface layer above, respectively, a conductor baselayer or a diffuse base layer. Scattering and absorption in the mediumbetween the interface and the base layer can also be specified. The"coatedconductor" model is useful both for modeling metals with a glazingas well as metals with a tarnish layer. The "coateddiffuse" model is agood match for the surface appearance of materials like plastic andvarnished wood.
Both take a number of common parameters that specify the volumetricmedium between the two layers, if any, and control some of the parametersof the algorithm used to simulate scattering between the layers.
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum texture | albedo | 0 | Scattering albedo of the medium between the interface and thediffuse base layer. Must be less than or equal to 1. |
| float texture | g | 0 | Henyey-Greenstein asymmetry parameter ranging from -1 to 1 that describes thedistribution of scattered light in the medium. |
| integer | maxdepth | 10 | Maximum number of bounces of light to model when modeling lightscattering among the interface, the base layer, and the medium (ifpresent). |
| integer | nsamples | 1 | Number of independent samples to take when performing Monte Carlointegration of light scattering between the layers. |
| float | thickness | 0.01 | Thickness of the medium between the two layers. |
The "coateddiffuse" material takes a single additional parameter todescribe reflection from the diffuse base.The roughness of the dielectric interface and its index of refractionare specified using the parametersdescribed above (i.e., "roughness", "uroughness", "vroughness", and"remaproughness"). Therefore those parameters are not included inthe following table.
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum texture | reflectance | 0.5 | Reflectance of the base diffuse layer. |
The "coatedconductor" material takes the common parameters listed aboveas well as the additional ones listed in the table below. Although ituses the same general scheme forspecifying roughness as above, there is the added challenge that boththe interface and the conductor layers may have different roughnesses.Therefore, there are two sets of controls, prefaced with "interface" and"conductor". For example, the roughness of the interface layer is setvia the "interface.roughness" parameter, while the conductor layer is setvia "conductor.roughness".
"coatedconductor" takes a few additional parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum | conductor.eta | (Copper's index of refraction) | The conductor's index of refraction. |
| spectrum | conductor.k | (Copper's extinction coefficient) | The conductor's exctinction coefficient. |
| spectrum | reflectance | (none) | As an alternative to specifying the conductor's index of refractionand extinction coefficient, its average spectral reflectance can bespecified instead; in this case plausible values for the index ofrefraction and extinction cofficient are found for rendering. |
Conductor
The "conductor" material describes scattering from metals, where theindex of refraction (eta) and the absorption coefficient (k) affect theconductor's appearance. Alternatively, the average reflectance of theconductor can be specified; this can be especially useful if a conductor'sappearance has been described with an image texture map.
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum texture | eta | (Copper's index of refraction) | The wavelength-dependent index of refraction of the conductor. |
| spectrum texture | k | (Copper's absorption coefficient) | The conductor's wavelength-dependent absorption coefficient. |
| spectrum texture | reflectance | (none) | Average reflectance of the conductor. Plausible values of "eta" and"k" are computed based on the reflectance if it is provided. |
As described above the spectraldistributions for etaand k for a variety of conductors are built in topbrt. For example, silver can be specified using"metal-Ag-eta" and "metal-Ag-k".The refractiveindex.infowebsite is also a useful resource for such data.
The "conductor" material takesthe standard set of parameters forspecifying surface roughness that were described above.
Dielectric
The "dielectric" material models a dielectric interface (e.g., glass).The outside of the interface is taken to be the side of the surface wherethe surface normal is pointing; the interior is then on the otherside.
The index of refraction of the interior medium is specified using the"eta" parameter, which may be wavelength-dependent or may be the sameover all wavelengths. If it does vary over wavelengths then light atdifferent wavelengths will refract in different directions, giving riseto dispersion.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float texture | eta | 1.5 | Index of refraction of the medium inside the surface. |
| spectrum texture | eta | (none) | Wavelength-dependent index of refraction of the medium inside thesurface. (Corresponding data for a variety of mediaare built in to pbrt; seealsothe refractiveindex.infowebsite. |
This material also takes the set ofparameters for specifying surface roughness that were describedabove.
Diffuse
The "diffuse" material models surfaces with ideal Lambertian reflection.In addition to an optional bump or normal map, it takes a singleparameter that describes the surface's reflectance:
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum texture | reflectance | 0.5 | The reflectivity of the surface. Must be between 0 and 1. |
DiffuseTransmission
"diffusetransmission" models both diffuse reflection and transmission,taking an additional parameter to specify the amount oftransmission. (Note also that its default reflectance is different thanthat of "diffuse".)
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum texture | reflectance | 0.25 | The reflectivity of the surface. |
| spectrum texture | transmittance | 0.25 | The transmissivity of the surface. |
| float texture | scale | 1 | A scale factor that is applied to both the reflectance andtransmittance values. |
Hair
The "hair" material models reflection and transmission from cylindricalfibers like hair and fur. It is generally only useful with the "curve"shape.
The color of the hair can be specified using a number of differentparameters.
| 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 | reflectance | If specified, a value of the absorption coefficient is computed usingan approximation that leads to the hair having roughly this reflectance,after multiple 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 "reflectance" is specified,the eumelanin and pheomelanin parameters are ignored, if present. If nohair color parameters are specified, a eumelanin concentration of 1.3 isused, 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. |
Measured
The "measured" material can be used with materials that use therepresentation described in Dupuy and Jakob'spaper AnAdaptive Parameterization for Efficient Material Acquisition andRendering. A wide variety of such materials are available in theRGB Material Database.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | filename | (none) | Name of file storing measured BRDF data. |
Mix
The "mix" material can be used to select between two materials using atexture or to blend between them. More than two materials can be blendedusing "mix" materials that themselves blend between other "mix"materials. It takes the following parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| string[2] | materials | none | Names of two named materials (specifiedusing MakeNamedMaterial) to mix between. |
| texture float | amount | 0.5 | Weighting factor for the blend between materials. A value of zerocorresponds to just the first material, a value of one corresponds tojust the second, and values in between interpolate linearly. |
Unlike most other materials, a bump or normal map may not bespecified with the "mix" material: bump and normal maps should be appliedto the constituent materials that they blend between, however.
Subsurface
The "subsurface" material provides a convenient way to specify thescattering materials of a material that exhibits subsurface scattering,where light may exit at a different place where it enters. Thescattering characteristics of these materials can be specified in one ofthree ways:
- Direct specification of the absorption coefficient "sigma_a" and thescattering coefficient "sigma_s". (If those values are available, thenthis approach is the best, though it can be unintuitive to tune thesevalue to achieve a desired visual effect.)
- Specification of the surface's reflectance and the mean free pathinside the medium. (The smallerthe mean free path, the thicker the medium is.) These two values are thenused to derive scattering coefficients for the medium.)
- Providing the name of measured scattering properties that are includedin pbrt.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float texture | eta | 1.33 | Index of refraction of the scattering volume. Note thatwavelength-dependent indices of refraction are not supported in thecurrent implementation. |
| float texture | g | 0 | Henyey-Greenstein asymmetry parameter, which ranges from -1 to 1,going from completely backwards-scattering to completelyforward-scattering. |
| float texture | mfp | (none) | Mean free path of light in the volume, specified in meters. (Usedonly if "reflectance" is specified.) |
| string | name | none | Name of measured subsurface scattering coefficients. See theGetMediumScatteringProperties()function in the pbrt-v4 source code themeasured subsurface scattering coefficients that are available. |
| spectrum texture | reflectance | (none) | Average reflectance of the volume. If specified, absorption and scatteringcoefficients are computed from this value and the specified mean free path. |
| spectrum texture | sigma_a | RGB (.0011, .0024, .014) | Absorption coefficient of the volume, measured in mm^-1. |
| spectrum texture | sigma_s | RGB (2.55, 3.12, 3.77) | Scattering coefficient of the volume, measured in mm^-1. |
| float | scale | 1 | Scale factor that is applied to sigma_a and sigma_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. |
The "subsurface" material also takesthe standard set of parameters forspecifying surface roughness that were described earlier.
Textures
The Texture statement creates a named textureof a particular type. The only types that are supportedare spectrumand 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 textureimplementations. Those that support both "float" and "spectrum"-typedvariants are implemented as two separate classes.
| Name | Implementation Class |
|---|---|
| "bilerp" | {Float,Spectrum}BilerpTexture |
| "checkerboard" | {Float,Spectrum}CheckerboardTexture |
| "constant" | {Float,Spectrum}ConstantTexture |
| "directionmix" | {Float,Spectrum}DirectionMixTexture |
| "dots" | {Float,Spectrum}DotsTexture |
| "fbm" | FBmTexture |
| "imagemap" | {Float,Spectrum}ImageTexture |
| "marble" | MarbleTexture |
| "mix" | {Float,Spectrum}MixTexture |
| "ptex" | {Float,Spectrum}PtexTexture |
| "scale" | {Float,Spectrum}ScaledTexture |
| "windy" | WindyTexture |
| "wrinkled" | WrinkledTexture |
In the below, note that a number of textures ("scale", "mix", and"directionmix") themselves take textures as parameters; thus, one can buildup small "trees" of computation to compose a series of texturefunctions.
Texture Mapping and Parameterization
Textures can be separated into three categories: any-D, 2D, and 3D.Any-D texturesare ConstantTexture, ScaleTexture,DirectionMixTexture,and MixTexture. These kinds of textures do nothave a specific dimensionality and have no common arguments.
2D textures use a (u,v) parameterization for evaluation. Theyare both float and spectrum variantsof BilerpTexture, ImageTexture,the 2D variant of the CheckerboardTexture,and DotsTexture. 2D textures all take aparameter that describes the texture mapping function to use togenerate (u,v) coordinates:
| 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". Thedefault, "uv", is based on the surface's (u,v)parameterization. |
If the "uv" mapping is selected, additional parameters can be used tooffset and scale the (u,v) values.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | uscale, vscale | 1 | Scaling factors to be applied to the u and v texture coordinates,respectively. |
| float | udelta, vdelta | 0 | An offset to be applied to the u and v texture coordinates,respectively. This offset is applied after any scaling from "uscale"and "vscale". |
The "spherical" mapping is based on spherical coordinates where theta ismeasured with respect to the z axis in texture space and is thenremapped to a v value between 0 and 1. Phi is measured withrespect respect to x and y and remapped between 0 and 1for u. The "cylindrical" mapping directly maps the zaxis to v and computes a u value like the "spherical"mapping does.
For both the "spherical" and "cylindrical" mapping, the currenttransformation matrix when the associated texture is specified gives therendering space from texture space transformation. It can be set asneeded to orient and center the mapping functions.
Finally, the "planar" mapping projects the texture space 3D position ofthe lookup point to a plane specified by two basis vectors, one forthe u coordinate and the other for v. It takes thefollowing parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | udelta, vdelta | 0 | An offset to be applied to the u and v texture coordinates,respectively. This offset is applied after any scaling from "uscale"and "vscale". |
| 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". |
(Note that "uscale" and "vscale" are redundant for the "planar" mappingand are therefore not provided since their effect can be had by scalingthe "v1" and "v2" vectors.)
3D textures use a texture space point location to evaluate themselves.The current transformation matrix at the time they are created gives thetransformation from object space to the texture evaluation space. Theyare 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.
Bilinear Interpolation
"bilerp" bilinearly interpolates between the four textures using thetexture evaluation(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. |
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. |
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. |
DirectionMix
"directionmix" takes two textures and linearly interpolates betweentheir values using an interpolant based on the absolute value of dotproduct of the surface normal at the texture evaluation point with aspecified vector.
| 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 thesame type (float or spectrum). |
| vector | dir | (0,1,0) | Vector with with the dot product of the surface normal is computed. |
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, Wrinkled, and Windy
"fbm", "wrinkled", and "windy" are textures based on the Perlin noisefunction. They are 3D textures, so the scale of the features of thetexture can be adjusted by setting accordingly the CTM when the texture isdefined.
| 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. |
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. |
| string | filter | "bilinear" | Filter function to use for anti-aliasing texture lookups. Thedefault, "bilinear", does bilinear sampling of a single MIP level;it is a good choice if a reasonable number of samples are beingtaken at each pixel. Alternatives that give higher quality for eachsample are "ewa", which uses the high quality but much slowerelliptically weighted average algorithm and "trilinear", which doestrilinear interpolation between two MIP levels. Alternatively,even more efficient but lower quality point sampling may bespecified with "point". |
| string | encoding | "sRGB" | "sRGB", "linear", "gamma val". Specification of how toconvert 8-bit color values to floating point values between 0 and 1:"sRGB" applies the sRGB nonlinear mapping, "linear" directly mapsthem, dividing their values by 255, and "gamma val" appliesa gamma correction curve with the specified exponent. |
| float | scale | 1 | Scale factor to apply to value looked up in texture. |
| bool | invert | false | If true, then given a texture value x,returns 1-x instead. |
Marble
"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. |
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 thesame type (float or spectrum). |
| float texture | amount | 0.5 | The amount to use when linearly interpolating between the two mix textures. |
Ptex
The "ptex" texture provides support forDisney's Ptex texture format. Note thatpbrt has limited support for Ptex textures whenrendering on the GPU: only the highest MIP level is used on each face andno filtering is performed across faces.
| Type | Name | Default Value | Description |
|---|---|---|---|
| string | encoding | "gamma 2.2" | May be "sRGB", "linear", "gamma val: specifies how toconvert 8-bit color values from the texture to floating point valuesbetween 0 and 1: "sRGB" applies the sRGB nonlinear mapping, "linear"directly maps them, dividing their values by 255, and"gamma val" applies a gamma correction curve with thespecified exponent. |
| string | filename | (none) | Filename of the Ptex texture to use. |
| float | scale | 1 | Scale factor applied to texture values. |
Scale
Finally, "scale" takes two textures as parameters, evaluates each ofthem, and returns their product. It is often convenient to scale a textureused as a bump map by a constant float value tomodulate the perceived height of the bumps, for example.
| Type | Name | Default Value | Description |
|---|---|---|---|
| spectrum/float texture | tex | 1 | Texture to be scaled. |
| float texture | scale | 1 | Scale factor by which to multiply the values returned by "tex". |
Participating media can be associated with regions of space in thescene using the MakeNamedMediumand MediumInterface directives. First,MakeNamedMedium associates a user-specified namewith medium scattering characteristics.
MakeNamedMedium "mymedium" "string type" "homogeneous" "rgb sigma_s" [100 100 100]
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 "interface" is specified for theshape's material, it will be ignored in ray intersection calculations(except for allowing the current medium to be updated.)
There are five different representations of participating mediaavailable in pbrt.
| Name | Implementation Class |
|---|---|
| "cloud" | CloudMedium |
| "homogeneous" | HomogeneousMedium |
| "nanovdb" | NanoVDBMedium |
| "rgbgrid" | RGBGridMedium |
| "uniformgrid" | GridMedium |
The simplest of them, "homogeneous", models uniform scatteringproperties within its volume of space.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | g | 0 | The medium's Henyey-Greenstein phase function asymmetryparameter. |
| spectrum | Le | 0 | Spectral distribution of the medium's emitted radiance, if any. |
| float | Lescale | 1 | Scale factor applied to the medium's emitted radiance. |
| string | preset | none | Named measured scattering medium properties to use; see theGetMediumScatteringProperties()function in the pbrt-v4 source codefor the measurements that are available. |
| spectrum | sigma_a | 1 | The absorption cross section. |
| spectrum | sigma_s | 1 | The scattering cross section. |
| float | scale | 1 | Scale factor applied to the absorption and scattering crosssections. |
The "uniformgrid" medium generalizes the "homogeneous" medium by allowing thespecification of a uniformly-sampled grid of density values that aretrilinearly interpolated and then used to scale the provided absorptionand scattering coefficients. This medium also allows the specificationof spatially-varying emission that either has a fixed spectraldistribution and is scaled by the local density or is specified by a gridof blackbody emission temperatures.
The "uniformgrid" medium takes the following parameters:
| Type | Name | Default Value | Description |
|---|---|---|---|
| float[] | density | (none) | nx*ny*nz density values, in row-major order. |
| float | g | 0 | The medium's Henyey-Greenstein phase function asymmetryparameter. |
| spectrum | Le | 0 | Spectral distribution of the medium's emitted radiance. |
| float | Lescale | 1 | Scale factor applied to the medium's emitted radiance. |
| point3 | p0, p1 | (0,0,0), (1,1,1) | Extent of the density grid in the medium's space: the coordinatesof the lookup point are found with respect to these bounds before thedensity interpolant weights are computed. |
| integer | nx, ny, nz | 1 | Number of density samples in the x, y,and z dimensions. |
| string | preset | none | Named measured scattering medium properties to use; see theGetMediumScatteringProperties()function in the pbrt-v4 source codefor the measurements that are available. |
| spectrum | sigma_a | 1 | The absorption cross section. |
| spectrum | sigma_s | 1 | The scattering cross section. |
| float | scale | 1 | Scale factor applied to the absorption and scattering crosssections. |
| float[] | temperature | (none) | nx*ny*nz blackbody temperature values in kelvin, in row-majororder. If specified, these are trilinearly interpolated and thenconverted to blackbody emission spectra to describe the medium'semission. |
| float | temepratureoffset | 0 | Offset value that is added to the emission temperature, if present. |
| float | temperaturescale | 1 | Scale factor applied to the ofsetted emission temperature to geta temperature in degrees kelvin before the blackbody emission isdetermined. |
The "rgbrid" medium is similar to "uniformgrid", but it allows thespecification of spatially-varying emission and absorption and scatteringcoefficients with RGB colors. Its parameters are:
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | g | 0 | The medium's Henyey-Greenstein phase function asymmetryparameter. |
| rgb[] | Le | (none) | nx*ny*nz RGB colors that specify a grid of emission spectra. |
| float | Lescale | 1 | Scale factor applied to the medium's emitted radiance. |
| point3 | p0, p1 | (0,0,0), (1,1,1) | Extent of the density grid in the medium's space: the coordinatesof the lookup point are found with respect to these bounds before thedensity interpolant weights are computed. |
| rgb[] | sigma_a | (none) | nx*ny*nz RGB colors that specify the grid of absorption cross sections. |
| rgb[] | sigma_s | (none) | nx*ny*nz RGB colors that specify the grid of scattering cross sections. |
| float | scale | 1 | Scale factor applied to the absorption and scattering crosssections. |
The "cloud" medium is a fully-procedural model that is based on usingPerlin noise to synthesize a cloud-like density.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | density | 1 | Additional scale factor applied to the computed cloud density. |
| float | frequency | 5 | Parameter that controls the frequency at which the cloud's density varies. |
| float | g | 0 | The medium's Henyey-Greenstein phase function asymmetryparameter. |
| point3 | p0, p1 | (0,0,0), (1,1,1) | Extent of the cloud in the medium's space. |
| spectrum | sigma_a | 1 | The cloud's absorption cross section. |
| spectrum | sigma_s | 1 | The cloud's scattering cross section. |
| float | wispiness | 1 | Parameter that controls how wispy the cloud density is. |
Finally, the "nanovdb" medium allows the use of media stored inthe NanoVDB format, whichcan efficiently represent complex media through an adaptive hierarchy ofgrids. The density stored in the NanoVDB volume is used to scale thespecified absorption and scattering coefficients and if the volumeincludes a grid of temperature values, those are mapped totemperatures that are used to specify blackbody emission spectra.
| Type | Name | Default Value | Description |
|---|---|---|---|
| float | g | 0 | The medium's Henyey-Greenstein phase function asymmetryparameter. |
| float | Lescale | 1 | Scale factor applied to the medium's emitted radiance. |
| spectrum | sigma_a | 1 | The absorption cross section; this value is scaled by theNanoVDB volume's density at each point. |
| spectrum | sigma_s | 1 | The scattering cross section; this value is scaled by theNanoVDB volume's density at each point. |
| float | scale | 1 | Additional scale factor applied to the absorption and scatteringcross sections. |
| string | filename | (none) | Filename of the NanoVDB volume. |
| float | temepratureoffset | 0 | Offset value that is added to the emission temperature, if present. |
| float | temperaturescale | 1 | Scale factor applied to the ofsetted emission temperature to geta temperature in degrees kelvin before the blackbody emission isdetermined. |
