Skip to content

Version 1.5.0

ziviDomeLive 1.5.0 is the final consolidation release of the 1.x renderer. It keeps the established Processing-facing API while making render selection, lifecycle ownership, spherical calibration, output routing, automated qualification, and release packaging explicit and testable.

Highlights

  • RenderMode defines which rendering family is active: FULL, STANDARD, DOMEMASTER, EQUIRECTANGULAR, or SKYBOX.
  • Render requirements are derived from the active mode, preview, floating domemaster, and enabled output routes, so unused passes can be omitted.
  • Pitch, yaw, and roll are cyclic controls composed onto one normalized quaternion, avoiding Euler-state gimbal lock.
  • The ControlP5 panel exposes only controls relevant to the current RenderMode; route selectors remain editable in FULL and become fixed in dedicated modes.
  • NDI, Syphon, and Spout have explicit availability, initialization, publication, failure, and shutdown states.
  • CalibrationTool provides repeatable cube-face and 360-degree visual qualification targets.
  • JUnit qualification, strict bilingual documentation, Javadocs, package verification, and GitHub workflows now form one release process.

The detailed file-by-file record is available in the repository CHANGELOG.md.

Render Modes

RenderMode.FULL is the compatibility default. Existing sketches that do not call setRenderMode() retain the independent preview and per-output routing model.

Dedicated modes narrow the public rendering intent:

Mode Main view Route selectors Relevant spherical controls
FULL Selected ViewType Editable per output According to selected routes
STANDARD Standard perspective Fixed Hidden unless floating domemaster requires them
DOMEMASTER Fisheye domemaster Fixed FOV, Size%, pitch, yaw, roll
EQUIRECTANGULAR Equirectangular Fixed pitch, yaw, roll
SKYBOX Cubemap layout Fixed pitch, yaw, roll

The runtime computes the transitive requirements for each frame. For example, a domemaster needs equirectangular and cubemap sources, while Standard remains independent from spherical capture. See Render Modes and Rendering Pipeline.

Spherical Orientation

The 1.5 controls preserve the familiar pitch/yaw/roll interface, but their rendering state is quaternion-based:

  • pitch rotates around local X;
  • yaw rotates around local Z;
  • roll rotates around local Y;
  • each setter applies the shortest cyclic delta from the previous control value;
  • every delta is composed into a normalized quaternion.

The getter values are control accumulators, not an Euler decomposition of the quaternion. Because rotations do not commute, applying pitch then yaw can produce a different attitude from applying yaw then pitch, even if the final displayed values match. Integrations that replay calibration values should preserve command order or start with resetOrientation().

Lifecycle And Outputs

Initialization now has observable states and bounded failure behavior. The library owns its registered Processing hooks; sketches should call setup() once and should not manually call zividomelive.draw().

Output routing and backend state are separate. A route may require a render view even while its native sender is still initializing. Diagnostic methods expose failure reasons and NDI frame counters. Pause, resume, resize, and dispose paths preserve intended publication state without leaking background workers.

NDI remains an experimental, unofficial, video-only output. Processing does not provide an official native NDI library, and the public Devolay artifact is runtime-separated, so users must complete the operating-system-specific NDI Runtime installation themselves.

Calibration Tool

Scene 1 maps procedural GLSL 4.10 focus, alignment, color, grayscale, clipping, point, and star targets directly onto all six cube faces. The complete surface follows the shared spherical orientation.

Scene 2 maps the original Paul Bourke v14 equirectangular pattern onto a full 360-degree sphere centered at (0, 0, 0), with poles at +Z and -Z. One of four source resolutions is selected from the active output bucket, or from the window when all outputs are disabled. The slow-rotation profiles implement the author's one-revolution-per-minute recommendation without changing Processing's animator from inside the scene.

See Spherical Calibration and the Calibration Tool Protocol.

Testing And Packaging

The release introduces qualificationTests as the canonical, headless JUnit evidence task. Tests remain in src/test and in Git, but are excluded from sketchbook deployment and release packages. GitHub runs the same suite in a dedicated workflow.

buildReleaseArtifacts produces and verifies the Processing ZIP, PDEX, and metadata text. Verification rejects missing legal or citation files, accidental test sources, local compile-only helper JARs, and mismatched ZIP/PDEX contents.

Compatibility Notes

  • The public lowercase facade remains zividomelive.
  • RenderMode.FULL remains the default.
  • ViewType order is unchanged because ControlP5 and compatibility paths map it by index.
  • Deprecated direct render methods remain as 1.x shims.
  • Renderer getters remain public for 1.x source compatibility, but internal renderer topology is not a stable 2.0 contract.
  • The packaged projection and calibration shaders require OpenGL 4.1 / GLSL 4.10 support.

Upgrade Checklist

  1. Keep one zividomelive instance per sketch and call setup() once.
  2. Remove manual calls to zividomelive.draw() and scene-owned beginDraw()/endDraw() pairs.
  3. Leave RenderMode unset for legacy routing, or select a dedicated mode when the sketch has one fixed projection.
  4. Reset orientation before replaying an ordered calibration sequence.
  5. Requalify GPU output, seams, focus, color, NDI/Syphon/Spout, pause/resume, and shutdown on production hardware.
  6. Run the Release Readiness checklist before tagging v1.5.0.