Package com.victorvalentim.zividomelive

Class ziviDomeLive

java.lang.Object
com.victorvalentim.zividomelive.ziviDomeLive
public class ziviDomeLive extends Object
Main artist-facing facade for live fulldome, spherical, and Standard rendering in Processing.

Create one instance in the sketch's setup(), call setup() after the P3D surface exists, and provide content through Scene. The facade owns scene activation, renderers, Processing hooks, camera synchronization, the built-in control panel, outputs, and terminal cleanup.

Methods documented as Processing Callback are Java-public only because the constructor registers them with Processing. Sketches must not call those callbacks directly. Performance methods are explicitly Experimental; the remaining artist-facing facade is Stable for the 2.x series.

API stability: Stable, except methods explicitly marked Experimental or Processing Callback.

  • Constructor Details

    • ziviDomeLive

      public ziviDomeLive(processing.core.PApplet p)
      Creates a facade owned by the supplied Processing sketch and registers runtime callbacks.

      Call setup() from the sketch's setup() after creating its P3D surface.

      Parameters:
      p - non-null Processing sketch used for rendering
      Throws:
      IllegalArgumentException - if the PApplet instance is null

  • Method Details

    • setLogMode

      public static void setLogMode(LogMode mode)
      Sets the global logging mode used by the library. Call this before creating a ziviDomeLive instance so startup follows the selected profile.
      Parameters:
      mode - desired logging mode

    • enableDebugLogging

      public static void enableDebugLogging()
      Enables verbose DEBUG logs to the console and library log file.

    • enableReleaseLogging

      public static void enableReleaseLogging()
      Enables RELEASE mode, which disables library-managed log output.

    • getLogMode

      public static LogMode getLogMode()
      Returns the currently active logging mode.
      Returns:
      active logging mode

    • setScene

      public void setScene(Scene scene)
      Selects and activates a scene through the facade-owned manager.

      An unregistered instance is registered automatically. Switching performs the complete activation order: stop old activation work, dispose the previous scene, create fresh services, configure the new scene, then set it up.

      Parameters:
      scene - scene instance to activate; null is ignored

    • registerScene

      public void registerScene(Scene scene)
      Registers a scene with the facade-owned manager without activating it when another user scene is already active. The first registered user scene replaces the bootstrap fallback.

      The facade lifecycle guarantees that Scene.configure(SceneServices) runs before the first setup.

      Parameters:
      scene - scene to register

    • setup

      public void setup()
      Sets up the rendering environment, including frame rate, OpenGL info, texture hints, output coordination, and the built-in interface.

      Call once from the sketch's setup() after its P3D surface has been created. The operation is idempotent; renderer allocation completes lazily in the registered post() callback when the OpenGL context is active.

      Throws:
      IllegalStateException - if the PApplet instance is not properly configured

    • setStandardOutputAspectMode

      public void setStandardOutputAspectMode(ziviDomeLive.StandardOutputAspectMode mode)
      Sets the aspect policy used to compute Standard output dimensions.

      Changing this setting schedules an output-render-target rebuild on the next frame so the Standard output FBO dimensions are updated without recreating preview targets.

      Parameters:
      mode - desired aspect mode, ignored when null

    • getStandardOutputAspectMode

      public ziviDomeLive.StandardOutputAspectMode getStandardOutputAspectMode()
      Returns the aspect policy currently used to compute Standard output dimensions.
      Returns:
      current Standard output aspect mode

    • draw

      public void draw()
      Processing Callback that renders the already-updated frame and built-in interface.

      The constructor registers this method automatically. Sketches must not call it directly or call a second ziviDomeLive render method from their own draw().

    • resetGraphics

      public void resetGraphics(int newResolution)
      Schedules output-target recreation at a safe draw boundary. Preview resolution remains derived from the Processing window.
      Parameters:
      newResolution - positive output resolution in pixels
      Throws:
      IllegalArgumentException - when newResolution is not positive

    • getOutputResolution

      public int getOutputResolution()
      Returns the current output resolution used by offscreen render targets.
      Returns:
      current output resolution

    • setCurrentScene

      public void setCurrentScene(Scene newScene)
      Alias for setScene(Scene) retained as part of the 2.x scene API.
      Parameters:
      newScene - scene instance to activate; null is ignored

    • keyEvent

      public void keyEvent(processing.event.KeyEvent event)
      Processing Callback that routes key events to built-ins, named scene actions, and the active scene's raw callback.

      The constructor registers this method automatically; sketches must not call or register it themselves.

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

    • mouseEvent

      public void mouseEvent(processing.event.MouseEvent event)
      Processing Callback that routes mouse events to named actions, the active scene, the built-in interface, and exactly one navigation camera.

      The constructor registers this method automatically; sketches must not call or register it themselves. A visible control under the pointer owns its gesture and suppresses navigation.

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

    • getOutputManager

      public OutputManager getOutputManager()
      Returns artist-facing output control and telemetry.
      Returns:
      output manager, or null before setup() completes

    • getFishSize

      public float getFishSize()
      Returns the domemaster circle size.
      Returns:
      configured size as a percentage of the square target

    • setFishSize

      public void setFishSize(float fishSize)
      Sets the domemaster circle size.
      Parameters:
      fishSize - size percentage; values outside 0..100 are constrained

    • getFov

      public float getFov()
      Returns the domemaster angular field of view.
      Returns:
      field of view in degrees

    • setFov

      public void setFov(float fov)
      Sets the domemaster angular field of view.
      Parameters:
      fov - field of view in degrees; finite values are constrained to 0..360 and non-finite values are ignored

    • getPitch

      public float getPitch()
      Returns the spherical pitch control accumulator.
      Returns:
      pitch in radians

    • setPitch

      public void setPitch(float pitch)
      Sets spherical pitch by composing the shortest delta around the local X axis.
      Parameters:
      pitch - control value in radians; non-finite values are ignored

    • getYaw

      public float getYaw()
      Returns the spherical yaw control accumulator.
      Returns:
      yaw in radians

    • setYaw

      public void setYaw(float yaw)
      Sets spherical yaw by composing the shortest delta around the local Z axis.
      Parameters:
      yaw - control value in radians; non-finite values are ignored

    • getRoll

      public float getRoll()
      Returns the spherical roll control accumulator.
      Returns:
      roll in radians

    • setRoll

      public void setRoll(float roll)
      Sets spherical roll by composing the shortest delta around the local Y axis.
      Parameters:
      roll - control value in radians; non-finite values are ignored

    • resetOrientation

      public void resetOrientation()
      Restores the spherical orientation to the identity quaternion.

    • getCurrentView

      public ViewType getCurrentView()
      Gets the configured preview view.

      In a dedicated RenderMode, the effective representation is controlled by that mode while this value is preserved for a later return to RenderMode.FULL.

      Returns:
      configured preview view

    • setCurrentView

      public void setCurrentView(ViewType currentView)
      Sets the configured preview view.

      The selection takes effect immediately in RenderMode.FULL. Dedicated modes keep it as the preview selection to restore when FULL is selected again.

      Parameters:
      currentView - new preview view; null is ignored

    • getRenderMode

      public RenderMode getRenderMode()
      Returns the active global render mode.
      Returns:
      active mode, defaulting to RenderMode.FULL
      Since:
      1.5.0

    • setRenderMode

      public void setRenderMode(RenderMode renderMode)
      Selects the global rendering behavior.

      FULL preserves independent preview and external-output routing. A dedicated mode overrides their effective representation without mutating the configured ViewType values.

      Parameters:
      renderMode - new global mode; null is ignored
      Since:
      1.5.0

    • setTargetFrameRate

      public void setTargetFrameRate(int fps)
      Sets the target frame rate applied during setup. Defaults to 60. Call before setup() to take effect at startup; calling afterwards applies immediately and updates the default NDI frame-rate metadata. Reapplying the configured value does not restart Processing's animator.
      Parameters:
      fps - desired frame rate, must be positive

    • getTargetFrameRate

      public int getTargetFrameRate()
      Returns the configured target frame rate.
      Returns:
      target frame rate in frames per second

    • setPerformanceOutputDemand

      public void setPerformanceOutputDemand(ViewType view)
      Configures an offscreen output-resolution view for performance qualification.

      This demand is honored only while performance profiling is enabled. It renders the requested high-resolution output dependency chain without enabling, disabling, or sending NDI, Syphon, or Spout. Passing null clears the qualification demand.

      This is an experimental benchmarking hook; normal applications should route output through OutputManager.

      API stability: Experimental.

      Parameters:
      view - output-resolution view to render during profiling, or null to clear
      Since:
      2.0.0

    • isShowPreview

      public boolean isShowPreview()
      Checks if the preview is shown.
      Returns:
      true if the preview is shown, false otherwise

    • setShowPreview

      public void setShowPreview(boolean showPreview)
      Sets whether the preview is shown.
      Parameters:
      showPreview - true to show the preview, false to hide

    • resetControls

      public void resetControls()
      Resets the built-in controls to their default state when the interface is initialized.

    • getSceneCamera

      public OrbitCamera getSceneCamera()
      Returns the native scene-space orbit camera service.

      Scenes normally obtain this same camera from SceneServices.camera() and apply it inside sceneRender between pushMatrix/popMatrix. The camera transforms the scene modelview directly, so it works across every projection without touching the dome parameters (yaw/pitch/roll/fov). Its current rotational quaternion is synchronized with the shared Environment every frame; target and distance remain scene-only so the background stays infinite.

      Returns:
      the shared OrbitCamera instance

    • isSphericalCaptureActive

      public boolean isSphericalCaptureActive()
      Reports whether the current Scene.sceneRender(PGraphicsOpenGL) call is being executed by a spherical cubemap capture pass.

      Scenes can use this to skip viewport-only background geometry, HUDs, or helper elements that should not be baked into domemaster, equirectangular, or skybox outputs. The method does not change the sceneRender(PGraphicsOpenGL) contract; it only exposes the current renderer phase.

      Returns:
      true while a cubemap capture pass is rendering the scene
      Since:
      2.0.0

    • setEquirectangularBackground

      public void setEquirectangularBackground(processing.core.PImage image)
      Sets an LDR equirectangular environment background for all render modes.

      The image is rendered by the library as an infinite far-depth background after the active Scene is drawn. This keeps backgrounds out of scene geometry, survives scene-owned background() calls, and makes the same environment available to domemaster, equirectangular, skybox, and Standard projections. In Standard view the environment follows camera rotation but remains invariant under camera translation. Passing null clears the environment.

      Parameters:
      image - equirectangular Processing image, or null to clear

    • setEquirectangularBackground

      public void setEquirectangularBackground(String imagePath)
      Loads and sets an LDR equirectangular environment background from the sketch data path.

      This is a synchronous Processing asset load. Use it during sketch setup, not inside a recurring frame callback or background task.

      Parameters:
      imagePath - Processing data path or absolute image path; null or blank clears the source

    • clearEnvironmentBackground

      public void clearEnvironmentBackground()
      Clears the configured environment background.

    • hasEnvironmentBackground

      public boolean hasEnvironmentBackground()
      Reports whether an environment background image is currently configured.
      Returns:
      true when an image is configured

    • setEnvironmentBackgroundVisible

      public void setEnvironmentBackgroundVisible(boolean visible)
      Shows or hides the configured environment background without releasing the image.
      Parameters:
      visible - true to draw the environment background

    • isEnvironmentBackgroundVisible

      public boolean isEnvironmentBackgroundVisible()
      Reports whether the configured environment background is visible.
      Returns:
      true when visible

    • setEnvironmentBackgroundIntensity

      public void setEnvironmentBackgroundIntensity(float intensity)
      Sets the colour multiplier applied to the LDR environment background.
      Parameters:
      intensity - colour multiplier; finite negative values are clamped to zero and non-finite values are ignored

    • getEnvironmentBackgroundIntensity

      public float getEnvironmentBackgroundIntensity()
      Returns the current environment background colour multiplier.
      Returns:
      non-negative colour multiplier

    • setEnvironmentBackgroundYawOffset

      public void setEnvironmentBackgroundYawOffset(float yawOffset)
      Rotates the equirectangular environment lookup around the vertical axis.
      Parameters:
      yawOffset - radians added to the source longitude lookup; non-finite values are ignored

    • getEnvironmentBackgroundYawOffset

      public float getEnvironmentBackgroundYawOffset()
      Returns the current equirectangular environment yaw offset.
      Returns:
      yaw offset in radians

    • setSceneCameraInputEnabled

      public void setSceneCameraInputEnabled(boolean enabled)
      Enables or disables built-in mouse handling for the scene camera. When enabled, the library forwards mouse drag/wheel events to getSceneCamera() automatically and suspends the independent Standard-view camera input, preventing the same gesture from rotating two cameras at once.
      Parameters:
      enabled - true to let the library drive the scene camera from mouse input

    • isSceneCameraInputEnabled

      public boolean isSceneCameraInputEnabled()
      Returns whether built-in mouse handling for the scene camera is enabled.
      Returns:
      true if the library forwards mouse input to the scene camera

    • getPApplet

      public processing.core.PApplet getPApplet()
      Returns the Processing sketch that owns this facade.

      Scenes should prefer SceneServices.applet() so ownership remains explicit for the current activation.

      Returns:
      non-null owning Processing sketch

    • isInitialized

      public boolean isInitialized()
      Reports whether setup and lazy OpenGL manager initialization completed successfully.
      Returns:
      true when the facade can render frames

    • enablePerformanceProfiling

      public void enablePerformanceProfiling(PerformanceMode mode)
      Enables experimental performance collection using the default ring-buffer capacity.

      PerformanceMode.CPU_GPU adds one capability-gated asynchronous GPU timestamp interval around the complete render pipeline. Unsupported contexts fall back to CPU, and no synchronous query or glFinish() is introduced.

      API stability: Experimental.

      Parameters:
      mode - non-null requested profiling mode
      Throws:
      IllegalArgumentException - when mode is null
      Since:
      2.0.0

    • enablePerformanceProfiling

      public void enablePerformanceProfiling(PerformanceMode mode, int sampleCapacity)
      Enables experimental performance collection with preallocated sample storage. Calling this method resets previously collected samples.

      API stability: Experimental.

      Parameters:
      mode - non-null requested profiling mode
      sampleCapacity - number of completed frames retained in the ring buffer, from 2 to 100000
      Throws:
      IllegalArgumentException - when an argument is invalid
      Since:
      2.0.0

    • enablePerformanceProfiling

      public void enablePerformanceProfiling(PerformanceMode mode, int sampleCapacity, GpuTimerPolicy timerPolicy)
      Enables profiling with an explicit GPU timer ownership/fallback policy.

      GpuTimerPolicy.ARCHITECTURE_AWARE is intended for controlled benchmark scenes. On Apple Silicon it may own GL_TIME_ELAPSED for the complete pipeline, so scene code must not start another elapsed timer query during the interval.

      API stability: Experimental.

      Parameters:
      mode - non-null requested profiling mode
      sampleCapacity - number of completed frames retained in the ring buffer, from 2 to 100000
      timerPolicy - non-null GPU timer selection policy
      Throws:
      IllegalArgumentException - when an argument is invalid
      Since:
      2.0.0

    • disablePerformanceProfiling

      public void disablePerformanceProfiling()
      Disables collection without discarding completed samples.

      API stability: Experimental.

      Since:
      2.0.0

    • resetPerformanceStatistics

      public void resetPerformanceStatistics()
      Clears all performance samples and invariant counters.

      API stability: Experimental.

      Since:
      2.0.0

    • getPerformanceSnapshot

      public PerformanceSnapshot getPerformanceSnapshot()
      Creates an immutable performance snapshot. Call outside a measured interval because snapshot aggregation intentionally allocates and sorts copies of retained samples.

      API stability: Experimental.

      Returns:
      immutable snapshot of completed frames
      Since:
      2.0.0

    • getGraphicsCapabilities

      public GraphicsCapabilities getGraphicsCapabilities()
      Returns a read-only diagnostic report for the active Processing graphics renderer.

      Call on the Processing/OpenGL thread after the renderer is initialized.

      API stability: Experimental.

      Returns:
      current graphics capability report
      Since:
      2.0.0

    • setSceneManager

      public void setSceneManager(SceneManager sceneManager)
      Sets the SceneManager instance for managing multiple scenes.

      A detached manager selects, but does not set up, its first registered scene. Attaching it here begins that activation with facade-owned services. Replacing the manager disposes the previously owned activation first.

      Parameters:
      sceneManager - the SceneManager instance to manage scenes

    • getSceneManager

      public SceneManager getSceneManager()
      Returns the current SceneManager instance.
      Returns:
      the current SceneManager

    • pre

      public void pre()
      Processing Callback that establishes the authoritative frame boundary.

      It drains activation queues and bounded external input, ticks the frame clock, processes a deferred reload or calls Scene.update(), refreshes tracked camera targets, and advances camera interpolation once. The constructor registers it automatically; sketches must not call it directly.

    • post

      public void post()
      Processing Callback that performs lazy renderer initialization after setup().

      The constructor registers it automatically and the facade unregisters it after successful initialization. Sketches must not call it directly.

    • stop

      public void stop()
      Processing Callback that stops the instance permanently and releases all owned resources.

      This terminal operation delegates to dispose() and is idempotent. Processing calls it automatically; applications normally do not.

    • resume

      public void resume()
      Processing Callback that resumes activation input and outputs remembered by pause().

      The constructor registers it automatically; sketches must not call it directly.

    • pause

      public void pause()
      Processing Callback that pauses frame work, drops queued external input, clears pointer anchors, and disables outputs while remembering their enabled state.

      The constructor registers it automatically; sketches must not call it directly.

    • dispose

      public void dispose()
      Processing Callback that performs terminal, idempotent cleanup.

      Processing calls this method automatically. It may also be invoked once by an application that intentionally ends the facade early; no facade operation may reactivate it afterward.