Terrain Macro Material Component

The Terrain Macro Material component applies a terrain base color texture to all terrain regions that fall within its volume.

Provider

Terrain Gem

Dependencies

Terrain World
Terrain World Renderer
Axis Aligned Box Shape

The Terrain Macro Material also depends on at least one Terrain Layer Spawner existing within its volume because this component enhances existing terrain data.

Properties

Usage

The Terrain Macro Material component provides low-fidelity color information to the terrain system within a volume. The color data is used as the only source of color for any portion of the terrain that exists beyond the Detail material render distance defined on the Terrain World Renderer component. Within the Detail material render distance the color data is blended with the terrain detail materials to provide color variation as the detail textures repeat on the surface.

The component also provides optional macro normal information to the terrain system so that distant terrain can have higher quality normals on the lower-poly LODs. The macro normals are difficult to author correctly, so they aren’t recommended for typical use. The macro normals must be in world space and generated at the same terrain scale in all dimensions as the terrain in the O3DE level. If the terrain in O3DE is resized unevenly in any direction, the normals will no longer line up with the terrain geometry and the terrain surface lighting will be incorrect.

You can configure the dimensions of the volume by adjusting the Axis Aligned Box Shape component on the entity. You can assign a color texture and an optional normal texture by dragging texture assets to the Color Texture or Normal Texture fields, or by clicking . When the textures are assigned, you can adjust the direction and magnitude of the normals by using the Normal Flip X and Normal Flip Y toggles, and the Normal Factor slider.

The Terrain Macro Material can exist on the same entity as a Terrain Layer Spawner component if it’s convenient, but this is not a requirement. This component can be used with any world region whether it overlaps multiple spawners, a single spawner, or no spawners at all. The macro material data is applied to any terrain data that appears within its volume and does not render wherever terrain is absent. This flexibility allows the terrain macro material to be authored, loaded, and unloaded at different sizes and resolutions than the rest of the terrain data.

If two Terrain Macro Material volumes overlap, the Priority field dictates which macro material data will be used. Larger values are higher in priority.

Creating a new image

To create a new image, press the Create New Image… button. You will be prompted for an image width and height in pixels, then for a location to save the image. If the image is saved into a source asset directory that is used by the project, the Terrain Macro Material will automatically populate the Color Texture field with the saved image.

Editing an image

To edit an existing color texture, press the Edit button on the Terrain Macro Material component or select the Terrain Macro Material component’s icon in the Component Switcher in the viewport. This will enter Paint Brush mode. Refer to the Paint Brush documentation for more details on how to use the Paint Brush.

After editing is complete, end the Paint Brush mode by pressing Esc, pressing the Done button on the Terrain Macro Material component, or by selecting a different component’s icon in the Component Switcher in the viewport. At this point, the image changes will be saved, re-processed by the Asset Processor, and reloaded when processing is complete.

The Save Mode determines where the image will be saved.

MacroMaterialData

This structure is used when sending out information about the macro material settings.

TerrainMacroMaterialRequestBus

The TerrainMacroMaterialRequestBus is an internal system bus that is only intended for communication between the terrain rendering and editing systems and the Terrain Macro Material component. Other systems generally do not need to use this EBus since nothing outside the terrain system should need any information from the individual component instances. However, if a use case arises, the following request functions on the TerrainMacroMaterialRequestBus EBus interface can be used to query individual Terrain Macro Material components.

TerrainMacroMaterialNotificationBus

The TerrainMacroMaterialNotificationBus is an internal EBus used by the terrain rendering and editing systems to monitor changes to Terrain Macro Materials. Other systems generally do not need to use this EBus since nothing outside the terrain system should need any information about individual Terrain Macro Materials. However, if a use case arises, the following notification functions on the TerrainMacroMaterialNotificationBus EBus interface can be used to monitor Terrain Macro Material changes.

TerrainMacroColorModificationBus

The TerrainMacroColorModificationBus is an internal EBus used by the terrain editing systems to modify the Terrain Macro Material color texture. This is a lower-level API, most systems should use the higher-level Paint Brush painting API to modify the texture.

TerrainMacroColorModificationNotificationBus

The TerrainMacroColorModificationNotificationBus is an internal EBus used by the terrain editing systems to modify the Terrain Macro Material color texture. This is a lower-level API, most systems should use the higher-level Paint Brush painting API to modify the texture.