Ocular Engine
Ocular::Core::SceneObject Class Reference

#include <SceneObject.hpp>

Inheritance diagram for Ocular::Core::SceneObject:
Ocular::Core::Object Ocular::Core::ObjectIO Ocular::Core::Exposable Ocular::Core::Buildable Ocular::Core::Camera Ocular::Core::LightSource Ocular::Editor::Gizmo Ocular::Core::DirectionalLight Ocular::Core::PointLight Ocular::Core::SpotLight Ocular::Editor::AxisComponentGizmo Ocular::Editor::AxisGizmo

Public Member Functions

 SceneObject (std::string const &name, SceneObject *parent=nullptr, std::string const &type="SceneObject")
 
 SceneObject ()
 
virtual ~SceneObject ()
 
virtual void onVariableModified (std::string const &varName) override
 
Math::TransformgetTransform ()
 
void setActive (bool active)
 
bool isActive () const
 
void setVisible (bool visible)
 
bool isVisible () const
 
void setForcedVisible (bool forced)
 
bool isForcedVisible () const
 
void setStatic (bool isStatic)
 
bool isStatic () const
 
void setPersistent (bool persists)
 
bool isPersistent () const
 
Graphics::UniformPerObject const & getUniformData (Math::Matrix4x4 const &viewMatrix, Math::Matrix4x4 const &projMatrix)
 
void setPosition (float x, float y, float z)
 
void setPosition (Math::Vector3f const &position)
 
Math::Vector3f getPosition (bool local=true) const
 
void translate (Math::Vector3f const &translation, bool local=true)
 
void rotate (float angle, Math::Vector3f const &axis)
 
void rotate (Math::Quaternion const &rotation)
 
void setRotation (Math::Quaternion const &rotation)
 
void resetRotation ()
 
Math::Quaternion const & getRotation () const
 
void setScale (Math::Vector3f const &scale)
 
void setScale (float xScale, float yScale, float zScale)
 
Math::Vector3f getScale (bool local=true) const
 
void setTransform (Math::Transform const &transform)
 
void lookAt (Math::Vector3f const &point)
 
Math::Transform const & getTransform () const
 
virtual Math::Matrix4x4 getModelMatrix (bool local=true) const
 
void setParent (SceneObject *parent, bool maintainWorldPos=true)
 
SceneObjectgetParent () const
 
SceneObjectcreateChild (std::string const &name)
 
void addChild (SceneObject *child, bool maintainWorldPos=true)
 
SceneObjectfindChild (std::string const &name)
 
SceneObjectfindChild (UUID const &uuid)
 
SceneObjectremoveChild (std::string const &name)
 
SceneObjectremoveChild (UUID const &uuid)
 
SceneObjectremoveChild (SceneObject const *object)
 
uint32_t getNumChildren () const
 
std::vector< SceneObject * > const & getAllChildren () const
 
ARoutineaddRoutine (std::string const &name)
 
void addRoutine (ARoutine *routine)
 
template<class T >
T * addRoutine ()
 
bool removeRoutine (std::string const &name)
 
bool removeRoutine (ARoutine *routine, bool transferring=false)
 
void removeAllRoutines ()
 
ARoutinegetRoutine (std::string const &name)
 
std::vector< ARoutine * > const & getAllRoutines () const
 
uint32_t getNumRoutines () const
 
ARenderablesetRenderable (std::string const &name)
 
void setRenderable (ARenderable *renderable)
 
template<class T >
T * setRenderable ()
 
void removeRenderable (bool transferring=false)
 
ARenderablegetRenderable () const
 
virtual void onLoad (BuilderNode const *node) override
 
virtual void onSave (BuilderNode *node) const override
 
void forceBoundsRebuild ()
 
Math::BoundsSphere getBoundsSphere (bool local)
 
Math::BoundsAABB getBoundsAABB (bool local)
 
Math::BoundsOBB getBoundsOBB (bool local)
 
- Public Member Functions inherited from Ocular::Core::Object
 Object (std::string name, std::string className)
 Creates a new Object with the specified name and class. More...
 
 Object (std::string name)
 Creates a new Object with the specified name. More...
 
 Object ()
 Creates a new Object with the default name ('Name').
 
std::string const & getName () const
 
