This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Landscape Class

Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

This class is used to manage landscape terrain rendering and modification.

Terrain modification is performed in asynchronous mode on GPU side by calling a corresponding method, that commences a drawing operation. When calling such a method you should specify the GUID of an .lmap file landscape layer map to be modified, the coordinates of the upper-left corner and the resolution of the segment of data to be modified, you should also define which data layers are to be affected (heights, albedo, masks) via a set of flags. The operation itself is to be implemented inside a callback handler.

GPU-Based Terrain Modification#

The workflow is as follows:

  1. Implement your GPU-based terrain modification logic in a function.
  2. Set this callback function to be fired when a Texture Draw (GPU-based terrain modification) operation is performed by calling the addTextureDrawCallback() method.
  3. Commence a GPU drawing operation by calling the asyncTextureDraw() method. Here you should specify the GUID of an .lmap file landscape layer map to be modified, the coordinates of the upper-left corner and the resolution of the segment of data to be modified, you should also define which data layers are to be affected (heights, albedo, masks) via a set of flags
    Notice
    In case your modification requires additional data beyond the specified area as well as the data of other landscape layer maps (e.g. a copy brush) you can enable force loading of required data, in this case you should use this overload of the asyncTextureDraw() method.
Source code (C++)
// GPU-based modification
void my_texture_draw(UGUID guid, int id, LandscapeTexturesPtr buffer, ivec2 coord, int data_mask)
{
	// getting a built-in "cirle_soft" Editor's brush
	MaterialPtr mat = Materials::findMaterial("circle_soft");

	if (mat) {
		// setting necessary textures (e.g., albedo and heights)
		mat->setTexture("terrain_albedo", buffer->getAlbedo());
		mat->setTexture("terrain_height", buffer->getHeight());
		
		// setting up brush material parameters (size, color, etc. and specifying masks to be affected by the brush)
		mat->setParameterFloat("size", 100.0f);
		mat->setParameterFloat("height", 10.0f);
		mat->setParameterFloat4("color", vec4::RED);
		mat->setParameterInt("data_mask", Landscape::FLAGS_DATA_ALBEDO | Landscape::FLAGS_DATA_HEIGHT);

		// running material's "brush" expression
		mat->runExpression("brush", buffer->getResolution().x, buffer->getResolution().y);
		
		// resetting material textures
		mat->setTexture("terrain_albedo", nullptr);
		mat->setTexture("terrain_height", nullptr);
	}
}

// ... 

virtual int AppWorldLogic::init()
{
	// adding a callback to be fired on a Texture Draw operation
	Landscape::addTextureDrawCallback(MakeCallback(my_texture_draw));
	
	// getting an existing landscape terrain object named "MyTerrain" from the world
	ObjectLandscapeTerrainPtr terrain = checked_ptr_cast<ObjectLandscapeTerrain>(World::getNodeByName("MyTerrain"));
	
	// getting the first layermap that we're going to modify
	LandscapeLayerMapPtr lmap = checked_ptr_cast<LandscapeLayerMap>(terrain->getChild(0));
	
	// generating a new ID for the draw operation
	int id =Landscape::generateOperationID();

	// user's code (bounding to ID)
	
	// commencing a Texture Draw operation for the selected landscape map at (1, 1) with the size of [32 x 32]
	Landscape::asyncTextureDraw(id, lmap->getGUID(), ivec2(1, 1), ivec2(32, 32), ~0);

	return 1;
}

// ...

virtual int shutdown()
{
	// clearing callbacks
	Landscape::clearTextureDrawCallbacks();

	return 1;
}

And the process:

  1. After commencing of a terrain modification operation with all necessary parameters specified, the Engine copies a fragment of terrain data from the specified landscape layer map file at the specified coordinates to a buffer (LandscapeTextures) of the specified resolution.
  2. Upon completion of the copying process a callback function set via the addTextureDrawCallback() method is called. This function modifies the buffer.
  3. After this selected data layers of the modified buffer are pasted back to the landscape layer map file.

Landscape Class

Members


LandscapeTextures getTemporaryTexture ( ivec2 resolution ) #

Returns a fragment of terrain data as a LandscapeTextures of the specified resolution.

Arguments

  • ivec2 resolution - Resolution of a temporary texture to be obtained.

