Skip to content

Latest commit

 

History

History
943 lines (731 loc) · 34.6 KB

API.md

File metadata and controls

943 lines (731 loc) · 34.6 KB
Raw

Classes

Snelly
Scene
Renderer
Material
Surface ⇐ Material
Volume ⇐ Material
Metal ⇐ Material
Dielectric ⇐ Material
Materials

Objects

GLU : object

Namespace for webGL utility wrappers. Functions for loading shader uniform variables are exposed to the user for convenience.

Snelly

Kind: global class

new Snelly(sceneObj)

Snelly is the global object providing access to all functionality in the system.

Param Type Description
sceneObj Scene The user-defined scene

snelly.getVersion() ⇒ Array

Returns the current version number of the snelly system, in the format [1, 2, 3] (i.e. major, minor, patch version)

Kind: instance method of Snelly

snelly.getRenderer() ⇒ Renderer

Access to the Renderer object

Kind: instance method of Snelly

snelly.getGUI() ⇒ GUI

Access to the GUI object

Kind: instance method of Snelly

snelly.getCamera() ⇒ THREE.PerspectiveCamera

Access to the camera object

Kind: instance method of Snelly
Returns: THREE.PerspectiveCamera - .

snelly.getControls() ⇒ THREE.OrbitControls

Access to the camera controller object

Kind: instance method of Snelly

snelly.showGUI(show)

Programmatically show or hide the dat.GUI UI

Kind: instance method of Snelly

Param Type Description
show Boolean toggle

snelly.setStatus(statusText)

Specify arbitrary status text (one line only) to display in the lower right of the viewport

Kind: instance method of Snelly

Param Type Description
statusText Boolean text to display

snelly.getGLContext() ⇒ WebGLRenderingContext

Kind: instance method of Snelly
Returns: WebGLRenderingContext - The webGL context

snelly.getMaterials() ⇒ Materials

Get materials object

Kind: instance method of Snelly

snelly.getSurface() ⇒ Surface

Get Surface object

Kind: instance method of Snelly

snelly.getVolume() ⇒ Volume

Get Volume object

Kind: instance method of Snelly

snelly.getUserTextureUnitStart() ⇒ number

Kind: instance method of Snelly
Returns: number - - the minimum texture unit for user supplied textures in the shader

Scene

Kind: global class

scene.init(snelly)

Optionally (but usually), provide this function to set scene and renderer initial state. This is called only once during execution, on loading the scene HTML page (or on global reset via 'R' key).

Kind: instance method of Scene

Param Type Description
snelly Snelly The snelly object

scene.initGenerator()

Optionally, provide this function which generates the init code to re-generate the current UI parameter settings. This will be dumped to the console (along with the rest of the UI state) on pressing key 'O', allowing the scene and renderer state to be tweaked in the UI then saved by copy-pasting code into the init function.

Kind: instance method of Scene

scene.envMap() ⇒ String

Optionally, supply an env-map texture URL (must be a lat-long format image). (If this is function not implemented, or it returns the empty string, a uniform temperature blackbody sky is used).

Kind: instance method of Scene

scene.getName() ⇒ String

Optional name (displayed in UI)

Kind: instance method of Scene

scene.getURL() ⇒ String

Optional clickable URL (displayed in UI)

Kind: instance method of Scene

scene.shader() ⇒ String

Returns a chunk of GLSL code defining the SDFs which determine the geometry of uber-surface, metal and dielectric materials in the scene. Define also (optionally) functions giving the 3d spatial dependence of the material parameters. This function is mandatory! The code must define at least one of the four functions:

     float SDF_SURFACE(vec3 X);
     float SDF_METAL(vec3 X);
     float SDF_DIELECTRIC(vec3 X);
     float SDF_VOLUME(vec3 X);

Only the SDFs which are defined will be rendered.

Optionally, any of the following functions defining the spatial dependence of material reflectances and roughnesses can be defined. The UI-exposed reflectance or roughness is supplied, and can be modified arbitrarily based on the supplied data of the primary ray hit point (and/or any other computed shader variables). The arguments to these functions are as follows:

  • refl_ui: The UI-exposed constant reflectance color ([0,1] floats in sRGB color space)
  • roughness_ui: The UI-exposed constant roughness
  • X: world space hit point
  • N: world space (outward) normal at the hit point
  • V: world space view direction at the hit point (i.e. direction from the hit point to the eye).

Note that the vec3 color returned is also in sRGB color space. (Any of these functions can be omitted, in which case they will be replaced with the default indicated).

        // return surface diffuse reflectance (defaults to just return the input UI constant refl_ui)
        vec3 SURFACE_DIFFUSE_REFLECTANCE(in vec3 refl_ui, in vec3 X, in vec3 N, in vec3 V);

        // return surface specular reflectance (defaults to just return the input UI constant refl_ui)
        vec3 SURFACE_SPECULAR_REFLECTANCE(in vec3 refl_ui, in vec3 X, in vec3 N, in vec3 V);

        // return surface roughness in [0,1] (defaults to just return the input roughness_ui)
        float SURFACE_ROUGHNESS(in float roughness_ui, in vec3 X, in vec3 N);

        // return local space normal (z is up), given world space X and world space unperturbed normal N
        vec3 SURFACE_NORMAL_MAP(in vec3 X, in vec3 N);

        // return world space surface displacement, given local tangent frame vectors
        vec3 SURFACE_DISPLACEMENT(in vec3 X, in vec3 N, in vec3 T, in vec3 B);

        // return metal roughness in [0,1] (defaults to just return the input UI constant roughness_ui)
        float METAL_ROUGHNESS(in float roughness_ui, in vec3 X, in vec3 N);

        // return metal specular reflectance (defaults to just return the input refl_ui)
        vec3 METAL_SPECULAR_REFLECTANCE(in vec3 refl_ui, in vec3 X, in vec3 N, in vec3 V);

        // return local space normal (z is up)
        vec3 METAL_NORMAL_MAP(in vec3 X);

        // return world space metal displacement, given local tangent frame vectors
        vec3 METAL_DISPLACEMENT(in vec3 X, in vec3 N, in vec3 T, in vec3 B);

        // return dielectric roughness in [0,1] (defaults to just return the input UI constant roughness_ui)
        float DIELECTRIC_ROUGHNESS(in float roughness_ui, in vec3 X, in vec3 N);

        // return dielectric specular reflectance (defaults to just return the input UI constant refl_ui)
        vec3 DIELECTRIC_SPECULAR_REFLECTANCE(in vec3 refl_ui, in vec3 X, in vec3 N, in vec3 V);

        // return local space normal (z is up)
        vec3 DIELECTRIC_NORMAL_MAP(in vec3 X);

        // return world space dielectric displacement, given local tangent frame vectors
        vec3 DIELECTRIC_DISPLACEMENT(in vec3 X, in vec3 N, in vec3 T, in vec3 B);

        // Volumetric emission field
        vec3 VOLUME_EMISSION(in vec3 emission_ui, in vec3 X);

Optionally, an init function can also be provided, which will be called first by each primary ray. This is occasionally useful to prepare global variables for use during the succeeding computation for this pixel.

    void INIT();

Kind: instance method of Scene

scene.initGui(gui)

Optional. Set up gui and callbacks for this scene

Kind: instance method of Scene

Param Type Description
gui GUI wrapper for dat.GUI object

scene.isReady(snelly) ⇒ boolean

Optional callack which, if implemented, the renderer consults before each frame to determine whether to render. This is needed if the scene has to do some pre-processing, or load something, before rendering is possible.

Kind: instance method of Scene
Returns: boolean - - whether the scene is ready to render

Param Type Description
snelly Snelly The snelly object

scene.syncShader(snelly, shader)