void setName (std::string name)
 Sets the name of the Object. More...
 
std::string const & getClass () const
 
void setUUID (std::string const &uuid)
 
UUID const & getUUID () const
 
int64_t getCreationTime () const
 
virtual std::string toString () const
 
template<class T >
bool isType ()
 
- Public Member Functions inherited from Ocular::Core::Exposable
void getAllExposedNames (std::vector< std::string > &names) const
 
bool getVariable (std::string const &name, ExposedVariable &var)
 
template<typename T >
bool getVariableValue (std::string const &name, T &var)
 
template<typename T >
bool setVariableValue (std::string const &name, T const &value)
 

Protected Member Functions

void getModelMatrix (Math::Matrix4x4 &matrix)
 
virtual void updateBounds (uint32_t dirtyFlags)
 
- Protected Member Functions inherited from Ocular::Core::Exposable
void exposeVariable (std::string const &name, std::string const &type, bool isPointer, bool isExposed, void *data)
 

Protected Attributes

SceneObjectm_Parent
 
uint32_t m_Layer
 The render layer this object is part of.
 
Graphics::UniformPerObject m_UniformData
 
Math::Transform m_Transform
 
Math::BoundsSphere m_BoundsSphereLocal
 
Math::BoundsAABB m_BoundsAABBLocal
 
Math::BoundsOBB m_BoundsOBBLocal
 
Math::BoundsSphere m_BoundsSphereWorld
 
Math::BoundsAABB m_BoundsAABBWorld
 
Math::BoundsOBB m_BoundsOBBWorld
 
- Protected Attributes inherited from Ocular::Core::Object
std::string m_Name
 
std::string m_Class
 
UUID m_UUID
 
const int64_t m_CreationTime
 
- Protected Attributes inherited from Ocular::Core::Exposable
std::unordered_map< std::string, ExposedVariablem_ExposedVariables
 

Friends

class SceneManager
 

Detailed Description

A SceneObject represents the instance of an arbitrary object in a Scene. This can range from a static scenery object, such as a rock, to a particle effect, to a physics volume, to a multifaceted actor.

A single SceneObject can have multiple child objects attached to it. This can be thought of as similar to a car. A parent chassis object could have child axle objects which in turn have child wheel objects. Each level down inherits the parent's transform and active/visible status (unless otherwise overridden).

Additionally, there are Routine and Renderable instances that may be attached to a SceneObject. A Routine represents the logic behind an object while the Renderable is any part of the object that is to be rendered onto the screen.

When a SceneObject is created, it is automatically added to the current SceneManager which then takes ownership of the object. This means it will be automatically destroyed when the current Scene is unloaded or when the SceneManager is destroyed in the case of an object marked as persistent.

There are two options when creating/destroying a standalone object:

SceneObject* object = new SceneObject();
delete object;

SceneObject* object = OcularScene->createObject();
OcularScene->destroyObject();

In either case, the SceneManager owns the object and handles adding it to the Scene, invoking the Routines and Renderables, intersection testing, etc.

Constructor & Destructor Documentation

Ocular::Core::SceneObject::SceneObject ( std::string const &  name,
SceneObject parent = nullptr,
std::string const &  type = "SceneObject" 
)

Creates a new SceneObject with the specified name.

Note
The object is automatically added to the Ocular SceneManager, and the SceneManager takes ownership of it. If a completely unmanaged object is required see ... (not yet available)
Parameters
[in]nameIdentifier name of the object. Note that the name does not need to be unique as all objects are already uniquely identified via a UUID (see getUUID()).
[in]parent
Ocular::Core::SceneObject::SceneObject ( )

Creates a new SceneObject with the default name of "SceneObject".

Note
The object is automatically added to the Ocular SceneManager, and the SceneManager takes ownership of it. If a completely unmanaged object is required see ... (not yet available)
Ocular::Core::SceneObject::~SceneObject ( )
virtual

At this point the SceneManager/Scene have done the following:

- Removed this object from it's parent
- Removed this object from the SceneTrees
- Removed this object's routines from the Scene
- Removed this object from the SceneManager

What is left is to:

- Verify the above as much as possible
- Destroy the routines
- Destroy the renderables

Member Function Documentation

