Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nasaworldwind/worldwindjava/llms.txt

Use this file to discover all available pages before exploring further.

WorldWindow is the top-level interface that every WorldWind rendering surface implements. It binds together a Model (globe + layers), a View (camera), a SceneController (render loop), an InputHandler (mouse/keyboard routing), and a set of event-listener registries into a single object that an application can embed in its UI hierarchy. All rendering, picking, and event dispatch flows through a WorldWindow. The interface extends AVList so that arbitrary key-value metadata can be attached to any window instance. Package: gov.nasa.worldwind Interface: public interface WorldWindow extends AVList

​
Implementations

WorldWind ships two ready-to-use concrete implementations, both located in gov.nasa.worldwind.awt.

​
WorldWindowGLCanvas

WorldWindowGLCanvas — heavyweight AWT component
package gov.nasa.worldwind.awt;

public class WorldWindowGLCanvas extends GLCanvas
    implements WorldWindow, PropertyChangeListener
WorldWindowGLCanvas is a heavyweight AWT component backed by JOGL’s GLCanvas. Because it is a native peer component it has the best and most consistent performance across platforms and is the recommended choice for most applications. It can be mixed with lightweight Swing components provided the standard Swing light/heavyweight workarounds are applied (disable lightweight pop-ups via ToolTipManager.setLightWeightPopupEnabled(false) etc.). It is stereo-capable: set the JVM property gov.nasa.worldwind.stereo.mode=device before constructing the canvas to request a stereo-capable OpenGL context; pair this with a StereoSceneController in worldwind.xml.

​
WorldWindowGLJPanel

WorldWindowGLJPanel — lightweight Swing component
package gov.nasa.worldwind.awt;

public class WorldWindowGLJPanel extends GLJPanel
    implements WorldWindow, PropertyChangeListener
WorldWindowGLJPanel is a lightweight Swing panel backed by JOGL’s GLJPanel. It allows the WorldWind globe to participate in z-ordering with other Swing components (translucent panels, overlays, etc.) without the airspace clipping problems that heavyweight components impose. The trade-off is historically lower and less predictable rendering performance. Use it only when Swing z-order integration is essential.
JOGL’s GLJPanel implementation has had known stability and performance issues on some hardware/driver combinations. Prefer WorldWindowGLCanvas whenever possible.

​
Model and View

​
setModel / getModel

Model access
void setModel(Model model)
Model getModel()
Attaches or detaches a Model (the globe plus its layer list) to this window. Passing null disassociates any current model. The scene controller is notified automatically.
​
model
Model
The model to display. May be null to detach the current model.

​
setView / getView

View access
void setView(View view)
View getView()
Attaches or detaches the View (camera) used to render this window’s model. Passing null disassociates the current view.
​
view
View
The view to use. May be null to detach the current view.

​
setModelAndView

Atomic model and view assignment
void setModelAndView(Model model, View view)
Convenience method that atomically sets both the model and the view in a single call. Either argument may be null.
​
model
Model
The model to display. May be null.
​
view
View
The view to use. May be null.

​
getSceneController / setSceneController

SceneController access
SceneController getSceneController()
void setSceneController(SceneController sceneController)
Gets or replaces the SceneController that drives the render and pick loops for this window. When replacing the scene controller the caller is responsible for populating the new instance with a View, Model, and any desired per-frame statistics keys before passing it in.
​
sceneController
SceneController
The new scene controller. The caller must configure its view and model before attaching it.
Returns: SceneController — the current scene controller, or null if none is associated.

​
Rendering

​
redraw

Asynchronous repaint request
void redraw()
Enqueues a repaint event with the window system. The actual repaint occurs on the window system’s event-dispatch thread at the toolkit’s discretion. This is the preferred way to trigger a new frame because it coalesces multiple requests and integrates naturally with the AWT/Swing event queue. In WorldWindowGLCanvas this delegates to Component.repaint().

​
redrawNow

Synchronous immediate repaint
void redrawNow()
Forces an immediate repaint without waiting for the window system event queue. Use this only in the rare cases where synchronous rendering is unavoidable (e.g., screen-capture utilities). Under normal circumstances, prefer redraw().

​
getGpuResourceCache

GPU resource cache
GpuResourceCache getGpuResourceCache()
Returns the GpuResourceCache that manages all GPU-resident resources (textures, VBOs, display lists) allocated for this window’s OpenGL context. This method is primarily for use by custom shapes and layers that manage their own GPU objects. Applications should not clear or modify the cache directly. Returns: GpuResourceCache
Do not clear or modify the GpuResourceCache directly from application code. Doing so will cause excessive memory usage or application crashes. Access GPU resources only through the DrawContext during rendering.

​
Event Listeners

​
Select Listeners

Select listener registration
void addSelectListener(SelectListener listener)
void removeSelectListener(SelectListener listener)
Select listeners receive SelectEvent notifications whenever the user performs an operation that identifies a visible object — a left-click, right-click, hover, drag, or box-select. The event carries the PickedObjectList of all objects under the cursor at the time of the event.
​
listener
SelectListener
The listener to add or remove.

​
Position Listeners

Position listener registration
void addPositionListener(PositionListener listener)
void removePositionListener(PositionListener listener)
Position listeners are called each time the cursor’s geographic position changes. The event reports the current Position (latitude, longitude, altitude) under the cursor, or null if the cursor is not over the globe.
​
listener
PositionListener
The listener to add or remove.

​
Rendering Listeners

