Class RIAMap

Creates a new map.

A boolean indicating whether the near and far planes of this map's camera should automatically adjust when the camera or terrain gets updated. By default, this is true to avoid rendering artifacts while keeping objects on the earth's surface visible. Setting this to false removes this safeguard but allows you to have more fine-grained control of the near and far planes, for example when you want to be able to navigate close to objects that are far away from the earth. On maps with a 3D cartesian world reference, with likely application-specific near and far settings, the default is false.

Determines whether the map automatically adjusts RIAMap.displayScale.

If you enable this setting, the map automatically adjusts RIAMap.displayScale so that it always matches window.devicePixelRatio. It will update RIAMap.displayScale when the display scale changes on the monitor, when users zoom on the web page, or drag the browser window to a monitor with a different devicePixelRatio.

The default value is false.

The camera that is used by this map.

For now, you can only set a PerspectiveCamera instance on a map if the map has a geocentric reference (EPSG:4978) or a 3D cartesian reference (e.g. LUCIAD:XYZ, and you can only set a OrthographicCamera on the map if the map does NOT have a geocentric reference (ie. it's a projected (grid) or cartesian reference).

The key used to animate the camera on the map.

The currently active controller of the map.

A controller defines how user input is interpreted. If RIAMap.controller is null or didn't handle the user input event, the event is passed to defaultController.

RIAMap.controller typically remains null the majority of the time, and is only set when a special user interaction is required. For example:

• CreateController: create a new Feature
• EditController: edit an existing Feature
• SwipeController: Compare layers by swiping
• FlickerController: Compare layers by flickering
• A measurement controller

By contrast, defaultController is typically non-null for the lifetime of the RIAMap and handles navigation, hovering and selection.

See the Implementing custom user interaction guide and the Managing user input with LuciadRIA controllers tutorial for more information.

map.controller = new BasicCreateController(ShapeType.POINT);
Copy

The map's CursorManager. Use this to change the mouse cursor on the map's DOM node.

See the Implementing custom user interaction guide for more information on working with cursors on the map.

The currently active default controller of the map.

This controller handles user input, if no RIAMap.controller is active on the map or the RIAMap.controller didn't handle the user input. As opposed to RIAMap.controller, RIAMap.defaultController typically is set to controllers that handle navigation, hovering and selection. For example:

• DefaultController: implements the default LuciadRIA map behavior. You can customize parts of this, like just zooming or rotation.
• ContextMenuController: implements context menu actions on the map
• A custom navigation controller

If RIAMap.defaultController is null or didn't handle the user input, the DOM event is forwarded back to the browser. If RIAMap.defaultController did handle the user input, propagation of the DOM event is stopped.

By default, this field is initialized with a DefaultController. If both RIAMap.controller and RIAMap.defaultController are null, map interactions are completely disabled.

See the Implementing custom user interaction guide and the Managing user input with LuciadRIA controllers tutorial for more information.

The RIAMap.displayScale to use on the map.

The display scale is the ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device. A value of 1 indicates a classic 96 DPI display, while a value of 2 (or even 4) is preferable for HiDPI/Retina displays.

This setting scales the pixel density of the map. For example:

• displayScale = 1: the map renders at the classic 96 DPI.
• displayScale = 2: the map renders at double the pixel density.
• displayScale = 0.5: the map renders at half the pixel density.

Increasing the display scale results in sharper images and crisper text, but it might have a negative impact on performance.

If you enable RIAMap.autoAdjustDisplayScale, the Map's display scale automatically adjusts to match the display scale of the browser or operating system.

The default value is 1.

Whenever this value changes, a "DisplayScaleChanged" event is emitted.

The DOM element that contains the map. This is the same element provided (by ID) when the map was constructed.

The number of virtual pixels ("dots") on the screen per centimeter, as determined by the Map. This value usually varies depending on the device, OS-settings and browser.

The number of virtual pixels ("dots") on the screen per inch, as determined by the Map. This value usually varies depending on the device, OS-settings and browser.

The graphics effects that are applied on this map. Have a look at GraphicsEffects for a list of effects that are available.

You should directly assign properties of the effects fields.

Any effect that has complex parameters (using an object literal) can be disabled by setting its value to null. For simple effects that have boolean toggles, you can turn the effect off by setting the boolean value to false.:

    map.effects.light = null;
    map.effects.atmosphere = false;
Copy

An object describing the thresholds for gesture recognition on this map.

Adjusting these values changes how the map interprets mouse and touch input. For example, increasing drag thresholds makes it harder to accidentally start a drag when tapping, which is useful in shaky environments or when wearing gloves.

Changes take effect immediately. A "GestureDetectionChanged" event is emitted whenever any value changes.

You can assign individual properties:

  map.gestureDetection.touch.dragThreshold = 20;
  map.gestureDetection.mouse.doubleClickTimeout = 400;
Copy

Or assign a partial object (unspecified values are preserved):

  map.gestureDetection = {
    touch: { dragThreshold: 20, doubleTapTimeout: 500 },
    mouse: { doubleClickTimeout: 400 }
  };
Copy

A CSS color string to indicate the desired color of the globe if no imagery layers are present.

   map.globeColor = "#aabbcc";  // or "rgba(110, 120, 130, 1.0)"
Copy

The default color for the globe is light-grey ("rgba(204, 204, 204, 1.0)")

This only has an effect on 3D maps. On 2D maps, there is no globe.

There are three distinct values that you can use, each with their specific behaviour.

• rgba(red, green, blue, alpha), where alpha is non-zero or #RRGGBB
  the globe is painted fully opaque with the given color in the absence of raster layers.
• rgba(red, green, blue, 0)
  the globe is painted fully transparent in the absence of raster layers.
  The value of red, green and blue is ignored, "rgba(0,0,0,0)" has the same effect as "rgba(255,255,255,0)". The globe still allows you to drape 2D shapes and images on top of it.
• null
  no globe is painted.
  This also disables 2D vector and raster painting. Only data that does not need draping will be rendered on the map.

The set of objects which are currently displayed as "hovered" (i.e. a cursor is hovering over them).

The layer tree that contains all the layers in this map. This property is immutable.

To wait until the map has finished loading and rendering all data, call LayerTreeNode.whenReady on this layer tree.

Returns the current bounds of the map as a rectangle in the map's reference.

The map's MapNavigator. Use this to manipulate the area which is shown in the map.

Returns the scale values of this map view as an array of two Numbers (scale along the X-axes and the Y-axes, in that order). This is a read-only property.

In the case when the unit of measure is a length (like distance, altitude, easting,....), the scale is the ratio between the distance, as it is measured on the screen of the device, to the distance in the real world. This corresponds with paper map scales. For instance to obtain a 1:10000 map display the scale should be set to 1 / 10000.

In the case when the unit of measure is of a different type (for example, time or temperature), the scale is the ratio of 1cm on the screen per units of measure. For example, such a scale might express something like 1cm equals 5 hours.

Note that since web browsers do not provide unambiguous information on the correct screen resolution (which is commonly expressed in dpi (dots per inch)), the distance of 1cm on a device's display is an approximation. To retrieve the conversion factor used by LuciadRIA, you can use the dotsPerCentimeter property of the Map.

The transformation that can be used to transform coordinates specified in the Map's reference to view coordinates (pixels). See viewToMapTransformation for the inverse transformation.

In a 3D map, this transformation will throw OutOfBoundsError when the world coordinate is not visible in the current view. This happens when the world coordinate is obscured by terrain or on the back-facing side of the globe.

In a 2D map that has RIAMap.wrapAroundWorld set to true, this transformation will return a pixel in view if it exists. If this point is visible on multiple maps, the pixel corresponding to the center most map will be returned.
For more information, check Things to consider when using wrapAroundWorld.

The maximum scale value of the map. A user cannot zoom in further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.

The default value of the horizontal and vertical components is Infinity, meaning there is no upper scale limit in both dimensions.

An error will be thrown when attempting to set an invalid value (e.g. the maxMapScale is smaller than the minMapScale).

Note that this value may conflict with the minimum scale which is implied by the bounds constraint (RIAMap.restrictNavigationToBounds). When this value is smaller than that minimum-scale (which depends on the width/height of those bounds as well as the width/height of the view), the scale of the bounds-restriction will have precedence over this one.

This value may conflict with the scale implied by the navigation restriction RIAMap.getBoundsNavigationRestriction. Because the map will be zoomed in so no data outside the restriction is shown, that scale value may be larger than this value. If that is the case, the scale value of the restriction will take precedence. Note that in such a case, it is impossible to zoom the map.

A hint indicating the amount of memory that this application is allowed to use.

These hints apply only to internal data managed by the RIAMap, and not to any user data present in the application.

This can help prevent the browser tab from crashing. If you experience such behavior, try reducing both CPU and GPU memory from their default values. Alternatively, if memory is not a problem and the browser is stable enough, increasing these values can improve caching efficiency.

Notes:

• The values are expressed in megabytes.
• The available memory is distributed across the layers in the map.
• The distribution happens automatically and continuously.
• The distribution can be uneven, allowing some layers to use more memory than others.
• Each layer implementation attempts to restrict its memory usage to its allocated portion.
• Typically, layers will evict cached data to stay within their limits.
• Some layers may reduce the quality or the amount of data loaded. When this happens, it will be clearly logged.
• If a layer still requires more memory than allocated, it will log warnings but continue to use the memory.
• The browser process memory usage may be significantly higher than these limits. In addition to layer data, the application itself requires memory, and browsers often keep copies of GPU data and additional structures to support the JavaScript engine and DOM.

By default, the limits are 500 MB for CPU and 1000 MB for GPU. On high-resolution displays, the default GPU memory limit is automatically increased to 2000 MB.

  map.maxMemoryUsageHint = {
    cpuMB: 500,
    gpuMB: 1200
  }
Copy

The minimum scale value of the map. A user cannot zoom out further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.

The default value of the horizontal and vertical components is 0, meaning there is no lower scale limit in both dimensions.

An error will be thrown when attempting to set an invalid value (e.g., the minMapScale is larger than the maxMapScale).

map.minMapScale = 1/200000;
map.maxMapScale = 1/50000;
Copy

The current world reference of the map.

The current world reference of the map.

When switching the map's reference, parts of the map are destroyed and recreated, which has the following effects:

• The visible layers can unload and quickly reload.
• After switching reference, map.controller is set to null and map.defaultController is set to a new DefaultController.
• Map creation options that are not supported in the new reference, will be lost. For example, when switching from a map that has wrapAroundWorld: true to a 3D reference and then back to a 2D reference, wrapAroundWorld will be false.

The camera state is also saved before switching and restored after switching if possible.

You can not switch from or to a non-geospatial projection, even between LUCIAD:XY and LUCIAD:XYZ.

The selected objects of the map. This is an array of Objects where each Object contains the layer and the selected objects as properties. The name of those properties is layer and selected respectively.

Performing an action on each selected object of a certain layer can for example be achieved as shown below.

  var map = ...;
  var selection = map.selectedObjects;
  var i, j;
  var layer, selectedObjects,selectedObject;
  for ( i = 0; i < selection.length; i++ ){
    layer = selection[i].layer;
    if ( isSearchedLayer( layer ) ){
      selectedObjects = selection[i].selected;//array of the selected objects for layer
      for ( j = 0; j < selectedObjects.length; j++ ){
        selectedObject = selectedObjects[j];
        //do something with the selected object
      }
    }
  }
Copy

The size of the view, represented as a two-element array containing the width and height in pixels. This corresponds to the area in which the data is rendered.

The transformation that can be used to transform coordinates specified in view coordinates (pixels) to the map reference. See mapToViewTransformation for the inverse transformation.

In a 3D map, this transformation will return a world point on the terrain at the input view coordinate. If the view coordinate does not hit the terrain, the transformation will throw OutOfBoundsError.

In a 2D map, the world point will never contain elevation.

This is a shorthand for Map#getViewToMapTransformation(LocationMode.TERRAIN)

If you are working with a Map.wrapAroundWorld map, and you're transforming the map point to a model reference afterward, make sure you enable CreateTransformationOptions.normalizeWrapAround on the map to model transformation you will create.

The WebGL context of the map.

The WebGPU context of the map.

It can be null if the map is not initialized. Listen to on("WebGPUContextChanged") event to be notified when the context changes.

The GPUDevice of the map.

It can be null if the map is not initialized. Listen to the on("WebGPUDeviceChanged") event to be notified when the device changes.

Whether the map should wrap around the projection boundary.

This is forced to false if the map has a reference that does not use a cylindrical projection.

Whether the map should wrap around the projection boundary.

This is forced to false if the map has a reference that does not use a cylindrical projection.

Because wrapAroundWorld influences various aspects of the map, changing this setting requires reinitializing many parts.

Clear the current set of hovered objects. See hoverObjects for more information.

Clear the current selection.

This method must be called if the map is to be removed from the web page. This method cleans up the DOM and unregisters DOM event handlers.

Retrieve the bounds to which the navigation is restricted. You should not modify this object while it is set on the map.

Returns all bounds of the map in the reference of your choosing

• if wrapAroundWorld is false this will always return a list with a single bounds element.
• if wrapAroundWorld is true and the map visualizes the world across the dateline, this will return a bounds left of that dateline and a bounds right of the dateline.

Creates a Transformation object that is used to transform a view position to a corresponding world (map) position in 3D scenes, based on a mechanism that is defined by LocationMode parameter.

In 3D space there are multiple interpretations possible for a given view point expressed in pixel coordinates. Possible options are:

• LocationMode.CLOSEST_SURFACE - This transformation yields a world point position corresponding to the visible object at the view location closest to the viewer (camera eye point). The closest 3D object can be represented by 3D meshes, point clouds, extruded shapes, 3D icons or the terrain.
• LocationMode.TERRAIN - This transformation yields a world point position on the terrain.
• LocationMode.ELLIPSOID - This transformation yields a world point position on the ellipsoid.

For 3D cartesian world references, the z = 0 plane takes on the role of terrain and ellipsoid. So for the corresponding location modes, the transformation yields a world point position on the z = 0 plane.

Note: In 2D space the LocationMode parameter is disregarded and the returned Transformation object is same as the one obtained by viewToMapTransformation.

If the view coordinate does not represent a point on an object or terrain, then OutOfBoundsError will be thrown.

The first image shows the view point that was used for the transformations. The second image shows from a different perspective the transformation results, points that were created by the Transformation object with different locationMode properties.

Hides the currently shown balloon, if any.

Updates the set of objects which are displayed as "hovered" (i.e. a cursor is hovering over them). Note that this method probably should not be called except from a custom Controller which is reacting to a cursor. If you try to hover an object that is not available in the layer, a ProgrammingError will be thrown. Objects that do not pass the layer's filter (if any) will not be hovered.

Refreshes the map unconditionally. This triggers a repaint of the entire view.

Determine whether a particular object on a layer is displayed as "hovered" (i.e. a cursor is hovering over it).

Determine whether a particular object on a layer is selected.

Override this when you wish to respond to click events on the map

Override this method to add view-wide content to the map's context menu.

Override this method to display a populated context menu. Implementations of this method should provide the required glue code to display the context menu using UI toolkit dependent code.

Retrieves all touched Features in an array of PickInfo objects. The type of the underlying layer determines the content of the array:

• For FeatureLayer, the method returns the touched Features directly from the model
• For TileSet3DLayer, the method returns an array of proxy features with metadata about the touched 3D geometry. For more information and edge cases, consult the developer guide.

A pick info object is a JavaScript object with two properties: the objects that were touched, and the layer these objects reside in. One pickinfo object for each layer with a touched object will be added to the result.

Since 2026.0, this method no longer reports features from Tileset3DLayer by default. Instead, it is recommended to use pickAtAsync to obtain 3D Tiles pick info. For more details, see Picking on 3D Tiles.

Retrieves all touched Features in an array of PickInfo objects. This is the asynchronous version of the pickAt method. It has exactly the same parameters and has the same return value encapsulated in a Promise. See pickAt for more information.

For TileSet3DLayer containing point clouds, the pick info object will contain a Feature with:

• the identifier set as "unknown"
• a Point representing the point location in the map's reference frame as Feature.Shape
• all the properties defined for this point
• an extra property called pointLocation, indicating the point's location as it appears in the original data

Retrieves all touched Features in an array of pick info objects: a pick info object is a JavaScript object with two properties: the objects that were touched, and the layer these objects reside in. One pickinfo object for each layer with a touched object will be added to the result.

Since 2026.0, this method no longer reports features from Tileset3DLayer by default. Instead, it is recommended to use pickAtRectangleAsync to obtain 3D Tiles pick info. For more details, see Picking on 3D Tiles.

Retrieves all touched Features in an array of pick info objects. This is the asynchronous version of the pickAtRectangle method. It has exactly the same parameters and has the same return value encapsulated in a Promise. See pickAtRectangle for more information.

Retrieves the first touched Feature. The return value of the result is null if no object is touched, or a PickInfo object, with two properties: the objects that were touched (in this case it will be an array with a single element), and the layer that object resides in.

The closest object is picked by checking distances between the input location and feature shapes, or their labels if the paintRepresentations parameter includes the LABEL.

Since 2026.0, this method no longer reports features from Tileset3DLayer by default. Instead, it is recommended to use pickClosestObjectAsync to obtain 3D Tiles pick info. For more details, see Picking on 3D Tiles.

Retrieves the first touched Feature. This is the asynchronous version of the pickClosestObject method. It has exactly the same parameters and has the same return value encapsulated in a Promise. See pickClosestObject for more information.

Retrieves the first touched Feature. The return value of the result is null if no object is touched, or a PickInfo object, with two properties: the objects that were touched (in this case it will be an array with a single element), and the layer that object resides in.

The closest object is picked by checking distances between the input location and feature shapes, or their labels if the paintRepresentations parameter includes the LABEL.

Since 2026.0, this method no longer reports features from Tileset3DLayer by default. Instead, it is recommended to use pickClosestObjectRectangleAsync to obtain 3D Tiles pick info. For more details, see Picking on 3D Tiles.

Retrieves the first touched Feature. This is the asynchronous version of the pickClosestObjectRectangle method. It has exactly the same parameters and has the same return value encapsulated in a Promise. This method will also report touched 3D Tiles features.

See pickClosestObjectRectangle for more information.

This method reboots all GPU resources used by the map. This can be useful when the device has been lost and the map has to re-create GPU resources.

Typically, you call this some time after a "GPU device lost" event. For example, when the WebGPU device is lost, you can show an overlay on the map that informs the user that the device was lost. The user can try to reboot the map with a button in the overlay.

If you call this while the existing GPUDevice is lost, the map creates a new GPUDevice for rendering. This changes the value of webGPUDevice

If the device was not lost, calling this function has no effect.

Because LuciadRIA interrupts any animations when the device is lost, you might have to restart an animation after rebooting.

For more information on dealing with WebGPU device losses in LuciadRIA, check out the Dealing with WebGPU device losses article.

This method can be called when the size of the map's container has changed. The map will automatically refit itself to the size of the Map container at that time.

The map listens by default to window resize events to resize automatically. However, if the map container is resized by JavaScript, for example by a JavaScript SplitContainer component that divides the web page in two parts that can be resized, there is no way to detect this resizing of the map container automatically. In that case this method can be called by the application developer

Restores the state of the map based on a state object that has been returned by the saveState method.

It is possible to restore the state of a map with a reference that's different from this map's reference. Note that this is only true if a matching camera position can be found.

For example, it is not possible to restore a map state that's looking at Australia if this map has a Polar Stereographic North reference (because the southern hemisphere is not defined in that projection). In that case, an Error is thrown.

Specify a bounds which identifies the area beyond which the map cannot zoom or pan. When set, a user will not be able to zoom or pan to an area that falls outside this bounds. The default value is null.

While the bounds can be specified in any spatial reference, the constraints will be evaluated on a bounds in the spatial reference of the map. For example, if the map's reference is in a Mercator grid reference, but the bounds constraint is specified in a geodetic reference, this bounds will be first converted to a bounds in a Mercator grid reference.
In general, this transformation of the bounds to the map's reference may make the bounds larger. For example, a rectangle in longitude-latitude, will not be a rectangle in a reference with a Polar projection, so the area needs to be distorted somewhat. For high accuracy, it is thus best to use specify the bounds in the reference of the Map.
See also Transformation for more information about transforming coordinates between reference systems.

Visual feedback will be shown when the user hits the edges of the constraint during panning. Note that the style of this feedback cannot be modified.

When calling this method and the center of the view is not inside this bounds, the map will fit on this bounds.

To cancel the constraint, call this method with null.

On a 3D map, the constraint is ignored.

On a 2D map, rotation is not possible when there is a constraint.

Returns the current state of the map, so that it can be restored at a later time. Currently this state encompasses a snapshot of the mapToViewTransformation configuration. The returned state object does not have a fixed layout, so accessing properties of the state is not allowed.

The state of the map does not include the state of the individual layers, nor any of the the navigation or scale restrictions.

If you're using a custom map reference, this reference needs to have an identifier when saving the map state. When restoring the saved state, ensure the reference can be retrieved from the ReferenceProvider, using the reference identifier.

Selects a number of objects, passed to this method as an array of PickInfo objects. A PickInfo object is a JavaScript object with two properties: the objects property is an array of the objects that must be selected, the layer property indicates what the layer is these objects are supposed to be in. If you try to select an object that is not available in the layer, a ProgrammingError will be thrown.
Note: You can select features only on a layer that is marked as selectable. Also, objects that do not pass the layer's filter will not be selected either.

Places a balloon on the map. All parameters are optional, but at least ShowBalloonOptions.feature or ShowBalloonOptions.anchor must be provided. If the ShowBalloonOptions.contentProvider option is present it will be used to generate the balloon content. If not, the balloonContentProvider of the layer will be used to generate the balloon content, provided the layer is configured with one. In all other cases, a string representation of the object will be used as the balloon's content.

The balloon can be styled using the following CSS selectors:

• .luciad .lcdBalloon: The balloon's container element. This element is absolutely positioned by LuciadRIA.
• .luciad .lcdBalloon .lcdFrame: A container that wraps the header and the content.
• .luciad .lcdBalloon .lcdHeader: The header of the balloon. Contains the close button.
• .luciad .lcdBalloon .lcdClose: The close button of the balloon.
• .luciad .lcdBalloon .lcdContent: The main content of the balloon.

See @luciad/samples-common-ui/sample-common-style.css for an example usage of these selectors.

Only one balloon instance can be shown at the same time. Consider using labels if you want to show balloons for multiple objects at the same time. Labels support HTML, so they can show the same contents as a balloon. An additional benefit is that labels can be decluttered.

Call this method to show a context menu at the given position.

Event hook that is called when the map comes to rest. For example, this event is fired after the user has finished panning or zooming the map.

Note: This event fires when navigation input stops, but it does not indicate that all data has finished loading or that the screen is fully up-to-date. To wait until all pending work is reflected on screen, use LayerTreeNode.whenReady on RIAMap.layerTree instead.

Event hook that is called when the selection of the map changes.

Event hook that is called when the hover of the map changes.

Event hook that is called when the map extent has changed, for instance by panning or zooming. Note that the MapChange event is fired only once per frame.

Event hook that is called when a balloon opens on the map.

Event hook that is called when a balloon closes on the map.

Event hook that is called when RIAMap.controller changes. Note that:

• controller can be null.
• Changing controllers is delayed when the currently active Controller returns a Promise from its Controller.onDeactivate. The ControllerChanged event will fire once deactivation is complete (ie. the deactivation promise resolves). Only then the new controller becomes active on the map.

Event hook that is called when RIAMap.defaultController changes. Note that:

• defaultController can be null.
• Changing controllers is delayed when the currently active Controller returns a Promise from its Controller.onDeactivate. The DefaultControllerChanged event will fire once deactivation is complete (ie. the deactivation promise resolves). Only then the new controller becomes active on the map.

Event hook that is called when RIAMap.displayScale changes.

Event hook that is called when RIAMap.autoAdjustDisplayScale changes.

An event that is emitted whenever webGPUDevice changes.

webGPUDevice typically changes when the map is initialized (from null to a device) or when the map reboots (from one device to another).

An event that is emitted whenever webGPUContext changes.

webGPUContext typically changes when the map is initialized (from null to a context), when the map reboots (from one context to another), or when the reference is changed.

Called when the reference of this map was changed.

Event hook that is called when RIAMap.wrapAroundWorld changes.

Event hook that is called when any property of RIAMap.gestureDetection changes.

Event hook that is called every frame after the map's layers have been rendered, but before the frame is displayed. This allows you to paint additional content directly on the map's WebGPU canvas in a post-render step.

A depth texture is made available for depth testing. This enables the external content to be immersed in the environment, meaning it will not be painted when it is behind opaque obstacles originating from LuciadRIA layers.

Drawing directly with the Map's WebGPU context, or even delegating that to an external renderer, requires some WebGPU knowledge and is likely much more complex than rendering through regular LuciadRIA layers. Additionally, this rendering approach comes with some limitations that are documented below, which may not make the content behave the way that you want it to. For those reasons, we recommend only using this callback when your use case cannot be achieved by conventional means. For example, when you want to display non-animated 3D content, this can be done with LuciadRIA's 3D icons API instead.

Since this callback is only a post-render step, it is not fully integrated in LuciadRIA's rendering cycle and comes with some limitations:

• Painting always happens after all layers have been painted. In other words, the external content cannot be painted before or in-between LuciadRIA layers. Note that, even though the painting order is fixed, depth testing can still be used to place your content behind objects in LuciadRIA layers.
• LuciadRIA controllers cannot interact with the external content. Because the content is painted directly on the WebGPU context, LuciadRIA is essentially not aware of its existence. This makes it impossible to select the content, for example, or use it as an anchor for panning and zooming.
• Transparent objects from LuciadRIA layers will always appear below the content you paint yourself.
  While depth testing enables you to hide content behind opaque obstacles, the depth buffer does not contain data on transparent obstacles. This means that your content will be painted as though the transparent obstacles are not even there.
  When this situation occurs within or between regular layers, LuciadRIA will blend the colors of the involved objects. This results in a much more natural-looking rendering, as it gives the impression that you're only seeing the object through the transparent obstacle. For content rendered in this post-render step, that color blending is not possible.
• LuciadRIA effects such as lighting and shadows will not be applied to the external content.