void Ocular::Core::SceneObject::addChild ( SceneObject child,
bool  maintainWorldPos = true 
)

Adds the specified object as a child of this SceneObject and removes it from it's previous parent.

The object's parent will change, and it's state will be modified to reflect it's new parent (active, forced visible, static/dynamic, etc.).

May also specify whether or not to preserve the absolute world position.

By default, the world position is maintained. This means that the local position is modified such that, upon being added to the new parent, the world position remains the same.

Alternatively (by setting the maintainWorldPos parameter to FALSE), the local position will remain the same but the absolute world position will be different.

For example:

We have a parentless SceneObject positioned at (0, 5, 0). We assign it a parent at position (5, 0, 0).

If maintainWorldPos is TRUE, then the SceneObject's absolute world position will remain as (0, 5, 0), while its new local position to the parent is (-5, 5, 0)

If maintainWorld is FALSE, then the SceneObject's local position to the parent will remain as (0, 5, 0), while it's new world position will be (5, 5, 0).

Parameters
[in]child
[in]maintainWorldPos
ARoutine * Ocular::Core::SceneObject::addRoutine ( std::string const &  name)

Adds a new instance of the specified routine to the SceneObject.

Parameters
[in]nameName of the ARoutine implementation to add.
Returns
TRUE if the ARoutine implementation was successfully added. If it fails, then no matching implementation with that name was discovered.
template<class T >
T* Ocular::Core::SceneObject::addRoutine ( )
inline

Adds a new instance of a routine to the SceneObject.

The object takes full ownership of the routine and frees it when no longer in use.

SceneObject * Ocular::Core::SceneObject::createChild ( std::string const &  name)

Creates a new SceneObject with the specified name and adds it as a child of this SceneObject.

Calling this method is functionally identical to:

OcularEngine.SceneManager()->createObject(name, thisObject);
Parameters
[in]nameName for the new object (does not have to be unique).
Returns
Pointer to the new object.
SceneObject * Ocular::Core::SceneObject::findChild ( std::string const &  name)
Parameters
[in]nameName to search for.
Returns
Pointer to first discovered child with specified name (NULL if not found).
SceneObject * Ocular::Core::SceneObject::findChild ( UUID const &  uuid)
Parameters
[in]uuidUUID to search for.
Returns
Pointer to child with matching UUID (NULL if not found).
std::vector< SceneObject * > const & Ocular::Core::SceneObject::getAllChildren ( ) const
Returns
A vector containing pointers to all children owned by this SceneObject.
std::vector< ARoutine * > const & Ocular::Core::SceneObject::getAllRoutines ( ) const

Returns a collection of all routines that are owned by this SceneObject.

Math::BoundsAABB Ocular::Core::SceneObject::getBoundsAABB ( bool  local)

Returns the axis-aligned bounding box for the object.

Parameters
[in]localIf TRUE, returns the local untransformed bounds for the object (local space). If FALSE, returns the bounds modified according to the transform (world space).
Math::BoundsOBB Ocular::Core::SceneObject::getBoundsOBB ( bool  local)

Returns the orientated bounding box for the object.

Parameters
[in]localIf TRUE, returns the local untransformed bounds for the object (local space). If FALSE, returns the bounds modified according to the transform (world space).
Math::BoundsSphere Ocular::Core::SceneObject::getBoundsSphere ( bool  local)

Returns the bounding sphere for the object.

Parameters
[in]localIf TRUE, returns the local untransformed bounds for the object (local space). If FALSE, returns the bounds modified according to the transform (world space).
uint32_t Ocular::Core::SceneObject::getNumChildren ( ) const
Returns
The number of child objects owned by this SceneObject.
SceneObject * Ocular::Core::SceneObject::getParent ( ) const
Returns
Parent of this SceneObject (NULL if no parent)
Math::Vector3f Ocular::Core::SceneObject::getPosition ( bool  local = true) const
Returns
The SceneObject's position
ARoutine * Ocular::Core::SceneObject::getRoutine ( std::string const &  name)

Retrieves the first discovered instance of the specified ARoutine implementation.

Parameters
[in]name
Returns
The ARoutine instance or NULL if no matching routines were discovered.
Math::Transform & Ocular::Core::SceneObject::getTransform ( )

Returns the current local transform of this object.

