CoreObject Class Reference

Description

Core objects provides functionality for dealing with objects that need to exist on both simulation and core thread.

It handles cross-thread initialization, destruction as well as syncing data between the two threads.

It also provides a standardized way to initialize/destroy objects, and a way to specify dependant CoreObjects. For those purposes it might also be used for objects that only exist on the core thread.

Note
ct::CoreObject is a counterpart to CoreObject that is used exclusively on the core thread. CoreObject on the other hand should be used exclusively on the simulation thread. Types that exist on both threads need to implement both of these.

Inherited by Animation, BlendState, Camera, ComputePipelineState, DepthStencilState, GpuBuffer, GpuParamBlockBuffer, GpuParams, GpuPipelineParamInfo, GpuProgram, GraphicsPipelineState, IndexBuffer, Light, MeshHeap, Pass, RasterizerState, ReflectionProbe, Renderable, RenderTarget, Resource, SamplerState, Skybox, Technique, VertexBuffer, VertexDeclaration, and Viewport.

Internal

void _setThisPtr (SPtr< CoreObject > ptrThis)
 Sets a shared this pointer to this object. More...
 
template<class T , class MemAlloc >
static void _delete (CoreObject *obj)
 Schedules the object to be destroyed, and then deleted. More...
 

Methods

virtual void destroy ()
 Frees all the data held by this object. More...
 
virtual void initialize ()
 Initializes all the internal resources of this object. More...
 
bool isDestroyed () const
 Returns true if the object has been destroyed. More...
 
void blockUntilCoreInitialized () const
 Blocks the current thread until the resource is fully initialized. More...
 
UINT64 getInternalID () const
 Returns an unique identifier for this object. More...
 
SPtr< CoreObjectgetThisPtr () const
 Returns a shared_ptr version of "this" pointer. More...
 
SPtr< ct::CoreObjectgetCore () const
 Returns an object that contains a core thread specific implementation of this CoreObject. More...
 
void syncToCore ()
 Ensures all dirty syncable data is send to the core thread counterpart of this object (if any). More...
 

Protected Types

enum  Flags { CGO_DESTROYED = 0x01, CGO_INIT_ON_CORE_THREAD = 0x02 }
 Values that represent current state of the core object. More...
 

Method documentation

static void _delete ( CoreObject obj)
static

Schedules the object to be destroyed, and then deleted.

void _setThisPtr ( SPtr< CoreObject ptrThis)

Sets a shared this pointer to this object.

This must be called immediately after construction, but before initialize().

Note
This should be called by the factory creation methods so user doesn't have to call it manually.
void blockUntilCoreInitialized ( ) const

Blocks the current thread until the resource is fully initialized.

Note
If you call this without calling initialize first a deadlock will occur. You should not call this from core thread.
virtual SPtr<ct::CoreObject> createCore ( ) const
protectedvirtual
virtual void destroy ( )
virtual

Frees all the data held by this object.

Note
If this object require initialization on core thread destruction is not done immediately, and is instead just scheduled on the core thread. Otherwise the object is destroyed immediately.

Reimplemented in RenderWindow.

SPtr<ct::CoreObject> getCore ( ) const

Returns an object that contains a core thread specific implementation of this CoreObject.

Null is a valid return value in case object requires no core thread implementation.

Note
Thread safe to retrieve, but its data is only valid on the core thread.
virtual void getCoreDependencies ( Vector< CoreObject * > &  dependencies)
protectedvirtual

Populates the provided array with all core objects that this core object depends upon.

Dependencies are required for syncing to the core thread, so the system can be aware to update the dependant objects if a dependency is marked as dirty (for example updating a camera's viewport should also trigger an update on camera so it has a chance to potentially update its data).

Reimplemented in Camera, Renderable, Pass, Viewport, Technique, and Font.

UINT64 getInternalID ( ) const

Returns an unique identifier for this object.

SPtr<CoreObject> getThisPtr ( ) const

Returns a shared_ptr version of "this" pointer.

virtual void initialize ( )
virtual

Initializes all the internal resources of this object.

Must be called right after construction. Generally you should call this from a factory method to avoid the issue where user forgets to call it.

Note
If this object require initialization on core thread initialization is not done immediately, and is instead just scheduled on the core thread. Otherwise the object is initialized immediately.

Reimplemented in Material, Texture, AnimationClip, Pass, AudioClip, Mesh, PhysicsMesh, FMODAudioClip, and OAAudioClip.

bool isCoreDirty ( ) const
protected

Checks is the core dirty flag set.

This is used by external systems to know when internal data has changed and core thread potentially needs to be notified.

bool isDestroyed ( ) const

Returns true if the object has been destroyed.

Destroyed object should not be used.

void markCoreClean ( )
protected

Marks the core data as clean.

Normally called right after syncToCore() has been called.

void markCoreDirty ( UINT32  flags = 0xFFFFFFFF)
protected

Marks the core data as dirty.

This causes the syncToCore() method to trigger the next time objects are synced between core and sim threads.

Parameters
[in]flags(optional) Flags in case you want to signal that only part of the internal data is dirty. syncToCore() will be called regardless and it's up to the implementation to read the flags value if needed.
void markDependenciesDirty ( )
protected

Notifies the core object manager that this object is dependant on some other CoreObject(s), and the dependencies changed since the last call to this method.

This will trigger a call to getCoreDependencies() to collect the new dependencies.

static void queueGpuCommand ( const SPtr< ct::CoreObject > &  obj,
std::function< void()>  func 
)
staticprotected

Queues a command to be executed on the core thread, without a return value.

Note
Requires a shared pointer to the object this function will be executed on, in order to make sure the object is not deleted before the command executes. Can be null if the function is static or global.
static AsyncOp queueReturnGpuCommand ( const SPtr< ct::CoreObject > &  obj,
std::function< void(AsyncOp &)>  func 
)
staticprotected

Queues a command to be executed on the core thread, with a return value in the form of AsyncOp.

See also
AsyncOp
Note
Requires a shared pointer to the object this function will be executed on, in order to make sure the object is not deleted before the command executes. Can be null if the function is static or global.
void syncToCore ( )

Ensures all dirty syncable data is send to the core thread counterpart of this object (if any).

Note
Call this if you have modified the object and need to make sure core thread has an up to date version. Normally this is done automatically at the end of a frame.
This is an asynchronous method.
virtual CoreSyncData syncToCore ( FrameAlloc allocator)
protectedvirtual

Copy internal dirty data to a memory buffer that will be used for updating core thread version of that data.

Note
This generally happens at the end of every sim thread frame. Synced data becomes available to the core thread the start of the next core thread frame.

Reimplemented in Camera, GpuParams, Light, Renderable, ReflectionProbe, Pass, Viewport, MeshBase, Skybox, RenderTexture, and GpuParamBlockBuffer.

Member Enumeration Documentation

enum Flags
protected

Values that represent current state of the core object.

Enumerator
CGO_DESTROYED 

Object has been destroyed and shouldn't be used.

CGO_INIT_ON_CORE_THREAD 

Object requires initialization on core thread.

Constructor & Destructor Documentation

CoreObject ( bool  requiresCoreInit = true)
protected

Constructs a new core object.

Parameters
[in]requiresCoreInit(optional) Determines if the ct::CoreObject counterpart of this object (if it has any, see createCore()) requires initialization and destruction on the core thread.