Base class for objects in a G3D::Scene. More...

Inherited by G3D::Camera, G3D::MarkerEntity, G3D::Skybox, G3D::SoundEntity, and G3D::VisibleEntity.

Classes
class	EntityTrack

class	SplineTrack

class	Track
	Base class for Entity animation controllers. More...

Public Member Functions
bool	canCauseCollisions () const

bool	canChange () const
	True if this Entity can change (when not Scene::editing(); all objects can change when in editing mode). More...

const CoordinateFrame &	frame () const
	Current position, i.e., as of last onSimulation call. More...

virtual void	getLastBounds (class AABox &box) const
	Return a world-space axis-aligned bounding box as of the last call to onPose(). More...

virtual void	getLastBounds (class Sphere &sphere) const
	Return a world-space bounding sphere as of the last call to onPose(). More...

virtual void	getLastBounds (class Box &box) const
	Return a world-space bounding box as of the last call to onPose(). More...

virtual bool	intersect (const Ray &R, float &maxDistance, Model::HitInfo &info=Model::HitInfo::ignore) const

virtual bool	intersectBounds (const Ray &R, float &maxDistance, Model::HitInfo &info=Model::HitInfo::ignore) const
	Returns true if there is conservatively some intersection with the object's bounds closer than maxDistance to the ray origin. More...

virtual const Array< Box > &	lastBoxBoundArray () const
	Return a world-space bounding box array for all surfaces produced by this Entity as of the last call to onPose(). More...

bool	lastBoxBoundArraysOverlap (const shared_ptr< Entity > &other) const
	Returns true if the world space bounds of these two entities overlap. More...

RealTime	lastChangeTime () const
	Wall-clock time at which this entity changed in some way, e.g., that might require recomputing a spatial data structure. More...

virtual void	makeGUI (class GuiPane pane, class GApp app)
	Create a user interface for controlling the properties of this Entity. More...

void	markChanged ()
	Sets the lastChangeTime() to the current System::time() More...

float	mass () const

const String &	name () const

virtual void	onPose (Array< shared_ptr< class Surface > > &surfaceArray)
	Pose as of the last simulation time. More...

virtual void	onSimulation (SimTime absoluteTime, SimTime deltaTime)
	Physical simulation callback. More...

bool	physicalSimulation () const

virtual shared_ptr< SoundEntity >	playSound (const shared_ptr< Sound > &sound, const CFrame &childFrame=CFrame(), bool attach=true)
	Creates a new G3D::SoundEntity attached to this Entity at childFrame by an Entity::EntityTrack and returns it. More...

const CoordinateFrame &	previousFrame () const

virtual void	setCanCauseCollisions (bool c)
	If true, causes collisions for other objects during physical simulation. More...

virtual void	setFrame (const CFrame &f, bool updatePreviousFrame=true)
	This sets the position of the Entity for the current simulation step. More...

virtual void	setFrameSpline (const PhysicsFrameSpline &spline)
	If there is a controller on this object and it is a SplineTrack, mutate it to store this value. More...

virtual void	setMass (float m)
	Set to a negative number to tell the physics system to use the absolute value as a density and infer the mass from the mesh on load. More...

virtual void	setPhysicalSimulation (bool s)
	If true, this object should receive physical simulation for its motion. More...

virtual void	setPreviousFrame (const CFrame &f)
	Explicitly override the previous frame value used for computing motion vectors. More...

void	setShouldBeSaved (bool b)

virtual void	setTrack (const shared_ptr< Track > &c)

bool	shouldBeSaved () const
	True if this Entity should be saved when the scene is converted to Any for saving/serialization. More...

virtual Any	toAny (const bool forceAll=false) const
	Converts the current Entity to an Any. More...

virtual shared_ptr< Track >	track () const

virtual void	visualize (RenderDevice *rd, bool isSelected, const class SceneVisualizationSettings &s, const shared_ptr< GFont > &font, const shared_ptr< Camera > &camera)
	Called by Scene::visualize every frame. More...

Protected Member Functions
	Entity ()
	Construct an entity, m_framSplineChange defaults to false. More...

void	init (const String &name, Scene *scene, AnyTableReader &propertyTable)
	The initialization sequence for Entity and its subclasses is different than for typical C++ classes. More...

void	init (const String &name, Scene *scene, const CFrame &frame, const shared_ptr< Track > &controller, bool canChange, bool shouldBeSaved)

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
bool	m_canCauseCollisions = false

bool	m_canChange
	If true, the canChange() method returns true. More...

CoordinateFrame	m_frame
	Current position. More...

