Structure describing a LOD group (set of meshes), LOD transitions, and their materials. More...

#include <model.h>

Inheritance diagram for unravel::model:

Classes
struct	submit_callbacks
	Callbacks for submitting the model for rendering. More...

struct	submit_vertex_pulling_callbacks
	Callbacks for submitting the model using vertex-pulling rendering. More...

Public Types
using	seconds_t = std::chrono::duration<float>

Public Member Functions
auto	is_valid () const -> bool
	Checks if the model is valid.

auto	get_lod (uint32_t lod) const -> asset_handle< mesh >
	Gets the LOD (Level of Detail) mesh for the specified level.

void	set_lod (asset_handle< mesh > mesh, uint32_t lod)
	Sets the LOD (Level of Detail) mesh for the specified level.

void	set_material (asset_handle< material > material, uint32_t index)
	Sets the material for the specified index.

void	set_material_instance (material::sptr material, uint32_t index)

auto	get_lods () const -> const std::vector< asset_handle< mesh > > &
	Gets all the LOD meshes.

auto	get_lods_count () const -> uint32_t
	Gets the number of LOD levels available. If there is only one explicit mesh, returns the internal LOD count of that mesh. Otherwise, returns the number of mesh LODs.

void	set_lods (const std::vector< asset_handle< mesh > > &lods)
	Sets the LOD meshes.

auto	get_materials () const -> const std::vector< asset_handle< material > > &
	Gets all the materials.

auto	get_material_instances () const -> const std::vector< material::sptr > &

void	set_materials (const std::vector< asset_handle< material > > &materials)
	Sets the materials.

void	set_material_instances (const std::vector< material::sptr > &materials)

auto	get_material (uint32_t index) const -> asset_handle< material >
	Gets the material for the specified index.

auto	get_material_instance (uint32_t index) const -> material::sptr

auto	get_or_emplace_material_instance (uint32_t index) -> material::sptr

auto	get_lod_override_enabled () const -> bool
	Gets whether LOD override is enabled.

void	set_lod_override_enabled (bool enabled)
	Sets whether LOD override is enabled.

auto	get_lod_override_level () const -> uint32_t
	Gets the LOD override level.

void	set_lod_override_level (uint32_t level)
	Sets the LOD override level.

auto	get_lod_selection_bias () const -> float
	Gets the LOD selection bias.

void	set_lod_selection_bias (float bias)
	Sets the LOD selection bias.

auto	get_lod_hysteresis () const -> float
	Gets the LOD hysteresis factor used to prevent rapid LOD switching.

void	set_lod_hysteresis (float hysteresis)
	Sets the LOD hysteresis factor.

auto	get_lod_transition_time () const -> seconds_t
	Gets the LOD transition time in seconds.

void	set_lod_transition_time (seconds_t time)
	Sets the LOD transition time in seconds.

auto	calculate_lod_data (lod_data &data, const math::bbox &world_bounds, const camera &cam, float dt) const -> bool
	Calculates the LOD data for the model using distance-based hysteresis with time-based transitions. Hysteresis prevents rapid LOD switching; transitions smooth the actual switch when it occurs. Uses data.current_lod_index for hysteresis and updates target_lod_index when a switch is triggered.

auto	calculate_submesh_lod (const mesh &m, uint32_t submesh_index, uint32_t base_lod, const math::mat4 &world_matrix, const camera &cam) const -> uint32_t
	Selects a LOD for a specific submesh based on its own screen size.

auto	calculate_submesh_lod_from_world_bounds (const mesh &m, uint32_t submesh_index, uint32_t base_lod, const math::bbox &world_bounds, const camera &cam) const -> uint32_t
	Selects a LOD for a submesh from an already-known world-space AABB.

auto	compute_lod_index (const math::bbox &world_bounds, const camera &cam, float extra_bias=0.0f) const -> uint32_t
	Computes a LOD index for this model without hysteresis, transitions or visibility culling.

auto	get_lod_screen_size_min () const -> float
	Gets the minimum screen size used by the screen-radius-squared LOD and culling method.

void	set_lod_screen_size_min (float value)
	Sets the minimum screen size used by the screen-radius-squared LOD and culling method.

auto	get_lod_auto_screen_size_power_base () const -> float
	Gets the auto LOD screen size power base (used for generating a screen-size table).

