IN THIS ARTICLE
Terrain Macro Material Component
The Terrain Macro Material component applies a terrain base color texture to all terrain regions that fall within its volume.
The Terrain Macro Material also depends on at least one Terrain Layer Spawner existing within its volume because this component enhances existing terrain data.
|Color Texture||The image that will be rendered on the terrain.||Texture||None|
|Normal Texture||The texture that will be used as the normal map.||Texture||None|
|Normal Flip X||Set to true to flip the normals about X.||Boolean|
|Normal Flip Y||Set to true to flip the normals about Y.||Boolean|
|Normal Factor||Adjusts the strength of the normal values.||Float|
|Priority||The priority of the macro material data relative to other Terrain Macro Material components. Larger values are higher in priority.||Integer|
|Save Mode||Specify how to choose the path for saving the image after any image edits.|
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.
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.
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.
|Prompts for a save location every time the image is saved.|
|Prompts for a save location the first time the image is saved after loading the level, but on every subsequent save, it automatically overwrites the image in that location.|
|Automatically saves the image with an incrementing number at the end of the name and only prompts for a save location if there is already an existing image with that name.|
For example, if the initially-selected image is
This structure is used when sending out information about the macro material settings.
|m_entityId||The EntityId of the owning entity.|
|m_bounds||The bounds of the region that this macro-material component affects.|
|m_colorImage||The image that should be applied to the terrain.|
|m_normalImage||The normal map to be used in this region.|
|m_normalFlipX||Whether or not the normal map should be flipped about the X axis.|
|m_normalFlipY||Whether or not the normal map should be flipped about the Y axis.|
|m_normalFactor||The strength of the normal map.|
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.
|Returns the ||None||MacroMaterialData||Yes|
|Returns the height/width/depth of the color texture in pixels.||None||RHI::Size||No|
|Returns the number of color texture pixels per meter in world space.||None||Vector2||No|
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.
|Notifies listeners when a new macro material has been created.||None||EntityId; MacroMaterialData||Yes|
|Notifies listeners when a macro material has been changed.||None||EntityId; MacroMaterialData||Yes|
|Notifies listeners when a macro material is removed.||None||EntityId||Yes|
|Notifies listeners when the bounding area of the macro material changes.||None||EntityId; Old Region: Aabb; New Region: Aabb||Yes|
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.
|Start an image modification session.||None||None||No|
|Finish an image modification session.||None||None||No|
|Given a list of world positions, return a list of pixel indices into the image.||positions: The list of positions to query, outIndices: The output list of pixel indices||None||No|
|Get the image pixel values at a list of positions.||positions: The list of positions to query, outValues: The output list of pixel colors||None||No|
|Get the image pixel values at a list of pixel indices.||indices: The list of pixel indices to query, outValues: The output list of pixel colors||None||No|
|Start a series of pixel modifications.||None||None||No|
|Finish a series of pixel modifications.||None||None||No|
|Set the image pixel values at a list of pixel indices.||indices: The list of pixel indices to set the values for, outValues: The list of pixel colors to set||None||No|
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.
|Notify any listeners that a brush stroke has started on the macro color image.||None||None||No|
|Notify any listeners that a brush stroke has ended on the macro color image.||changedDataBuffer: A pointer to the ImageTileBuffer containing the changed data, dirtyRegion: The AABB defining the world space region affected by the brush stroke||None||No|