com.threed.jpct.util

Class ShadowHelper

java.lang.Object

com.threed.jpct.util.ShadowHelper

public class ShadowHelper
extends java.lang.Object

The ShadowHelper class eases shadow mapping. While shadow mapping in jPCT-AE is possible without this helper class, you have to have a good knowledge of how shadow mapping works in practice to implement it yourself using the methods that jPCT-AE is offering for it.
To simplify shadow mapping, this helper exists and it should be sufficient for most shadow applications.
jPCT-AE uses a shader based approach for shadow mapping, so it needs a GL content in OpenGL ES 2.0+ mode to work.
The ShadowHelper relies on the GLSLShadowInjector class to modify shaders for shadow mapping on the fly. If you are using it on objects that use custom shaders, please refer to the documation of that class to see how to deal with this.

See Also:

GLSLShadowInjector

Constructor Summary

Constructors

Constructor and Description
ShadowHelper(FrameBuffer buffer, Projector lightSource, int maxSize) Creates a new shadow helper.
ShadowHelper(FrameBuffer buffer, Projector lightSource, int maxSize, float bias) Creates a new shadow helper.

Method Summary

Modifier and Type	Method and Description
void	addCaster(Object3D obj) Adds a caster.
void	addReceiver(Object3D obj) Adds a receiver.
int	getCasterCount() Gets the number of casters in the helper.
float	getEdgeSize() Returns the relative edge size used, if edge smoothing is enabled.
int	getFilterSize() Returns the size of the filter kernel used, if PCF is enabled.
Projector	getLightSource() Returns the light source.
int	getReceiverCount() Gets the number of receivers in the helper.
Texture	getShadowMap() Returns the shadow map's texture.
static int	getShadowMode() Returns the shadow mode.
boolean	isAutoAdjustFov() Returns if the fov will be adjusted automatically or not.
void	removeCaster(Object3D caster) Removes a caster.
static void	resetTextureCounter() Resets the texture counter.
void	setAdditionalColorMode(boolean disabled) Sets how an objects additional color will be treated.
void	setAmbientLight(RGBColor col) Sets the ambient lighting used during the shadow pass.
void	setAutoAdjustFov(boolean autoAdjustFov) If enabled, the fov will be adjusted to the near plane of the projector to avoid the "zoom-in" effect that this will otherwise have.
void	setBorder(int width) Sets a border around the actual shadow map to prevent the shadows from bleeding into parts of the scene that are not covered by the projector's view.
void	setCullingMode(boolean inverted) Sets the culling mode.
void	setEdgeSize(float edgeSize) Sets the relative edge size used, if edge smoothing is enabled.
void	setFilterSize(int filterSize) Sets the size of the filter kernel used, if PCF is enabled.
void	setLightMode(boolean disabled) Sets the lighting mode.
void	setLightSource(Projector projector) Sets the light source to another one.
static void	setShadowMode(int shadowMode) Sets the shadow mode.This method is static and it's actually a short cut to the method with the same name in GLSLShadowInjector.
void	updateShadowMap(FrameBuffer buffer, World world) Updates the shadow map.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ShadowHelper

public ShadowHelper(FrameBuffer buffer,
                    Projector lightSource,
                    int maxSize)

Creates a new shadow helper.

Parameters:

buffer - the framebuffer into which will be rendered

lightSource - the light source that casts the shadows

maxSize - the maximum size of the shadow map. The actual resolution might be lower if the hardware doesn't support this size. Has to be a power of 2.

ShadowHelper

public ShadowHelper(FrameBuffer buffer,
                    Projector lightSource,
                    int maxSize,
                    float bias)

Creates a new shadow helper.

Parameters:

buffer - the framebuffer into which will be rendered

lightSource - the light source that casts the shadows

maxSize - the maximum size of the shadow map. The actual resolution might be lower if the hardware doesn't support this size. Has to be a power of 2.

bias - the offset of the depth to prevent shadow acne. Default is 0.008f.

Method Detail

addCaster

public void addCaster(Object3D obj)

Adds a caster. A caster is an object that casts shadows. It doesn't necessarily receives them.

Parameters:

obj - the new caster

addReceiver

public void addReceiver(Object3D obj)

Adds a receiver. A receiver is an object that is affected by the shadows. It doesn't necessarily casts them. Making an object a receiver makes it use an additional texture stage. If the number of stages that an objects uses exceeds the number that the underlying hardware supports, shadows won't work on that object.
Once an object has been added, it can't be removed, i.e. you can't "deshadow" it.
If your objects use their own implementation of the IRenderHook interface, make sure that it has been assigned before calling this method. Also, don't change it after calling this method or your shadows will break.

Parameters:

obj - the receiver

resetTextureCounter

public static void resetTextureCounter()

Resets the texture counter. The ShadowHelper creates additional textures for the depth maps. If no ShadowHelpers are referenced anymore by an application, this method can be used to reset the counter, so that the next texture will get the initial id. This may help to save some memory in the TextureManager.

getLightSource

public Projector getLightSource()

Returns the light source.

Returns:

the light source

setLightSource

public void setLightSource(Projector projector)

Sets the light source to another one.

Parameters:

lightSource - the new source

setBorder

public void setBorder(int width)

Sets a border around the actual shadow map to prevent the shadows from bleeding into parts of the scene that are not covered by the projector's view. Default is 1.

Parameters:

width -

setCullingMode

public void setCullingMode(boolean inverted)

Sets the culling mode. If set to true (which is default), the culling will be inverted when rendering the depth map. If set to false, it won't.

Parameters:

inverted - should it be inverted?

setLightMode

public void setLightMode(boolean disabled)

Sets the lighting mode. If set to true (i.e. disabled), all lights but the ambient lights will be disabled when doing the shadow pass of the calculation.
Setting this to false will work only in combination with normal shadows. It's not support by either edge smoothing shadows or PCF shadows.

Parameters:

disabled - should the light be disabled during shadow pass? Default is true.

setAdditionalColorMode

public void setAdditionalColorMode(boolean disabled)

Sets how an objects additional color will be treated. If set to true, it will be ignored when rendering the shadows. Otherwise, it will be taken into account.

Parameters:

disabled - should the additional color be disabled during shadow pass? Default is true.

setAmbientLight

public void setAmbientLight(RGBColor col)

Sets the ambient lighting used during the shadow pass.

Parameters:

col - the color of the light source. Default is 60,60,60

getReceiverCount

public int getReceiverCount()

Gets the number of receivers in the helper.

Returns:

the number

getCasterCount

public int getCasterCount()

Gets the number of casters in the helper.

Returns:

the number

removeCaster

public void removeCaster(Object3D caster)

Removes a caster. It won't be removed from the world or something, it just doesn't cast shadows any longer.

Parameters:

caster - the caster to remove

getShadowMap

public Texture getShadowMap()

Returns the shadow map's texture. In normal apps, you shouldn't need this.

Returns:

the texture

updateShadowMap

public void updateShadowMap(FrameBuffer buffer,
                            World world)

Updates the shadow map. This is needed if either the light source or the objects in the scene have moved.

Parameters:

buffer - the current FrameBuffer

world - the world instance that contains the objects that should cast shadows

isAutoAdjustFov

public boolean isAutoAdjustFov()

Returns if the fov will be adjusted automatically or not.

Returns:

setAutoAdjustFov

public void setAutoAdjustFov(boolean autoAdjustFov)

If enabled, the fov will be adjusted to the near plane of the projector to avoid the "zoom-in" effect that this will otherwise have.
However, that effect can increase depth accuracy at the cost of a more narrow fov, so one might actually want it. Default is false.

Parameters:

autoAdjustFov - should it be adjusted?

getShadowMode

public static int getShadowMode()

Returns the shadow mode. This method is static and it's actually a short cut to the method with the same name in GLSLShadowInjector.

Returns:

the current shadow mode as defined by the constants in GLSLShadowInjector

See Also:

GLSLShadowInjector.getShadowMode(), GLSLShadowInjector.NORMAL_SHADOWS, GLSLShadowInjector.NORMAL_SHADOWS_WITH_EDGE_SMOOTHING, GLSLShadowInjector.PCF_FILTERED_SHADOWS, GLSLShadowInjector.PCF_FILTERED_SHADOWS_WITH_EDGE_SMOOTHING

setShadowMode

public static void setShadowMode(int shadowMode)

Sets the shadow mode.This method is static and it's actually a short cut to the method with the same name in GLSLShadowInjector.

Parameters:

shadowMode - the shadow mode as defined by the constants in GLSLShadowInjector

See Also:

GLSLShadowInjector.setShadowMode(int), GLSLShadowInjector.NORMAL_SHADOWS, GLSLShadowInjector.NORMAL_SHADOWS_WITH_EDGE_SMOOTHING, GLSLShadowInjector.PCF_FILTERED_SHADOWS, GLSLShadowInjector.PCF_FILTERED_SHADOWS_WITH_EDGE_SMOOTHING

getEdgeSize

public float getEdgeSize()

Returns the relative edge size used, if edge smoothing is enabled. Default is 0.1f.

Returns:

the edge size

setEdgeSize

public void setEdgeSize(float edgeSize)

Sets the relative edge size used, if edge smoothing is enabled. This value defined the width (and height) of the section that will be effected by the smoothing.

Parameters:

edgeSize - the size

getFilterSize

public int getFilterSize()

Returns the size of the filter kernel used, if PCF is enabled. This value defines the pixel offset in each direction, i.e. 1 means from -1 to 1 in both direction, i.e. 9 samples. 2 means 25 samples and so on. Higher values give better filtering, but are much slower.

Returns:

the size, default is 1

setFilterSize

public void setFilterSize(int filterSize)

Sets the size of the filter kernel used, if PCF is enabled. This value defines the pixel offset in each direction, i.e. 1 means from -1 to 1 in both direction, i.e. 9 samples. 2 means 25 samples and so on. Higher values give better filtering, but are much slower.

Parameters:

filterSize - the size