Unigine::Landscape Class

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
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 the desired brush material (built - in "cirle_soft" Editor's brush)
	// and inheriting a child material from it
	auto file_guid = FileSystem::getGUID(FileSystem::resolvePartialVirtualPath("circle_soft.brush"));
	if (!file_guid.isValid())
	{
		Log::warning("LandscapePainter::init(): can not find \"circle_soft.brush\" material\n");
		return;
	}

	MaterialPtr brush_material = Materials::findMaterialByFileGUID(file_guid)->inherit();

	// setting necessary textures (e.g., albedo and heights)
	brush_material->setTexture("terrain_albedo", buffer->getAlbedo());
	brush_material->setTexture("terrain_height", buffer->getHeight());

	// setting up brush material parameters (size, color, etc. and specifying masks to be affected by the brush)
	brush_material->setParameterFloat("size", 100.0f);
	brush_material->setParameterFloat("height", 10.0f);
	brush_material->setParameterFloat4("color", vec4_green);
	brush_material->setParameterInt("data_mask", data_mask);

	// running material's "brush" expression
	brush_material->runExpression("brush", buffer->getResolution().x, buffer->getResolution().y);

	// resetting material textures
	brush_material->setTexture("terrain_albedo", nullptr);
	brush_material->setTexture("terrain_height", nullptr);

}

// ... 

int AppWorldLogic::init()
{
	// getting an existing landscape terrain object
	ObjectLandscapeTerrainPtr terrain = Landscape::getActiveTerrain();

	// getting the first layermap that we're going to modify
	LandscapeLayerMapPtr lmap = checked_ptr_cast<LandscapeLayerMap> (terrain->getChild(0));

	// adding a callback to be fired on a Texture Draw operation
	Landscape::addTextureDrawCallback(MakeCallback(my_texture_draw));
	
	// 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), Landscape::FLAGS_DATA_HEIGHT | Landscape::FLAGS_DATA_ALBEDO);

	return 1;
}

// ...

 int AppWorldLogic::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.

Usage Example: Brush Editor#

Below is a C++ component implementing brush-based Landscape Terrain modification.

LandscapeBrush.h

#pragma once