AABox	m_lastAABoxBounds
	Bounds at the last pose() call, in world space. More...

RealTime	m_lastBoundsTime
	Time at which the bounds were computed. More...

Array< Box >	m_lastBoxBoundArray
	Bounds on all of the surfaces from the last pose() call, in world space. More...

Box	m_lastBoxBounds
	Bounds at the last pose() call, in world space. More...

RealTime	m_lastChangeTime

AABox	m_lastObjectSpaceAABoxBounds
	Bounds at the last pose() call, in object space. More...

Sphere	m_lastSphereBounds
	Bounds at the last pose() call, in world space. More...

float	m_mass = 1

bool	m_movedSinceLoad
	True if the frame has changed since load. More...

bool	m_movedSinceSimulation = false
	Has this Entity been explicitly moved by setFrame() since it was last simulated? If so, onSimulation will not update the m_previousFrame because it assumes some external logic is moving the Entity. More...

String	m_name

bool	m_physicalSimulation = false

CoordinateFrame	m_previousFrame
	Frame before onSimulation(). More...

Scene *	m_scene

bool	m_shouldBeSaved
	True if this Entity should be saved when the scene is converted to Any for saving/serialization. More...

Any	m_sourceAny
	The Any from which this was originally constructed. More...

shared_ptr< Track >	m_track
	Basic simulation behavior for the Entity. More...

Detailed Description

Base class for objects in a G3D::Scene.

Entity can be subclassed as long as you override the Scene::createEntity method to understand the new subclass.

To make an object controled by its own logic (instead of moving along a predetermined spline), subclass VisibleEntity and override Entity::onSimulation(). Do not invoke the base class's Entity::onSimulation() in that case.

See also: G3D::VisibleEntity, G3D::Widget

Constructor & Destructor Documentation

◆ Entity()

G3D::Entity::Entity ( )

protected

Construct an entity, m_framSplineChange defaults to false.

Member Function Documentation

◆ canCauseCollisions()

bool G3D::Entity::canCauseCollisions ( ) const

inline

◆ canChange()

bool G3D::Entity::canChange ( ) const

inline

True if this Entity can change (when not Scene::editing(); all objects can change when in editing mode).

It is safe to build static data structures over Entitys that cannot change.

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ frame()

const CoordinateFrame& G3D::Entity::frame ( ) const

inline

Current position, i.e., as of last onSimulation call.

◆ getLastBounds() [1/3]

virtual void G3D::Entity::getLastBounds ( class AABox & box ) const

virtual

Return a world-space axis-aligned bounding box as of the last call to onPose().

◆ getLastBounds() [2/3]

virtual void G3D::Entity::getLastBounds ( class Sphere & sphere ) const

virtual

Return a world-space bounding sphere as of the last call to onPose().

◆ getLastBounds() [3/3]

virtual void G3D::Entity::getLastBounds ( class Box & box ) const

virtual

Return a world-space bounding box as of the last call to onPose().

This is always at least as tight as the AABox bounds and often tighter.

◆ init() [1/2]

void G3D::Entity::init	(	const String &	name,
		Scene *	scene,
		AnyTableReader &	propertyTable
	)

protected

The initialization sequence for Entity and its subclasses is different than for typical C++ classes.

That is because they must avoid throwing exceptions from a constructor when parsing, need to support both AnyTableReader and direct parameter versions, and have to verify that all fields from an AnyTableReader are actually consumed. See samples/entity and G3D::VisibleEntity for examples of how to initialize an Entity subclass.

Parameters

name The name of this Entity, e.g., "Player 1"

propertyTable

The form is given below. It is intended that subclasses replace the table name and add new fields.

<some base class name> {
    model     = <modelname>;
    frame     = <initial CFrame or equivalent; overriden if a controller is present>
    track     = <see Entity::Track>;
    canChange = <boolean>
}

The pose field is optional. The Entity base class reads this field. Other subclasses read their own fields.
The original caller (typically, a Scene subclass createEntity or Entity subclass create method) should invoke AnyTableReader::verifyDone to ensure that all of the fields specified were read by some subclass along the inheritance chain.
See VisibleEntity::init for an example of using this method. This method is separate from the constructor solely because it will throw an exception on a parse error, which is dangerous to do during a constructor because the destructor will not run.

scene May be nullptr so long as no entity() controller is used

◆ init() [2/2]

void G3D::Entity::init	(	const String &	name,
		Scene *	scene,
		const CFrame &	frame,
		const shared_ptr< Track > &	controller,
		bool	canChange,
		bool	shouldBeSaved
	)

protected

◆ intersect()

