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 UnigineScript (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:
- Implement your GPU-based terrain modification logic in a function.
- Set this callback function to be fired when a Texture Draw (GPU-based terrain modification) operation is performed by calling the addTextureDrawCallback() method.
- 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
NoticeIn 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:
- 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.
- Upon completion of the copying process a callback function set via the addTextureDrawCallback() method is called. This function modifies the buffer.
- 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
- LandscapeTextures texture - Temporary landscape texture to be released.
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
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:
2022-02-24
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)