#include <UnigineComponentSystem.h>
#include <UniginePlayers.h>
class LandscapeBrush :
	public Unigine::ComponentBase
{
public:
	COMPONENT_DEFINE(LandscapeBrush, Unigine::ComponentBase);
	COMPONENT_INIT(init);
	COMPONENT_UPDATE(update);
	COMPONENT_SHUTDOWN(shutdown);

	PROP_PARAM(Float, brush_size, 10.0f, "Brush Size");
	PROP_PARAM(Float, brush_height, 1.0f, "Brush Height");

private:
	void init();
	void update();
	void shutdown();
	void my_texture_draw(Unigine::UGUID guid, int id, Unigine::LandscapeTexturesPtr buffer, Unigine::Math::ivec2 coord, int data_mask);
	Unigine::LandscapeLayerMapPtr lmap;
	Unigine::PlayerPtr player;
	Unigine::LandscapeFetchPtr landscape_fetch;
	Unigine::MaterialPtr brush_material;

LandscapeBrush.cpp

#include "LandscapeBrush.h"
#include <UnigineGame.h>
REGISTER_COMPONENT(LandscapeBrush);

using namespace Unigine;
using namespace Math;

// GPU-based modification
void LandscapeBrush::my_texture_draw(UGUID guid, int id, LandscapeTexturesPtr buffer, Math::ivec2 coord, int data_mask)
{
	// setting necessary textures (e.g., albedo and heights)
	brush_material->setTexture("terrain_albedo", buffer->getAlbedo());
	brush_material->setTexture("terrain_height", buffer->getHeight());

	// setting up brush material parameters (size, color, etc. and specifying masks to be affected by the brush)
	brush_material->setParameterFloat("size", brush_size);
	brush_material->setParameterFloat("height", brush_height);
	brush_material->setParameterFloat4("color", Math::vec4_green);
	brush_material->setParameterInt("data_mask", data_mask);

	// running material's "brush" expression
	brush_material->runExpression("brush", buffer->getResolution().x, buffer->getResolution().y);

	// resetting material textures
	brush_material->setTexture("terrain_albedo", nullptr);
	brush_material->setTexture("terrain_height", nullptr);
}

void LandscapeBrush::init()
{
	// getting the desired brush material (built - in "cirle_soft" Editor's brush) and inheriting a child material from it
	auto guid = FileSystem::getGUID(FileSystem::resolvePartialVirtualPath("circle_soft.brush"));
	if (!guid.isValid())
	{
		Log::warning("LandscapePainter::init(): can not find \"circle_soft.brush\" material\n");
		return;
	}

	brush_material = Materials::findMaterialByFileGUID(guid)->inherit();

	// getting an existing landscape terrain object
	ObjectLandscapeTerrainPtr terrain = Landscape::getActiveTerrain();

	// getting the first layermap that we're going to modify
	lmap = checked_ptr_cast<LandscapeLayerMap>(terrain->getChild(0));

	// adding a callback to be fired on a Texture Draw operation
	Landscape::addTextureDrawCallback(MakeCallback(this, &LandscapeBrush::my_texture_draw));

	// setting the mouse handling mode to USER to display the cursor on the screen
	ControlsApp::setMouseHandle(Input::MOUSE_HANDLE_USER);
	
	// Getting the current player
	player = Game::getPlayer();

	return;
}

void LandscapeBrush::update()
{
	// Write here code to be called before updating each render frame: specify all graphics-related functions you want to be called every frame while your application executes.
	// if right mouse button is clicked
	if (Input::isMouseButtonDown(Input::MOUSE_BUTTON_RIGHT))
	{
		landscape_fetch = LandscapeFetch::create();

		// getting direction from the current mouse position
		Math::ivec2 mouse = Input::getMousePosition();
		Math::Vec3 dir = Math::Vec3(player->getDirectionFromMainWindow(mouse.x, mouse.y));
		// fetching the coordinates of the point of intersection
		bool fetched = landscape_fetch->intersectionForce(player->getPosition(),
			player->getPosition() + Vec3(dir) * 10000.0);

		if (fetched)
		{
			// getting the local position of the brush relative to the layer map
			Vec3 brush_local_position = lmap->getIWorldTransform() * landscape_fetch->getPosition();

			// calculating the bound of the layer map area to be affected by the brush
			float half_size = brush_size / 2.0f;
			Vec3 brush_local_corners[4] = {
				brush_local_position + Vec3(-half_size, -half_size, 0.0),
				brush_local_position + Vec3(half_size, -half_size, 0.0),
				brush_local_position + Vec3(-half_size,  half_size, 0.0),
				brush_local_position + Vec3(half_size,  half_size, 0.0)
			};
			auto brush_local_bbox_min = Vec2{
				min(min(brush_local_corners[0].x, brush_local_corners[1].x), min(brush_local_corners[2].x, brush_local_corners[3].x)),
				min(min(brush_local_corners[0].y, brush_local_corners[1].y), min(brush_local_corners[2].y, brush_local_corners[3].y))
			};
			auto brush_local_bbox_max = Vec2{
				max(max(brush_local_corners[0].x, brush_local_corners[1].x), max(brush_local_corners[2].x, brush_local_corners[3].x)),
				max(max(brush_local_corners[0].y, brush_local_corners[1].y), max(brush_local_corners[2].y, brush_local_corners[3].y))
			};

			// calculating the number of pixels per unit length
			auto pixels_per_unit = Vec2{ lmap->getResolution() } / Vec2{ lmap->getSize() };

			// calculating the coordinates and the size of the region or the landscape layer texture to be modified
			auto drawing_region_coord = ivec2{ pixels_per_unit * brush_local_bbox_min };
			auto drawing_region_size = ivec2{ pixels_per_unit * (brush_local_bbox_max - brush_local_bbox_min) };

			// user's code (bounding to ID)
			auto id = Landscape::generateOperationID();

			// commencing a Texture Draw operation for the selected landscape map for the region with the specified coords and size
			// affecting Height and Albedo data
			Landscape::asyncTextureDraw(id, lmap->getGUID(), drawing_region_coord,
				drawing_region_size, Landscape::FLAGS_DATA_HEIGHT | Landscape::FLAGS_DATA_ALBEDO);
		}

	}
	return;
}

void LandscapeBrush::shutdown()
{
	// clearing callbacks
	Landscape::clearTextureDrawCallbacks();

	return;
}

功能列表:

Name	说明/描述 View: Sort by:
isFilesClosed	Returns a value indicating if .lmap files for all landscape layer maps are closed.
getTemporaryTexture	Returns a fragment of terrain data as a LandscapeTextures of the specified resolution.
releaseTemporaryTexture	Releases the specified temporary texture.
terrainLoad	Loads terrain data (tiles) for all landscape layer maps within the specified bounding box to cache.
render	Renders the area of the specified landscape layer maps defined by the specified transform and texel size, to the specified buffers.
asyncTextureDraw	Commences an asynchronous GPU-based drawing operation with forced pre-loading of terrain data within the specified bounding box (all landscape layer maps).
asyncApplyDiff	Applies the state of the landscape layer map stored in the specified file to the landscape layer map file with the specified GUID.
asyncSaveFile	Saves the landscape layer map file with the specified GUID.
filesClose	Closes .lmap files for all landscape layer maps.
filesOpen	Opens .lmap files for all landscape layer maps.
getActiveTerrain	Returns the current active Landscape Terrain object.
addTextureDrawCallback	Adds a callback function to be called when a Texture Draw (GPU-based terrain modification) operation is performed.
removeTextureDrawCallback	Removes the specified callback from the list of texture draw callbacks.
clearTextureDrawCallback	Clears all added texture draw callbacks.
addApplyDiffCallback	Adds a callback function to be called on applying a diff to the landscape layer map file.
removeApplyDiffCallback	Removes the specified callback from the list of apply diff callbacks.
clearApplyDiffCallback	Clears all added apply diff callbacks.
addSaveFileCallback	Adds a callback function to be called on applying changes made to a landscape layer map file and saving old and new states to temporary files.
removeSaveFileCallback	Removes the specified callback from the list of save file callbacks.
clearSaveFileCallback	Clears all added save file callbacks.
generateOperationID	Generates a new ID for the operation.

Landscape Class

Enums

TYPE_DATA#

Name	说明/描述
TYPE_DATA_HEIGHT = 0	Heights data type.
TYPE_DATA_ALBEDO = 1	Albedo data type.
TYPE_DATA_MASK_0 = 2	Mask0 data type.
TYPE_DATA_MASK_1 = 3	Mask1 data type.
TYPE_DATA_MASK_2 = 4	Mask2 data type.
TYPE_DATA_MASK_3 = 5	Mask3 data type.
TYPE_DATA_MASK_4 = 6	Mask4 data type.
TYPE_DATA_MASK_5 = 7	Mask5 data type.
TYPE_DATA_MASK_6 = 8	Mask6 data type.
TYPE_DATA_MASK_7 = 9	Mask7 data type.
TYPE_DATA_MASK_8 = 10	Mask8 data type.
TYPE_DATA_MASK_9 = 11	Mask9 data type.
TYPE_DATA_MASK_10 = 12	Mask10 data type.
TYPE_DATA_MASK_11 = 13	Mask11 data type.
TYPE_DATA_MASK_12 = 14	Mask12 data type.
TYPE_DATA_MASK_13 = 15	Mask13 data type.
TYPE_DATA_MASK_14 = 16	Mask14 data type.
TYPE_DATA_MASK_15 = 17	Mask15 data type.
TYPE_DATA_MASK_16 = 18	Mask16 data type.
TYPE_DATA_MASK_17 = 19	Mask17 data type.
TYPE_DATA_MASK_18 = 20	Mask18 data type.
TYPE_DATA_MASK_19 = 21	Mask19 data type.

FLAGS_DATA#

Name	说明/描述
FLAGS_DATA_HEIGHT = 1 << 0	Heights data flag.
FLAGS_DATA_ALBEDO = 1 << 1	Albedo data flag.
FLAGS_DATA_MASK_0 = 1 << 2	Mask0 data flag.
FLAGS_DATA_MASK_1 = 1 << 3	Mask1 data flag.
FLAGS_DATA_MASK_2 = 1 << 4	Mask2 data flag.
FLAGS_DATA_MASK_3 = 1 << 5	Mask3 data flag.
FLAGS_DATA_MASK_4 = 1 << 6	Mask4 data flag.
FLAGS_DATA_MASK_5 = 1 << 7	Mask5 data flag.
FLAGS_DATA_MASK_6 = 1 << 8	Mask6 data flag.
FLAGS_DATA_MASK_7 = 1 << 9	Mask7 data flag.
FLAGS_DATA_MASK_8 = 1 << 10	Mask8 data flag.
FLAGS_DATA_MASK_9 = 1 << 11	Mask9 data flag.
FLAGS_DATA_MASK_10 = 1 << 12	Mask10 data flag.
FLAGS_DATA_MASK_11 = 1 << 13	Mask11 data flag.
FLAGS_DATA_MASK_12 = 1 << 14	Mask12 data flag.
FLAGS_DATA_MASK_13 = 1 << 15	Mask13 data flag.
FLAGS_DATA_MASK_14 = 1 << 16	Mask14 data flag.
FLAGS_DATA_MASK_15 = 1 << 17	Mask15 data flag.
FLAGS_DATA_MASK_16 = 1 << 18	Mask16 data flag.
FLAGS_DATA_MASK_17 = 1 << 19	Mask17 data flag.
FLAGS_DATA_MASK_18 = 1 << 20	Mask18 data flag.
FLAGS_DATA_MASK_19 = 1 << 21	Mask19 data flag.

TYPE_FILE_DATA#

File data types.

Name	说明/描述
TYPE_FILE_DATA_HEIGHT = 0	Landscape map file heights data.
TYPE_FILE_DATA_ALBEDO = 1	Landscape map file albedo data.
TYPE_FILE_DATA_MASK_0 = 2	Landscape map file detail mask data (masks with indices 0, 1, 2, 3).
TYPE_FILE_DATA_MASK_1 = 3	Landscape map file detail mask data (masks with indices 4, 5, 6, 7).
TYPE_FILE_DATA_MASK_2 = 4	Landscape map file detail mask data (masks 8, 9, 10, 11).
TYPE_FILE_DATA_MASK_3 = 5	Landscape map file detail mask data (masks with indices 12, 13, 14, 15).
TYPE_FILE_DATA_MASK_4 = 6	Landscape map file detail mask data (masks with indices 16, 17, 18, 19).
TYPE_FILE_DATA_OPACITY_HEIGHT = 7	Landscape map file height opacity data.
TYPE_FILE_DATA_OPACITY_MASK_0 = 8	Landscape map file detail mask opacity data (masks with indices 0, 1, 2, 3).
TYPE_FILE_DATA_OPACITY_MASK_1 = 9	Landscape map file detail mask opacity data (masks with indices 4, 5, 6, 7).
TYPE_FILE_DATA_OPACITY_MASK_2 = 10	Landscape map file detail mask opacity data (masks with indices 8, 9, 10, 11).
TYPE_FILE_DATA_OPACITY_MASK_3 = 11	Landscape map file detail mask opacity data (masks with indices 12, 13, 14, 15).
TYPE_FILE_DATA_OPACITY_MASK_4 = 12	Landscape map file detail mask opacity data (masks with indices 16, 17, 18, 19).

FLAGS_FILE_DATA#

File data layer flags.

Name	说明/描述
FLAGS_FILE_DATA_HEIGHT = 1 << 0	Landscape map file height data.
FLAGS_FILE_DATA_ALBEDO = 1 << 1	Landscape map file albedo data.
FLAGS_FILE_DATA_MASK_0 = 1 << 2	Landscape map file first masks data block (masks with indices 0,1,2,3).
FLAGS_FILE_DATA_MASK_1 = 1 << 3	Landscape map file second masks data block (masks with indices 4,5,6,7).
FLAGS_FILE_DATA_MASK_2 = 1 << 4	Landscape map file third masks data block (masks with indices 8,9,10,11).
FLAGS_FILE_DATA_MASK_3 = 1 << 5	Landscape map file fourth masks data block (masks with indices 12,13,14,15).
FLAGS_FILE_DATA_MASK_4 = 1 << 6	Landscape map file fifth masks data block (masks with indices 16,17,18,19).
FLAGS_FILE_DATA_OPACITY_HEIGHT = 1 << 7	Landscape map file height opacity data.
FLAGS_FILE_DATA_OPACITY_MASK_0 = 1 << 8	Landscape map file first masks opacity data block (for masks with indices 0,1,2,3).
FLAGS_FILE_DATA_OPACITY_MASK_1 = 1 << 9	Landscape map file second masks opacity data block (for masks with indices 4,5,6,7).
FLAGS_FILE_DATA_OPACITY_MASK_2 = 1 << 10	Landscape map file third masks opacity data block (for masks with indices 8,9,10,11).
FLAGS_FILE_DATA_OPACITY_MASK_3 = 1 << 11	Landscape map file fourth masks opacity data block (for masks with indices 12,13,14,15).
FLAGS_FILE_DATA_OPACITY_MASK_4 = 1 << 12	Landscape map file fifth masks opacity data block (for masks with indices 16,17,18,19).

COMPRESSOR_TYPE#

Compression method used for the layer map.

Name	说明/描述
COMPRESSOR_TYPE_NONE = 0	No compression is used.
COMPRESSOR_TYPE_JACKALLESS = 1	Our Method compression is used. It is optimized for compressing 2D and 3D textures and provides better results than LZ4 and Zlib without deteriorating the quality.
COMPRESSOR_TYPE_LZ4 = 2	LZ4 compression is used (temporary option, planned to be removed in the upcoming releases).
COMPRESSOR_TYPE_ZLIB = 3	Zlib compression (can provide up to 2 times higher compression ratio, but takes up to 20 times longer).

BLENDING_MODE#

Blending mode used for the layer map.

Name	说明/描述
ALPHA_BLEND = 0	Alpha blending mode - the colors of the layer map and the underlying one are blended.
ADDITIVE = 1	Additive blending mode - data of the layer map is added atop of the data of underlying maps.
OVERLAY = 2	Overlay blending mode - data of the layer map replaces the data of underlying maps.
MULTIPLICATIVE = 3	Multiplicative blending mode - albedo colors of the underlying map are multiplied by the colors of the layer map.

Members

Ptr<LandscapeTextures> getTemporaryTexture ( const Math::ivec2 & resolution ) #

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

Arguments

const Math::ivec2 & resolution - Resolution of a temporary texture to be obtained.

Return value

LandscapeTextures instance containing a fragment of terrain data.

void releaseTemporaryTexture ( const Ptr<LandscapeTextures> & texture ) #

Releases the specified temporary texture.

Arguments

const Ptr<LandscapeTextures> & texture - Temporary landscape texture to be released.

bool terrainLoad ( const Math::WorldBoundBox & bb ) #

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

Arguments

const Math::WorldBoundBox & bb - Bounding box, defining landscape layer maps for which the data is to be loaded.

Return value

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

bool render ( const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size ) #

Renders the area of the specified landscape layer maps defined by the specified transform and texel size, to the specified buffers.

Arguments

const Ptr<LandscapeTextures> & buffers - Target texture buffers to which the specified landscape layer maps are to be rendered.
const Math::Mat4 & transform - Transformation of the landscape terrain area to be rendered (Z-coordinate is ignored).
Math::Scalar texel_size - Texel size to be used. Defines the size of the area depending on the buffers resolution.

Return value

true if the data of the landscape terrain area (all landscape layer maps) defined by the specified transformation and texel size, was successfully rendered to the specified buffers; otherwise, false.

bool render ( const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size, int padding ) #

Renders the area of the specified landscape layer maps defined by the specified transform and texel size, to the specified buffers. Use the padding parameter to set inner padding size for the area (when necessary).

Arguments

const Ptr<LandscapeTextures> & buffers - Target texture buffers to which the specified landscape layer maps are to be rendered.
const Math::Mat4 & transform - Transformation of the landscape terrain area to be rendered (Z-coordinate is ignored).
Math::Scalar texel_size - Texel size to be used. Defines the size of the area depending on the buffers resolution.
int padding - Inner padding size for the area to be rendered (if necessary).

Return value

true if the data of the landscape terrain area (all landscape layer maps) defined by the specified transformation and texel size, was successfully rendered to the specified buffers; otherwise, false.

bool render ( const Vector< Ptr<LandscapeLayerMap> > & maps, const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size ) #

Arguments

const Vector< Ptr<LandscapeLayerMap> > & maps - List of the landscape layer maps to be rendered.
const Ptr<LandscapeTextures> & buffers - Target texture buffers to which the specified landscape layer maps are to be rendered.
const Math::Mat4 & transform - Transformation of the landscape terrain area to be rendered (Z-coordinate is ignored).
Math::Scalar texel_size - Texel size to be used. Defines the size of the area depending on the buffers resolution.

Return value

true if the data of the landscape terrain area (specified landscape layer maps) defined by the specified transformation and texel size, was successfully rendered to the specified buffers; otherwise, false.

bool render ( const Vector< Ptr<LandscapeLayerMap> > & maps, const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size, int padding ) #

Arguments

const Vector< Ptr<LandscapeLayerMap> > & maps - List of the landscape layer maps to be rendered.
const Ptr<LandscapeTextures> & buffers - Target texture buffers to which the specified landscape layer maps are to be rendered.
const Math::Mat4 & transform - Transformation of the landscape terrain area to be rendered (Z-coordinate is ignored).
Math::Scalar texel_size - Texel size to be used. Defines the size of the area depending on the buffers resolution.
int padding - Inner padding size for the area to be rendered.

Return value

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data, const Vector< Math::WorldBoundBox > & bounds_preload ) #

