Terrain3DStorage
Inherits: Resource < RefCounted < Object
Description
This resource stores all map data for Terrain3D. Also see Controlmap Format and Storage Format Changelog.
Properties
Image[] |
|
|
Image[] |
|
|
Image[] |
|
|
Vector2 |
|
|
Vector2i[] |
|
|
|
||
bool |
|
|
float |
|
Methods
godot.Error |
add_region ( Vector3 global_position, Image[] images=[], bool update=true ) |
godot.Error |
export_image ( String file_name, MapType map_type ) |
void |
force_update_maps ( MapType map_type=3 ) |
Color |
get_color ( Vector3 global_position ) |
int |
get_control ( Vector3 global_position ) |
float |
get_height ( Vector3 global_position ) |
Image |
get_map_region ( MapType map_type, int region_index ) |
Image[] |
|
Image[] |
get_maps_copy ( MapType map_type ) |
Vector3 |
get_mesh_vertex ( int lod, HeightFilter filter, Vector3 global_position ) |
Vector3 |
get_normal ( Vector3 global_position ) |
Color |
|
int |
get_region_count ( ) |
int |
get_region_index ( Vector3 global_position ) |
Vector2i |
get_region_offset ( Vector3 global_position ) |
float |
get_roughness ( Vector3 global_position ) |
Vector3 |
get_texture_id ( Vector3 global_position ) |
bool |
has_region ( Vector3 global_position ) |
void |
import_images ( Image[] images, Vector3 global_position=Vector3(0, 0, 0), float offset=0.0, float scale=1.0 ) |
Image |
layered_to_image ( MapType map_type ) |
Image |
load_image ( String file_name, int cache_mode=0, Vector2 r16_height_range=Vector2(0, 255), Vector2i r16_size=Vector2i(0, 0) ) static |
void |
remove_region ( Vector3 global_position, bool update=true ) |
void |
save ( ) |
void |
set_color ( Vector3 global_position, Color color ) |
void |
set_control ( Vector3 global_position, int control ) |
void |
set_height ( Vector3 global_position, float height ) |
void |
set_map_region ( MapType map_type, int region_index, Image image ) |
void |
|
void |
set_pixel ( MapType map_type, Vector3 global_position, Color pixel ) |
void |
set_roughness ( Vector3 global_position, float roughness ) |
void |
Signals
height_maps_changed ( )
Emitted when the height maps have changed and been regenerated.
maps_edited ( AABB edited_area )
This signal is emitted whenever the editor is used to:
add or remove a region,
alter a region map with a brush tool,
undo or redo any of the above operations.
The parameter contains the axis-aligned bounding box of the area edited.
region_size_changed ( )
Emitted when region_size is changed.
regions_changed ( )
Emitted when any of the maps or regions are modified and regenerated.
Enumerations
enum MapType:
MapType TYPE_HEIGHT = 0
Height map.
MapType TYPE_CONTROL = 1
Control map.
MapType TYPE_COLOR = 2
Color map.
MapType TYPE_MAX = 3
The number of elements in this enum.
enum RegionSize:
RegionSize SIZE_1024 = 1024
Region size is 1024 x 1024 vertices or pixels on maps.
enum HeightFilter:
HeightFilter HEIGHT_FILTER_NEAREST = 0
Samples the height map at the exact coordinates given.
HeightFilter HEIGHT_FILTER_MINIMUM = 1
Samples (1 << lod) * 2 heights around the given coordinates and returns the lowest.
Constants
REGION_MAP_SIZE = 16
Hard coded number of regions on a side. The total number of regions is this squared.
Property Descriptions
Image[] color_maps = []
void set_color_maps ( Image[] value )
Image[] get_color_maps ( )
The Array of Images containing all the color maps for all regions.
Image format: FORMAT_RGBA8, 32-bits per pixel as four 8-bit components.
RGB is used for color, which is multiplied by albedo in the shader. Multiply is a blend mode that only darkens.
A is used for a roughness modifier. A value of 0.5 means no change to the existing texture roughness. Higher than this value increases roughness, lower decreases it.
The setter calls set_maps.
Image[] control_maps = []
void set_control_maps ( Image[] value )
Image[] get_control_maps ( )
The Array of Images containing all the control maps for all regions.
Image format: FORMAT_RF, 32-bit per pixel as full-precision floating-point.
However we interpret these images as format: RenderingDevice.DATA_FORMAT_R32_UINT aka OpenGL RG32UI 32-bit per pixel as unsigned integer. See Control map format.
The setter calls set_maps.
Image[] height_maps = []
void set_height_maps ( Image[] value )
Image[] get_height_maps ( )
The Array of Images containing all the heightmaps for all regions.
Image format: FORMAT_RF, 32-bit per pixel as full-precision floating-point.
Defines the height value of the terrain at a given pixel. This is sent to the vertex shader on the GPU which modifies the mesh in real-time.
Editing is always done in 32-bit. We do provide an option to save as 16-bit, see save_16_bit, which converts to 32-bit on load and back to 16-bit on save.
The setter calls set_maps.
Vector2 height_range = Vector2(0, 0)
void set_height_range ( Vector2 value )
Vector2 get_height_range ( )
The highest and lowest heights for the sculpted terrain. Any Terrain3DMaterial.world_background used that extends the mesh height outside of this range will not change this variable. Also see Terrain3D.render_cull_margin.
Vector2i[] region_offsets = []
void set_region_offsets ( Vector2i[] value )
Vector2i[] get_region_offsets ( )
An array of the active regions in region grid coordinates (+/-8, +/-8). e.g. { (0, 0), (-1, 3), (1, 1) }. It is ordered by the sequence in which regions were created, not by location.
Also see get_region_index which returns the index into this array based on location.
And get_region_offset which converts a location in world space to a region space, which is what is stored in this array. Eg. get_region_offset(Vector3(1500, 0, 1500)) would return (1, 1).
RegionSize region_size = 1024
void set_region_size ( RegionSize value )
RegionSize get_region_size ( )
The number of vertices in each sculptable region, and the number of pixels for each layer in the TextureArrays that store the height, control, and color maps. Limited to 1024 for now. This does not factor in Terrain3D.mesh_vertex_spacing.
bool save_16_bit = false
void set_save_16_bit ( bool value )
bool get_save_16_bit ( )
Heightmaps are loaded and edited in 32-bit. This option converts the file to 16-bit upon saving to reduce file size. This process is lossy.
float version = 0.8
void set_version ( float value )
float get_version ( )
Current version of this storage resource. This is used for upgrading data files and is independent of Terrain3D.version. The file and this variable are updated to the latest version upon saving this resource.
Method Descriptions
godot.Error add_region ( Vector3 global_position, Image[] images=[], bool update=true )
Adds a region for sculpting and painting. This allocates new set of region_size sized image maps in memory and on disk to store sculpting and texture painting data.
If the region already exists and image maps are included, the current maps will be overwritten. This means that if some maps are null, existing maps will be removed.
Parameters:
p_global_position - the world location to place the region, which gets rounded down to the nearest region_size multiple. That means adding a region at (1500, 0, 1500) is the same as adding it at (1024, 0, 1024) when region_size is 1024.
p_images - Optional array of { Height, Control, Color } with region_sized images. See MapType.
p_update - rebuild the maps if true. Set to false if bulk adding many regions, then true on the last one or use force_update_maps.
godot.Error export_image ( String file_name, MapType map_type )
Exports the specified map type as one of r16/raw, exr, jpg, png, webp, res, tres.
R16 or exr are recommended for roundtrip external editing.
R16 can be edited by Krita, however you must know the dimensions and min/max before reimporting. This information is printed to the console.
Res/tres allow storage in any of Godot’s native Image formats.
void force_update_maps ( MapType map_type=3 )
Regenerates the TextureArrays that house the requested map types. Using the default MapType TYPE_MAX(3) will regenerate all map types.
Color get_color ( Vector3 global_position )
Returns the associated pixel on the color map at the requested location. Calls get_pixel.
int get_control ( Vector3 global_position )
Returns the associated pixel on the control map at the requested location. Calls get_pixel.
float get_height ( Vector3 global_position )
Returns the associated pixel on the height map at the requested location. This function is only accurate at vertex coordinates, and on flat areas. It does not currently interpolate heights between vertices, while mesh faces do. Locations between vertices will return the height of the vertex at the floored coordinates. See issue 324.
Returns NAN if the requested position is a hole.
Calls get_pixel.
Image get_map_region ( MapType map_type, int region_index )
Returns the Image for the specified map type and region. E.g. Returns the region_size height map Image at the first defined region 0.
Image[] get_maps ( MapType map_type )
Returns an Array of Images containing all of the regions for the specified map type.
Image[] get_maps_copy ( MapType map_type )
Returns a copy of the Array of Images containing all of the regions for the specified map type.
Vector3 get_mesh_vertex ( int lod, HeightFilter filter, Vector3 global_position )
Returns the location of a terrain vertex at a certain LOD. If there is a hole at the position, it returns NAN in the vector’s Y coordinate.
lod - Determines how many heights around the given global position will be sampled. Range 0 - 8.
filter - Specifies how samples are filtered. See HeightFilter.
global_position - X and Z coordinates of the vertex. Heights will be sampled around these coordinates.
Vector3 get_normal ( Vector3 global_position )
Returns the terrain normal at the specified location. This function uses get_height, which is not currently accurate between vertices. Therefore, this function may also be inacurate between vertices.
Returns Vector3(NAN, NAN, NAN) if the requested position is a hole or outside of defined regions.
Color get_pixel ( MapType map_type, Vector3 global_position )
Returns the pixel for the map type associated with the specified location.
Returns Color(NAN, NAN, NAN, NAN) if the position is outside of defined regions.
int get_region_count ( )
Returns the number of allocated regions.
int get_region_index ( Vector3 global_position )
Returns the index into the region_offsets array for the region associated with the specified location.
Vector2i get_region_offset ( Vector3 global_position )
Converts a world space location to region space. For a region_size of 1024 this basically means global_position/1024.0. Also see region_offsets.
float get_roughness ( Vector3 global_position )
Returns the roughness modifier (wetness) on the color map alpha channel associated with the specified location. Calls set_pixel.
Vector3 get_texture_id ( Vector3 global_position )
Returns a Vector3 with x = base texture id, y = overlay id, z = blend value.
It’s up to you to determine which is visually apparent based on your shader settings, such as height or alpha blending.
This is often used for things like footsteps. Observing how this is done in Witcher 3, there are only about 6 sounds used (snow, foliage, dirt, gravel, rock, wood), and they are not pixel perfect, except for wood. However that is easy to do by detecting if the player is walking on wood meshes. The other 5 sounds are played when the player is in an area where the textures are blending. So it might play rock while over a dirt area, but the end result is still a seamless audio visual experience.
bool has_region ( Vector3 global_position )
Returns true if the specified location has a region allocated.
void import_images ( Image[] images, Vector3 global_position=Vector3(0, 0, 0), float offset=0.0, float scale=1.0 )
Imports an Image set (Height, Control, Color) into this resource. It does NOT normalize values to 0-1. You must do that using get_min_max() and adjusting scale and offset.
images - MapType.TYPE_MAX sized array of Images for Height, Control, Color. Images can be blank or null.
global_position - X,0,Z location on the region map. Valid range is (+/-8192, +/-8192) * Terrain3D.mesh_vertex_spacing.
offset - Add this factor to all height values, can be negative.
scale - Scale all height values by this factor (applied after offset).
Image layered_to_image ( MapType map_type )
Returns an Image of the given map type that contains all regions in one large image. If the world has multiple islands, this function will return an image large enough to encompass all used regions, with black areas in between the islands.
Image load_image ( String file_name, int cache_mode=0, Vector2 r16_height_range=Vector2(0, 255), Vector2i r16_size=Vector2i(0, 0) ) static
Loads a file from disk and returns an Image.
filename - The file name on disk to load. Loads EXR, R16/RAW, PNG, or a ResourceLoader format (jpg, res, tres, etc).
cache_mode - Send this flag to the resource loader to force caching or not.
height_range - Heights for R16 format. x=Min & y=Max value ranges. Required for R16 import.
size - Image dimensions for R16 format. Default (0,0) auto detects size, assuming square images. Required for non-square R16.
void remove_region ( Vector3 global_position, bool update=true )
Removes the region at the specified location from the region_offsets and the height, control, and color map arrays.
void save ( )
Saves this storage resource to disk, if saved as an external .res file, which is the recommended practice.
void set_color ( Vector3 global_position, Color color )
Sets the color on the color map pixel associated with the specified location. Calls set_pixel.
void set_control ( Vector3 global_position, int control )
Sets the value on the control map pixel associated with the specified location. Calls set_pixel.
void set_height ( Vector3 global_position, float height )
Sets the height value on the heightmap pixel associated with the specified location. Calls set_pixel.
void set_map_region ( MapType map_type, int region_index, Image image )
Sets the Image for the specified map type and region. This method calls force_update_maps.
void set_maps ( MapType map_type, Image[] maps )
Sets the Array of Images for the specified map type. This method calls force_update_maps.
void set_pixel ( MapType map_type, Vector3 global_position, Color pixel )
Sets the pixel for the map type associated with the specified location. This method is fine for setting a few pixels, but if you wish to modify thousands of pixels quickly, you should use get_maps or get_map_region and edit the images directly.
After setting pixels you need to call force_update_maps. You may also need to regenerate collision if you don’t have dynamic collision enabled.
void set_roughness ( Vector3 global_position, float roughness )
Sets the roughness modifier (wetness) on the color map alpha channel associated with the specified location. Calls set_pixel.
void update_height_range ( )
Evaluates every height map pixel for every region and updates height_range.