bool Ocular::Core::SceneObject::isActive ( ) const

Returns if the object is active.

bool Ocular::Core::SceneObject::isForcedVisible ( ) const
Returns
TRUE if the object is being forced visible and being rendered irregardless of culling tests.
bool Ocular::Core::SceneObject::isPersistent ( ) const
Returns
TRUE if this object persists between scenes.
bool Ocular::Core::SceneObject::isStatic ( ) const
Returns
TRUE if the object (or a parent) is marked as static.
bool Ocular::Core::SceneObject::isVisible ( ) const
Returns
If TRUE, then the object is being rendered.
void Ocular::Core::SceneObject::onLoad ( BuilderNode const *  node)
overridevirtual

Alternate creation method (opposed to the constructor) in which one is provided with a BuilderNode chain. This chain may be explored to retrieve any relevant variables, and their values, that may have been stored in it.

This method will typically mirror the onSave, in which relevant values are stored within the chain.

Parameters
[in]nodeNode to extract variable information from

Reimplemented from Ocular::Core::ObjectIO.

Reimplemented in Ocular::Core::LightSource.

void Ocular::Core::SceneObject::onSave ( BuilderNode node) const
overridevirtual

Method used to add an object's data to an existing node chain in preparation for being save to a file.

Parameters
[in]nodeNode to place variable information in

Reimplemented from Ocular::Core::ObjectIO.

void Ocular::Core::SceneObject::onVariableModified ( std::string const &  varName)
overridevirtual

Reacts to the modification of certain exposed variables. Variables that are reacted to include:

- m_Rotation
- m_Scale

Reimplemented from Ocular::Core::Exposable.

Reimplemented in Ocular::Core::PointLight.

void Ocular::Core::SceneObject::removeAllRoutines ( )

Removes all routine instances that belong to this SceneObject.

SceneObject * Ocular::Core::SceneObject::removeChild ( std::string const &  name)

Removes the first discovered child with the specified name.

This does not delete the child object, but simply removes it from this SceneObject. The removed object will continue to exist, along with all of it's routines, renderables, and children.

A pointer to the removed object is returned. If you desired to fully destroy the object, then you must call:

OcularEngine.SceneManager()->removeObject(object);

Note that the removed object will retain the state of it's old parent (active, forced visible, static/dynamic, etc.). It's transform will also be unmodified, but may appear to move as it is no longer being based on the parent but now on the world.

Parameters
[in]name
Returns
Pointer to the removed object (NULL if no matching child was found).
SceneObject * Ocular::Core::SceneObject::removeChild ( UUID const &  uuid)

Removes the first discovered child with the specified UUID.

This does not delete the child object, but simply removes it from this SceneObject. The removed object will continue to exist, along with all of it's routines, renderables, and children.

A pointer to the removed object is returned. If you desired to fully destroy the object, then you must call:

OcularScene->removeObject(object);

Note that the removed object will retain the state of it's old parent (active, forced visible, static/dynamic, etc.). It's transform will also be unmodified, but may appear to move as it is no longer being based on the parent but now on the world.

Parameters
[in]uuid
Returns
Pointer to the removed object (NULL if no matching child was found).
SceneObject * Ocular::Core::SceneObject::removeChild ( SceneObject const *  object)

Removes the first discovered child with the specified name.

This does not delete the child object, but simply removes it from this SceneObject. The removed object will continue to exist, along with all of it's routines, renderables, and children.

A pointer to the removed object is returned. If you desired to fully destroy the object, then you must call:

OcularScene->removeObject(object);

Note that the removed object will retain the state of it's old parent (active, forced visible, static/dynamic, etc.). It's transform will also be unmodified, but may appear to move as it is no longer being based on the parent but now on the world.

Parameters
[in]object
Returns
Pointer to the removed object (NULL if no matching child was found).
bool Ocular::Core::SceneObject::removeRoutine ( std::string const &  name)

Removes an instance of the specified routine implementation from the SceneObject. Will only remove the first instance of the implementation that it finds.

Parameters
[in]nameName of the ARoutine implementation to remove.
Returns
TRUE if the routine implementation was successfully removed. If it fails, then no matching implementation instance with that name was discovered.
bool Ocular::Core::SceneObject::removeRoutine ( ARoutine routine,
bool  transferring = false 
)

