Nebula
Loading...
Searching...
No Matches
Game::TransformHierarchy Class Reference

#include <transformhierarchy.h>

Detailed Description

The parent, child and sibling links of the entities in one world's hierarchy.

The hierarchy is the index of which entity is below which. The transforms are not stored here: the local transform is the Game::HTransform component and the world transform is Game::Position, Game::Orientation and Game::Scale, which is what every consumer reads through the query buffers.

An instance is an entity which has a local transform, or an entity which is the parent of one, because a world transform written on a parent has to reach the entities below it.

A write which goes through Game::World::SetComponent is computed at the time it happens, and it propagates to the instances below it, so a transform read after a write is the transform which was written. Propagation goes one way only, towards the leaves.

IsInHierarchy() is the test a transform writer makes before it does anything. It is one bit in a dense array, keyed by entity.index, which is what keeps the common case - an entity which is not part of a hierarchy - on a single cache line. The bit says that the entity had an instance when the bit was set, so an instance which outlived its entity can still answer true for a reused entity id. The instance lookup checks the generation and answers false for that, which is the only case where a write pays the lookup.

A component which has been queued but not executed yet is not in a table, so it cannot be computed. Such an instance is put in the pending set, and ResolvePending() computes it when its components, and the components of its parent, are in a table.

See also
Game::World

Inherits Core::RefCounted.

Classes

struct  ComponentPointers
 the component pointers of an instance. More...

Private Types

enum  Member {
  OwnerEntity = 0 , Parent = 1 , FirstChild = 2 , NextSibling = 3 ,
  PreviousSibling = 4 , HasLocalTransform = 5
}
 the members of the instance data More...

Private Member Functions

__DeclareClass(TransformHierarchy) public void Initialize (Game::World *world)
 the world this hierarchy belongs to. Set by the world which owns it
void SetLocalTransform (uint32_t instance, Math::mat4 const &value)
 Set the local transform of an instance, compute the world transform it implies and propagate to the instances below it.
void SetLocalTransform (Game::Entity entity, Math::mat4 const &value)
void SetLocalTransform (uint32_t instance)
void SetLocalTransform (Game::Entity entity)
void SetWorldTransform (uint32_t instance, Math::mat4 const &value)
 Set the world transform of an instance, which derives the local transform it implies through the inverse of the parent, and propagate to the instances below it.
void SetWorldTransform (Game::Entity entity, Math::mat4 const &value)
void SetWorldTransform (uint32_t instance)
void SetWorldTransform (Game::Entity entity)
Math::mat4 GetLocalTransform (uint32_t instance) const
 the transforms of an instance, read from the components which own them
Math::mat4 GetLocalTransform (Game::Entity entity) const
Math::mat4 GetWorldTransform (uint32_t instance) const
Math::mat4 GetWorldTransform (Game::Entity entity) const
void SetParent (Game::Entity entity, Game::Entity parent)
 Update relationships.
void SetParent (uint32_t instance, uint32_t parentInstance)
 Set the parent of an instance and compute it.
uint32_t GetParent (uint32_t instance) const
 Get parent of instance.
Game::Entity GetOwner (uint32_t instance) const
 Get owner of instance.
uint32_t GetFirstChild (uint32_t instance) const
 Get first child of instance.
uint32_t GetNextSibling (uint32_t instance) const
 Get the first sibling of this instance.
uint32_t GetPreviousSibling (uint32_t instance) const
 Get the previous sibling of this instance.
bool HasChildren (uint32_t instance) const
 an instance which has children is one the writer has to walk into
uint32_t GetInstance (Game::Entity entity) const
 the instance of an entity, or InvalidInstance when the entity is not part of the hierarchy
bool IsInHierarchy (Game::Entity entity) const
 the fast test for a transform writer, one bit in a dense array keyed by entity.index
uint32_t Add (Game::Entity entity, Game::Entity parent)
 add an entity to the hierarchy with the parent its component names, and compute it
