Manages the visual presentation, camera, and visual queries for a Scene. More...

#include <a3d/visual/VisualWorld.h>

Classes
struct	Capabilities
	Rendering capabilities available through this VisualWorld. More...

struct	HitTestOptions
	Options controlling visual hit testing. More...

struct	RenderInfo
	Timing and progression information associated with a rendered frame. More...

Public Types
using	DidBeginFrameCallback = std::function< void(VisualWorld &visualWorld, const RenderInfo &info)>
	Callback invoked after renderer frame setup and before Scene rendering begins. More...

Public Member Functions
	VisualWorld (RenderContext &context)
	Creates a VisualWorld that renders through `context`. More...

Capabilities	capabilities () const
	Returns the rendering capabilities currently available to the VisualWorld. More...

const std::optional< Background > &	background () const
	Returns the optional Scene background. More...

void	background (const std::optional< Background > &background)
	Sets or disables the Scene background. More...

const std::optional< Fog > &	fog () const
	Returns the optional distance fog configuration. More...

void	fog (const std::optional< Fog > &fog)
	Sets or disables distance fog. More...

const std::optional< Atmosphere > &	atmosphere () const
	Returns the optional atmosphere configuration. More...

void	atmosphere (const std::optional< Atmosphere > &atmosphere)
	Sets or disables atmospheric effects. More...

const std::optional< Ground > &	ground () const
	Returns the optional visual ground configuration. More...

void	ground (const std::optional< Ground > &ground)
	Sets or disables visual ground rendering. More...

const std::optional< a3d::Surface > &	surface () const
	Returns the optional reference Surface used by ground and atmospheric effects. More...

void	surface (const std::optional< a3d::Surface > &surface)
	Sets or removes the reference Surface used by ground and atmospheric effects. More...

std::weak_ptr< Node > &	pointOfView ()
	Returns the weak reference to the camera Node used as the point of view. More...

void	pointOfView (const std::weak_ptr< Node > &cameraNode)
	Sets the camera Node used as the point of view. More...

math::vec3	projectPoint (const math::vec3 &point) const
	Projects a world-space point into logical viewport coordinates. More...

math::vec3	unprojectPoint (const math::vec3 &point) const
	Unprojects a logical viewport point into world coordinates. More...

std::vector< HitTestResult >	hitTest (const math::vec2 &point, const HitTestOptions &options) const
	Hit-tests visible Scene mesh geometry beneath a logical viewport point. More...

std::vector< HitTestResult >	hitTest (const math::vec2 &point) const
	Hit-tests the closest visible Scene mesh geometry beneath a logical viewport point. More...

bool	defaultLightingEnabled () const
	Returns whether renderer-provided default lighting is enabled. More...

void	defaultLightingEnabled (bool enabled)
	Enables or disables renderer-provided default lighting. More...

DidBeginFrameCallback	didBeginFrameCallback () const
	Returns the callback invoked immediately before Scene rendering begins. More...

void	didBeginFrameCallback (DidBeginFrameCallback function)
	Sets the begin-frame callback; an empty callback disables it. More...

RenderContext *	renderContext () const
	Returns the non-owning RenderContext associated with this VisualWorld. More...

Scene *	scene () const
	Returns the Scene this VisualWorld is attached to, or nullptr if unattached. More...

Detailed Description

Manages the visual presentation, camera, and visual queries for a Scene.

A VisualWorld renders through the RenderContext supplied at construction and stores a non-owning reference to that context. The RenderContext must outlive the VisualWorld.

If no point of view is set before the first draw, VisualWorld uses the first camera node it finds in the Scene. If the Scene contains no camera, a default perspective camera node is created and added to the Scene root.

Definition at line 53 of file VisualWorld.h.

Member Typedef Documentation

◆ DidBeginFrameCallback

using a3d::VisualWorld::DidBeginFrameCallback = std::function<void(VisualWorld& visualWorld, const RenderInfo& info)>

Callback invoked after renderer frame setup and before Scene rendering begins.

Definition at line 99 of file VisualWorld.h.

Constructor & Destructor Documentation

◆ VisualWorld()

a3d::VisualWorld::VisualWorld ( RenderContext & context )

explicit

Creates a VisualWorld that renders through context.

context is retained non-owningly and must outlive this VisualWorld.

Member Function Documentation

◆ atmosphere() [1/2]

const std::optional< Atmosphere > & a3d::VisualWorld::atmosphere ( ) const

Returns the optional atmosphere configuration.

◆ atmosphere() [2/2]

void a3d::VisualWorld::atmosphere ( const std::optional< Atmosphere > & atmosphere )

Sets or disables atmospheric effects.

An enabled Atmosphere requires a Surface; limb glow additionally requires a SphereSurface.

Exceptions

std::logic_error	if the required Surface configuration is absent.
std::invalid_argument	if an atmospheric numeric parameter is invalid.

◆ background() [1/2]

const std::optional< Background > & a3d::VisualWorld::background ( ) const

Returns the optional Scene background.

◆ background() [2/2]

void a3d::VisualWorld::background ( const std::optional< Background > & background )

Sets or disables the Scene background.

Background contents must be a Color or a Texture containing a CubeImage. A cubemap Texture is expected to have a non-null Sampler; its wrapping is set to ClampToEdge on all three axes.

Exceptions

std::invalid_argument if the supplied background contents are invalid.

◆ capabilities()

Capabilities a3d::VisualWorld::capabilities ( ) const

Returns the rendering capabilities currently available to the VisualWorld.

◆ defaultLightingEnabled() [1/2]

bool a3d::VisualWorld::defaultLightingEnabled ( ) const

Returns whether renderer-provided default lighting is enabled.

◆ defaultLightingEnabled() [2/2]

void a3d::VisualWorld::defaultLightingEnabled ( bool enabled )

Enables or disables renderer-provided default lighting.

When enabled, material base content is rendered without evaluating the Scene's ambient, directional, point, or spot lights.

◆ didBeginFrameCallback() [1/2]

DidBeginFrameCallback a3d::VisualWorld::didBeginFrameCallback ( ) const

Returns the callback invoked immediately before Scene rendering begins.

◆ didBeginFrameCallback() [2/2]

void a3d::VisualWorld::didBeginFrameCallback ( DidBeginFrameCallback function )

Sets the begin-frame callback; an empty callback disables it.

◆ fog() [1/2]

const std::optional< Fog > & a3d::VisualWorld::fog ( ) const

Returns the optional distance fog configuration.

◆ fog() [2/2]

void a3d::VisualWorld::fog ( const std::optional< Fog > & fog )

Sets or disables distance fog.

Exceptions

std::invalid_argument if distances or transition exponent are invalid.

◆ ground() [1/2]

const std::optional< Ground > & a3d::VisualWorld::ground ( ) const

Returns the optional visual ground configuration.

◆ ground() [2/2]

void a3d::VisualWorld::ground ( const std::optional< Ground > & ground )

Sets or disables visual ground rendering.

An enabled Ground requires a Surface.

Exceptions

std::logic_error	if no Surface is configured.
std::invalid_argument	if a ground, fade, or haze parameter is invalid.

◆ hitTest() [1/2]

std::vector< HitTestResult > a3d::VisualWorld::hitTest ( const math::vec2 & point ) const

Hit-tests the closest visible Scene mesh geometry beneath a logical viewport point.

◆ hitTest() [2/2]

std::vector< HitTestResult > a3d::VisualWorld::hitTest	(	const math::vec2 &	point,
		const HitTestOptions &	options
	)		const

Hit-tests visible Scene mesh geometry beneath a logical viewport point.

With elementBoundsOnly enabled, MeshElement bounds are tested instead of triangles and returned hits do not contain a face index.

Exceptions

std::runtime_error if the Scene, point of view, or viewport cannot produce a valid hit-test ray.

◆ pointOfView() [1/2]

std::weak_ptr< Node > & a3d::VisualWorld::pointOfView ( )

Returns the weak reference to the camera Node used as the point of view.

◆ pointOfView() [2/2]

void a3d::VisualWorld::pointOfView ( const std::weak_ptr< Node > & cameraNode )

Sets the camera Node used as the point of view.

Passing an empty weak pointer clears the explicit point of view. If no point of view is set before the first draw, first-draw initialization selects or creates a Scene camera automatically.

◆ projectPoint()

math::vec3 a3d::VisualWorld::projectPoint ( const math::vec3 & point ) const

Projects a world-space point into logical viewport coordinates.

The returned X and Y use a top-left viewport origin. Z is normalized so 0 corresponds to the near clip plane and 1 to the far clip plane.

Exceptions

std::runtime_error if no valid point of view or viewport is available.

◆ renderContext()

RenderContext * a3d::VisualWorld::renderContext ( ) const

Returns the non-owning RenderContext associated with this VisualWorld.

◆ scene()

Scene * a3d::VisualWorld::scene ( ) const

Returns the Scene this VisualWorld is attached to, or nullptr if unattached.

◆ surface() [1/2]

const std::optional< a3d::Surface > & a3d::VisualWorld::surface ( ) const

Returns the optional reference Surface used by ground and atmospheric effects.

◆ surface() [2/2]

void a3d::VisualWorld::surface ( const std::optional< a3d::Surface > & surface )

Sets or removes the reference Surface used by ground and atmospheric effects.

The Surface cannot be removed while Ground or Atmosphere is enabled, and an Atmosphere with limb glow requires a SphereSurface.

Exceptions

std::logic_error	if the requested Surface conflicts with enabled effects.
std::invalid_argument	if the Surface contains invalid geometry.

◆ unprojectPoint()

math::vec3 a3d::VisualWorld::unprojectPoint ( const math::vec3 & point ) const

Unprojects a logical viewport point into world coordinates.

Input X and Y use a top-left viewport origin. Input Z uses normalized depth, with 0 at the near clip plane and 1 at the far clip plane.

Exceptions

std::runtime_error if no valid point of view or viewport is available.

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

a3d/visual/VisualWorld.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ DidBeginFrameCallback

Constructor & Destructor Documentation

◆ VisualWorld()

Member Function Documentation

◆ atmosphere() [1/2]

◆ atmosphere() [2/2]

◆ background() [1/2]

◆ background() [2/2]

◆ capabilities()

◆ defaultLightingEnabled() [1/2]

◆ defaultLightingEnabled() [2/2]

◆ didBeginFrameCallback() [1/2]

◆ didBeginFrameCallback() [2/2]

◆ fog() [1/2]

◆ fog() [2/2]

◆ ground() [1/2]

◆ ground() [2/2]

◆ hitTest() [1/2]

◆ hitTest() [2/2]

◆ pointOfView() [1/2]

◆ pointOfView() [2/2]

◆ projectPoint()

◆ renderContext()

◆ scene()

◆ surface() [1/2]

◆ surface() [2/2]

◆ unprojectPoint()