Class ViewPanel

java.lang.Object
java.awt.Component
java.awt.Canvas
eu.svjatoslav.aukio.e3d.gui.ViewPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class ViewPanel extends Canvas
AWT Canvas that provides a 3D rendering surface with built-in camera navigation.

ViewPanel is the primary entry point for embedding the Aukio 3D engine into a Java application. It manages the render loop, maintains a scene graph (ShapeCollection), and handles user input for camera navigation.

Uses BufferStrategy for efficient page-flipping and tear-free rendering.

Quick start - creating a 3D view in a window:

// Option 1: Use ViewFrame (creates a maximized JFrame for you)
ViewFrame frame = new ViewFrame();
ViewPanel viewPanel = frame.getViewPanel();

// Option 2: Embed ViewPanel in your own window
JFrame frame = new JFrame("My 3D App");
ViewPanel viewPanel = new ViewPanel();
frame.add(viewPanel);
frame.setSize(800, 600);
frame.setVisible(true);

// Add shapes to the scene
ShapeCollection scene = viewPanel.getRootShapeCollection();
scene.addShape(new WireframeCube(
    new Point3D(0, 0, 200), 50,
    new LineAppearance(5, Color.GREEN)
));

// Position the camera
viewPanel.getCamera().setLocation(new Point3D(0, 0, -100));

// Listen for frame updates (e.g., for animations)
viewPanel.addFrameListener((panel, deltaMs) -> {
    // Called before each frame. Return true to force repaint.
    return false;
});

Architecture:

  • A background render thread continuously generates frames at the target FPS
  • The engine intelligently skips rendering when no visual changes are detected
  • FrameListeners are notified before each potential frame, enabling animations
  • Mouse/keyboard input is managed by InputManager
  • Keyboard focus is managed by KeyboardFocusStack
See Also:

  • Field Details

    • backgroundColor

      public Color backgroundColor
      The background color of the view.

  • Constructor Details

    • ViewPanel

      public ViewPanel()
      Creates a new view panel with default settings.

  • Method Details

    • getCamera

      public Camera getCamera()
      Returns the camera representing the viewer's position and orientation.
      Returns:
      the camera

    • getKeyboardFocusStack

      public KeyboardFocusStack getKeyboardFocusStack()
      Returns the keyboard focus stack, which manages which component receives keyboard input.
      Returns:
      the keyboard focus stack

    • getRootShapeCollection

      public ShapeCollection getRootShapeCollection()
      Returns the root shape collection (scene graph). Add your 3D shapes here to make them visible in the view. 
      viewPanel.getRootShapeCollection().addShape(myShape);
      Returns:
      the root shape collection

    • getInputManager

      public InputManager getInputManager()
      Returns the input manager handling mouse and keyboard events for this view.
      Returns:
      the input manager

    • addFrameListener

      public void addFrameListener(FrameListener listener)
      Registers a listener that will be notified before each frame render. Listeners can trigger repaints by returning true from FrameListener.onFrame(ViewPanel, int).
      Parameters:
      listener - the listener to add
      See Also:

    • getPreferredSize

      public Dimension getPreferredSize()
      Overrides:
      getPreferredSize in class Component

    • getMinimumSize

      public Dimension getMinimumSize()
      Overrides:
      getMinimumSize in class Component

    • getMaximumSize

      public Dimension getMaximumSize()
      Overrides:
      getMaximumSize in class Component

    • getRenderingContext

      public RenderingContext getRenderingContext()
      Returns the current rendering context for the active frame.
      Returns:
      the rendering context, or null if no frame is being rendered

    • getDeveloperTools

      public DeveloperTools getDeveloperTools()
      Returns the developer tools for this view panel.
      Returns:
      the developer tools

    • getDebugLogBuffer

      public DebugLogBuffer getDebugLogBuffer()
      Returns the debug log buffer for this view panel.
      Returns:
      the debug log buffer

    • getLastFrameImage

      public BufferedImage getLastFrameImage()
      Returns the most recently completed frame, for bug report screenshots. The buffer belongs to the render pipeline and is reused — copy it before use. Null until the first frame completes.
      Returns:
      the last presented frame image, or null

    • getLightingManager

      public LightingManager getLightingManager()
      Returns the global lighting manager for the scene. Add light sources here to illuminate the world.
      Returns:
      the lighting manager

    • enableGlobalIllumination

      public GlobalIllumination enableGlobalIllumination()
      Enables progressive global illumination with the default of 2 dedicated low-priority CPU threads. GI is opt-in: without this call lighting behaves exactly as before. Shadows and bounced light fade in over the first seconds and keep adapting to scene changes.
      Returns:
      the running GI system

    • enableGlobalIllumination

      public GlobalIllumination enableGlobalIllumination(int threadCount)
      Enables progressive global illumination with the given number of dedicated low-priority CPU threads. Calling again returns the already-running system.
      Parameters:
      threadCount - worker threads for ray tracing
      Returns:
      the running GI system

    • enableGlobalIllumination

      public GlobalIllumination enableGlobalIllumination(int threadCount, Consumer<GlobalIllumination> configurer)
      Enables progressive global illumination, applying the given configurer (radius/density overrides) BEFORE the worker threads start — the first eligibility evaluation already sees them. Needed when one JVM hosts scenes of different scales (the demo launcher): per-instance overrides instead of global -D properties. Calling again returns the already-running system (configurer ignored).
      Parameters:
      threadCount - worker threads for ray tracing
      configurer - applied to the new GI system before start; may be null
      Returns:
      the running GI system

    • getGlobalIllumination

      public GlobalIllumination getGlobalIllumination()
      The running global illumination system, or null when GI was never enabled for this view. Read-only; for the developer tools panel.
      Returns:
      the GI system or null

    • showDeveloperToolsPanel

      public void showDeveloperToolsPanel()
      Shows the developer tools panel, toggling it if already open. Called when F12 is pressed.

    • paint

      public void paint(Graphics g)
      Overrides:
      paint in class Canvas

    • update

      public void update(Graphics g)
      Overrides:
      update in class Canvas

    • addNotify

      public void addNotify()
      Overrides:
      addNotify in class Canvas

    • repaintDuringNextViewUpdate

      public void repaintDuringNextViewUpdate()
      Calling these methods tells 3D engine that current 3D view needs to be repainted on first opportunity.

      Also (re)starts the render thread when the component is showable: the thread is otherwise started only from componentShown/Resized, which under window managers without reparenting (bare Xvfb) can fire before the panel is displayable — leaving the view dark forever despite pending repaints. Idempotent; the render thread guards on renderThread != null.

    • setFrameRate

      public void setFrameRate(int frameRate)
      Set target frames per second rate for this view. Target FPS can be changed at runtime. Use 0 or negative value for unlimited FPS (max performance mode for benchmarking).
      Parameters:
      frameRate - target frames per second rate for this view.

    • getTargetFPS

      public int getTargetFPS()
      Returns the current target frames per second rate.
      Returns:
      target FPS; 0 or less means unlimited

    • getMeasuredFPS

      public double getMeasuredFPS()
      Returns the measured production rate: frames completed per second, averaged over the last ~500 ms window. This is the benchmark number: how fast the pipeline produces frames, regardless of how quickly the display path presents them (the mailbox present thread may drop stale frames when the display is slower than production).
      Returns:
      measured frames per second

    • getNumRenderThreads

      public int getNumRenderThreads()
      Returns the current number of render threads.
      Returns:
      the number of render threads

    • setNumRenderThreads

      public void setNumRenderThreads(int count)
      Sets the number of render threads. Takes effect on the next frame. The executor service is recreated lazily when the render loop detects the change.
      Parameters:
      count - number of render threads (must be at least 1)

    • isStereoModeEnabled

      public boolean isStereoModeEnabled()
      Returns whether side-by-side stereoscopic rendering is currently enabled.
      Returns:
      true if stereo mode is active

    • setStereoModeEnabled

      public void setStereoModeEnabled(boolean enabled)
      Enables or disables side-by-side stereoscopic rendering. When enabled, each frame renders two eye views side-by-side.
      Parameters:
      enabled - true to enable stereo mode, false to disable

    • getStereoIPD

      public double getStereoIPD()
      Returns the current inter-pupillary distance used for stereo rendering.
      Returns:
      IPD in world units (centimeters)

    • setStereoIPD

      public void setStereoIPD(double ipd)
      Sets the inter-pupillary distance for stereo rendering. Human IPD ranges from ~5.5 to ~7.5 cm; for XR glasses the optical IPD may differ from the user's anatomical IPD.
      Parameters:
      ipd - the inter-pupillary distance in world units (centimeters)

    • getSpaceMouse

      public SpaceNavigatorHid getSpaceMouse()
      Returns the active SpaceMouse device, or null when no 6DOF mouse is currently connected.

    • getHeadTracker

      public HeadTracker getHeadTracker()
      Returns the active head tracker, or null when no glasses are currently connected.

    • stop

      public void stop()
      Stops rendering of this view.

    • removeFrameListener

      public void removeFrameListener(FrameListener frameListener)
      Removes a previously registered frame listener.
      Parameters:
      frameListener - the listener to remove