void Remove (Game::Entity entity)
 remove an entity from the hierarchy. Its children become roots with the world transform they have
void RemoveInstance (uint32_t instance)
 remove an instance, patching the links which name the slot the swap-erase moves into it
void ResolvePending ()
 compute the instances which could not be computed when they were written
SizeT Size () const
 number of hierarchy instances, and number of instances waiting for their components
SizeT NumPending () const
void Clear ()
 clear the hierarchy
bool LinkUnderParent (uint32_t instance, uint32_t parentInstance)
 link an instance under a parent instance. False when the link would close a cycle
void Unlink (uint32_t instance)
 take an instance out of the links, without touching its components
void Detach (uint32_t instance, ComponentPointers const &components)
 make the local transform of an instance be the world transform it currently has, and detach it
void DeriveLocal (uint32_t instance, ComponentPointers const &components)
 derive the local transform from the world transform the components hold
void Compute (uint32_t instance)
 compute one instance from what its components hold and put its children in the walk queue
void Walk (uint32_t instance)
 walk the instances below an instance, computing each of them
void FlushStale ()
 take out the instances which were found to name an entity that is gone during a walk
uint32_t EnsureInstance (Game::Entity entity, bool hasLocalTransform)
 the instance of an entity, creating it when it is not part of the hierarchy yet
ComponentPointers GetComponents (Game::Entity entity, bool hasLocalTransform) const
 the component pointers of an entity.

Private Attributes

Game::World * world
Util::ArrayAllocator< Game::Entity, uint32_t, uint32_t, uint32_t, uint32_t, bool > data
Util::Array< uint32_t > entityToInstance
Util::BitArray entityInHierarchy
Util::Dictionary< MemDb::TableId, MemDb::ColumnIndex > localColumn
Util::Array< uint32_t > stack
Util::Array< Game::Entity > pending
Util::Array< uint32_t > stale

Additional Inherited Members

Public Member Functions inherited from Core::RefCounted
 RefCounted ()
 constructor
int GetRefCount () const
 get the current refcount
void AddRef ()
 increment refcount by one
void Release ()
 decrement refcount and destroy object if refcount is zero
bool IsInstanceOf (const Rtti &rtti) const
 return true if this object is instance of given class
bool IsInstanceOf (const Util::String &className) const
 return true if this object is instance of given class by string
bool IsInstanceOf (const Util::FourCC &classFourCC) const
 return true if this object is instance of given class by fourcc
bool IsA (const Rtti &rtti) const
 return true if this object is instance of given class, or a derived class
bool IsA (const Util::String &rttiName) const
 return true if this object is instance of given class, or a derived class, by string
bool IsA (const Util::FourCC &rttiFourCC) const
 return true if this object is instance of given class, or a derived class, by fourcc
const Util::String & GetClassName () const
 get the class name
Util::FourCC GetClassFourCC () const
 get the class FourCC code
Static Public Member Functions inherited from Core::RefCounted
static void DumpRefCountingLeaks ()
 dump refcounting leaks, call at end of application (NEBULA_DEBUG builds only!)
Protected Member Functions inherited from Core::RefCounted
virtual ~RefCounted ()
 destructor (called when refcount reaches zero)

Member Enumeration Documentation

◆ Member

the members of the instance data

Enumerator
OwnerEntity 
Parent 
FirstChild 
NextSibling 
PreviousSibling 
HasLocalTransform 

Member Function Documentation

◆ Add()

uint32_t Game::TransformHierarchy::Add ( Game::Entity entity,
Game::Entity parent )
private

add an entity to the hierarchy with the parent its component names, and compute it

Add an entity to the hierarchy with the parent its component names, and compute it.

◆ Clear()

void Game::TransformHierarchy::Clear ( )
private

clear the hierarchy

◆ Compute()

void Game::TransformHierarchy::Compute ( uint32_t instance)
private

compute one instance from what its components hold and put its children in the walk queue

Compute one instance from what its components hold, write the world transform, and put its children in the walk queue.

