Package org.sunflow.core

# Class ShadingState

java.lang.Object
org.sunflow.core.ShadingState

All Implemented Interfaces:
  `Iterable<LightSample>`

public final class ShadingState extends Object implements Iterable<LightSample>
Represents a point to be shaded and provides various options for the shading of this point, including spawning of new rays.

## Method Summary

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

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Method Details

### init

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

### shade

public final Color shade()
Run the shader at this surface point.

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.

### 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

### getCosND

public final float getCosND()
Cosine between the shading normal and the ray. This is set by `faceforward()`.

Returns:
  cosine between shading normal and the ray

### isBehind

public final boolean isBehind()
Returns true if the ray hit the surface from behind. This is set by `faceforward()`.

Returns:
  `true` if the surface was hit from behind.

### getU

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

Returns:
  u barycentric coordinate

### getV

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

Returns:
  v barycentric coordinate

### getW

public final float getW()
Get w barycentric coordinate of the intersection point.

Returns:
  w barycentric coordinate

### getInstance

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

Returns:
  intersected instance object

### getPrimitiveID

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

Returns:
  intersected primitive ID

### transformObjectToWorld

public Point3 transformObjectToWorld(Point3 p)
Transform the given point from object space to world space. A new `Point3` object is returned.

Parameters:
  `p` - object space position to transform
Returns:
  transformed position

### transformWorldToObject

public Point3 transformWorldToObject(Point3 p)
Transform the given point from world space to object space. A new `Point3` object is returned.

Parameters:
  `p` - world space position to transform
Returns:
  transformed position

### transformNormalObjectToWorld

public Vector3 transformNormalObjectToWorld(Vector3 n)
Transform the given normal from object space to world space. A new `Vector3` object is returned.

Parameters:
  `n` - object space normal to transform
Returns:
  transformed normal

### transformNormalWorldToObject

public Vector3 transformNormalWorldToObject(Vector3 n)
Transform the given normal from world space to object space. A new `Vector3` object is returned.

Parameters:
  `n` - world space normal to transform
Returns:
  transformed normal

### transformVectorObjectToWorld

public Vector3 transformVectorObjectToWorld(Vector3 v)
Transform the given vector from object space to world space. A new `Vector3` object is returned.

Parameters:
  `v` - object space vector to transform
Returns:
  transformed vector

### transformVectorWorldToObject

public Vector3 transformVectorWorldToObject(Vector3 v)
Transform the given vector from world space to object space. A new `Vector3` object is returned.

Parameters:
  `v` - world space vector to transform
Returns:
  transformed vector

### getResult

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

Returns:
  shaded result

### 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

### 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)

### 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

### getShader

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

Returns:
  shader to be used

### 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

### 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

### 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

### 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

### getPoint

public final Point3 getPoint()
Get hit point.

Returns:
  hit point

### getNormal

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

Returns:
  shading normal

### getUV

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

Returns:
  texture coordinate

### getGeoNormal

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

Returns:
  geometric normal of the current hit point

### getBasis

public final OrthoNormalBasis getBasis()
Gets the local orthonormal basis for the current hit point.

Returns:
  local basis or `null` if undefined

### setBasis

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

Parameters:
  `basis` -

### getRay

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

Returns:
  ray associated with this state.

### getCameraToWorld

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

Returns:
  camera to world transform

### getWorldToCamera

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

Returns:
  world to camera transform

### 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, `false`otherwise

### initLightSamples

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

### initCausticSamples

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

### 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.

### 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.

### 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

### 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

### 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

### 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

### 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

### 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

### getGlobalRadiance

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

Returns:
  global diffuse radiance estimate

### 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

### 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

### 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

### 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

### 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

### iterator

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

Specified by:
  `iterator` in interface `Iterable<LightSample>`

### getShadowDepth

public final int getShadowDepth()

### traceTransparentShadow

public Color traceTransparentShadow(float oldMaxT)