eve::procgen::TerrainWaterField类 参考

Owned water/flux/velocity state for deterministic execution of the Pcg water stage. No terrain pointer is retained. Each advance reads an immutable terrain and previous field, computes all fluxes, then computes velocities and depth, publishing once. This deliberately retains the source's final rain/evaporation overwrite of transported depth and its velocity signs. It is not a conservative shallow-water solver. Undefined source behavior is resolved explicitly: current flux is fully computed before neighbor reads, and zero average depth produces zero velocity instead of division by zero. Thread affinity is caller-owned: exclusive reset/advance, immutable sampling when idle; no callbacks, borrowed output pointers, ECS handles, implicit clock or RNG. 更多...

#include <TerrainWaterField.h>

类
struct	Impl

Public 成员函数
	TerrainWaterField ()
	Construct an empty field; reset must succeed before advance or sample.
	~TerrainWaterField ()
	Destroy all owned simulation buffers; no external registrations are retained.
	TerrainWaterField (TerrainWaterField &&) noexcept
	Transfer owned buffers; a moved-from field is empty and can be reset.
TerrainWaterField &	operator= (TerrainWaterField &&) noexcept
	Transfer owned buffers, releasing this field's previous buffers.
	TerrainWaterField (const TerrainWaterField &)=delete
	State has one mutable owner; implicit copying is prohibited.
TerrainWaterField &	operator= (const TerrainWaterField &)=delete
	State has one mutable owner; implicit copy assignment is prohibited.
Result< int >	reset (int width, int height, float depth=0)
	Reset dimensions, uniform depth and zero flux/velocity atomically.
Result< int >	advance (const Heightmap &terrain, const TerrainWaterSettings &settings)
	Advance one injected time step, with clamped neighbor indices.
Result< int >	advanceHydraulic (Heightmap &heights, Heightmap &sediment, const TerrainWaterSettings &water, const TerrainSedimentSettings &reaction, const TerrainThermalSettings &thermal, int iterations)
	Advance water, source sediment and thermal stages as one transaction.
Result< TerrainWaterSample >	sample (int x, int z) const
	Read an owned value snapshot; invalid coordinates or empty state return InvalidArgument.
Result< int >	exportChannel (Heightmap &target, TerrainWaterChannel channel) const
	Copy one stored channel into an existing matching raster for mask processing.
int	getWidth () const noexcept
	Return X sample count, or zero for an empty/moved-from field.
int	getHeight () const noexcept
	Return Z sample count, or zero for an empty/moved-from field.

详细描述

Owned water/flux/velocity state for deterministic execution of the Pcg water stage. No terrain pointer is retained. Each advance reads an immutable terrain and previous field, computes all fluxes, then computes velocities and depth, publishing once. This deliberately retains the source's final rain/evaporation overwrite of transported depth and its velocity signs. It is not a conservative shallow-water solver. Undefined source behavior is resolved explicitly: current flux is fully computed before neighbor reads, and zero average depth produces zero velocity instead of division by zero. Thread affinity is caller-owned: exclusive reset/advance, immutable sampling when idle; no callbacks, borrowed output pointers, ECS handles, implicit clock or RNG.

在文件 TerrainWaterField.h 第 71 行定义.

构造及析构函数说明

TerrainWaterField() [1/3]

eve::procgen::TerrainWaterField::TerrainWaterField ( )

default

Construct an empty field; reset must succeed before advance or sample.

~TerrainWaterField()

eve::procgen::TerrainWaterField::~TerrainWaterField ( )

default

Destroy all owned simulation buffers; no external registrations are retained.

TerrainWaterField() [2/3]

eve::procgen::TerrainWaterField::TerrainWaterField ( TerrainWaterField &&  )

defaultnoexcept

Transfer owned buffers; a moved-from field is empty and can be reset.

TerrainWaterField() [3/3]

eve::procgen::TerrainWaterField::TerrainWaterField ( const TerrainWaterField &  )

delete

State has one mutable owner; implicit copying is prohibited.

成员函数说明

advance()

Result< int > eve::procgen::TerrainWaterField::advance	(	const Heightmap &	terrain,
		const TerrainWaterSettings &	settings
	)

Advance one injected time step, with clamped neighbor indices.

参数

terrain	Borrowed matching finite height raster; never modified or retained.
settings	Finite positive spacing/scales, nonnegative dt/precipitation/evaporation; flowAcceleration is signed. dt=0 is identity. No hidden UI scaling is applied.

返回

Number of cells with any changed output, or InvalidArgument. All state is unchanged on invalid input, overflow or allocation failure.

异常

std::bad_alloc

Old state remains intact.

在文件 TerrainWaterField.cpp 第 202 行定义.

引用了 area, bottom, cell, depth, direction, height, index, eve::procgen::raster_detail::invalid(), eve::procgen::raster_detail::isRepresentable(), left, n, right, s, eve::Result< T >::success(), terrain, top, v, eve::procgen::raster_detail::validRaster(), value, vx, vz, width, x , 以及 z.

被这些函数引用 advanceHydraulic().

advanceHydraulic()

