WorldCanvas

Infinite 2D/3D world canvas supporting camera pan and zoom, coordinate transformations, background world layers, and pinned screen-space anchor widgets.

Overview

WorldCanvas is an infinite 2D/3D camera canvas that maps world coordinates into screen-space UI pixels.

Key capabilities: - Interactive camera panning and zooming via mouse dragging and wheel scroll (panningEnabled, zoomEnabled, wheelPanningEnabled). - Viewport models and camera bounds (viewport, worldBounds, clampToWorldBounds). - Coordinate transformation utilities: worldToRoot, rootToWorld, worldToLocal, localToWorld. - Layered architecture hosting background WorldLayer renderers underneath interactive AnchorLayer widgets.

Setting Up World Canvas with Viewport and Layers

WorldCanvas canvas = new WorldCanvas()
    .viewport(0, 0, 1.0f)
    .zoomRange(0.1f, 5.0f);
canvas.anchorLayer().add("marker", 100, 200, new Button("POI"));

Related links

• AnchorLayer: Layer managing screen-space UI widgets pinned to 3D/2D world coordinates inside WorldCanvas.
• MapCanvas: Interactive 2D map widget extending WorldCanvas with map sizing, texture and grid layers, coordinate projection, and marker handles.
• RibbonLayer: World canvas layer rendering textured or solid ribbon lines, paths, and waypoint routes in world coordinates.
• WorldLayer: Functional contract for background or decorative rendering layers drawn inside WorldCanvas.

API

WorldCanvas::addWorldLayer(WorldLayer)

Registers a new world rendering layer.

Parameter	Type	Description
layer	WorldLayer	WorldLayer instance to register or remove.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::anchorLayer()

Returns the AnchorLayer managing world-pinned UI widgets.

Returns AnchorLayer: The AnchorLayer managing world-pinned widgets..

WorldCanvas::clampToWorldBounds(boolean)

Enables or disables clamping of camera pan within world boundaries.

Parameter	Type	Description
clampToWorldBounds	boolean	Whether camera panning is clamped within world bounds.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::clearWorldBounds()

Clears world boundaries allowing infinite camera panning.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::clearWorldLayers()

Clears all registered world rendering layers.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::clippingEnabled()

Returns true if canvas rendering is clipped to widget layout bounds.

Returns boolean: True if active, enabled, or successful..

WorldCanvas::clippingEnabled(boolean)

Enables or disables clipping of rendering to widget layout bounds.

Parameter	Type	Description
clippingEnabled	boolean	Whether rendering is clipped to canvas layout boundaries.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::consumeWheelWhileHovered()

Returns true if mouse wheel events are consumed when hovered over this canvas.

Returns boolean: True if active, enabled, or successful..

WorldCanvas::consumeWheelWhileHovered(boolean)

Sets whether mouse wheel events are swallowed when hovered.

Parameter	Type	Description
consumeWheelWhileHovered	boolean	Whether mouse wheel events are swallowed when hovered.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::localToWorldX(float)

Transforms a widget local X coordinate back to world X coordinate space.

Parameter	Type	Description
localX	float	Widget local X coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::localToWorldY(float)

Transforms a widget local Y coordinate back to world Y coordinate space.

Parameter	Type	Description
localY	float	Widget local Y coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::onViewportChanged(EventListener)

Registers a listener invoked whenever the viewport position or zoom changes.

Parameter	Type	Description
listener	EventListener	Listener invoked on viewport position or zoom changes.

Returns EventSubscription: EventSubscription for unregistering the listener..

WorldCanvas::panButton()

Returns the mouse pointer button used to drag and pan.

Returns PointerButton: The pointer button used for drag panning..

WorldCanvas::panButton(PointerButton)

Sets the mouse pointer button used to drag and pan.

Parameter	Type	Description
panButton	PointerButton	Pointer button used for drag panning.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::panningEnabled()

Returns true if mouse dragging can pan the camera viewport.

Returns boolean: True if active, enabled, or successful..

WorldCanvas::panningEnabled(boolean)

Enables or disables pointer dragging to pan the viewport.

Parameter	Type	Description
panningEnabled	boolean	Whether pointer dragging pans the viewport.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::preferredHeight()

Returns the preferred layout height of the canvas.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::preferredHeight(float)

