com.threed.jpct.util
Class ShadowHelper

java.lang.Object
  com.threed.jpct.util.ShadowHelper

All Implemented Interfaces:

java.io.Serializable

public class ShadowHelper

extends java.lang.Object

implements java.io.Serializable

The ShadowHelper-class eases shadow mapping. While shadow mapping in jPCT 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 is offering for it.
To simplify shadow mapping, this helper exists and it should be sufficient for most shadow applications.
jPCT uses a fixed function approach with depth textures for shadow mapping. It is advised to initialize this class after enabling the OpenGL renderer when render-to-texture should be done by using FBOs because otherwise, it's not known if the hardware actually supports it and the helper has to rely on the setting in Config alone. The software renderer doesn't support shadow mapping. It will only cost you performance for no visual benefit when using this class on a software rendered scene.

See Also:

Config.glShadowZBias, Config.glUseFBO, Serialized Form

Constructor Summary

ShadowHelper(World world, FrameBuffer buffer, Projector lightSource, int maxSize)
Creates a new shadow helper.

Method Summary

void	addCaster(Object3D caster) Adds a caster.
void	addReceiver(Object3D rec) Adds a receiver.
void	dispose() Disposes the helper.
void	drawScene() Draws the scene using the most current shadow map.
void	drawScene(boolean complete) Draws the scene using the most current shadow map.
void	finalize()
int	getCasterCount() Gets the number of casters in the helper.
Projector	getLightSource() Returns the directional light source.
int	getReceiverCount() Gets the number of receivers in the helper.
Texture	getShadowMap() Returns the shadow map's texture.
boolean	isInitialized() Returns true, if the helper has been correctly initialized.
boolean	isRenderingShadowMap() Returns true if, at the time of the call, the helper is working on the shadow map itself.
boolean	isRenderingShadowPass() Returns true if, at the time of the call, the helper is doing the shadow pass.
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(java.awt.Color col) Sets the ambient lighting used during the shadow pass.
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	setFiltering(boolean pcf) Enabled percentage closer filtering on the shadow edges.
void	setFrameBuffer(FrameBuffer buffer) Sets a new FrameBuffer.
void	setLightMode(boolean disabled) Sets the lighting mode.
void	setLightSource(Projector lightSource) Sets the directional light source to another one.
void	setRevertMode(boolean mode) If enabled, every MODE_ADD texture operation will be reverted to a MODE_MODULATE when doing the shadow pass.
void	updateShadowMap() Updates the shadow map as seen from the directional light source.

Methods inherited from class java.lang.Object

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

Constructor Detail

ShadowHelper

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

Creates a new shadow helper.

Parameters:

world - the world that includes the objects to be shadowed

buffer - the framebuffer into which the world will be rendered

lightSource - the directional light source that casts the shadows

maxSize - the maximum size of the shadow map. This isn't necessarily the used size but an upper bound for it.

Method Detail

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 directional light source.

Returns:

the light source

setLightSource

public void setLightSource(Projector lightSource)

Sets the directional 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 -

setFrameBuffer

public void setFrameBuffer(FrameBuffer buffer)

Sets a new FrameBuffer. There should be no need to call this method in a normal application.

Parameters:

buffer - the new FrameBuffer

setRevertMode

public void setRevertMode(boolean mode)

If enabled, every MODE_ADD texture operation will be reverted to a MODE_MODULATE when doing the shadow pass. Default is true.

Parameters:

mode - the mode

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?

setFiltering

public void setFiltering(boolean pcf)

Enabled percentage closer filtering on the shadow edges. Default is false. This can lead to small artifacts on some hardware but usually looks better if supported.

Parameters:

pcf - should we use it?

addReceiver

public void addReceiver(Object3D rec)

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.

Parameters:

rec - the receiver

isInitialized

public boolean isInitialized()

Returns true, if the helper has been correctly initialized.

Returns:

has it?

addCaster

public void addCaster(Object3D caster)

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

Parameters:

caster - the new caster

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

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.

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 set back to black when rendering the shadows. Otherwise, it won't be touched.

Parameters:

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

setAmbientLight

public void setAmbientLight(java.awt.Color col)

Sets the ambient lighting used during the shadow pass.

Parameters:

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

drawScene

public void drawScene()

Draws the scene using the most current shadow map. This is equivalent to a call to the renderScene()/draw() combination in the normal game loop, which can be omitted when calling this method instead.

drawScene

public void drawScene(boolean complete)

Draws the scene using the most current shadow map. This is equivalent to a call to the renderScene()/draw() combination in the normal game loop, which can be omitted when calling this method instead.

Parameters:

complete - if true, everything is rendered. If its false, the last call to draw() will be omitted (in case you want to do something else before making it).

isRenderingShadowMap

public boolean isRenderingShadowMap()

Returns true if, at the time of the call, the helper is working on the shadow map itself. Beware that this value refers to the method-call, not to the actual rendering, which may happen at another time when using a multi-threaded renderer.

Returns:

does it render into the map right now?

isRenderingShadowPass

public boolean isRenderingShadowPass()

Returns true if, at the time of the call, the helper is doing the shadow pass. Beware that this value refers to the method-call, not to the actual rendering, which may happen at another time when using a multi-threaded renderer.

Returns:

does it render the dark parts right now?

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

getShadowMap

public Texture getShadowMap()

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

Returns:

the texture

updateShadowMap

public void updateShadowMap()

Updates the shadow map as seen from the directional light source. Depending on the application and the use of shadows (and the performance), it may be necessary to call this every frame or just once.

dispose

public void dispose()

Disposes the helper. The used resources will be freed, the helper isn't usable after this.

finalize

public void finalize()