Package org.xjge.core

Class Scene

java.lang.Object
org.xjge.core.Scene
public abstract class Scene
extends java.lang.Object
A 3D representation of the game world that contains entities, light sources, and camera objects.

NOTE: The setScene command will fail if the default constructor of a Scene subclass uses parameters. You should instead set the value of the scenes name field explicitly with the super keyword.

Since:
2.0.0
See Also:
Entity, Light, Camera, Skybox, ShadowMap

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected java.util.LinkedHashMap<java.lang.String,​Entity> entities
    A collection of every Entity object in the scene.
    protected Light[] lights
    An array that contains every Light object currently present within the scene.
    static int MAX_LIGHTS
    The maximum number of light source objects that may be simultaneously present in the scene at any given time.
    java.lang.String name  

  • Constructor Summary

    Constructors
    Constructor Description
    Scene​(java.lang.String name)
    Creates a new 3D scene that will contain entities, light sources, and camera objects.

  • Method Summary

    Modifier and Type Method Description
    abstract void exit()
    Called by the engine when this scene is left for another.
    abstract void render​(java.util.Map<java.lang.String,​GLProgram> glPrograms, int viewportID, Camera camera, int depthTexHandle)
    Organizes calls to the OpenGL API made by entities and other various objects located in the game world.
    abstract void renderShadows​(GLProgram depthProgram)
    Used to organize calls to the OpenGL API by entities and other objects within the scene who wish to cast shadows.
    protected void setShadowMap​(ShadowMap shadowMap)
    Sets the current shadow map that will be used to cast shadows onto various entities within the scene.
    protected void setSkybox​(Skybox skybox)
    Sets the current skybox the scene will render as part of its background.
    abstract void update​(double targetDelta, double trueDelta)
    Organizes and updates the game logic of the scene and every entity inhabiting it.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • MAX_LIGHTS

      public static final int MAX_LIGHTS
      The maximum number of light source objects that may be simultaneously present in the scene at any given time.
      See Also:
      Constant Field Values

    • name

      public final java.lang.String name

    • entities

      protected final java.util.LinkedHashMap<java.lang.String,​Entity> entities
      A collection of every Entity object in the scene.

      Because the engine actively makes use of this collection elsewhere you should not attempt to supplant its functionality with your own. Instead the collection should be used to iterate through the logic loop of each entity like so: 

       //In the scenes update() method...
 entities.values().forEach(entity -> {
     entity.update();
 });
 
 //In the scenes render() method...
 entities.values().foreach(entity -> {
     entity.render();
 });

      The details regarding how this is achieved are largely subject to the needs of the implementation, though generally speaking for a large volume of entity objects lambda expressions like those shown above are usually sufficient for most cases.

    • lights

      protected final Light[] lights
      An array that contains every Light object currently present within the scene.

      Like the entities collection the engine makes use of this array in other places- however it permits a greater degree of freedom as the values contained by the light objects are generic and can be used for custom lighting solutions should the implementing application decide not to utilize the engines built-in lighting utilities.

      NOTE: When using the engines built-in lighting utilities the index of zero is reserved for the scenes global light source. This light source will illuminate all entities within the scene regardless of their physical location or proximity to the light. Additionally, if a shadow map is present, it will project its frustum in the direction of the origin from the global light source. Any light object placed at the index of zero will instantly assume the role of the global light source.

  • Constructor Details

    • Scene

      public Scene​(java.lang.String name)
      Creates a new 3D scene that will contain entities, light sources, and camera objects.
      Parameters:
      name - the name used to refer to the scene in other parts of the engine

  • Method Details

    • setShadowMap

      protected final void setShadowMap​(ShadowMap shadowMap)
      Sets the current shadow map that will be used to cast shadows onto various entities within the scene.
      Parameters:
      shadowMap - the shadow map object to use

    • setSkybox

      protected final void setSkybox​(Skybox skybox)
      Sets the current skybox the scene will render as part of its background.
      Parameters:
      skybox - the completed skybox object to render

    • update

      public abstract void update​(double targetDelta, double trueDelta)
      Organizes and updates the game logic of the scene and every entity inhabiting it. Called automatically by the engine once every game tick.
      Parameters:
      targetDelta - a constant value denoting the desired time (in seconds) it should take for one game tick to complete
      trueDelta - the actual time (in seconds) it took the current game tick to complete.

    • render

      public abstract void render​(java.util.Map<java.lang.String,​GLProgram> glPrograms, int viewportID, Camera camera, int depthTexHandle)
      Organizes calls to the OpenGL API made by entities and other various objects located in the game world. This method is called automatically by the engine.
      Parameters:
      glPrograms - an immutable collection containing the shader programs compiled during startup
      viewportID - the ID number of the viewport currently rendering the scene. Supplied here in case certain objects are to be included or omitted from the viewports rendering pass
      camera - the Camera object of the current Viewport being rendered
      depthTexHandle - the handle of the texture generated by the current shadow map or -1 if one has not been set

    • renderShadows

      public abstract void renderShadows​(GLProgram depthProgram)
      Used to organize calls to the OpenGL API by entities and other objects within the scene who wish to cast shadows. This method is called automatically by the engine.

      NOTE: The depth shader program is provided here exclusively by the engine and is not accessible through other means such as the glPrograms collection.

      Parameters:
      depthProgram - the shader program provided by the engine that will be used to generate the shadow map texture

    • exit

      public abstract void exit()
      Called by the engine when this scene is left for another. Any memory/resources allocated by the scene including that of entities which are no longer needed should be freed here.