virtual bool G3D::Entity::intersect	(	const Ray &	R,
		float &	maxDistance,
		Model::HitInfo &	info = `Model::HitInfo::ignore`
	)		const

virtual

Reimplemented in G3D::VisibleEntity, G3D::MarkerEntity, and G3D::SoundEntity.

◆ intersectBounds()

virtual bool G3D::Entity::intersectBounds	(	const Ray &	R,
		float &	maxDistance,
		Model::HitInfo &	info = `Model::HitInfo::ignore`
	)		const

virtual

Returns true if there is conservatively some intersection with the object's bounds closer than maxDistance to the ray origin.

If so, updates maxDistance with the intersection distance.

The bounds used may be more accurate than any of the given getLastBounds() results because the method may recurse into individual parts of the scene graph within the Entity.

Reimplemented in G3D::VisibleEntity.

◆ lastBoxBoundArray()

virtual const Array<Box>& G3D::Entity::lastBoxBoundArray ( ) const

inlinevirtual

Return a world-space bounding box array for all surfaces produced by this Entity as of the last call to onPose().

◆ lastBoxBoundArraysOverlap()

bool G3D::Entity::lastBoxBoundArraysOverlap ( const shared_ptr< Entity > & other ) const

Returns true if the world space bounds of these two entities overlap.

See also: lastBoxBoundArray

◆ lastChangeTime()

RealTime G3D::Entity::lastChangeTime ( ) const

inline

Wall-clock time at which this entity changed in some way, e.g., that might require recomputing a spatial data structure.

◆ makeGUI()

virtual void G3D::Entity::makeGUI	(	class GuiPane *	pane,
		class GApp *	app
	)

virtual

Create a user interface for controlling the properties of this Entity.

Called by SceneEditorWindow on selection.

Parameters

app	May be nullptr.

Reimplemented in G3D::Light, G3D::Camera, and G3D::VisibleEntity.

◆ markChanged()

void G3D::Entity::markChanged ( )

inline

Sets the lastChangeTime() to the current System::time()

◆ mass()

float G3D::Entity::mass ( ) const

inline

◆ name()

const String& G3D::Entity::name ( ) const

inline

Referenced by G3D::Light::spotTarget().

◆ onPose()

virtual void G3D::Entity::onPose ( Array< shared_ptr< class Surface > > & surfaceArray )

virtual

Pose as of the last simulation time.

Reimplemented in G3D::Light, G3D::Camera, G3D::ParticleSystem, and G3D::VisibleEntity.

◆ onSimulation()

virtual void G3D::Entity::onSimulation	(	SimTime	absoluteTime,
		SimTime	deltaTime
	)

virtual

Physical simulation callback.

The default implementation animates the model pose (by calling simulatePose()) and moves the frame() along m_frameSpline.

If setFrame() has been called since the last onSimulation call, then the previous frame is not updated to the current frame by onSimulation because it assumes some external logic is maintaining the Entity's position.

Parameters

deltaTime The change in time since the previous call to onSimulation. Two values are special: 0 means that simulation is paused and time should not advance. As much as possible, all state should remain unchanged. For example, anything computed by differentials such as velocity should remain at its current value (rather than becoming infinite!). In particular, this allows freeze-frame rendering of motion blur. The default implementation leaves m_previousFrame and the previous pose unchanged. A value of nan() means that the time has been changed discontinuously, for example, by Scene::setTime. In this case, all state should update to the new absolute time and differentials can be approximated as zero (or whatever other result is reasonable for this Entity).

See also: Scene::setOrder

Reimplemented in G3D::Light, G3D::Camera, G3D::ParticleSystem, G3D::VisibleEntity, G3D::MarkerEntity, G3D::SoundEntity, and G3D::XRWidget::TrackedEntity.

◆ physicalSimulation()

bool G3D::Entity::physicalSimulation ( ) const

inline

◆ playSound()

virtual shared_ptr<SoundEntity> G3D::Entity::playSound	(	const shared_ptr< Sound > &	sound,
		const CFrame &	childFrame = `CFrame()`,
		bool	attach = `true`
	)

virtual

Creates a new G3D::SoundEntity attached to this Entity at childFrame by an Entity::EntityTrack and returns it.

The new SoundEntity is automatically added to the Scene and will remain rigidly attached to the Entity.

You do not need to retain the pointer to the created sound for it to remain playing and in the scene. The SoundEntity will automatically remove itself from the Scene when it stops playing.

If attach == false, then the EntityTrack is not created and the sound will remain fixed in space.

◆ previousFrame()

const CoordinateFrame& G3D::Entity::previousFrame ( ) const

inline

◆ setCanCauseCollisions()

