Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD