Base class and top-level entry point for A3D applications. More...

#include <a3d/Application.h>

Public Member Functions
	Application (int argc, char *argv[], log::Level logLevel=log::Level::Info)
	Creates application state from process arguments and configures logging. More...

Static Public Member Functions
static int	Run (std::unique_ptr< Application > application)
	Runs `application` using the platform host loop. More...

Protected Types
using	SceneCommand = std::function< void(Scene &)>
	Callable queued for execution at a simulation-step boundary. More...

Protected Member Functions
virtual std::unique_ptr< Scene >	init ()=0
	Creates the initial Scene for the application. More...

virtual SimulationConfig	simulationConfig () const
	Supplies the initial simulation scheduling configuration. More...

virtual bool	shouldContinue (const Scene &scene)
	Determines whether the application host loop should continue. More...

virtual void	didShutdown ()
	Called after the Runner and Scene have been destroyed during shutdown. More...

Runner &	runner ()
	Returns the application's Runner after initialization. More...

const Runner &	runner () const
	Returns the application's Runner after initialization. More...

Scene &	scene ()
	Returns the application's Scene after initialization. More...

const Scene &	scene () const
	Returns the application's Scene after initialization. More...

void	queueScenePreStepCommand (SceneCommand command)
	Queues `command` to run before the next simulation step. More...

void	queueScenePostStepCommand (SceneCommand command)
	Queues `command` to run after the next simulation step. More...

const std::vector< std::string > &	args () const
	Returns process command-line arguments excluding the executable name. More...

virtual void	runnerUpdate (Runner &runner, Scene &scene, const Runner::UpdateInfo &info)
	Called near the beginning of each Runner host update. More...

virtual void	inputDidUpdate (Runner &runner, Scene &scene, InputContext &inputContext, const InputContext::UpdateInfo &)
	Called after the InputContext has processed the current host update. More...

virtual void	sceneWillStep (Runner &runner, Scene &scene, const Scene::StepInfo &info)
	Called immediately before each Scene simulation step. More...

virtual void	sceneDidStep (Runner &runner, Scene &scene, const Scene::StepInfo &info)
	Called immediately after each Scene simulation step. More...

virtual void	frameDidBegin (Runner &runner, Scene &scene, VisualWorld &visualWorld, const VisualWorld::RenderInfo &info)
	Called after a render frame begins and before scene traversal and drawing. More...

virtual void	contactDidBegin (Runner &runner, Scene &scene, PhysicsWorld &physicsWorld, const PhysicsContact &contact)
	Called when the PhysicsWorld reports the beginning of a contact. More...

virtual void	contactDidContinue (Runner &runner, Scene &scene, PhysicsWorld &physicsWorld, const PhysicsContact &contact)
	Called when the PhysicsWorld reports a continuing contact. More...

virtual void	contactDidEnd (Runner &runner, Scene &scene, PhysicsWorld &physicsWorld, const PhysicsContact &contact)
	Called when the PhysicsWorld reports the end of a contact. More...

Detailed Description

Base class and top-level entry point for A3D applications.

Applications normally derive from Application, implement init() to create the initial Scene, and optionally override the protected lifecycle and simulation callbacks. Transfer ownership of the derived instance to Run(), which drives the platform host loop for the lifetime of the application.

Application owns the Scene and Runner created for an application and coordinates initialization, host updates, input, simulation callbacks, rendering, contact callbacks, and shutdown.

Unlike other A3D classes, Application is intentionally designed to be subclassed by application code; its protected API is part of the supported application interface.

Definition at line 46 of file Application.h.

Member Typedef Documentation

◆ SceneCommand

using a3d::Application::SceneCommand = std::function<void(Scene&)>

protected

Callable queued for execution at a simulation-step boundary.

Definition at line 90 of file Application.h.

Constructor & Destructor Documentation

◆ Application()

a3d::Application::Application	(	int	argc,
		char *	argv[],
		log::Level	logLevel = `log::Level::Info`
	)

Creates application state from process arguments and configures logging.

Derived application constructors normally forward their process arguments and desired initial log level to this constructor.

Parameters

argc	number of process command-line arguments.
argv	process command-line argument array.
logLevel	initial application log level.

Member Function Documentation

◆ args()

const std::vector< std::string > & a3d::Application::args ( ) const

protected

Returns process command-line arguments excluding the executable name.

◆ contactDidBegin()

virtual void a3d::Application::contactDidBegin	(	Runner &	runner,
		Scene &	scene,
		PhysicsWorld &	physicsWorld,
		const PhysicsContact &	contact
	)

protectedvirtual

Called when the PhysicsWorld reports the beginning of a contact.

The default implementation does nothing.

◆ contactDidContinue()

virtual void a3d::Application::contactDidContinue	(	Runner &	runner,
		Scene &	scene,
		PhysicsWorld &	physicsWorld,
		const PhysicsContact &	contact
	)

protectedvirtual

Called when the PhysicsWorld reports a continuing contact.

The default implementation does nothing.

◆ contactDidEnd()

virtual void a3d::Application::contactDidEnd	(	Runner &	runner,
		Scene &	scene,
		PhysicsWorld &	physicsWorld,
		const PhysicsContact &	contact
	)

protectedvirtual

Called when the PhysicsWorld reports the end of a contact.

The default implementation does nothing.

◆ didShutdown()

virtual void a3d::Application::didShutdown ( )

protectedvirtual

Called after the Runner and Scene have been destroyed during shutdown.

The default implementation does nothing. Exceptions escaping this hook are ignored because application teardown must not throw.

◆ frameDidBegin()

virtual void a3d::Application::frameDidBegin	(	Runner &	runner,
		Scene &	scene,
		VisualWorld &	visualWorld,
		const VisualWorld::RenderInfo &	info
	)

protectedvirtual

Called after a render frame begins and before scene traversal and drawing.

The default implementation does nothing.

◆ init()

virtual std::unique_ptr< Scene > a3d::Application::init ( )

protectedpure virtual

Creates the initial Scene for the application.

Called once during startup before the Runner is created. Implementations must return a non-null Scene. runner() and scene() are not available while init() is executing.

Returns: the Scene to own and drive for the lifetime of the application.

◆ inputDidUpdate()

virtual void a3d::Application::inputDidUpdate	(	Runner &	runner,
		Scene &	scene,
		InputContext &	inputContext,
		const InputContext::UpdateInfo &
	)

protectedvirtual

Called after the InputContext has processed the current host update.

The default implementation does nothing.

◆ queueScenePostStepCommand()

void a3d::Application::queueScenePostStepCommand ( SceneCommand command )

protected

Queues command to run after the next simulation step.

The command runs after physics advances and before sceneDidStep().

Exceptions

std::invalid_argument if command is empty.

◆ queueScenePreStepCommand()

void a3d::Application::queueScenePreStepCommand ( SceneCommand command )

protected

Queues command to run before the next simulation step.

The command runs before sceneWillStep() and before physics advances.

Exceptions

std::invalid_argument if command is empty.

◆ Run()

static int a3d::Application::Run ( std::unique_ptr< Application > application )

static

Runs application using the platform host loop.

Run() takes ownership of application. On native builds it blocks until execution stops and shutdown completes. On web builds it installs the browser main loop and returns after scheduling execution; the Application is destroyed when that loop terminates.

Returns: zero after successful launch or completion.

Exceptions

std::invalid_argument if application is nullptr.

◆ runner() [1/2]

Runner & a3d::Application::runner ( )

protected

Returns the application's Runner after initialization.

Exceptions

std::logic_error if the Runner has not yet been initialized.

◆ runner() [2/2]

const Runner & a3d::Application::runner ( ) const

protected

Returns the application's Runner after initialization.

Exceptions

std::logic_error if the Runner has not yet been initialized.

◆ runnerUpdate()

virtual void a3d::Application::runnerUpdate	(	Runner &	runner,
		Scene &	scene,
		const Runner::UpdateInfo &	info
	)

protectedvirtual

Called near the beginning of each Runner host update.

This hook runs before event polling, input update, simulation scheduling, and rendering. The default implementation does nothing.

◆ scene() [1/2]

Scene & a3d::Application::scene ( )

protected

Returns the application's Scene after initialization.

Exceptions

std::logic_error if the Scene has not yet been initialized.

◆ scene() [2/2]

const Scene & a3d::Application::scene ( ) const

protected

Returns the application's Scene after initialization.

Exceptions

std::logic_error if the Scene has not yet been initialized.

◆ sceneDidStep()

virtual void a3d::Application::sceneDidStep	(	Runner &	runner,
		Scene &	scene,
		const Scene::StepInfo &	info
	)

protectedvirtual

Called immediately after each Scene simulation step.

Queued post-step Scene commands execute before this hook. The default implementation does nothing.

◆ sceneWillStep()

virtual void a3d::Application::sceneWillStep	(	Runner &	runner,
		Scene &	scene,
		const Scene::StepInfo &	info
	)

protectedvirtual

Called immediately before each Scene simulation step.

Queued pre-step Scene commands execute before this hook. The default implementation does nothing.

◆ shouldContinue()

virtual bool a3d::Application::shouldContinue ( const Scene & scene )

protectedvirtual

Determines whether the application host loop should continue.

Called before each Runner host update. Returning false stops the Runner and begins application shutdown. The default implementation returns true.

◆ simulationConfig()

virtual SimulationConfig a3d::Application::simulationConfig ( ) const

protectedvirtual

Supplies the initial simulation scheduling configuration.

Called once after init() and before the Runner is started. The default implementation returns a default-constructed SimulationConfig.

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

a3d/Application.h

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ SceneCommand

Constructor & Destructor Documentation

◆ Application()

Member Function Documentation

◆ args()

◆ contactDidBegin()

◆ contactDidContinue()

◆ contactDidEnd()

◆ didShutdown()

◆ frameDidBegin()

◆ init()

◆ inputDidUpdate()

◆ queueScenePostStepCommand()

◆ queueScenePreStepCommand()

◆ Run()

◆ runner() [1/2]

◆ runner() [2/2]

◆ runnerUpdate()

◆ scene() [1/2]

◆ scene() [2/2]

◆ sceneDidStep()

◆ sceneWillStep()

◆ shouldContinue()

◆ simulationConfig()