virtual void G3D::Entity::setCanCauseCollisions ( bool c )

inlinevirtual

If true, causes collisions for other objects during physical simulation.

It may not react to those collisions if physicalSimulation is false. Default is true for VisibleEntity and false for other subclasses.

◆ setFrame()

virtual void G3D::Entity::setFrame	(	const CFrame &	f,
		bool	updatePreviousFrame = `true`
	)

virtual

This sets the position of the Entity for the current simulation step.

If there is a controller set and the base class Entity::onSimulation is invoked, it will override the value assigned here.

◆ setFrameSpline()

virtual void G3D::Entity::setFrameSpline ( const PhysicsFrameSpline & spline )

virtual

If there is a controller on this object and it is a SplineTrack, mutate it to store this value.

Otherwise, create a new SplineTrack to overwrite the current controller.

See also: setTrack

Used by SceneEditorWindow

◆ setMass()

virtual void G3D::Entity::setMass ( float m )

inlinevirtual

Set to a negative number to tell the physics system to use the absolute value as a density and infer the mass from the mesh on load.

Default is -10 (kg/m^3).

◆ setPhysicalSimulation()

virtual void G3D::Entity::setPhysicalSimulation ( bool s )

inlinevirtual

If true, this object should receive physical simulation for its motion.

If true, canMove must also be true and there must be no Track on this Entity.

◆ setPreviousFrame()

virtual void G3D::Entity::setPreviousFrame ( const CFrame & f )

inlinevirtual

Explicitly override the previous frame value used for computing motion vectors.

This is very rarely needed because simulation automatically updates this value.

◆ setShouldBeSaved()

void G3D::Entity::setShouldBeSaved ( bool b )

inline

◆ setTrack()

virtual void G3D::Entity::setTrack ( const shared_ptr< Track > & c )

inlinevirtual

See also: Entity::Track

◆ shouldBeSaved()

bool G3D::Entity::shouldBeSaved ( ) const

inline

True if this Entity should be saved when the scene is converted to Any for saving/serialization.

Defaults to true. Set to false for transient objects. For example, a character's spawn point Entity might have shouldBeSaved() = true, while the character itself might have shouldBeSaved() = false. This would allow editing of the scene while the simulation loop is running without having the scene at the end of the editing session reflecting the result of the character moving about.

◆ toAny()

virtual Any G3D::Entity::toAny ( const bool forceAll = false ) const

virtual

Converts the current Entity to an Any.

Subclasses should modify at least the name of the Table, which will be "Entity" if not changed.

See also: shouldBeSaved

Reimplemented in G3D::Light, G3D::ParticleSystem, G3D::VisibleEntity, G3D::Camera, G3D::MarkerEntity, G3D::Skybox, and G3D::SoundEntity.

◆ track()

virtual shared_ptr<Track> G3D::Entity::track ( ) const

inlinevirtual

See also: Entity::Track

◆ visualize()

virtual void G3D::Entity::visualize	(	RenderDevice *	rd,
		bool	isSelected,
		const class SceneVisualizationSettings &	s,
		const shared_ptr< GFont > &	font,
		const shared_ptr< Camera > &	camera
	)

virtual

Called by Scene::visualize every frame.

During this, Entitys may make rendering calls according to the SceneVisualizationSettings to display control points and other features.

Parameters

isSelected True if this entity is selected by a sceneEditorWindow, which may trigger additional visualization for it.

Reimplemented in G3D::MarkerEntity, and G3D::SoundEntity.

Member Data Documentation

◆ m_canCauseCollisions

bool G3D::Entity::m_canCauseCollisions = false

protected

Referenced by canCauseCollisions(), and setCanCauseCollisions().

◆ m_canChange

bool G3D::Entity::m_canChange

protected

If true, the canChange() method returns true.

Defaults to true.

It is illegal to set m_canChange to false if m_frameSpline has more than one control point because a spline implies animation.

Subclasses should set this to false during initialization if the object will never move so that other classes can precompute data structures that are affected by the Entity.

Referenced by canChange().

◆ m_frame

CoordinateFrame G3D::Entity::m_frame

protected

Current position.

Do not directly mutate–invoke setFrame() to ensure that times are modified correctly.

Referenced by G3D::Light::distance(), frame(), G3D::Light::frame(), and G3D::Light::position().

◆ m_lastAABoxBounds

AABox G3D::Entity::m_lastAABoxBounds

protected

Bounds at the last pose() call, in world space.

◆ m_lastBoundsTime

RealTime G3D::Entity::m_lastBoundsTime

protected

Time at which the bounds were computed.

◆ m_lastBoxBoundArray

