com.threed.jpct.util
Class ShadowHelper

java.lang.Object
  extended by 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
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
 void addCaster(Object3D obj)
          Adds a caster.
 void addReceiver(Object3D obj)
          Adds a receiver.
 void blit(FrameBuffer buffer)
           
 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

blit

public void blit(FrameBuffer buffer)

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