void	set_lod_auto_screen_size_power_base (float value)
	Sets the auto LOD screen size power base (used for generating a screen-size table).

auto	get_lod_screen_sizes () const -> const std::vector< float > &
	Gets the per-LOD screen size table used by the screen-radius-squared method.

void	set_lod_screen_sizes (const std::vector< float > &sizes)
	Sets the per-LOD screen size table used by the screen-radius-squared method.

void	recalulate_lod_screen_size_limits (uint32_t lod_count)
	Recalculates the screen-size LOD thresholds for the provided LOD count. This is a separate mechanism from the percent-based LOD limits and is used by calculate_lod_data_screen_size.

void	submit (const math::mat4 &world_transform, const submesh_pose_mat4 &submesh_transforms, const pose_mat4 &bone_transforms, const std::vector< pose_mat4 > &skinning_transforms, unsigned int lod, const submit_callbacks &callbacks, const math::frustum frustum=nullptr, const camera view=nullptr, const model_submit_extras &extras={}) const
	Submits the model for rendering.

void	submit_for_vertex_pulling (const math::mat4 &world_transform, const submesh_pose_mat4 &submesh_transforms, const std::vector< pose_mat4 > &skinning_transforms, unsigned int lod, const submit_vertex_pulling_callbacks &callbacks, const math::frustum frustum=nullptr, const camera view=nullptr, const model_submit_extras &extras={}) const
	Submits the model using vertex-pulling rendering.

void	submit_for_batching (batch_collector &collector, const math::mat4 &world_transform, const submesh_pose_mat4 &submesh_transforms, uint32_t lod_index, float lod_param=0.0f, const math::frustum frustum=nullptr, const camera view=nullptr, const model_submit_extras &extras={}) const
	Collects this model into a batch collector for instanced rendering.

auto	submit_for_shadow_batching_cascaded (std::vector< shadow_batch_collector > &collectors, uint8_t cascade_count, const math::mat4 &world_transform, const submesh_pose_mat4 &submesh_transforms, uint32_t lod_index, float lod_param, const math::frustum *frustums, bool nested_cascades, const model_submit_extras &extras={}) const -> bool
	Collects shadow-map geometry into per-cascade shadow batch collectors. Batches by mesh/lod/submesh/cull and alpha-cutout state instead of material pointer.

Public Member Functions inherited from crtp_meta_type< model >
virtual auto	get_meta_type () const -> entt::meta_type

auto	is () const -> bool

auto	is (const entt::meta_type &type) const -> bool

virtual auto	as_derived () -> entt::meta_any

Static Public Member Functions
static auto	default_material () -> asset_handle< material > &
	Gets the default material.

static auto	fallback_material () -> asset_handle< material > &
	Gets the fallback material.

Static Public Member Functions inherited from crtp_meta_type< model >
static auto	get_static_meta_type () -> entt::meta_type

Detailed Description

Structure describing a LOD group (set of meshes), LOD transitions, and their materials.

Definition at line 274 of file model.h.

Member Typedef Documentation

◆ seconds_t

using unravel::model::seconds_t = std::chrono::duration<float>

Definition at line 279 of file model.h.

Member Function Documentation

◆ calculate_lod_data()

auto unravel::model::calculate_lod_data	(	lod_data &	data,
		const math::bbox &	world_bounds,
		const camera &	cam,
		float	dt ) const -> bool

Calculates the LOD data for the model using distance-based hysteresis with time-based transitions. Hysteresis prevents rapid LOD switching; transitions smooth the actual switch when it occurs. Uses data.current_lod_index for hysteresis and updates target_lod_index when a switch is triggered.

Screen size is measured from the pose-aware world bounds (the same box culling uses - see model_component::get_world_bounds), so animated/root-motion models select LOD from where their geometry actually is, not from the bind-pose box at the entity transform.

Parameters

data	The LOD data to calculate and update.
world_bounds	Pose-aware world-space bounds of the model.
cam	The camera.
dt	Delta time for updating transition progress.

Returns: True if the LOD data was calculated successfully, false when the model is not loaded, has unpopulated bounds, or is below the minimum screen size (culled).

Definition at line 360 of file model.cpp.

