org.sunflow.core

Class ShadingState

Implemented Interfaces:
Iterable

public final class ShadingState
extends java.lang.Object
implements Iterable

Represents a point to be shaded and provides various options for the shading of this point, including spawning of new rays.

Method Summary

void
addSample(LightSample sample)
Add the specified light sample to the list of lights to be used
Color
diffuse(Color diff)
Computes a plain diffuse response to the current light samples and global illumination.
void
faceforward()
Flip the surface normals to ensure they are facing the current ray.
OrthoNormalBasis
getBasis()
Gets the local orthonormal basis for the current hit point.
Matrix4
getCameraToWorld()
Get a transformation matrix that will transform camera space points into world space.
float
getCosND()
Cosine between the shading normal and the ray.
int
getDepth()
Get the current total tracing depth.
int
getDiffuseDepth()
Get the current diffuse tracing depth.
Vector3
getGeoNormal()
Gets the geometric normal of the current hit point.
Color
getGlobalRadiance()
Returns the glboal diffuse radiance estimate given by the current GIEngine if present.
Instance
getInstance()
Get the instance which was intersected
Color
getIrradiance(Color diffuseReflectance)
Gets the total irradiance reaching the current point from diffuse surfaces.
Vector3
getNormal()
Get shading normal at the hit point.
Point3
getPoint()
Get hit point.
int
getPrimitiveID()
Get the primitive ID which was intersected
double
getRandom(int j, int dim)
Get a QMC sample from an infinite sequence.
double
getRandom(int j, int dim, int n)
Get a QMC sample from a finite sequence of n elements.
float
getRasterX()
Get x coordinate of the pixel being shaded.
float
getRasterY()
Get y coordinate of the pixel being shaded.
Ray
getRay()
Gets the ray that is associated with this state.
int
getReflectionDepth()
Get the current reflection tracing depth.
int
getRefractionDepth()
Get the current refraction tracing depth.
Color
getResult()
Get the result of shading this point
Shader
getShader()
Get the shader to be used to shade this surface.
boolean
getTrianglePoints(Point3[] p)
Get the three triangle corners in object space if the hit object is a mesh, returns false otherwise.
float
getU()
Get u barycentric coordinate of the intersection point.
Point2
getUV()
Get texture coordinates at the hit point.
float
getV()
Get v barycentric coordinate of the intersection point.
Matrix4
getWorldToCamera()
Get a transformation matrix that will transform world space points into camera space.
boolean
includeLights()
Checks to see if the shader should include emitted light.
boolean
includeSpecular()
Checks to see if the shader should include specular terms.
void
init()
Create objects needed for surface shading: point, normal, texture coordinates and basis.
void
initCausticSamples()
Add caustic samples to the current light sample set.
void
initLightSamples()
Initialize the use of light samples.
boolean
isBehind()
Returns true if the ray hit the surface from behind.
Iterator
iterator()
Allows iteration over current light samples.
Color
occlusion(int samples, float maxDist)
Simple black and white ambient occlusion.
Color
occlusion(int samples, float maxDist, Color bright, Color dark)
Ambient occlusion routine, returns a value between bright and dark depending on the amount of geometric occlusion in the scene.
void
setBasis(OrthoNormalBasis basis)
Define the orthonormal basis for the current hit point.
void
setModifier(Modifier modifier)
Record which modifier should be applied to the intersected surface
void
setShader(Shader shader)
Record which shader should be executed for the intersected surface.
Color
shade()
Run the shader at this surface point.
Color
specularPhong(Color spec, float power, int numRays)
Computes a phong specular response to the current light samples and global illumination.
void
storePhoton(Vector3 dir, Color power, Color diffuse)
Records a photon at the specified location.
void
traceDiffusePhoton(Ray r, Color power)
Trace a new photon from the current location.
ShadingState
traceFinalGather(Ray r, int i)
Trace a final gather ray and return the intersection result as a new render state
Color
traceGlossy(Ray r, int i)
Returns the color obtained by recursively tracing the specified ray.
Color
traceReflection(Ray r, int i)
Returns the color obtained by recursively tracing the specified ray.
void
traceReflectionPhoton(Ray r, Color power)
Trace a new photon from the current location.
Color
traceRefraction(Ray r, int i)
Returns the color obtained by recursively tracing the specified ray.
void
traceRefractionPhoton(Ray r, Color power)
Trace a new photon from the current location.
Color
traceShadow(Ray r)
Trace a shadow ray against the scene, and computes the accumulated opacity along the ray.
Color
traceTransparency()
Trace transparency, this is equivalent to tracing a refraction ray in the incoming ray direction.

