Package com.victorvalentim.zividomelive

Interface Scene

public interface Scene
Defines the lifecycle and drawing contract for a ziviDomeLive scene.

Mutable state that must advance once per Processing frame belongs in update(). Drawing belongs in sceneRender(PGraphicsOpenGL). Spherical capture may invoke sceneRender(...) multiple times during the same Processing frame, so advancing simulation, timelines, counters or mutable random state from the render callback can make spherical directions observe different states.

The library owns the supplied render target's beginDraw()/endDraw() pair. A scene must neither call those methods nor retain the target after the callback.

API stability: Stable.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    configure(SceneServices services)
    Supplies lifecycle-aware API services before this scene is set up.
    default void
    dispose()
    Ends one active setup cycle and releases scene-owned domain resources.
    default String
    getName()
    Returns the artist-facing scene name used by logging and scene controls.
    default void
    keyEvent(processing.event.KeyEvent event)
    Handles a Processing key event.
    default void
    mouseEvent(processing.event.MouseEvent event)
    Handles a Processing mouse event.
    void
    sceneRender(processing.opengl.PGraphicsOpenGL pg)
    Draws the current scene state into the supplied OpenGL render target.
    default void
    setupScene()
    Sets up the scene when it becomes active.
    default void
    update()
    Updates mutable scene state for the current Processing frame.

  • Method Details

    • configure

      default void configure(SceneServices services)
      Supplies lifecycle-aware API services before this scene is set up.

      The runtime calls this before the matching setupScene() on every activation, including reloads of the same scene instance. The supplied context belongs to that one activation and may be retained only until the matching dispose() returns.

      Parameters:
      services - services owned by this scene activation

    • setupScene

      default void setupScene()
      Sets up the scene when it becomes active.

      A scene instance may be activated more than once. Every activation receives fresh services through configure(SceneServices) and follows a complete setup/dispose cycle.

    • update

      default void update()
      Updates mutable scene state for the current Processing frame.

      Use this callback for simulation, animation counters, timelines, physics, state transitions and mutable randomization that must advance once per frame. Keep those mutations out of sceneRender(PGraphicsOpenGL) when all rendered views/faces must observe the same state.

      The runtime invokes this on the Processing frame thread after activation callbacks, bounded external input, and the frame clock have been advanced.

    • sceneRender

      void sceneRender(processing.opengl.PGraphicsOpenGL pg)
      Draws the current scene state into the supplied OpenGL render target.

      Spherical capture may call this method multiple times during one Processing frame. Implementations should therefore treat this callback as drawing-only whenever mutable state must advance once per frame.

      The render target is already inside an active draw frame owned by the library; scene implementations must not call beginDraw() or endDraw() here. The target is supplied for this render callback and should not be retained as scene-owned graphics state.

      Parameters:
      pg - the active PGraphicsOpenGL target used to draw the scene; never null for a library-initiated render callback

    • keyEvent

      default void keyEvent(processing.event.KeyEvent event)
      Handles a Processing key event. The default implementation does nothing.

      Named SceneActionMap bindings run first; the raw callback remains available for direct Processing-style input.

      Parameters:
      event - the KeyEvent object containing details of the key event

    • mouseEvent

      default void mouseEvent(processing.event.MouseEvent event)
      Handles a Processing mouse event. The default implementation does nothing.

      Named SceneActionMap bindings run first, this raw callback runs next, and library-owned camera navigation is routed afterward.

      Parameters:
      event - the MouseEvent object containing details of the mouse event

    • dispose

      default void dispose()
      Ends one active setup cycle and releases scene-owned domain resources.

      Before this callback, the runtime stops accepting activation work and cancels activation-owned tasks. After it returns, the runtime releases services and adapters. Scenes must not close runtime-supplied services themselves. The same Java scene object may be configured and activated again later.

    • getName

      default String getName()
      Returns the artist-facing scene name used by logging and scene controls.
      Returns:
      the scene name; by default the implementation class simple name