◆ calculate_submesh_lod()

auto unravel::model::calculate_submesh_lod	(	const mesh &	m,
		uint32_t	submesh_index,
		uint32_t	base_lod,
		const math::mat4 &	world_matrix,
		const camera &	cam ) const -> uint32_t

Selects a LOD for a specific submesh based on its own screen size.

Used at submit time when per-submesh culling is active (multi-submesh meshes) and a view camera is available. Each submesh independently picks its LOD from its world- space bounding sphere so tiny/distant submeshes on a large model can drop to a cheaper LOD than the model-wide selection would.

The returned LOD is CLAMPED to be at least base_lod: per-submesh selection is only allowed to drop quality relative to the model-wide LOD, never raise it. This preserves the guarantee made by calculate_lod_data (with its hysteresis and dithered transitions) that the model-wide LOD is a quality floor.

Returns base_lod (i.e. "no change") when per-submesh LOD is not viable:

The model uses manual multi-mesh LODs (submesh identity is not comparable across different mesh assets).
No screen-size table is populated, or the model has only one LOD.
LOD override is enabled.
The submesh has no populated per-submesh bbox (indistinguishable from the whole model).

Must run on the graphics API thread.

Parameters

m	The mesh asset (must be the same one returned by get_lod for `base_lod`).
submesh_index	Index into `m's` submesh array at `base_lod`.
base_lod	Model-wide LOD (floor for the returned value).
world_matrix	World transform for this submesh instance.
cam	Camera whose position/projection drives the screen-size computation.

Definition at line 523 of file model.cpp.

◆ calculate_submesh_lod_from_world_bounds()

auto unravel::model::calculate_submesh_lod_from_world_bounds	(	const mesh &	m,
		uint32_t	submesh_index,
		uint32_t	base_lod,
		const math::bbox &	world_bounds,
		const camera &	cam ) const -> uint32_t

Selects a LOD for a submesh from an already-known world-space AABB.

Same semantics and guards as calculate_submesh_lod but skips the per-call world matrix decomposition by using cached world bounds (see submesh_render_proxies). Also usable for skinned submeshes whose animated bounds are tracked per frame.

Definition at line 552 of file model.cpp.

◆ compute_lod_index()

auto unravel::model::compute_lod_index	(	const math::bbox &	world_bounds,
		const camera &	cam,
		float	extra_bias = 0.0f ) const -> uint32_t

Computes a LOD index for this model without hysteresis, transitions or visibility culling.

Used by passes that need a distance-appropriate LOD but do not track per-camera LOD state (e.g. shadow rendering, which previously always used LOD 0).

Parameters

world_bounds	Pose-aware world-space bounds of the model (see model_component::get_world_bounds).
cam	Camera whose position drives the screen-size computation.
extra_bias	Additional LOD bias on top of the model's own selection bias (positive = coarser).

Returns: The selected LOD index (0 when no LOD table is available).

Definition at line 567 of file model.cpp.

◆ default_material()

auto unravel::model::default_material ( ) -> asset_handle<material>&

static

Gets the default material.

Returns: A reference to the default material asset handle.

Definition at line 1242 of file model.cpp.

◆ fallback_material()

auto unravel::model::fallback_material ( ) -> asset_handle<material>&

static

Gets the fallback material.

Returns: A reference to the fallback material asset handle.

Definition at line 1248 of file model.cpp.

◆ get_lod()

auto unravel::model::get_lod ( uint32_t lod ) const -> asset_handle<mesh>

Gets the LOD (Level of Detail) mesh for the specified level.

Parameters

lod	The level of detail.

Returns: The asset handle for the mesh at the specified LOD.

Definition at line 179 of file model.cpp.

◆ get_lod_auto_screen_size_power_base()

auto unravel::model::get_lod_auto_screen_size_power_base ( ) const -> float

Gets the auto LOD screen size power base (used for generating a screen-size table).

Returns: Power base.

Definition at line 699 of file model.cpp.

◆ get_lod_hysteresis()

auto unravel::model::get_lod_hysteresis ( ) const -> float

Gets the LOD hysteresis factor used to prevent rapid LOD switching.

Returns: The hysteresis factor (percentage units for percent-based, dimensionless for screen-radius).

Definition at line 669 of file model.cpp.

◆ get_lod_override_enabled()

auto unravel::model::get_lod_override_enabled ( ) const -> bool

Gets whether LOD override is enabled.

Returns: True if LOD override is enabled, false otherwise.

Definition at line 639 of file model.cpp.

◆ get_lod_override_level()

auto unravel::model::get_lod_override_level ( ) const -> uint32_t

Gets the LOD override level.

Returns: The LOD level to use when override is enabled.

Definition at line 649 of file model.cpp.

◆ get_lod_screen_size_min()

auto unravel::model::get_lod_screen_size_min ( ) const -> float

Gets the minimum screen size used by the screen-radius-squared LOD and culling method.

Returns: Minimum screen size.

Definition at line 689 of file model.cpp.

◆ get_lod_screen_sizes()

auto unravel::model::get_lod_screen_sizes ( ) const -> const std::vector<float>&

Gets the per-LOD screen size table used by the screen-radius-squared method.

Returns: Screen size table.

Definition at line 709 of file model.cpp.

◆ get_lod_selection_bias()

auto unravel::model::get_lod_selection_bias ( ) const -> float

Gets the LOD selection bias.

Returns: The bias value added to the calculated LOD index.

Definition at line 659 of file model.cpp.

◆ get_lod_transition_time()

auto unravel::model::get_lod_transition_time ( ) const -> seconds_t

Gets the LOD transition time in seconds.

Returns: The transition duration (0 = instant switch, >0 = smooth dithered crossfade).

Definition at line 679 of file model.cpp.

◆ get_lods()

auto unravel::model::get_lods ( ) const -> const std::vector<asset_handle<mesh>>&

Gets all the LOD meshes.

Returns: A constant reference to the vector of LOD meshes.

Definition at line 240 of file model.cpp.

◆ get_lods_count()

auto unravel::model::get_lods_count ( ) const -> uint32_t

Gets the number of LOD levels available. If there is only one explicit mesh, returns the internal LOD count of that mesh. Otherwise, returns the number of mesh LODs.

Returns: Number of LOD levels available.

Definition at line 245 of file model.cpp.

◆ get_material()

auto unravel::model::get_material ( uint32_t index ) const -> asset_handle<material>

Gets the material for the specified index.

Parameters

index The index.

Returns: The asset handle for the material of the specified index.

Definition at line 298 of file model.cpp.

◆ get_material_instance()

auto unravel::model::get_material_instance ( uint32_t index ) const -> material::sptr

Definition at line 308 of file model.cpp.

◆ get_material_instances()

auto unravel::model::get_material_instances ( ) const -> const std::vector<material::sptr>&

Definition at line 282 of file model.cpp.

◆ get_materials()

auto unravel::model::get_materials ( ) const -> const std::vector<asset_handle<material>>&

Gets all the materials.

Returns: A constant reference to the vector of materials.

Definition at line 277 of file model.cpp.

◆ get_or_emplace_material_instance()

auto unravel::model::get_or_emplace_material_instance ( uint32_t index ) -> material::sptr

Definition at line 328 of file model.cpp.

◆ is_valid()

auto unravel::model::is_valid ( ) const -> bool

Checks if the model is valid.

Returns: True if the model is valid, false otherwise.

Definition at line 174 of file model.cpp.

◆ recalulate_lod_screen_size_limits()

void unravel::model::recalulate_lod_screen_size_limits ( uint32_t lod_count )

Recalculates the screen-size LOD thresholds for the provided LOD count. This is a separate mechanism from the percent-based LOD limits and is used by calculate_lod_data_screen_size.

Parameters

lod_count Number of LOD levels to calculate thresholds for.

Definition at line 614 of file model.cpp.

◆ set_lod()

void unravel::model::set_lod	(	asset_handle< mesh >	mesh,
		uint32_t	lod )

Sets the LOD (Level of Detail) mesh for the specified level.

Parameters

mesh	The mesh to set.
lod	The level of detail.

Definition at line 200 of file model.cpp.

◆ set_lod_auto_screen_size_power_base()

void unravel::model::set_lod_auto_screen_size_power_base ( float value )

Sets the auto LOD screen size power base (used for generating a screen-size table).

Parameters

value Power base.

Definition at line 704 of file model.cpp.

◆ set_lod_hysteresis()

void unravel::model::set_lod_hysteresis ( float hysteresis )

Sets the LOD hysteresis factor.

Parameters

hysteresis The hysteresis factor to prevent ping-ponging between LOD levels.

Definition at line 674 of file model.cpp.

◆ set_lod_override_enabled()

void unravel::model::set_lod_override_enabled ( bool enabled )

Sets whether LOD override is enabled.

Parameters

enabled True to enable LOD override, false to disable.

Definition at line 644 of file model.cpp.

◆ set_lod_override_level()

void unravel::model::set_lod_override_level ( uint32_t level )

Sets the LOD override level.

Parameters

level The LOD level to use when override is enabled.

Definition at line 654 of file model.cpp.

◆ set_lod_screen_size_min()

void unravel::model::set_lod_screen_size_min ( float value )

Sets the minimum screen size used by the screen-radius-squared LOD and culling method.

Parameters

value Minimum screen size.

Definition at line 694 of file model.cpp.

◆ set_lod_screen_sizes()

void unravel::model::set_lod_screen_sizes ( const std::vector< float > & sizes )

Sets the per-LOD screen size table used by the screen-radius-squared method.

Parameters

sizes Screen size table.

Definition at line 714 of file model.cpp.

◆ set_lod_selection_bias()

void unravel::model::set_lod_selection_bias ( float bias )

Sets the LOD selection bias.

Parameters

bias	The bias value to add to the calculated LOD index. Positive values select less detailed LODs, negative values select more detailed LODs.

Definition at line 664 of file model.cpp.

◆ set_lod_transition_time()

void unravel::model::set_lod_transition_time ( seconds_t time )

Sets the LOD transition time in seconds.

Parameters

time	The transition duration (0 = instant switch, >0 = smooth dithered crossfade).

Definition at line 684 of file model.cpp.

◆ set_lods()

void unravel::model::set_lods ( const std::vector< asset_handle< mesh > > & lods )

Sets the LOD meshes.

Parameters

lods	The vector of LOD meshes to set.

Definition at line 264 of file model.cpp.

◆ set_material()

void unravel::model::set_material	(	asset_handle< material >	material,
		uint32_t	index )

Sets the material for the specified index.

Parameters

material	The material to set.
index	The index to set the material at.

Definition at line 220 of file model.cpp.

◆ set_material_instance()

void unravel::model::set_material_instance	(	material::sptr	material,
		uint32_t	index )

Definition at line 230 of file model.cpp.

◆ set_material_instances()

void unravel::model::set_material_instances ( const std::vector< material::sptr > & materials )

Definition at line 293 of file model.cpp.

◆ set_materials()

void unravel::model::set_materials ( const std::vector< asset_handle< material > > & materials )

Sets the materials.

Parameters

materials The vector of materials to set.

Definition at line 288 of file model.cpp.

◆ submit()

void unravel::model::submit	(	const math::mat4 &	world_transform,
		const submesh_pose_mat4 &	submesh_transforms,
		const pose_mat4 &	bone_transforms,
		const std::vector< pose_mat4 > &	skinning_transforms,
		unsigned int	lod,
		const submit_callbacks &	callbacks,
		const math::frustum *	frustum = nullptr,
		const camera *	view = nullptr,
		const model_submit_extras &	extras = {} ) const

Submits the model for rendering.

Parameters

world_transform	The world transform of the model.
submesh_transforms	The submesh transforms (many-to-many mapping).
bone_transforms	The bone transforms for skinned models.
skinning_transforms	The skinning matrices per submesh.
lod	The level of detail to render.
callbacks	The submit callbacks.
frustum	Optional view frustum for per-submesh culling on large meshes.
view	Optional camera enabling per-submesh LOD selection. When supplied together with `frustum` and the mesh has enough submeshes to warrant per-submesh work, distant submeshes may pick a cheaper LOD than `lod` via calculate_submesh_lod. Only affects non-skinned submeshes.

Definition at line 720 of file model.cpp.

◆ submit_for_batching()

void unravel::model::submit_for_batching	(	batch_collector &	collector,
		const math::mat4 &	world_transform,
		const submesh_pose_mat4 &	submesh_transforms,
		uint32_t	lod_index,
		float	lod_param = 0.0f,
		const math::frustum *	frustum = nullptr,
		const camera *	view = nullptr,
		const model_submit_extras &	extras = {} ) const

Collects this model into a batch collector for instanced rendering.

Parameters

collector	The batch collector to add this model to.
world_transform	The world transform of the model.
submesh_transforms	The submesh transforms (many-to-many mapping).
lod_index	The level of detail to use.
lod_param	The LOD transition parameter (for smooth LOD transitions).
frustum	Optional view frustum for per-submesh culling on large meshes.
view	Optional camera enabling per-submesh LOD selection. When supplied and the mesh has many submeshes, each submesh may be collected under a batch key with a per-submesh LOD >= `lod_index`. The batching layer already keys on LOD, so mixed-LOD submeshes for the same model land in the correct batches automatically.

Definition at line 1254 of file model.cpp.

◆ submit_for_shadow_batching_cascaded()

auto unravel::model::submit_for_shadow_batching_cascaded	(	std::vector< shadow_batch_collector > &	collectors,
		uint8_t	cascade_count,
		const math::mat4 &	world_transform,
		const submesh_pose_mat4 &	submesh_transforms,
		uint32_t	lod_index,
		float	lod_param,
		const math::frustum *	frustums,
		bool	nested_cascades,
		const model_submit_extras &	extras = {} ) const -> bool

Collects shadow-map geometry into per-cascade shadow batch collectors. Batches by mesh/lod/submesh/cull and alpha-cutout state instead of material pointer.

Definition at line 1386 of file model.cpp.

◆ submit_for_vertex_pulling()

void unravel::model::submit_for_vertex_pulling	(	const math::mat4 &	world_transform,
		const submesh_pose_mat4 &	submesh_transforms,
		const std::vector< pose_mat4 > &	skinning_transforms,
		unsigned int	lod,
		const submit_vertex_pulling_callbacks &	callbacks,
		const math::frustum *	frustum = nullptr,
		const camera *	view = nullptr,
		const model_submit_extras &	extras = {} ) const

Submits the model using vertex-pulling rendering.

Mirrors submit but skips per-submesh material handling and bind_render_buffers calls, and instead exposes the raw vertex/index buffers as read-only compute buffers so the shader can procedurally generate vertices from gl_VertexID.

Parameters

world_transform	The world transform of the model.
submesh_transforms	The submesh transforms (many-to-many mapping).
skinning_transforms	The per-submesh skinning matrices.
lod	The level of detail to render.
callbacks	The vertex-pulling submit callbacks.
frustum	Optional view frustum for per-submesh culling on large meshes.
view	Optional camera enabling per-submesh LOD selection. Same semantics as submit.

Definition at line 990 of file model.cpp.

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

engine/engine/rendering/model.h
engine/engine/rendering/model.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ seconds_t

Member Function Documentation

◆ calculate_lod_data()

◆ calculate_submesh_lod()

◆ calculate_submesh_lod_from_world_bounds()

◆ compute_lod_index()

◆ default_material()

◆ fallback_material()

◆ get_lod()

◆ get_lod_auto_screen_size_power_base()

◆ get_lod_hysteresis()

◆ get_lod_override_enabled()

◆ get_lod_override_level()

◆ get_lod_screen_size_min()

◆ get_lod_screen_sizes()

◆ get_lod_selection_bias()

◆ get_lod_transition_time()

◆ get_lods()

◆ get_lods_count()

◆ get_material()

◆ get_material_instance()

◆ get_material_instances()

◆ get_materials()

◆ get_or_emplace_material_instance()

◆ is_valid()

◆ recalulate_lod_screen_size_limits()

◆ set_lod()

◆ set_lod_auto_screen_size_power_base()

◆ set_lod_hysteresis()

◆ set_lod_override_enabled()

◆ set_lod_override_level()

◆ set_lod_screen_size_min()

◆ set_lod_screen_sizes()

◆ set_lod_selection_bias()

◆ set_lod_transition_time()

◆ set_lods()

◆ set_material()

◆ set_material_instance()

◆ set_material_instances()

◆ set_materials()

◆ submit()

◆ submit_for_batching()

◆ submit_for_shadow_batching_cascaded()

◆ submit_for_vertex_pulling()