Package com.jme3.shadow

Class AbstractShadowRenderer

java.lang.Object
com.jme3.shadow.AbstractShadowRenderer
All Implemented Interfaces:
Savable, SceneProcessor, JmeCloneable, Cloneable
Direct Known Subclasses:
DirectionalLightShadowRenderer, PointLightShadowRenderer, SpotLightShadowRenderer
public abstract class AbstractShadowRenderer extends Object implements SceneProcessor, Savable, JmeCloneable
An abstract shadow renderer that provides common features for shadow rendering.

  • Field Details

    • logger

      protected static final Logger logger

    • nbShadowMaps

      protected int nbShadowMaps

    • shadowMapSize

      protected float shadowMapSize

    • shadowIntensity

      protected float shadowIntensity

    • renderManager

      protected RenderManager renderManager

    • viewPort

      protected ViewPort viewPort

    • shadowFB

      protected FrameBuffer[] shadowFB

    • shadowMaps

      protected Texture2D[] shadowMaps

    • dummyTex

      protected Texture2D dummyTex

    • preshadowMat

      protected Material preshadowMat

    • postshadowMat

      protected Material postshadowMat

    • lightViewProjectionsMatrices

      protected Matrix4f[] lightViewProjectionsMatrices

    • assetManager

      protected AssetManager assetManager

    • debug

      protected boolean debug

    • edgesThickness

      protected float edgesThickness

    • edgeFilteringMode

      protected EdgeFilteringMode edgeFilteringMode

    • shadowCompareMode

      protected CompareMode shadowCompareMode

    • dispPic

      protected Picture[] dispPic

    • forcedRenderState

      protected RenderState forcedRenderState

    • renderBackFacesShadows

      protected boolean renderBackFacesShadows

    • prof

      protected AppProfiler prof

    • debugfrustums

      protected boolean debugfrustums

    • needsfallBackMaterial

      protected boolean needsfallBackMaterial

    • postTechniqueName

      protected String postTechniqueName

    • matCache

      protected List<Material> matCache

    • lightReceivers

      protected GeometryList lightReceivers

    • shadowMapOccluders

      protected GeometryList shadowMapOccluders

    • zFarOverride

      protected float zFarOverride

    • fadeInfo

      protected Vector2f fadeInfo

    • fadeLength

      protected float fadeLength

    • frustumCam

      protected Camera frustumCam

    • skipPostPass

      protected boolean skipPostPass

  • Constructor Details

    • AbstractShadowRenderer

      protected AbstractShadowRenderer()
      For serialization only. Do not use.

    • AbstractShadowRenderer

      protected AbstractShadowRenderer(AssetManager assetManager, int shadowMapSize, int nbShadowMaps)
      Creates an AbstractShadowRenderer. Subclasses invoke this constructor.
      Parameters:
      assetManager - The application's asset manager.
      shadowMapSize - The size of the rendered shadow maps (e.g., 512, 1024, 2048).
      nbShadowMaps - The number of shadow maps to render (1 to 4). More maps improve quality but can reduce performance.

  • Method Details

    • initForcedRenderState

      protected void initForcedRenderState()

    • setPostShadowMaterial

      protected final void setPostShadowMaterial(Material postShadowMat)
      Sets the post-shadow material for this renderer. This material is used to apply the shadows to the main scene.
      Parameters:
      postShadowMat - The desired Material instance to use (alias created).

    • setEdgeFilteringMode

      public final void setEdgeFilteringMode(EdgeFilteringMode filterMode)
      Sets the filtering mode for shadow edges. This affects the smoothness of shadow boundaries.
      Parameters:
      filterMode - The desired filtering mode (cannot be null). See EdgeFilteringMode for available options.

    • getEdgeFilteringMode

      public EdgeFilteringMode getEdgeFilteringMode()
      Returns the currently edge filtering mode for shadows.
      Returns:
      The current EdgeFilteringMode enum value.
      See Also:

    • setShadowCompareMode

      public final void setShadowCompareMode(CompareMode compareMode)
      Sets the shadow comparison mode. This determines how shadow map values are compared to generate shadows.
      Parameters:
      compareMode - The desired compare mode (cannot be null). See CompareMode for available options.

    • getShadowCompareMode

      public CompareMode getShadowCompareMode()
      Returns the currently shadow comparison mode.
      Returns:
      The current CompareMode enum value.
      See Also:

    • createFrustum

      protected Geometry createFrustum(Vector3f[] pts, int i)
      Debug function to create a visible wireframe frustum. This is useful for visualizing the shadow camera's view.
      Parameters:
      pts - Optional storage for vertex positions. If null, a new array will be created.
      i - The index, used to assign a color to the frustum for differentiation (e.g., for multiple shadow maps).
      Returns:
      A new Geometry representing the wireframe frustum.

    • initialize

      public void initialize(RenderManager rm, ViewPort vp)
      Initialize this shadow renderer prior to its first update.
      Specified by:
      initialize in interface SceneProcessor
      Parameters:
      rm - the render manager
      vp - the viewport

    • initFrustumCam

      protected abstract void initFrustumCam()
      Delegates the initialization of the frustum camera to child renderers. This camera defines the view for calculating shadow frustums.

    • isInitialized

      public boolean isInitialized()
      Test whether this shadow renderer has been initialized.
      Specified by:
      isInitialized in interface SceneProcessor
      Returns:
      true if initialized, otherwise false

    • updateShadowCams

      protected abstract void updateShadowCams(Camera viewCam)
      Invoked once per frame to update the shadow cameras according to the light view. Subclasses must implement this method to define how shadow cameras are positioned and oriented.
      Parameters:
      viewCam - The main scene camera.

    • getOccludersToRender

      protected abstract GeometryList getOccludersToRender(int shadowMapIndex, GeometryList shadowMapOccluders)
      Returns a subclass-specific GeometryList containing the occluders that should be rendered into the shadow map.
      Parameters:
      shadowMapIndex - The index of the shadow map being rendered.
      shadowMapOccluders - An existing GeometryList that can be reused or populated.
      Returns:
      A GeometryList containing the geometries that cast shadows for the given map.

    • getShadowCam

      protected abstract Camera getShadowCam(int shadowMapIndex)
      Returns the shadow camera to use for rendering the shadow map according to the given index. Subclasses must implement this to provide the correct camera for each shadow map.
      Parameters:
      shadowMapIndex - The index of the shadow map being rendered.
      Returns:
      The Camera instance representing the shadow's viewpoint.

    • doDisplayFrustumDebug

      protected void doDisplayFrustumDebug(int shadowMapIndex)
      Responsible for displaying the frustum of the shadow camera for debugging purposes. Subclasses can override this method to provide specific debug visualizations.
      Parameters:
      shadowMapIndex - The index of the shadow map for which to display the frustum.

    • postQueue

      public void postQueue(RenderQueue rq)
      Description copied from interface: SceneProcessor
      Called after the scene graph has been queued, but before it is flushed.
      Specified by:
      postQueue in interface SceneProcessor
      Parameters:
      rq - The render queue

    • renderShadowMap

      protected void renderShadowMap(int shadowMapIndex)

    • displayFrustum

      public void displayFrustum()
      Enables debugging of shadow frustums, making them visible in the scene. Call this before postQueue(RenderQueue) to see the frustums.

    • displayShadowMap

      protected void displayShadowMap(Renderer r)
      For debugging purposes, displays the depth shadow maps on screen as Picture quads.
      Parameters:
      r - The current Renderer (ignored).

    • displayDebug

      public void displayDebug()
      For debugging purposes, "snapshots" the current state of the shadow maps and displays them on screen.

    • getReceivers

      protected abstract void getReceivers(GeometryList lightReceivers)
      Populates the provided GeometryList with geometries that are considered shadow receivers. Subclasses must implement this method.
      Parameters:
      lightReceivers - The GeometryList to populate with shadow-receiving geometries.

    • postFrame

      public void postFrame(FrameBuffer out)
      Description copied from interface: SceneProcessor
      Called after a frame has been rendered and the queue flushed.
      Specified by:
      postFrame in interface SceneProcessor
      Parameters:
      out - The FB to which the scene was rendered.

    • clearMaterialParameters

      protected abstract void clearMaterialParameters(Material material)
      This method is called once per frame and is responsible for clearing any material parameters that subclasses may have set on the post-shadow material. This ensures that parameters from previous frames or other renderers do not interfere.
      Parameters:
      material - The material that was used for the post-shadow pass.

    • setMaterialParameters

      protected abstract void setMaterialParameters(Material material)
      This method is called once per frame and is responsible for setting any material parameters that subclasses may need to set on the post material.
      Parameters:
      material - the material to use for the post shadow pass

    • setPostShadowParams

      protected void setPostShadowParams()
      For internal use only. Sets the common shadow parameters on the internal post-shadow material. This is used when a fallback material is needed.

    • getShadowZExtend

      public float getShadowZExtend()
      Returns the maximum distance from the eye where shadows are rendered. A value of 0 indicates that the distance is dynamically computed based on scene bounds.
      Returns:
      The shadow Z-extend distance in world units.
      See Also:

    • setShadowZExtend

      public void setShadowZExtend(float zFar)
      Sets the distance from the camera where shadows will be rendered. By default (0), this value is dynamically computed based on the union bound of shadow casters and receivers, capped by the view frustum's far value. Setting a positive value overrides this dynamic computation.
      Parameters:
      zFar - The zFar value that overrides the computed one. Set to 0 to use dynamic computation.

    • setShadowZFadeLength

      public void setShadowZFadeLength(float length)
      Defines the length over which the shadow will fade out when using a custom `shadowZextend`. This is useful for smoothly transitioning dynamic shadows into baked shadows or for preventing abrupt shadow cut-offs.
      Parameters:
      length - The fade length in world units. Set to 0 to disable fading.

    • getShadowZFadeLength

      public float getShadowZFadeLength()
      Returns the length over which the shadow will fade out when using a custom `shadowZextend`.
      Returns:
      The fade length in world units. Returns 0 if no fading is applied.

    • checkCulling

      protected abstract boolean checkCulling(Camera viewCam)
      Abstract method to check if the light source's bounding box is within the view frustum of the given camera. This is used for culling to avoid unnecessary shadow computations.
      Parameters:
      viewCam - A Camera to define the view frustum against which to check.
      Returns:
      True if the light source's bounding box is in the view frustum, otherwise false.

    • preFrame

      public void preFrame(float tpf)
      Description copied from interface: SceneProcessor
      Called before a frame
      Specified by:
      preFrame in interface SceneProcessor
      Parameters:
      tpf - Time per frame

    • cleanup

      public void cleanup()
      Description copied from interface: SceneProcessor
      Called when the SP is removed from the RM.
      Specified by:
      cleanup in interface SceneProcessor

    • reshape

      public void reshape(ViewPort vp, int w, int h)
      Description copied from interface: SceneProcessor
      Called when the resolution of the viewport has been changed.
      Specified by:
      reshape in interface SceneProcessor
      Parameters:
      vp - the affected ViewPort
      w - the new width (in pixels)
      h - the new height (in pixels)

    • getShadowIntensity

      public float getShadowIntensity()
      Returns the current shadow intensity.
      Returns:
      The shadow intensity value, ranging from 0.0 to 1.0.
      See Also:

    • setShadowIntensity

      public final void setShadowIntensity(float shadowIntensity)
      Sets the shadow intensity. This value controls the darkness of the shadows. A value of 0.0 results in bright, almost invisible shadows, while 1.0 creates pitch-black shadows. The default value is 0.7.
      Parameters:
      shadowIntensity - The desired darkness of the shadow, a float between 0.0 and 1.0.

    • getEdgesThickness

      public int getEdgesThickness()
      Returns the configured shadow edges thickness. The value is returned as an integer representing tenths of a pixel (e.g., 10 for 1.0 pixel).
      Returns:
      The edges thickness in tenths of a pixel.
      See Also:

    • getNumShadowMaps

      public int getNumShadowMaps()
      Returns the number of shadow maps currently rendered by this processor.
      Returns:
      The count of shadow maps.

    • getShadowMapSize

      public int getShadowMapSize()
      Returns the size (width and height) of each shadow map rendered by this processor.
      Returns:
      The resolution of a single shadow map in pixels.

    • setEdgesThickness

      public void setEdgesThickness(int edgesThickness)
      Sets the shadow edges thickness. This parameter influences the smoothness of shadow edges, particularly with PCF (Percentage-Closer Filtering). Setting lower values can help reduce jagged artifacts.
      Parameters:
      edgesThickness - The desired thickness in tenths of a pixel (e.g., 10 for 1.0 pixel). The value is clamped between 1 and 10. Default is 10.

    • isFlushQueues

      @Deprecated public boolean isFlushQueues()
      Deprecated.
      isFlushQueues does nothing now and is kept only for backward compatibility
      Returns:
      false

    • getPreShadowForcedRenderState

      public RenderState getPreShadowForcedRenderState()
      Returns the RenderState that is forced during the pre-shadow pass. You can use this to adjust the rendering parameters for geometries that cast shadows. Note that this will be overridden if the "PreShadow" technique in the material definition has its own `ForcedRenderState`.
      Returns:
      The RenderState applied to the pre-shadow pass.

    • setRenderBackFacesShadows

      public void setRenderBackFacesShadows(boolean renderBackFacesShadows)
      Sets whether back faces of geometries should cast shadows. When enabled, shadows cast by the back side of an object can appear. Be aware that back face shadows can sometimes lead to overly dark lighting when blended with existing dark areas.

      Setting this parameter will globally override this setting for ALL materials in the scene for the shadow pass. Alternatively, you can control this on individual materials using Material.setBoolean(String, boolean) with the "BackfaceShadows" parameter.

      This method also automatically adjusts the RenderState.FaceCullMode and RenderState.setPolyOffset(float, float) of the pre-shadow pass to accommodate back face rendering. You can further modify these using getPreShadowForcedRenderState().

      Parameters:
      renderBackFacesShadows - True to enable back face shadows, false to disable.

    • isRenderBackFacesShadows

      public boolean isRenderBackFacesShadows()
      Checks if this shadow processor is configured to render shadows from back faces.
      Returns:
      True if back face shadows are enabled, false otherwise.

    • jmeClone

      public Object jmeClone()
      Description copied from interface: JmeCloneable
      Performs a regular shallow clone of the object. Some fields may also be cloned but generally only if they will never be shared with other objects. (For example, local Vector3fs and so on.)

      This method is separate from the regular clone() method so that objects might still maintain their own regular java clone() semantics (perhaps even using Cloner for those methods). However, because Java's clone() has specific features in the sense of Object's clone() implementation, it's usually best to have some path for subclasses to bypass the public clone() method that might be cloning fields and instead get at the superclass protected clone() methods. For example, through super.jmeClone() or another protected clone method that some base class eventually calls super.clone() in.

      Specified by:
      jmeClone in interface JmeCloneable
      Returns:
      a new instance

    • cloneFields

      public void cloneFields(Cloner cloner, Object original)
      Description copied from interface: JmeCloneable
      Implemented to perform deep cloning for this object, resolving local cloned references using the specified cloner. The object can call cloner.clone(fieldValue) to deep clone any of its fields.

      Note: during normal clone operations the original object will not be needed as the clone has already had all of the fields shallow copied.

      Specified by:
      cloneFields in interface JmeCloneable
      Parameters:
      cloner - The cloner that is performing the cloning operation. The cloneFields method can call back into the cloner to make clones of its subordinate fields.
      original - The original object from which this object was cloned. This is provided for the very rare case that this object needs to refer to its original for some reason. In general, all of the relevant values should have been transferred during the shallow clone, and this object need only clone what it wants.

    • setProfiler

      public void setProfiler(AppProfiler profiler)
      Description copied from interface: SceneProcessor
      Sets a profiler Instance for this processor.
      Specified by:
      setProfiler in interface SceneProcessor
      Parameters:
      profiler - the profiler instance.

    • read

      public void read(JmeImporter im) throws IOException
      De-serialize this instance, for example when loading from a J3O file.
      Specified by:
      read in interface Savable
      Parameters:
      im - importer (not null)
      Throws:
      IOException - from the importer

    • write

      public void write(JmeExporter ex) throws IOException
      Serialize this instance, for example when saving to a J3O file.
      Specified by:
      write in interface Savable
      Parameters:
      ex - exporter (not null)
      Throws:
      IOException - from the exporter