Method Details

addSample

public final void addSample(LightSample sample)
Add the specified light sample to the list of lights to be used
Parameters:
sample - a valid light sample

diffuse

public final Color diffuse(Color diff)
Computes a plain diffuse response to the current light samples and global illumination.
Parameters:
diff - diffuse color
Returns:
shaded result

faceforward

public final void faceforward()
Flip the surface normals to ensure they are facing the current ray. This method also offsets the shading point away from the surface so that new rays will not intersect the same surface again by mistake.

getBasis

public final OrthoNormalBasis getBasis()
Gets the local orthonormal basis for the current hit point.
Returns:
local basis or null if undefined

getCameraToWorld

public final Matrix4 getCameraToWorld()
Get a transformation matrix that will transform camera space points into world space.
Returns:
camera to world transform

getCosND

public final float getCosND()
Returns:
cosine between shading normal and the ray

getDepth

public final int getDepth()
Get the current total tracing depth. First generation rays have a depth of 0.
Returns:
current tracing depth

getDiffuseDepth

public final int getDiffuseDepth()
Get the current diffuse tracing depth. This is the number of diffuse surfaces reflected from.
Returns:
current diffuse tracing depth

getGeoNormal

public final Vector3 getGeoNormal()
Gets the geometric normal of the current hit point.
Returns:
geometric normal of the current hit point

getGlobalRadiance

public final Color getGlobalRadiance()
Returns the glboal diffuse radiance estimate given by the current GIEngine if present.
Returns:
global diffuse radiance estimate

getInstance

public final Instance getInstance()
Get the instance which was intersected
Returns:
intersected instance object

getIrradiance

public final Color getIrradiance(Color diffuseReflectance)
Gets the total irradiance reaching the current point from diffuse surfaces.
Parameters:
diffuseReflectance - diffuse reflectance at the current point, can be used for importance tracking
Returns:
indirect diffuse irradiance reaching the point

getNormal

public final Vector3 getNormal()
Get shading normal at the hit point. This may differ from the geometric normal
Returns:
shading normal

getPoint

public final Point3 getPoint()
Get hit point.
Returns:
hit point

getPrimitiveID

public final int getPrimitiveID()
Get the primitive ID which was intersected
Returns:
intersected primitive ID

getRandom

public final double getRandom(int j,
                              int dim)
Get a QMC sample from an infinite sequence.
Parameters:
j - sample number (starts from 0)
dim - dimension to sample
Returns:
pseudo-random value in [0,1)

getRandom

public final double getRandom(int j,
                              int dim,
                              int n)
Get a QMC sample from a finite sequence of n elements. This provides better stratification than the infinite version, but does not allow for adaptive sampling.
Parameters:
j - sample number (starts from 0)
dim - dimension to sample
n - number of samples
Returns:
pseudo-random value in [0,1)

getRasterX

public final float getRasterX()
Get x coordinate of the pixel being shaded.
Returns:
pixel x coordinate

getRasterY

public final float getRasterY()
Get y coordinate of the pixel being shaded.
Returns:
pixel y coordinate

getRay

public final Ray getRay()
Gets the ray that is associated with this state.
Returns:
ray associated with this state.

getReflectionDepth

public final int getReflectionDepth()
Get the current reflection tracing depth. This is the number of specular surfaces reflected from.
Returns:
current reflection tracing depth

getRefractionDepth

public final int getRefractionDepth()
Get the current refraction tracing depth. This is the number of specular surfaces refracted from.
Returns:
current refraction tracing depth

getResult

public final Color getResult()
Get the result of shading this point
Returns:
shaded result

getShader

public final Shader getShader()
Get the shader to be used to shade this surface.
Returns:
shader to be used

getTrianglePoints

public final boolean getTrianglePoints(Point3[] p)
Get the three triangle corners in object space if the hit object is a mesh, returns false otherwise.
Parameters:
p - array of 3 points
Returns:
true if the points were read succesfully, falseotherwise

getU

public final float getU()
Get u barycentric coordinate of the intersection point.
Returns:
u barycentric coordinate

getUV

public final Point2 getUV()
Get texture coordinates at the hit point.
Returns:
texture coordinate

getV

public final float getV()
Get v barycentric coordinate of the intersection point.
Returns:
v barycentric coordinate

getWorldToCamera

public final Matrix4 getWorldToCamera()
Get a transformation matrix that will transform world space points into camera space.
Returns:
world to camera transform

includeLights