Commences an asynchronous GPU-based drawing operation with forced pre-loading of terrain data within the specified bounding box (all landscape layer maps). The drawing operation represents modification of the texture buffer of the specified size taken at specified coordinates and combining data layers defined by the specified flags. The operation itself is to be implemented in the TextureDrawCallback handler. This method can be used for implementing GPU-based terrain modification (e.g. brushes) that requires additional data beyond the area specified by coords and resolution parameters as well as the data of other landscape layer maps (e.g. a copy brush).

Arguments

int operation_id - Draw operation ID.
const UGUID & guid - GUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.
int flags_file_data - Data layer mask. A combination of FLAGS_FILE_DATA_* flags indicating data layers to be affected (heights, albedo, certain masks).
const Vector< Math::WorldBoundBox > & bounds_preload - Bounding box (world) specifying the area containing terrain tiles (all landscape layer maps) to be loaded to memory prior to making modifications.

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data ) #

Commences an asynchronous GPU-based drawing operation. The drawing operation represents modification of the texture buffer of the specified size taken at specified coordinates and combining data layers defined by the specified flags. The operation itself is to be implemented in the TextureDrawCallback handler. This method can be used for implementing GPU-based terrain modification (e.g. brushes).

Arguments

int operation_id - Draw operation ID.
const UGUID & guid - GUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.
int flags_file_data - Data layer mask. A combination of FLAGS_FILE_DATA_* flags indicating data layers to be affected (heights, albedo, certain masks).

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution ) #