Return value

LandscapeTextures instance containing a fragment of terrain data.

void releaseTemporaryTexture ( LandscapeTextures texture ) #

Releases the specified temporary texture.

Arguments

int terrainLoad ( WorldBoundBox bb ) #

Loads terrain data (tiles) for all landscape layer maps within the specified bounding box to cache.

Arguments

  • WorldBoundBox bb - Bounding box, defining landscape layer maps for which the data is to be loaded.

Return value

1 if terrain data was successfully loaded for all landscape layer maps within the specified bounding box; otherwise, 0.

void asyncApplyDiff ( int operation_id, UGUID guid, string path ) #

Applies the state of the landscape layer map stored in the specified file to the landscape layer map file with the specified GUID.

Arguments

  • int operation_id - Operation ID.
  • UGUID guid - GUID of the landscape layer map file to which a state stored at the specified path is to be applied.
  • string path - Path to a file where the current landscape map modification state is stored.

void asyncApplyDiff ( UGUID guid, string path ) #

Applies the state of the landscape layer map stored in the specified file to the landscape layer map file with the specified GUID.

Arguments

  • UGUID guid - GUID of the landscape layer map file to which a state stored at the specified path is to be applied.
  • string path - Path to a file where the current landscape map modification state is stored.

void asyncSaveFile ( int operation_id, UGUID file_guid ) #

Saves the landscape layer map file with the specified GUID.

Arguments

  • int operation_id - Operation ID.
  • UGUID file_guid - GUID of the landscape layer map file.

void asyncSaveFile ( UGUID file_guid ) #

Saves the landscape layer map file with the specified GUID.

Arguments

  • UGUID file_guid - GUID of the landscape layer map file.

void asyncSaveFile ( int operation_id, UGUID guid, string path_new_state, string path_old_state ) #

Saves the specified landscape layer map file applying all changes along with saving old and new states (diff) to temporary files. These temporary files can be used to perform undo/redo operations via the applyDiff() method.

Arguments

  • int operation_id - Operation ID.
  • UGUID guid - GUID of the landscape layer map file.
  • string path_new_state - Path to a file to store the new landscape layer map state.
  • string path_old_state - Path to a file to store the old landscape layer map state.

void asyncSaveFile ( UGUID guid, string path_new_state, string path_old_state ) #

Saves the specified landscape layer map file applying all changes along with saving old and new states (diff) to temporary files. These temporary files can be used to perform undo/redo operations via the applyDiff() method.

Arguments

  • UGUID guid - GUID of the landscape layer map file.
  • string path_new_state - Path to a file to store the new landscape layer map state.
  • string path_old_state - Path to a file to store the old landscape layer map state.

int isFilesClosed ( ) #

Returns a value indicating if .lmap files for all landscape layer maps are closed. Call this method before making any changes (modification, deletion, renaming) to .lmap files of the landscape terrain object to ensure that these files are not currently used by the Engine to avoid conflicts. If not, you can use the filesClose() method co close them.

Return value

1 if .lmap files for all landscape layer maps are closed; otherwise, 0.

void filesClose ( ) #

Closes .lmap files for all landscape layer maps. This method should be called before making any changes (modification, deletion, renaming) to .lmap files of the landscape terrain object to avoid conflicts, as these files are streamed continuosly by the Engine. Thus, by calling this method you inform the Engine that it should stop streaming terrain data. As you're done with modification you should call the filesOpen() method to resume streaming operations.

void filesOpen ( ) #

Opens .lmap files for all landscape layer maps. This method should be called after making any changes (modification, deletion, renaming) to .lmap files of the landscape terrain object. Prior to making such modifications the filesClose() method should be called.

ObjectLandscapeTerrain getActiveTerrain ( ) #

Returns the current active Landscape Terrain object.
Notice
If a scene contains multiple Landscape Terrain objects, only one of them can be active (rendered).

Return value

Landscape Terrain object that is currently active.

int generateOperationID ( ) #

Generates a new ID for the operation. This ID is used to manage operations.
Source code (C++)
int id = Landscape::generateOperationID();
// user's code (bounding to ID)
Landscape::asyncTextureDraw(id, file_guid, coord, resolution, flags_file_data);

Return value

New operation ID.
Last update: 2020-07-31
Build: ()