◆ DeriveLocal()

void Game::TransformHierarchy::DeriveLocal ( uint32_t instance,
ComponentPointers const & components )
private

derive the local transform from the world transform the components hold

Make the local transform be the world transform the components hold.

This is the expensive part of a world write, because it needs the inverse of the parent, and it is only done for an instance which has a local transform of its own.

◆ Detach()

void Game::TransformHierarchy::Detach ( uint32_t instance,
ComponentPointers const & components )
private

make the local transform of an instance be the world transform it currently has, and detach it

◆ EnsureInstance()

uint32_t Game::TransformHierarchy::EnsureInstance ( Game::Entity entity,
bool hasLocalTransform )
private

the instance of an entity, creating it when it is not part of the hierarchy yet

◆ FlushStale()

void Game::TransformHierarchy::FlushStale ( )
private

take out the instances which were found to name an entity that is gone during a walk

Take out the instances which a walk found to name an entity that is deleted.

◆ GetComponents()

TransformHierarchy::ComponentPointers Game::TransformHierarchy::GetComponents ( Game::Entity entity,
bool hasLocalTransform ) const
private

the component pointers of an entity.

The transform columns have fixed indices in an entity table, the local transform column does not, and is null when the table does not have it

◆ GetFirstChild()

uint32_t Game::TransformHierarchy::GetFirstChild ( uint32_t instance) const
private

Get first child of instance.

◆ GetInstance()

uint32_t Game::TransformHierarchy::GetInstance ( Game::Entity entity) const
private

the instance of an entity, or InvalidInstance when the entity is not part of the hierarchy

The instance of an entity, or InvalidInstance when the entity is not part of the hierarchy.

◆ GetLocalTransform() [1/2]

Math::mat4 Game::TransformHierarchy::GetLocalTransform ( Game::Entity entity) const
private

◆ GetLocalTransform() [2/2]

Math::mat4 Game::TransformHierarchy::GetLocalTransform ( uint32_t instance) const
private

the transforms of an instance, read from the components which own them

◆ GetNextSibling()

uint32_t Game::TransformHierarchy::GetNextSibling ( uint32_t instance) const
private

Get the first sibling of this instance.

◆ GetOwner()

Game::Entity Game::TransformHierarchy::GetOwner ( uint32_t instance) const
private

Get owner of instance.

◆ GetParent()

uint32_t Game::TransformHierarchy::GetParent ( uint32_t instance) const
private

Get parent of instance.

◆ GetPreviousSibling()

uint32_t Game::TransformHierarchy::GetPreviousSibling ( uint32_t instance) const
private

Get the previous sibling of this instance.

◆ GetWorldTransform() [1/2]

Math::mat4 Game::TransformHierarchy::GetWorldTransform ( Game::Entity entity) const
private

◆ GetWorldTransform() [2/2]

Math::mat4 Game::TransformHierarchy::GetWorldTransform ( uint32_t instance) const
private

◆ HasChildren()

bool Game::TransformHierarchy::HasChildren ( uint32_t instance) const
private

an instance which has children is one the writer has to walk into

◆ Initialize()

void Game::TransformHierarchy::Initialize ( Game::World * world)
private

the world this hierarchy belongs to. Set by the world which owns it

◆ IsInHierarchy()

bool Game::TransformHierarchy::IsInHierarchy ( Game::Entity entity) const
private

the fast test for a transform writer, one bit in a dense array keyed by entity.index

◆ LinkUnderParent()

bool Game::TransformHierarchy::LinkUnderParent ( uint32_t instance,
uint32_t parentInstance )
private

link an instance under a parent instance. False when the link would close a cycle

Link an instance under a parent instance.

The link is refused when it would create a cycle.

◆ NumPending()

SizeT Game::TransformHierarchy::NumPending ( ) const
private

◆ Remove()

void Game::TransformHierarchy::Remove ( Game::Entity entity)
private

remove an entity from the hierarchy. Its children become roots with the world transform they have

