#include <VisualField.h>

Inheritance diagram for environmentmodels::VisualField:

Collaboration diagram for environmentmodels::VisualField:

Public Member Functions
void	FinalSetup (const double T, const double const X, ISimObjectCreator Creator) override

void	OdeFcn (const double T, const double const X, double const XDot) const override
	No state; the ODE function is a no-op.

util::Refresh	RefreshMode () const

Protected Member Functions
	VisualField (std::string SimObjectName, ISimObjectCreator *Creator, int numAxes)

	~VisualField () override
	Releases the cloned material and the textures.

void	ResolveCounts (const double extent[3], std::size_t budget, int counts[3]) const

void	ValidateGridCounts (ISimObjectCreator *Creator, const int counts[3], const std::string &extentParameterName) const

bool	MaskInaccurate () const

bool	ExpectsToSampleOnce () const

bool	MaySampleInTheBackground () const

environment::field::ScalarField &	Field () const

double	StartTime () const
	Simulation time of FinalSetup [s], the time of the first sample.

bool	RefreshDue (double T, bool moved) const

void	Refreshed (double T)

util::BakedField	SampleOver (double T, const util::SamplingBox &box)

double	ValueMin () const
	Field value encoded as code 1, fixed at the first SampleOver().

double	ValueMax () const
	Field value encoded as code 65535, fixed at the first SampleOver().

Detailed Description

Base class of the visualisers that sample a field of the environment onto a grid and let the GPU draw it.

Owns everything the plane and the volume share: the XML parameters naming what is shown (Quantity, Terms, Axis, FieldName) and when it is sampled (Refresh, RefreshPeriod); the colour, visible and alpha ranges; the Spacing xor Resolution rule; the field sampled, a registered scalar field or a util::EnvironmentQuantityField; the refresh schedule and the wakes' change signal; sampling in parallel; uploading the result, into the same textures on every refresh; and cloning the material each instance writes its uniforms on.

Sampling runs in RenderUpdate, on the simulation thread while the simulation waits, on every core (owner ruling 2026-10-13). The schedule keeps it rare: a field of the wakes alone is sampled again only when the wakes change (Refresh OnChange).

Every failure that does not need Ogre - a contradictory parameter, a missing field, an oversized grid - is detected in the constructor or in FinalSetup, so it is reachable in the no-visualisation build.

Note: Derived classes own their geometry and release it in their own destructor; this class releases only the cloned material and the textures.

Constructor & Destructor Documentation

◆ VisualField()

environmentmodels::VisualField::VisualField	(	std::string	SimObjectName,
		ISimObjectCreator *	Creator,
		int	numAxes
	)

protected

Read the shared XML parameters.

Parameters

[in]	SimObjectName	Unique name for this simulation object.
[in]	Creator	Object creator/registry.
[in]	numAxes	Axes the derived visualiser samples: 2 for a plane, 3 for a volume. Decides the length of `Spacing` and `Resolution`.

Exceptions

std::runtime_error for a contradictory or invalid parameter; the parameter is reported.

Member Function Documentation

◆ ExpectsToSampleOnce()

bool environmentmodels::VisualField::ExpectsToSampleOnce ( ) const

protected

Whether the configuration asks for a field sampled once: Refresh Once, or Auto with a scalar field.

Known in the constructor, before the field is resolved, so a derived visualiser can pick its default cell budget from it. A time-dependent scalar field under Auto is sampled every frame all the same, on that budget.

◆ Field()

environment::field::ScalarField & environmentmodels::VisualField::Field ( ) const

protected

The field sampled.

Returns: Reference to the field held since FinalSetup.

Exceptions

std::runtime_error when called before FinalSetup.

◆ FinalSetup()

void environmentmodels::VisualField::FinalSetup	(	const double	T,
		const double *const	X,
		ISimObjectCreator *	Creator
	)

override

Resolve the Environment Provider and the field, and resolve the refresh.

Parameters