Commences an asynchronous GPU-based drawing operation. The drawing operation represents modification of the texture buffer of the specified size taken at specified coordinates and combining all data layers. The operation itself is to be implemented in the TextureDrawCallback handler. This method can be used for implementing GPU-based terrain modification (e.g. brushes).

Arguments

int operation_id - Draw operation ID.
const UGUID & guid - GUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data, const Vector< Math::WorldBoundBox > & bounds_preload ) #

Arguments

const UGUID & guid - GUIGUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.
int flags_file_data - Data layer mask. A combination of FLAGS_FILE_DATA_* flags indicating data layers to be affected (heights, albedo, certain masks).
const Vector< Math::WorldBoundBox > & bounds_preload - Bounding box (world) specifying the area containing terrain tiles (all landscape layer maps) to be loaded to memory prior to making modifications.

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data ) #

Arguments

const UGUID & guid - GUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.
int flags_file_data - Data layer mask. A combination of FLAGS_FILE_DATA_* flags indicating data layers to be affected (heights, albedo, certain masks).

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution ) #

Commences an asynchronous GPU-based drawing operation. The drawing operation represents modification of the texture buffer of the specified size taken at specified coordinates and combining all data layers. The operation itself is to be implemented in the TextureDrawCallback handler. This method can be used for implementing GPU-based terrain modification (e.g. brushes).