Rendering listener registration
void addRenderingListener(RenderingListener listener)
void removeRenderingListener(RenderingListener listener)
Rendering listeners are notified at key stages of the WorldWind draw cycle (before/after render, before/after pick). They allow applications to inject custom OpenGL rendering or monitor frame progress.
​
listener
RenderingListener
The listener to add or remove.

​
Rendering Exception Listeners

Rendering exception listener registration
void addRenderingExceptionListener(RenderingExceptionListener listener)
void removeRenderingExceptionListener(RenderingExceptionListener listener)
Rendering exception listeners are called when an unrecovered exception or critical error occurs during drawable initialisation or the render loop. Use these to display user-facing error messages or initiate graceful degradation.
​
listener
RenderingExceptionListener
The listener to add or remove.

​
Input Handler

Input handler access
InputHandler getInputHandler()
void setInputHandler(InputHandler inputHandler)
The InputHandler translates AWT mouse and keyboard events into WorldWind SelectEvents and view-manipulation gestures. The default implementation installed by both concrete window classes is AWTInputHandler, configured via AVKey.INPUT_HANDLER_CLASS_NAME in worldwind.xml. Pass null to setInputHandler to detach the current handler (a no-op handler is installed internally so the window remains functional).
​
inputHandler
InputHandler
The input handler to use. Pass null to detach the current handler.

​
Performance

​
getPerFrameStatistics

Per-frame statistics
Collection<PerformanceStatistic> getPerFrameStatistics()
Returns the active per-frame performance statistics measured during the most recently completed frame, such as tile-draw counts, render time breakdowns, and pick pass timing. Only statistics whose keys have been activated via setPerFrameStatisticsKeys are populated. Returns: Collection<PerformanceStatistic>

​
setPerFrameStatisticsKeys

Activating statistics
void setPerFrameStatisticsKeys(Set<String> keys)
Specifies which performance metrics WorldWind should measure each frame. Keys are defined as constants on PerformanceStatistic (e.g., PerformanceStatistic.FRAME_RATE). Passing an empty set disables all per-frame measurement. The activated set is forwarded to the SceneController.
​
keys
Set<String>
The set of statistic keys to activate. Use PerformanceStatistic constant strings.

​
WorldWindowGLCanvas Constructors

WorldWindowGLCanvas provides four constructors to cover the most common deployment scenarios.
Default constructor — single window on the default graphics device
public WorldWindowGLCanvas()
Creates a new canvas on the default GraphicsDevice using WorldWind’s required GLCapabilities. A default View and AWTInputHandler are constructed and attached automatically.
Shared-context constructor
public WorldWindowGLCanvas(WorldWindow shareWith)
Creates a new canvas that shares the GpuResourceCache (and underlying OpenGL context) with an existing WorldWindow. Use this when displaying multiple synchronized views of the same scene so that textures and geometry are not duplicated in GPU memory.
​
shareWith
WorldWindow
An existing WorldWindow whose GPU resources should be shared. May be null for an independent context.
Device-specific constructor
public WorldWindowGLCanvas(WorldWindow shareWith, java.awt.GraphicsDevice device)
Creates a canvas on a specific GraphicsDevice (useful for multi-monitor setups) with optional GPU resource sharing.
​
shareWith
WorldWindow
An existing WorldWindow to share resources with. May be null.
​
device
GraphicsDevice
The target graphics device. Pass null to use the default screen device.
Full-control constructor
public WorldWindowGLCanvas(WorldWindow shareWith, java.awt.GraphicsDevice device,
    GLCapabilities capabilities, GLCapabilitiesChooser chooser)
Full-control constructor for applications that need to specify a custom GLCapabilities profile or GLCapabilitiesChooser.
​
shareWith
WorldWindow
Resource-sharing partner. May be null.
​
device
GraphicsDevice
Target display device. May be null.
​
capabilities
GLCapabilities
Custom OpenGL capabilities. May be null to use WorldWind defaults.
​
chooser
GLCapabilitiesChooser
Custom capabilities chooser. May be null to use the default BasicGLCapabilitiesChooser.

​
Code Example

The following example creates a basic application window with a WorldWindowGLCanvas embedded in a Swing frame and registers a SelectListener to print the name of any picked object.
Creating a WorldWindowGLCanvas with a SelectListener
import gov.nasa.worldwind.*;
import gov.nasa.worldwind.awt.WorldWindowGLCanvas;
import gov.nasa.worldwind.event.*;

import javax.swing.*;

public class SimpleWorldWindApp {

    public static void main(String[] args) {
        // Workaround for Swing/AWT mixing
        javax.swing.ToolTipManager.sharedInstance().setLightWeightPopupEnabled(false);
        javax.swing.JPopupMenu.setDefaultLightWeightPopupEnabled(false);

        SwingUtilities.invokeLater(() -> {
            // Create the WorldWindow canvas with default model and view
            WorldWindowGLCanvas wwd = new WorldWindowGLCanvas();
            wwd.setPreferredSize(new java.awt.Dimension(1200, 800));

            // Attach a default model (WGS84 Earth + default layer set)
            wwd.setModel(new BasicModel());

            // Register a select listener to react to user picks
            wwd.addSelectListener(event -> {
                if (event.getTopObject() != null) {
                    System.out.println("Picked: " + event.getTopObject());
                }
            });

            JFrame frame = new JFrame("WorldWind");
            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.getContentPane().add(wwd, java.awt.BorderLayout.CENTER);
            frame.pack();
            frame.setVisible(true);
        });
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us