Removes the specified ARoutine instance from the SceneObject.

Parameters
[in]routineRoutine instance to remove from the SceneObject.
[in]transferringIf true, then this Routine is being transferred to another SceneObject and should not be deleted.
Returns
TRUE if the routine instance was successfully discovered and removed. If it fails, then no matching instance was discovered.
void Ocular::Core::SceneObject::resetRotation ( )

Resets the orientation of the object

void Ocular::Core::SceneObject::rotate ( float  angle,
Math::Vector3f const &  axis 
)

Rotates the SceneObject along the given axis by the given angle

Parameters
[in]angleAngle to rotate in degrees
[in]axisAxis to rotate around
void Ocular::Core::SceneObject::setActive ( bool  active)

Sets whether this object is active or not. An inactive object will not have it's render or update methods called.

The active state propagates to child SceneObjects.

If attempting to set active, and the parent is currently inactive, the state will not be changed.

Children may not be set active while the parent is inactive, but they can be set inactive while the parent is active.

Parameters
[in]active(default TRUE)
void Ocular::Core::SceneObject::setForcedVisible ( bool  forced)

Sets whether this object is forced visible. If an object is forced visible, then it's renderables will always be rendered irregardless of whether or not it is in view or passes any culling tests.

Note
This flag has a cascading effect. Any children of a forced visible object will automatically be forced visible themselves.
Parameters
[in]forced
void Ocular::Core::SceneObject::setParent ( SceneObject parent,
bool  maintainWorldPos = true 
)

Sets the specified SceneOject as the parent of this SceneObject.

If the new parent is not null, then the cascading states of the parent (active, forced visible, static/dynamic, etc.) are applied to this object.

May also specify whether or not to preserve the absolute world position.

By default, the world position is maintained. This means that the local position is modified such that, upon being added to the new parent, the world position remains the same.

Alternatively (by setting the maintainWorldPos parameter to FALSE), the local position will remain the same but the absolute world position will be different.

For example:

We have a parentless SceneObject positioned at (0, 5, 0). We assign it a parent at position (5, 0, 0).

If maintainWorldPos is TRUE, then the SceneObject's absolute world position will remain as (0, 5, 0), while its new local position to the parent is (-5, 5, 0)

If maintainWorld is FALSE, then the SceneObject's local position to the parent will remain as (0, 5, 0), while it's new world position will be (5, 5, 0).

Parameters
[in]parentNew parent of this object. Pass NULL if no parent is desired.
[in]maintainWorldPos
void Ocular::Core::SceneObject::setPersistent ( bool  persists)

Sets whether this object should persist inbetween scenes.

Typically, all active objects are unloaded along with the currently active scene. However, if an object is marked as persistent, then it will not be unloaded with the scene and will automatically added to the new scene.

Parameters
[in]persists
void Ocular::Core::SceneObject::setPosition ( float  x,
float  y,
float  z 
)

Sets the position of the SceneObject.

Parameters
[in]x
[in]y
[in]z
void Ocular::Core::SceneObject::setPosition ( Math::Vector3f const &  position)

Sets the position of the SceneObject.

Parameters
[in]
void Ocular::Core::SceneObject::setRotation ( Math::Quaternion const &  rotation)

Sets the SceneObject's rotation

Parameters
[in]rotation
void Ocular::Core::SceneObject::setStatic ( bool  isStatic)

Sets whether this object is static or not. If an object is static, then no transformations (translation, rotation, scaling) will have any effect on it.

This is useful for objects such as terrain pieces that once created, will never move. By setting to static, it allows for numerous rendering optimizations to take place.

Note
This flag has a cascading effect. Any children of a static object will automatically be static themselves.
Parameters
[in]isStatic
void Ocular::Core::SceneObject::setVisible ( bool  visible)

Sets whether this object is visible or not. Note that this method is called every frame by the scene, and thus manually calling it will have little or no effect.

If you wish to force an object to always be rendered, then you should instead call setForcedVisible.

Parameters
[in]visible
void Ocular::Core::SceneObject::translate ( Math::Vector3f const &  translation,
bool  local = true 
)

Translates the SceneObject along the given vector

Parameters
[in]translation

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