Arguments

const UGUID & guid - GUID of the landscape layer map file to be modified.
const Math::ivec2 & coord - Coordinates of the upper left corner of the landscape layer map data segment to be modified along the X and Y axes.
const Math::ivec2 & resolution - Resolution of the landscape layer map data segment to be modified along the X and Y axes.

void asyncApplyDiff ( int operation_id, const UGUID & guid, const char * 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.
const UGUID & guid - GUID of the landscape layer map file to which a state stored at the specified path is to be applied.
const char * path - Path to a file where the current landscape map modification state is stored.

void asyncApplyDiff ( const UGUID & guid, const char * 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

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

void asyncSaveFile ( int operation_id, const UGUID & file_guid ) #

Saves the landscape layer map file with the specified GUID.

Arguments

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

void asyncSaveFile ( const UGUID & file_guid ) #

Saves the landscape layer map file with the specified GUID.

Arguments

const UGUID & file_guid - GUID of the landscape layer map file.

void asyncSaveFile ( int operation_id, const UGUID & guid, const char * path_new_state, const char * 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.
const UGUID & guid - GUID of the landscape layer map file.
const char * path_new_state - Path to a file to store the new landscape layer map state.
const char * path_old_state - Path to a file to store the old landscape layer map state.

void asyncSaveFile ( const UGUID & guid, const char * path_new_state, const char * path_old_state ) #

Source code (C++)

UGUID lmap_file_guid;	// .lmap file GUID
String cache_path;		// path to some cache directory

String new_filepath;	// path to store a new state
String old_filepath;	// path to store an old state

// method implementing the "apply" operation
void apply() override
{
	// generating necessary paths to save states (generate_filepath - some abstract method)
	new_filepath = generate_filepath(cache_path);
	old_filepath_ = generate_filepath(cache_path);

	// applying changes and saving current and previous states
	Landscape::asyncSaveFile(lmap_file_guid, new_filepath, old_filepath);
}

// method implementing the "undo" operation by applying the previous saved state
void undo() override
{
	if (!old_filepath.empty())
		Landscape::asyncApplyDiff(lmap_file_guid, old_filepath);
}

// method implementing the "redo" operation by applying the new saved state
void redo() override
{
	if (!new_filepath.empty())
		Landscape::asyncApplyDiff(lmap_file_guid, new_filepath);
}

Arguments

const UGUID & guid - GUID of the landscape layer map file.
const char * path_new_state - Path to a file to store the new landscape layer map state.
const char * path_old_state - Path to a file to store the old landscape layer map state.

bool 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

true if .lmap files for all landscape layer maps are closed; otherwise, false.

void filesClose ( const Vector< UGUID > & reload_files ) #

Closes .lmap files for all landscape layer maps and reloads the ones with specified GUIDs. 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. The list informs the Engine which files are no longer valid and should be reloaded or removed. As you're done with modification you should call the filesOpen() method to resume streaming operations.

Arguments

const Vector< UGUID > & reload_files - List of GUIDs of .lmap files to be reloaded. This list should contain .lmap files, that were deleted or having their data changed (albedo, heights, masks). If there are no such files, you can simply call the filesClose() method.

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.

Ptr<ObjectLandscapeTerrain> getActiveTerrain ( ) #

Returns the current active Landscape Terrain object.

NoticeIf a scene contains multiple Landscape Terrain objects, only one of them can be active (rendered).

Return value

Landscape Terrain object that is currently active.

void * addTextureDrawCallback ( Unigine::CallbackBase5< UGUID, int, Ptr<LandscapeTextures>, Math::ivec2, int > * func ) #

Adds a callback function to be called when a Texture Draw (GPU-based terrain modification) operation is performed. The signature of the callback function must be as follows:

Source code (C++)

void texture_draw_callback(UGUID guid, int id, LandscapeTexturesPtr buffer, ivec2 coord, int data_mask);

You can set a callback function as follows:

Source code (C++)

addTextureDrawCallback(MakeCallback(texture_draw_callback));

Example: Setting a texture draw callback function for a certain class:

Source code (C++)

// callback function implementing modification of the buffer
void SomeClass::textureDraw(UGUID guid, int id, LandscapeTexturesPtr buffer, ivec2 coord, int data_mask)
{
	// insert your buffer modification code here (the following lines can be used as an example)

	// getting a brush material to be used (e.g., built-in "cirle_soft" Editor's brush)
	MaterialPtr mat = Materials::findMaterial("circle_soft");
	
	if (mat) {
		// setting necessary textures to be modified by the brush
		mat->setTexture("terrain_albedo", buffer->getAlbedo());
		mat->setTexture("terrain_height", buffer->getHeight());

		// setting up brush material parameters
		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()
{
	// setting the textureDraw() function to handle texture drawing
	Landscape::addTextureDrawCallback(MakeCallback(SomeClass::textureDraw));
}

Arguments

Unigine::CallbackBase5< UGUID, int, Ptr<LandscapeTextures>, Math::ivec2, int > * func - Callback pointer.

Return value

ID of the last added texture draw callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeTextureDrawCallback ( void * id ) #

Removes the specified callback from the list of texture draw callbacks.

Arguments

void * id - Texture draw callback ID obtained when adding it.

Return value

True if the texture draw callback with the given ID was removed successfully; otherwise false.

void clearTextureDrawCallback ( ) #

Clears all added texture draw callbacks.

void * addApplyDiffCallback ( Unigine::CallbackBase3< UGUID, int, const char* > * func ) #

Adds a callback function to be called on applying a diff to the landscape layer map file. The signature of the callback function must be as follows:

Source code (C++)

void apply_diff_callback(UGUID guid, int id, const char*);

You can set a callback function as follows:

Source code (C++)

addApplyDiffCallback(MakeCallback(apply_diff_callback));

Example: Setting an apply diff callback function for a certain class:

Source code (C++)

// callback function implementing certain actions to be performed on applying a diff
void applyDiff(UGUID guid, int id, const char* path)
{
	// insert your specific handling code here
}

// ...
virtual int AppWorldLogic::init()
{
	// setting the applyDiff() function to handle an apply diff event
	Landscape::addApplyDiffCallback(MakeCallback(&applyDiff));
}

Arguments

Unigine::CallbackBase3< UGUID, int, const char* > * func - Callback pointer.

Return value

ID of the last added apply diff callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeApplyDiffCallback ( void * id ) #

Removes the specified callback from the list of apply diff callbacks.

Arguments

void * id - Apply diff callback ID obtained when adding it.

Return value

True if the apply diff callback with the given ID was removed successfully; otherwise false.

void clearApplyDiffCallback ( ) #

Clears all added apply diff callbacks.

void * addSaveFileCallback ( Unigine::CallbackBase4< UGUID, int, const char, const char > * func ) #

Adds a callback function to be called on applying changes made to a landscape layer map file and saving old and new states to temporary files. The signature of the callback function must be as follows:

Source code (C++)

void save_file_callback(UGUID guid, int id, const char*, const char*);

You can set a callback function as follows:

Source code (C++)

addFileSaveCallback(MakeCallback(save_file_callback));

Example: Setting an apply diff callback function for a certain class:

Source code (C++)

// callback function implementing certain actions to be performed on applying a certain state
void saveFile(UGUID guid, int id, const char* path_new_state, const char* path_old_state)
{
	// insert your specific handling code here
}

// ...
virtual int AppWorldLogic::init()
{
	// setting the saveFile() function to handle file saving
	Landscape::addSaveFileCallback(MakeCallback(&saveFile));
}

Arguments

Unigine::CallbackBase4< UGUID, int, const char*, const char* > * func - Callback pointer.

Return value

ID of the last added save file callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeSaveFileCallback ( void * id ) #

Removes the specified callback from the list of save file callbacks.

Arguments

void * id - Save file callback ID obtained when adding it.

Return value

True if the save file callback with the given ID was removed successfully; otherwise false.

void clearSaveFileCallback ( ) #

Clears all added save file callbacks.

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: 2023-06-23

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine::Landscape Class

In This Article:

GPU-Based Terrain Modification#

Usage Example: Brush Editor#

功能列表:

Landscape Class

Enums

TYPE_DATA#

FLAGS_DATA#

TYPE_FILE_DATA#

FLAGS_FILE_DATA#

COMPRESSOR_TYPE#

BLENDING_MODE#

Members

Ptr<LandscapeTextures> getTemporaryTexture ( const Math::ivec2 & resolution ) #

Arguments

Return value

void releaseTemporaryTexture ( const Ptr<LandscapeTextures> & texture ) #

Arguments

bool terrainLoad ( const Math::WorldBoundBox & bb ) #

Arguments

Return value

bool render ( const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size ) #

Arguments

Return value

bool render ( const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size, int padding ) #

Arguments

Return value

bool render ( const Vector< Ptr<LandscapeLayerMap> > & maps, const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size ) #

Arguments

Return value

bool render ( const Vector< Ptr<LandscapeLayerMap> > & maps, const Ptr<LandscapeTextures> & buffers, const Math::Mat4 & transform, Math::Scalar texel_size, int padding ) #

Arguments

Return value

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data, const Vector< Math::WorldBoundBox > & bounds_preload ) #

Arguments

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data ) #

Arguments

void asyncTextureDraw ( int operation_id, const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution ) #

Arguments

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data, const Vector< Math::WorldBoundBox > & bounds_preload ) #

Arguments

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution, int flags_file_data ) #

Arguments

void asyncTextureDraw ( const UGUID & guid, const Math::ivec2 & coord, const Math::ivec2 & resolution ) #

Arguments

void asyncApplyDiff ( int operation_id, const UGUID & guid, const char * path ) #

Arguments

void asyncApplyDiff ( const UGUID & guid, const char * path ) #

Arguments

void asyncSaveFile ( int operation_id, const UGUID & file_guid ) #

Arguments

void asyncSaveFile ( const UGUID & file_guid ) #

Arguments

void asyncSaveFile ( int operation_id, const UGUID & guid, const char * path_new_state, const char * path_old_state ) #

Arguments

void asyncSaveFile ( const UGUID & guid, const char * path_new_state, const char * path_old_state ) #

Arguments

bool isFilesClosed ( ) #

Return value

void filesClose ( const Vector< UGUID > & reload_files ) #

Arguments

void filesClose ( ) #

void filesOpen ( ) #

Ptr<ObjectLandscapeTerrain> getActiveTerrain ( ) #

Return value

void * addTextureDrawCallback ( Unigine::CallbackBase5< UGUID, int, Ptr<LandscapeTextures>, Math::ivec2, int > * func ) #

Arguments

Return value

bool removeTextureDrawCallback ( void * id ) #

Arguments

Return value

void clearTextureDrawCallback ( ) #

void * addApplyDiffCallback ( Unigine::CallbackBase3< UGUID, int, const char* > * func ) #

Arguments

Return value

bool removeApplyDiffCallback ( void * id ) #

Arguments

Return value

void clearApplyDiffCallback ( ) #

void * addSaveFileCallback ( Unigine::CallbackBase4< UGUID, int, const char, const char > * func ) #