public final boolean includeLights()
Checks to see if the shader should include emitted light.
Returns:
true if emitted light should be included, false otherwise

includeSpecular

public final boolean includeSpecular()
Checks to see if the shader should include specular terms.
Returns:
true if specular terms should be included, false otherwise

init

public final void init()
Create objects needed for surface shading: point, normal, texture coordinates and basis.

initCausticSamples

public final void initCausticSamples()
Add caustic samples to the current light sample set. This method does nothing if caustics are not enabled.

initLightSamples

public final void initLightSamples()
Initialize the use of light samples. Prepares a list of visible lights from the current point.

isBehind

public final boolean isBehind()
Returns:
true if the surface was hit from behind.

iterator

public Iterator iterator()
Allows iteration over current light samples.

occlusion

public final Color occlusion(int samples,
                             float maxDist)
Simple black and white ambient occlusion.
Parameters:
samples - number of sample rays
maxDist - maximum length of the rays
Returns:
occlusion color

occlusion

public final Color occlusion(int samples,
                             float maxDist,
                             Color bright,
                             Color dark)
Ambient occlusion routine, returns a value between bright and dark depending on the amount of geometric occlusion in the scene.
Parameters:
samples - number of sample rays
maxDist - maximum length of the rays
bright - color when nothing is occluded
dark - color when fully occluded
Returns:
occlusion color

setBasis

public final void setBasis(OrthoNormalBasis basis)
Define the orthonormal basis for the current hit point.
Parameters:
basis -

setModifier

public final void setModifier(Modifier modifier)
Record which modifier should be applied to the intersected surface
Parameters:
modifier - modifier to use the change this shading state

setShader

public final void setShader(Shader shader)
Record which shader should be executed for the intersected surface.
Parameters:
shader - surface shader to use to shade the current intersection point

shade

public final Color shade()
Run the shader at this surface point.
Returns:
shaded result

specularPhong

public final Color specularPhong(Color spec,
                                 float power,
                                 int numRays)
Computes a phong specular response to the current light samples and global illumination.
Parameters:
spec - specular color
power - phong exponent
numRays - number of glossy rays to trace
Returns:
shaded color

storePhoton

public final void storePhoton(Vector3 dir,
                              Color power,
                              Color diffuse)
Records a photon at the specified location.
Parameters:
dir - incoming direction of the photon
power - photon power
diffuse - diffuse reflectance at the given point

traceDiffusePhoton

public final void traceDiffusePhoton(Ray r,
                                     Color power)
Trace a new photon from the current location. This assumes that the photon was reflected by a diffuse surface.
Parameters:
r - ray to trace photon along
power - power of the new photon

traceFinalGather

public final ShadingState traceFinalGather(Ray r,
                                           int i)
Trace a final gather ray and return the intersection result as a new render state
Parameters:
r - ray to shoot
i - instance of the ray
Returns:
new render state object corresponding to the intersection result

traceGlossy

public final Color traceGlossy(Ray r,
                               int i)
Returns the color obtained by recursively tracing the specified ray. The reflection is assumed to be glossy.
Parameters:
r - ray to trace
i - instance number of this sample
Returns:
color observed along specified ray.

traceReflection

public final Color traceReflection(Ray r,
                                   int i)
Returns the color obtained by recursively tracing the specified ray. The reflection is assumed to be specular.
Parameters:
r - ray to trace
i - instance number of this sample
Returns:
color observed along specified ray.

traceReflectionPhoton

public final void traceReflectionPhoton(Ray r,
                                        Color power)
Trace a new photon from the current location. This assumes that the photon was reflected by a specular surface.
Parameters:
r - ray to trace photon along
power - power of the new photon

traceRefraction

public final Color traceRefraction(Ray r,
                                   int i)
Returns the color obtained by recursively tracing the specified ray.
Parameters:
r - ray to trace
i - instance number of this sample
Returns:
color observed along specified ray.

traceRefractionPhoton

public final void traceRefractionPhoton(Ray r,
                                        Color power)
Trace a new photon from the current location. This assumes that the photon was refracted by a specular surface.
Parameters:
r - ray to trace photon along
power - power of the new photon

traceShadow

public final Color traceShadow(Ray r)
Trace a shadow ray against the scene, and computes the accumulated opacity along the ray.
Parameters:
r - ray to trace
Returns:
opacity along the shadow ray

traceTransparency

public final Color traceTransparency()
Trace transparency, this is equivalent to tracing a refraction ray in the incoming ray direction.
Returns:
color observed behind the current shading point