Remove an entity from the hierarchy.

Its children become roots with the world transform they have.

◆ RemoveInstance()

void Game::TransformHierarchy::RemoveInstance ( uint32_t instance)
private

remove an instance, patching the links which name the slot the swap-erase moves into it

Remove an instance.

Pop'n'swaps instances.

◆ ResolvePending()

void Game::TransformHierarchy::ResolvePending ( )
private

compute the instances which could not be computed when they were written

Compute the instances which could not be computed when they were written.

◆ SetLocalTransform() [1/4]

void Game::TransformHierarchy::SetLocalTransform ( Game::Entity entity)
private

◆ SetLocalTransform() [2/4]

void Game::TransformHierarchy::SetLocalTransform ( Game::Entity entity,
Math::mat4 const & value )
private

◆ SetLocalTransform() [3/4]

void Game::TransformHierarchy::SetLocalTransform ( uint32_t instance)
private

◆ SetLocalTransform() [4/4]

void Game::TransformHierarchy::SetLocalTransform ( uint32_t instance,
Math::mat4 const & value )
private

Set the local transform of an instance, compute the world transform it implies and propagate to the instances below it.

Set the local transform of an instance, write it to the component which owns it, and propagate.

The no-value form takes what the components already hold as the input, which is what a writer which wrote through a query buffer needs.

◆ SetParent() [1/2]

void Game::TransformHierarchy::SetParent ( Game::Entity entity,
Game::Entity parent )
private

Update relationships.

◆ SetParent() [2/2]

void Game::TransformHierarchy::SetParent ( uint32_t instance,
uint32_t parentInstance )
private

Set the parent of an instance and compute it.

◆ SetWorldTransform() [1/4]

void Game::TransformHierarchy::SetWorldTransform ( Game::Entity entity)
private

◆ SetWorldTransform() [2/4]

void Game::TransformHierarchy::SetWorldTransform ( Game::Entity entity,
Math::mat4 const & value )
private

◆ SetWorldTransform() [3/4]

void Game::TransformHierarchy::SetWorldTransform ( uint32_t instance)
private

◆ SetWorldTransform() [4/4]

void Game::TransformHierarchy::SetWorldTransform ( uint32_t instance,
Math::mat4 const & value )
private

Set the world transform of an instance, which derives the local transform it implies through the inverse of the parent, and propagate to the instances below it.

Set the world transform of an instance, derive the local transform it implies, and propagate.

An instance which has no local transform of its own keeps the world transform as it was written.

◆ Size()

SizeT Game::TransformHierarchy::Size ( ) const
private

number of hierarchy instances, and number of instances waiting for their components

◆ Unlink()

void Game::TransformHierarchy::Unlink ( uint32_t instance)
private

take an instance out of the links, without touching its components

Take an instance out of the links.

The components are not touched here, which makes this half of a detach. Remove use it for the entity it takes out of the hierarchy.

◆ Walk()

void Game::TransformHierarchy::Walk ( uint32_t instance)
private

walk the instances below an instance, computing each of them

Walk the instances below an instance, computing each of them.

Member Data Documentation

◆ data

Util::ArrayAllocator< Game::Entity, uint32_t, uint32_t, uint32_t, uint32_t, bool> Game::TransformHierarchy::data
private

◆ entityInHierarchy

Util::BitArray Game::TransformHierarchy::entityInHierarchy
private

◆ entityToInstance

Util::Array<uint32_t> Game::TransformHierarchy::entityToInstance
private

◆ localColumn

Util::Dictionary<MemDb::TableId, MemDb::ColumnIndex> Game::TransformHierarchy::localColumn
mutableprivate

◆ pending

Util::Array<Game::Entity> Game::TransformHierarchy::pending
private

◆ stack

Util::Array<uint32_t> Game::TransformHierarchy::stack
private

◆ stale

Util::Array<uint32_t> Game::TransformHierarchy::stale
private

◆ world

Game::World* Game::TransformHierarchy::world
private

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