[in]	T	Simulation time [s]; the first sample is taken at it.
[in]	X	State vector.
[in]	Creator	Object creator/registry.

Exceptions

std::runtime_error when the Environment resource is absent or no scalar field named FieldName is registered.

◆ MaskInaccurate()

bool environmentmodels::VisualField::MaskInaccurate ( ) const

inlineprotected

Whether a cell the field flagged as inaccurate is masked.

Returns: True unless ShowExtrapolated was set.

◆ MaySampleInTheBackground()

bool environmentmodels::VisualField::MaySampleInTheBackground ( ) const

protected

Whether the field may be sampled from a worker thread while the simulation runs.

Only a time-invariant scalar field that declares itself thread-safe may: nothing the simulation does between steps changes it, and concurrent reads are its contract.

◆ RefreshDue()

bool environmentmodels::VisualField::RefreshDue	(	double	T,
		bool	moved
	)		const

protected

Whether the field is to be sampled at T.

Parameters

[in]	T	Simulation time of the frame [s].
[in]	moved	The sampled region moved since the last sample.

Returns: True when the schedule says so, given the field's change signal.

◆ Refreshed()

void environmentmodels::VisualField::Refreshed ( double T )

protected

Records a sample taken at T for the schedule.

Parameters

[in] T Simulation time sampled at [s].

◆ RefreshMode()

util::Refresh environmentmodels::VisualField::RefreshMode ( ) const

When the field is sampled, resolved in FinalSetup.

Returns: The resolved Refresh, never Auto.

Exceptions

std::runtime_error when called before FinalSetup.

◆ ResolveCounts()

void environmentmodels::VisualField::ResolveCounts	(	const double	extent[3],
		std::size_t	budget,
		int	counts[3]
	)		const

protected

Turn the configured spacing or resolution into per-axis sample counts.

Uses Resolution when configured, Spacing when that is configured instead, and otherwise derives a spacing that lands near budget cells.

Parameters

[in]	extent	Edge length of each axis of the sampling box [m].
[in]	budget	Target cell count used when neither parameter is configured.
[out]	counts	Resulting samples along each axis; each at least 1.

◆ SampleOver()

util::BakedField environmentmodels::VisualField::SampleOver	(	double	T,
		const util::SamplingBox &	box
	)

protected

Sample the field over a box at T and encode it.

The encoding range is fixed at the first call: from ColorRange and VisibleRange, probing the field at T for a range not configured when the field is sampled once, else taking the defaults 0, 1. Sampled on every core when the field is thread-safe.

Parameters

[in]	T	Simulation time [s].
[in]	box	Sampling grid, already carrying the resolved counts.

Returns: The encoded grid.

Exceptions

std::runtime_error when a needed probe found no drawable cell.

◆ ValidateGridCounts()

void environmentmodels::VisualField::ValidateGridCounts	(	ISimObjectCreator *	Creator,
		const int	counts[3],
		const std::string &	extentParameterName
	)		const

protected

Fail on a grid the render system could not hold.

Parameters

[in]	Creator	Object creator/registry, used to report the failing parameter.
[in]	counts	Samples along each axis.
[in]	extentParameterName	Parameter naming the size of the sampled region - `BoxSize` for a volume, `Size` for a plane. It is blamed only when neither `Spacing` nor `Resolution` is configured.

Exceptions

std::runtime_error when the grid exceeds util::kMaxBakeCells, or when an axis exceeds util::kMaxAxisSize2D for a two-axis visualiser or util::kMaxAxisSize3D for a three-axis one.

The documentation for this class was generated from the following file:

webfhsim/reloadrepos/fhsim_environment/src/environment/VisualField.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VisualField()

Member Function Documentation

◆ ExpectsToSampleOnce()

◆ Field()

◆ FinalSetup()

◆ MaskInaccurate()

◆ MaySampleInTheBackground()

◆ RefreshDue()

◆ Refreshed()

◆ RefreshMode()

◆ ResolveCounts()

◆ SampleOver()

◆ ValidateGridCounts()