Optional. Called whenever the UI is changed, /* and must sync the params of the shader with the current UI settings

Kind: instance method of Scene

Param Type Description
snelly Snelly The snelly object
shader this.Shader wrapper of webGL fragment shader, see this.Shader

scene.getLengthScale() ⇒ number

Optional. Gives the raytracer some indication of the (rough) typical length scale of this scene, so it can set tolerances and defaults appropriately. Defaults to 1.0.

Kind: instance method of Scene

scene.getMinLengthScale() ⇒ number

Optional. Gives the raytracer some indication of the (rough) minimum length scale, so it can set tolerances appropriately. This sets the rough length scale of the smallest resolvable structure. (Note that decreasing this will usually lead to longer render times). Defaults to 0.0001 of the scene length scale.

Kind: instance method of Scene

scene.getMaxLengthScale() ⇒ number

Optional. Gives the raytracer some indication of the (rough) maximum length scale, so it can set tolerances appropriately. The raymarcher will march no further from the camera than this scale, thus it acts as the "far plane" distance. (Note that increasing this will usually lead to longer render times). Defaults to 100.0 of the scene length scale;

Kind: instance method of Scene

scene.preframeCallback(snelly, gl)

Optional callback before every frame. Animation rendering logic can be implemented here by updating the scene programmatically according to the global time since init.

Kind: instance method of Scene

Param Type Description
snelly Snelly The Snelly object
gl WebGLRenderingContext The webGL context

scene.postframeCallback(snelly, gl)

Optional callback after every frame. Animation rendering logic can be implemented here by updating the scene programmatically according to the global time since init.

Kind: instance method of Scene

Param Type Description
snelly Snelly The Snelly object
gl WebGLRenderingContext The webGL context

scene.onkeydownCallback(Javascript, snelly, gl)

Optional callback on key down.

Kind: instance method of Scene

Param Type Description
Javascript Event keydown Event
snelly Snelly The Snelly object
gl WebGLRenderingContext The webGL context

Renderer

Kind: global class
Properties

Name Type Default Description
width number (if not specified, fits to window)
height number (if not specified, fits to window)
[renderMode] String 'pt' rendering mode (either 'pt', 'ptsimple', 'ao', 'normals')
[dispersive] number false enable dispersive (i.e. spectral) rendering
[maxSamplesPerFrame] number 1 maximum number of per-pixel samples per frame
[maxSpp] number 1 maximum number of samples-per-pixel, after which the render terminates
[maxBounces] number 3 maximum number of surface bounces
[maxAtmosphereScatters] number 1 maximum number of scatters in atmosphere (1 -> single scattering only)
[maxMarchSteps] number 256 maximum number of raymarching steps per path segment
[maxStepsIsMiss] number true whether rays which exceed max step count are considered hits or misses
[maxSSSSteps] number 1 maximum number of scatters under surface if SSS enabled (via subsurfaceMFP > 0)
[interactive] number true if enabled, tries to maintain interactive frame rate at the expense of more noise
[goalFPS] number 10.0 sampling will adjust to try to match goal FPS
[minsSPPToRedraw] number 0.0 if >0.0, renderer will not redraw until the specified SPP have been accumulated
[radianceClamp] number 3.0 clamp radiance to (10^) this max value, for firefly reduction
[wavelengthSamples] number 256 number of samples to take over visible wavelength range
[exposure] number 0.0 exposure, on a log scale
[gamma] number 2.2 display gamma correction
[contrast] number 1.0 tonemapping contrast
[saturation] number 1.0 tonemapping saturation
[skyPower] number 4.0 sky power (arbitrary units)
[skyTemperature] number 6000 sky emission blackbody temperature (in Kelvin), used in dispersive mode only
[skyTintUp] Array sky color upwards tint
[skyTintDown] Array sky color downwards tint
[envMapVisible] number true whether env map is visible to primary rays (otherwise black)
[envMapPhiRotation] number 0.0 env map rotation about pole in degrees (0 to 360)
[envMapThetaRotation] number 0.0 env map rotation about equator in degrees (0 to 180)
[envMapTransitionAngle] number 0.0 angle over which env map tint transitions from upwards to downwards tint [degrees]
[sunPower] number 1.0 sun power (arbitrary units)
[sunColor] Array sun color
[sunAngularSize] number 5.0 sun angular size (degrees)
[sunLatitude] number 50.0 sun latitude (degrees)
[sunLongitude] number 0.0 sun longitude (degrees)
[sunVisibleDirectly] number true whether sun is directly visible
[sphereLightRadius] number 0.0 sphere light radius
[sphereLightPower] number sphere light power (arbitrary units)
[sphereLightPosition] Array whether sun is directly visible
[shadowStrength] number 1.0 if <1.0, areas in shadow are not completely dark (provided mostly to allow rendering of occluded areas, e.g. fractals)

new Renderer()

Interface to the renderer. The rendering modes available are:

  • 'pt': pathtracer (uni-directional)
  • 'ao': ambient occlusion, colored via Surface material diffuse albedo modulated by the SURFACE_DIFFUSE_REFLECTANCE shader function
  • 'normals': view normal at first hit as a color

renderer.focusAt

Kind: instance class of Renderer
Properties

Name Type Description
x number x coordinate of focus as a fraction of current frame width
y number y coordinate of focus as a fraction of current frame width

new Renderer.prototype.focusAt()

Adjust focal length to match the distance to the (first) object visible at a given location in the frame.

renderer.reset([no_recompile])

Restart accumulating samples.

Kind: instance method of Renderer

Param Type Default Description
[no_recompile] Boolean false set to true if shaders need recompilation too

renderer.getSPP() ⇒ number

Read access to the current per-pixel sample count average.

Kind: instance method of Renderer
Returns: number - - the current sample count average

Material

Kind: global class

new Material()

Generic material.

Surface ⇐ Material

Kind: global class
Extends: Material
Properties

Name Type Description
roughness number The surface roughness
ior number The surface coating ior
diffuseAlbedo Array The surface diffuse (RGB) color
specAlbedo Array The surface spec (RGB) color

new Surface()

Generic uber-surface material. Control via properties:

Example

surface.roughness = 0.05;
surface.ior = 1.3530655391120507;
surface.diffuseAlbedo = [0.5, 0.5, 0.5];
surface.specAlbedo = [0.0, 0.0, 0.0];

Volume ⇐ Material

Kind: global class
Extends: Material
Properties

Name Type Description
mfp number MFP in units of inverse scene scale (gives grey extinction as inverse MFP)
maxOpticalDepth number maximum optical depth (in any channel), used to bound attenuation to infinity
scatteringColor Array Scattering (RGB) color (multiplies grey extinction to give per-channel scattering coefficient)
absorptionColor Array The absorption (RGB) color (multiplies extinction to give per-channel absorption coefficient)
anisotropy number Phase function anisotropy in [-1,1]
emission number emission power magnitude
emissionColor Array emission color (multiplies emission to give per-channel emission)

new Volume()

Volumetric material (a homogeneous atmosphere, with heterogeneous emission). Control via properties:

Example

volume.mfp = 0.1;
volume.scatteringColor = [0.5, 0.5, 0.5];
volume.absorptionColor = [0.0, 0.5, 0.0];
volume.anisotropy = 0.0;
volume.emission = 0.0;
volume.emissionColor = [0.5, 0.5, 0.5];

Metal ⇐ Material

Kind: global class
Extends: Material
Properties

Name Type Description
roughness number The metal surface roughness

new Metal()

Generic metal material. Supported physical metals are:

 "Aluminium"
 "Brass"
 "Calcium"
 "Chromium"
 "Cobalt"
 "Copper" 
 "Gold"   
 "Iridium"
 "Iron" 
 "Lead"   
 "Mercury"
 "Molybdenum"
 "Nickel"
 "Palladium"
 "Platinum"
 "Silicon"
 "Silver"
 "Titanium"
 "Tungsten"
 "Vanadium"
 "Zinc"
 "Zirconium"

Example

let metal = materials.loadMetal('Gold');
metal.roughness = 0.05;

Dielectric ⇐ Material

Kind: global class
Extends: Material
Properties

Name Type Description
roughness number The dielectric surface roughness
absorptionColor array The dielectric surface absorption color
absorptionScale number The dielectric surface absorption scale (m.f.p in multiples of scene max scale)

new Dielectric()

Generic dielectric material. Supported physical dielectrics are:

 "Abbe dielectric"
 "Glass (BK7)"
 "Glass (K7)"
 "Glass (F5)"
 "Glass (LAFN7)"
 "Glass (LASF35)"
 "Glass (N-LAK33A)"
 "Glass (N-FK51A)"
 "Glass (SF4)"
 "Glass (SF67)"
 "Water"
 "Polycarbonate"
 "Glycerol"
 "Liquid Crystal (E7)"
 "Diamond"
 "Quartz"
 "Fused Silica"
 "Sapphire"
 "Sodium Chloride"
 "Proustite"
 "Rutile"
 "Silver Chloride"

Example

let dielectric = materials.loadDielectric('Diamond');
dielectric.absorptionColor = [1.0, 1.0, 1.0];
dielectric.absorptionScale = 1.0; // mfp in multiples of scene scale
dielectric.roughness = 0.030443974630021145;

Materials

Kind: global class

new Materials()

This object controls the properties of the three basic material types:

  • Dielectric (multiple different sub-types)
  • Metal (multiple different sub-types)
  • Surface (an uber-shader like materal)

materials.loadDielectric(dielectricName) ⇒ Dielectric

Load the desired Dielectric object by name. Supported dielectrics are:

 "Abbe dielectric"
 "Glass (BK7)"
 "Glass (K7)"
 "Glass (F5)"
 "Glass (LAFN7)"
 "Glass (LASF35)"
 "Glass (N-LAK33A)"
 "Glass (N-FK51A)"
 "Glass (SF4)"
 "Glass (SF67)"
 "Water"
 "Polycarbonate"
 "Glycerol"
 "Liquid Crystal (E7)"
 "Diamond"
 "Quartz"
 "Fused Silica"
 "Sapphire"
 "Sodium Chloride"
 "Proustite"
 "Rutile"
 "Silver Chloride"

Kind: instance method of Materials
Returns: Dielectric - - the loaded dielectric

Param Type Description
dielectricName String one of the names listed above

materials.getDielectric() ⇒ Dielectric

Get the currently loaded Dielectric object.

Kind: instance method of Materials

materials.loadMetal(metalName) ⇒ Metal

Load the desired Metal object by name. Supported metals are:

 "Aluminium"
 "Brass"
 "Calcium"
 "Chromium"
 "Cobalt"  
 "Copper"  
 "Gold"    
 "Iridium"
 "Iron"    
 "Lead"    
 "Mercury" 
 "Molybdenum"
 "Nickel"
 "Palladium"
 "Platinum"
 "Silicon"
 "Silver" 
 "Titanium"
 "Tungsten"
 "Vanadium"
 "Zinc" 
 "Zirconium"

Kind: instance method of Materials
Returns: Metal - - the loaded metal

Param Type Description
metalName String one of the names listed above

materials.getMetal() ⇒ Metal

Get the currently loaded Metal object.

Kind: instance method of Materials

materials.getSurface() ⇒ Surface

Get the Surface object.

Kind: instance method of Materials

materials.getVolume() ⇒ Surface

Get the Volume object.

Kind: instance method of Materials

GLU : object

Namespace for webGL utility wrappers. Functions for loading shader uniform variables are exposed to the user for convenience.

Kind: global namespace

GLU.this.Shader

Kind: static class of GLU

new this.Shader()

Represents a webGL vertex or fragment shader:

this.Shader.uniformI(name, i)

Provide an integer (via uniform1i) to the currently bound shader

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
i number The integer value

this.Shader.uniformF(name, f)

Provide a float (via uniform1f) to the currently bound shader

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
f number The float value

this.Shader.uniform2F(name, f1, f2)

Provide a vec2 uniform (via uniform2f) to the currently bound shader

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
f1 number The first float value
f2 number The second float value

this.Shader.uniform1Fv(name, fvec)

Provide an array of floats (via uniform1Fv) to the currently bound shader i.e. the shader declares e.g. uniform float values[19];

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
fvec Float32Array An array of floats

this.Shader.uniform2Fv(name, fvec2)

Provide an array of vec2 (via uniform2fv) to the currently bound shader i.e. the shader declares e.g. uniform vec2 vectors[19];

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
fvec2 Float32Array An array of floats, 2 per vector

this.Shader.uniform3F(name, f1, f2, f3)

Provide a vec3 uniform (via uniform3f) to the currently bound shader

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
f1 number The first float value
f2 number The second float value
f3 number The third float value

this.Shader.uniform3Fv(name, fvec3)

Provide an array of vec3 (via uniform3fv) to the currently bound shader i.e. the shader declares e.g. uniform vec3 vectors[19];

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
fvec3 Float32Array An array of floats, 3 per vector

this.Shader.uniform4F(name, f1, f2, f3, f4)

Provide a vec4 uniform (via uniform4F) to the currently bound shader

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
f1 number The first float value
f2 number The second float value
f3 number The third float value
f4 number The fourth float value

this.Shader.uniform4Fv(name, fvec4)

Provide an array of vec4 (via uniform4fv) to the currently bound shader i.e. the shader declares e.g. uniform vec4 vectors[19];

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
fvec4 Float32Array An array of floats, 4 per vector

this.Shader.uniformMatrix4fv(name, matrixArray16)

Provide a matrix (via uniformMatrix4fv) to the currently bound shader i.e. the shader declares e.g. uniform mat4 matrix;

Kind: static method of this.Shader

Param Type Description
name string The name of the uniform variable
matrixArray16 Float32Array An array of 16 floats