Sets the preferred layout height of the canvas.

Parameter	Type	Description
preferredHeight	float	Preferred layout height.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::preferredSize(float, float)

Sets the preferred width and height of the canvas simultaneously.

Parameter	Type	Description
width	float	Width dimension.
height	float	Height dimension.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::preferredWidth()

Returns the preferred layout width of the canvas.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::preferredWidth(float)

Sets the preferred layout width of the canvas.

Parameter	Type	Description
preferredWidth	float	Preferred layout width.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::removeWorldLayer(WorldLayer)

Removes a registered world rendering layer.

Parameter	Type	Description
layer	WorldLayer	WorldLayer instance to register or remove.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::rootToWorldX(float)

Transforms a screen root X coordinate back to world X coordinate space.

Parameter	Type	Description
rootX	float	Screen root X coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::rootToWorldY(float)

Transforms a screen root Y coordinate back to world Y coordinate space.

Parameter	Type	Description
rootY	float	Screen root Y coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::viewport()

Returns the active 2D viewport model.

Returns Viewport2D: The active Viewport2D model..

WorldCanvas::viewport(Viewport2D)

Sets the 2D pan and zoom viewport model.

Parameter	Type	Description
viewport	Viewport2D	2D viewport model for pan and zoom.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::viewport(float, float)

Sets viewport center coordinates while maintaining current zoom.

Parameter	Type	Description
x	float	Horizontal X coordinate.
y	float	Vertical Y coordinate.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::viewport(float, float, float)

Sets viewport center coordinates and zoom level simultaneously.

Parameter	Type	Description
x	float	Horizontal X coordinate.
y	float	Vertical Y coordinate.
zoom	float	Zoom scale factor.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::wheelPanStep()

Returns the distance panned per wheel scroll click.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::wheelPanStep(float)

Sets the distance panned per wheel scroll click.

Parameter	Type	Description
wheelPanStep	float	Distance panned per wheel scroll click.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::wheelPanningEnabled()

Returns true if mouse wheel scrolling pans the camera.

Returns boolean: True if active, enabled, or successful..

WorldCanvas::wheelPanningEnabled(boolean)

Enables or disables mouse wheel scrolling to pan the camera.

Parameter	Type	Description
wheelPanningEnabled	boolean	Whether mouse wheel scrolling pans the viewport.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::worldBounds(float, float, float, float)

Sets the rectangular world bounds constraining camera movement.

Parameter	Type	Description
x	float	Horizontal X coordinate.
y	float	Vertical Y coordinate.
width	float	Width dimension.
height	float	Height dimension.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::worldLayers()

Returns an unmodifiable list of all registered world rendering layers.

Returns List: Unmodifiable list of registered world layers..

WorldCanvas::worldToLocalX(float)

Transforms a world X coordinate to widget local X coordinate space.

Parameter	Type	Description
worldX	float	World X coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::worldToLocalY(float)

Transforms a world Y coordinate to widget local Y coordinate space.

Parameter	Type	Description
worldY	float	World Y coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::worldToRootX(float)

Transforms a world X coordinate to screen root X coordinate space.

Parameter	Type	Description
worldX	float	World X coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::worldToRootY(float)

Transforms a world Y coordinate to screen root Y coordinate space.

Parameter	Type	Description
worldY	float	World Y coordinate.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::zoomEnabled()

Returns true if mouse wheel zooming is enabled.

Returns boolean: True if active, enabled, or successful..

WorldCanvas::zoomEnabled(boolean)

Enables or disables mouse wheel zooming.

Parameter	Type	Description
zoomEnabled	boolean	Whether mouse wheel zooming is enabled.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::zoomRange(float, float)

Sets the allowed minimum and maximum zoom scale bounds.

Parameter	Type	Description
minZoom	float	Minimum allowed zoom scale factor.
maxZoom	float	Maximum allowed zoom scale factor.

Returns WorldCanvas: This instance for chaining..

WorldCanvas::zoomStep()

Returns the zoom multiplier applied per wheel tick.

Returns float: The floating-point coordinate or dimension value..

WorldCanvas::zoomStep(float)

Sets the zoom multiplier applied per wheel tick.

Parameter	Type	Description
zoomStep	float	Zoom multiplier applied per wheel tick.

Returns WorldCanvas: This instance for chaining..