Array<Box> G3D::Entity::m_lastBoxBoundArray

protected

Bounds on all of the surfaces from the last pose() call, in world space.

Referenced by lastBoxBoundArray().

◆ m_lastBoxBounds

Box G3D::Entity::m_lastBoxBounds

protected

Bounds at the last pose() call, in world space.

◆ m_lastChangeTime

RealTime G3D::Entity::m_lastChangeTime

protected

Referenced by lastChangeTime(), markChanged(), G3D::Light::setEnabled(), and G3D::Light::setShadowsEnabled().

◆ m_lastObjectSpaceAABoxBounds

AABox G3D::Entity::m_lastObjectSpaceAABoxBounds

protected

Bounds at the last pose() call, in object space.

◆ m_lastSphereBounds

Sphere G3D::Entity::m_lastSphereBounds

protected

Bounds at the last pose() call, in world space.

◆ m_mass

float G3D::Entity::m_mass = 1

protected

Referenced by mass(), and setMass().

◆ m_movedSinceLoad

bool G3D::Entity::m_movedSinceLoad

protected

True if the frame has changed since load.

Used by toAny() to decide if m_sourceAny is out of date.

◆ m_movedSinceSimulation

bool G3D::Entity::m_movedSinceSimulation = false

protected

Has this Entity been explicitly moved by setFrame() since it was last simulated? If so, onSimulation will not update the m_previousFrame because it assumes some external logic is moving the Entity.

◆ m_name

String G3D::Entity::m_name

protected

Referenced by name().

◆ m_physicalSimulation

bool G3D::Entity::m_physicalSimulation = false

protected

Referenced by physicalSimulation(), and setPhysicalSimulation().

◆ m_previousFrame

CoordinateFrame G3D::Entity::m_previousFrame

protected

Frame before onSimulation().

Used for tracking poses and for velocity estimation.

Referenced by previousFrame(), and setPreviousFrame().

◆ m_scene

Scene* G3D::Entity::m_scene

protected

◆ m_shouldBeSaved

bool G3D::Entity::m_shouldBeSaved

protected

True if this Entity should be saved when the scene is converted to Any for saving/serialization.

Defaults to true. Set to false for transient objects. For example, a character's spawn point Entity might have shouldBeSaved() = true, while the character itself might have shouldBeSaved() = false. This would allow editing of the scene while the simulation loop is running without having the scene at the end of the editing session reflecting the result of the character moving about.

Referenced by setShouldBeSaved(), and shouldBeSaved().

◆ m_sourceAny

Any G3D::Entity::m_sourceAny

protected

The Any from which this was originally constructed.

◆ m_track

shared_ptr<Track> G3D::Entity::m_track

protected

Basic simulation behavior for the Entity.

If nullptr, the Entity is never moved by the base class' onSimulation method. You can subclass Track, but it is usually easier to subclass Entity and override onSimulation directly when creating behaviors more complex than those supported by the default Track language.

Referenced by setTrack(), and track().

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Entity()

Member Function Documentation

◆ canCauseCollisions()

◆ canChange()

◆ createShared()

◆ frame()

◆ getLastBounds() [1/3]

◆ getLastBounds() [2/3]

◆ getLastBounds() [3/3]

◆ init() [1/2]

◆ init() [2/2]

◆ intersect()

◆ intersectBounds()

◆ lastBoxBoundArray()

◆ lastBoxBoundArraysOverlap()

◆ lastChangeTime()

◆ makeGUI()

◆ markChanged()

◆ mass()

◆ name()

◆ onPose()

◆ onSimulation()

◆ physicalSimulation()

◆ playSound()

◆ previousFrame()

◆ setCanCauseCollisions()

◆ setFrame()

◆ setFrameSpline()

◆ setMass()

◆ setPhysicalSimulation()

◆ setPreviousFrame()

◆ setShouldBeSaved()

◆ setTrack()

◆ shouldBeSaved()

◆ toAny()

◆ track()

◆ visualize()

Member Data Documentation

◆ m_canCauseCollisions

◆ m_canChange

◆ m_frame

◆ m_lastAABoxBounds

◆ m_lastBoundsTime

◆ m_lastBoxBoundArray

◆ m_lastBoxBounds

◆ m_lastChangeTime

◆ m_lastObjectSpaceAABoxBounds

◆ m_lastSphereBounds

◆ m_mass

◆ m_movedSinceLoad

◆ m_movedSinceSimulation

◆ m_name

◆ m_physicalSimulation

◆ m_previousFrame

◆ m_scene

◆ m_shouldBeSaved

◆ m_sourceAny

◆ m_track