Result< int > eve::procgen::TerrainWaterField::advanceHydraulic	(	Heightmap &	heights,
		Heightmap &	sediment,
		const TerrainWaterSettings &	water,
		const TerrainSedimentSettings &	reaction,
		const TerrainThermalSettings &	thermal,
		int	iterations
	)

Advance water, source sediment and thermal stages as one transaction.

参数

heights	Exclusively borrowed matching nonnegative scalar heights, never retained.
sediment	Exclusively borrowed matching signed sediment, distinct from heights.
water	Water step constants; dt and spacing also drive sediment transport.
reaction	Effective source sediment coefficients.
thermal	Thermal constants with already-computed substep dt; zero thermal iterations disables it.
iterations	Nonnegative number of complete iterations. Zero validates raster ownership/shape and leaves state unchanged.

返回

Cells changed in water, height or sediment, or InvalidArgument. All three owners remain unchanged on any stage failure, including after earlier successful iterations.

异常

std::bad_alloc

All caller-observable state remains unchanged. Each iteration uses the latest completed height state and publishes the last iteration, rather than the source wrapper's fixed buffer-1 output and reset thermal buffer index. Caller must hold exclusive access to this field and both rasters; no callbacks or retained borrows.

在文件 TerrainWaterField.cpp 第 283 行定义.

引用了 advance(), eve::procgen::applyTerrainSediment(), eve::procgen::applyTerrainThermal(), eve::procgen::Heightmap::data(), eve::procgen::Heightmap::getHeight(), eve::procgen::Heightmap::getWidth(), h, eve::procgen::raster_detail::invalid(), iterations, sediment, eve::Result< T >::success(), thermal, eve::procgen::raster_detail::validRaster(), vx, vz , 以及 water.

exportChannel()

Result< int > eve::procgen::TerrainWaterField::exportChannel	(	Heightmap &	target,
		TerrainWaterChannel	channel
	)		const

Copy one stored channel into an existing matching raster for mask processing.

参数

target	Exclusively borrowed finite matching raster; no resize or retained reference.
channel	Explicit scalar channel, without normalization, absolute value or clamping.

返回

Changed sample count or InvalidArgument; failure leaves target and field unchanged.

异常

std::bad_alloc

Target remains unchanged. @thread Synchronous immutable field access and exclusive target access; no callbacks.

在文件 TerrainWaterField.cpp 第 182 行定义.

引用了 eve::procgen::Depth, eve::procgen::TerrainWaterSample::depth, eve::procgen::FluxBottom, eve::procgen::TerrainWaterSample::fluxBottom, eve::procgen::FluxLeft, eve::procgen::TerrainWaterSample::fluxLeft, eve::procgen::FluxRight, eve::procgen::TerrainWaterSample::fluxRight, eve::procgen::FluxTop, eve::procgen::TerrainWaterSample::fluxTop, eve::procgen::raster_detail::invalid(), member, output, eve::procgen::raster_detail::publish(), target, eve::procgen::raster_detail::validRaster(), eve::procgen::VelocityX, eve::procgen::TerrainWaterSample::velocityX, eve::procgen::VelocityZ , 以及 eve::procgen::TerrainWaterSample::velocityZ.

getHeight()

int eve::procgen::TerrainWaterField::getHeight ( ) const

noexcept

Return Z sample count, or zero for an empty/moved-from field.

在文件 TerrainWaterField.cpp 第 158 行定义.

getWidth()

int eve::procgen::TerrainWaterField::getWidth ( ) const

noexcept

Return X sample count, or zero for an empty/moved-from field.

在文件 TerrainWaterField.cpp 第 157 行定义.

operator=() [1/2]

TerrainWaterField & eve::procgen::TerrainWaterField::operator= ( const TerrainWaterField &  )

delete

State has one mutable owner; implicit copy assignment is prohibited.

operator=() [2/2]

TerrainWaterField & eve::procgen::TerrainWaterField::operator= ( TerrainWaterField &&  )

defaultnoexcept

Transfer owned buffers, releasing this field's previous buffers.

reset()

Result< int > eve::procgen::TerrainWaterField::reset	(	int	width,
		int	height,
		float	depth = 0
	)

Reset dimensions, uniform depth and zero flux/velocity atomically.

参数

width	Positive X sample count.
height	Positive Z sample count; product must fit int.
depth	Finite nonnegative initial stored water depth.

返回

Initialized cell count or InvalidArgument; failure leaves old state intact.

异常

std::bad_alloc

Old state remains intact.

在文件 TerrainWaterField.cpp 第 160 行定义.

引用了 cell, depth, height, eve::procgen::raster_detail::invalid(), eve::Result< T >::success() , 以及 width.

sample()

Result< TerrainWaterSample > eve::procgen::TerrainWaterField::sample	(	int	x,
		int	z
	)		const

Read an owned value snapshot; invalid coordinates or empty state return InvalidArgument.

在文件 TerrainWaterField.cpp 第 175 行定义.

引用了 eve::Diagnostic::error(), eve::Result< T >::failure(), eve::InvalidArgument, eve::Result< T >::success(), x , 以及 z.

---

该类的文档由以下文件生成:

• src/modules/procgen/heightmap/TerrainWaterField.h
• src/modules/procgen/heightmap/TerrainWaterField.cpp