Version: 2019.1
Spatial Mapping Collider
Spatial Mapping low level API

Spatial Mapping Renderer

The Spatial Mapping Renderer component provides a visual representation of Spatial Mapping Surfaces. This is useful for visually debugging Surfaces and adding visual effects to the environment.

The system periodically sends data to the Spatial Mapping Renderer component about changes in physical space. Each time the component is notified of these changes by the Spatial Mapping system, it bakes the returned Surface data into GameObjects that contain both Mesh Filter and Mesh Renderer components. The Spatial Mapping Renderer component manages the lifetime of these Surface GameObjects. This means that it handles creating, updating, and destroying the Surface GameObject Mesh Renderers in the Scene.

Spatial Mapping Renderer component as it appears in the Unity Editor
Spatial Mapping Renderer component as it appears in the Unity Editor

Render Settings

The table below lists all unique Render Settings available for the Spatial Mapping Renderer component.

Setting Description
Render State All Surface GameObjects take their material from the Render State setting. When you change the Render State setting (for example, by script during run time), all Surface GameObjects’ render Materials change to those of the chosen Render State setting. This reduces the number of draw calls, which in turn improves the rendering performance. Using a shared material also reduces the amount of memory used by the application during rendering. Select one of the three options to render Surfaces.

See Using the Spatial Mapping Renderer, below, for more information.
Occlusion Apply the Material defined in Occlusion Material. This is a transparent Material which hides GameObjects behind real world Surfaces. See Using the Spatial Mapping Renderer, below, for more information.

Note: This enables all of a Surface’s Mesh Renderers, overriding any other setting.
Visualisation Apply the Material defined in Visualization Material for visualizing the Spatial Mapping Surfaces (usually a wireframe Material) in your environment. See Using the Spatial Mapping Renderer, below, for more information.

Note: This enables all of a Surface’s Mesh Renderers, overriding any other setting.
None Choose to disable all the Mesh Renderers assigned to the Spatial Mapping Surfaces.
Occlusion Material The material you select here applies when the Spatial Mapping Renderer’s Render State is set to Occlusion. The default is the built-in SpatialMappingOcclusion material.
Visual Material The material you select here is the Visual Material that applies when the Spatial Mapping Renderer Render State is set to Visualization. The default is the built-in SpatialMappingWireframe material.

General Settings

See SpatialMapping General Settings.

Using the Spatial Mapping Renderer

This component provides an easy way to change the material on all generated Surfaces dynamically. Unity provides two pre-built Material types for you to use:

Occlusion Material

This makes the GameObject appear transparent, but holograms are not visible through the GameObject. For example, this might be useful if you require a real-world desk to conceal an in-game holographic object placed underneath it.

Visual Material

This is a wireframe Material that Unity applies to all Surfaces in the Spatial Mapping Renderer component. With the default Wireframe Shader, the colors of the wireframe represent real-world distances. This is usually the most useful option for debugging, but you can also use it for visual effects. The Shader uses color mapping to indicate distance; the table below shows this color mapping:

Distance from HoloLens Color
0 to 1 meters Black
1 to 2 meters Red
2 to 3 meters Green
3 to 4 meters Blue
4 to 5 meters Yellow
5 to 6 meters Cyan
6 to 7 meters Magenta
7 to 8 meters Maroon
8 to 9 meters Teal
9 to 10 meters Orange
10 meters or greater White
The default wireframe Shader used as the Visualization Material in the Spatial Mapping Renderer component (colors in the wireframe represent distances)
The default wireframe Shader used as the Visualization Material in the Spatial Mapping Renderer component (colors in the wireframe represent distances)

When you assign a new Material to either the Visual Material or Occlusion Material, the Material of your Surface GameObjects does not automatically change. To apply the new Material to all Surfaces, you need to set the Render State to the Material you have changed (Visual Material or Occlusion Material).

If you only assign the Occlusion Material or Visual Material properties in Render State from the Unity Editor (directly on the GameObject in your scene), Spatial Mapping destroys them at the same time as the Spatial Mapping Renderer component. However, Spatial Mapping doesn’t destroy any Occlusion or Visual Materials assigned or changed through script with the component, so you will need to destroy them manually.

The code snippet below changes the Material that Spatial Mapping applies to all Surface GameObjects dynamically at run time.


SpatialMappingRenderer renderer = spatialMappingGameObject.AddComponent<SpatialMappingRenderer>();
renderer.visualMaterial = new Material(Shader.Find("VR/SpatialMapping/Wireframe"));
renderer.renderState = SpatialMappingRenderer.RenderState.Visualization;

Surface GameObjects

The Spatial Mapping Renderer component creates its own separate set of Surface GameObjects during run time. These appear in your Scene parented to a Surface Parent GameObject:

Example Surface Parent GameObject and Surface GameObject children
Example Surface Parent GameObject and Surface GameObject children

When a Spatial Mapping Renderer generates Surface GameObjects, they contain the following component

Inspector view of a Surface GameObject generated by a Spatial Mapping Renderer
Inspector view of a Surface GameObject generated by a Spatial Mapping Renderer

If you add multiple Spatial Mapping Renderer components to your Scene, each component generates its own set of Surface GameObjects. For example, if you have two GameObjects with Spatial Mapping Renderer components, then your Scene contains two sets of Surface GameObjects: one generated by each component at run time. This is important to keep in mind for optimization purposes.


  • 2018–05–01 Page published with editorial review

  • Spatial Mapping for Hololens documentation updated in 2017.3

Spatial Mapping Collider
Spatial Mapping low level API