The Audio::IRenderer interface represents a generic audio renderer. More...

#include <murl_audio_i_renderer.h>

Detailed Description

The Audio::IRenderer interface represents a generic audio renderer.

For most cases, an application does not need to directly interact with this interface. Instead, using audio-related nodes from the Murl::Graph Node Interfaces or Murl::Graph Node Classes sections is the preferred way to implement sound output functionality in a cross-platform manner.

Accessing the audio renderer interface directly may be useful in advanced use cases, when creating custom audio objects or even a complete custom renderer suite.

Inheritance diagram for Murl::Audio::IRenderer:

Public Member Functions
virtual IEnums::AudioApi	GetApi () const =0
	Get the underlying audio API. More...

virtual Bool	Init (IEngine engine, const IAppConfiguration appConfig, IFeatureSet features, IAudioInterface audioInterface)=0
	Initialize the renderer. More...

virtual Bool	DeInit ()=0
	Deinitialize the renderer. More...

virtual Bool	Start ()=0
	Start the renderer after it has been initialized. More...

virtual Bool	Stop ()=0
	Stop the renderer before it gets deinitialized. More...

virtual Bool	Pause ()=0
	Pause the renderer if it is running. More...

virtual Bool	Continue ()=0
	Continue the renderer if it is paused. More...

virtual Bool	Suspend ()=0
	Suspend the renderer. More...

virtual Bool	Resume ()=0
	Resume the renderer. More...

virtual const IFeatureSet *	GetFeatures () const =0
	Get the available features. More...

virtual IObject *	CreateObject (const String &className)=0
	Create a renderer object. More...

virtual Bool	DestroyObject (IObject *&object)=0
	Destroy an object that was created by this renderer. More...

virtual Bool	BeginSubmission ()=0
	Begin submission of renderer objects for the next frame. More...

virtual Bool	EndSubmission ()=0
	End submission of renderer objects for the next frame. More...

virtual Bool	BeginRendering (IEnums::SuspendTrigger trigger)=0
	Start the actual rendering process after all current objects have been submitted. More...

virtual Bool	EndRendering ()=0
	Wait for the current rendering process to complete, after calling BeginRendering(). More...

virtual Bool	RegisterRenderThread (UInt64 threadId)=0
	Register a render (main) thread with the renderer. More...

virtual Bool	RegisterLogicThread (UInt64 threadId)=0
	Register a logic processing thread with the renderer. More...

virtual Bool	RegisterLoaderThread (UInt64 threadId)=0
	Register a background loader thread with the renderer. More...

virtual Bool	UnregisterRenderThread (UInt64 threadId)=0
	Unregister a render (main) thread from the renderer. More...

virtual Bool	UnregisterLogicThread (UInt64 threadId)=0
	Unregister a logic processing thread from the renderer. More...

virtual Bool	UnregisterLoaderThread (UInt64 threadId)=0
	Unregister a background loader thread from the renderer. More...

virtual Bool	RegisterAutomaticallySuspendableObject (IObject *object)=0
	Register an object for automatic resource suspension. More...

virtual Bool	UnregisterAutomaticallySuspendableObject (IObject *object)=0
	Unregister an object from automatic resource suspension. More...

virtual Bool	RegisterManuallySuspendableObject (IObject *object)=0
	Register an object for manual resource suspension. More...

virtual Bool	UnregisterManuallySuspendableObject (IObject *object)=0
	Unregister an object from manual resource suspension. More...

virtual Bool	RegisterEmergencySuspendableObject (IObject *object)=0
	Register an object for emergency resource suspension. More...

virtual Bool	UnregisterEmergencySuspendableObject (IObject *object)=0
	Unregister an object from emergency resource suspension. More...

virtual void	SetCurrentListener (IListener *listener)=0
	Set the current listener affecting subsequent playables. More...

virtual void	SetCurrentTransform (const Matrix *transform)=0
	Set the current world transform affecting subsequent playables. More...

virtual void	PushObjectForUpdate (IObject *object, Real localTime=0.0)=0
	Queue up an object for updating. More...

virtual void	PushObjectForRendering (IPlayable *object, Real localTime)=0
	Queue up a playable object for rendering. More...

virtual Bool	LockStatistics ()=0
	Lock the module statistics. More...

virtual Bool	UnlockStatistics ()=0
	Unlock the module statistics. More...

virtual UInt64	GetAllocatedResourceByteSize (IEnums::MemoryType memoryType) const =0
	Query the total number of allocated resource bytes. More...

virtual UInt32	GetNumberOfObjectsCreated () const =0
	Query the number objects created after the most recent cycle. More...

virtual UInt32	GetNumberOfObjectsSuspended () const =0
	Query the number objects suspended after the most recent cycle. More...

virtual UInt32	GetNumberOfObjectsRendered () const =0
	Query the number of most recently rendered objects. More...

virtual UInt32	GetNumberOfBatchesRendered () const =0
	Query the number of most recently rendered object batches. More...

virtual Bool	CollectStatisticsObjects (Index< const IStatisticsObject * > &objects) const =0
	Populate a given index with all objects currently present in the renderer. More...

virtual void	IncreaseNumberOfResourceBytesAllocated (IEnums::MemoryType memoryType, UInt64 numBytes)=0
	Increase the internal number of allocated resource bytes. More...

virtual void	DecreaseNumberOfResourceBytesAllocated (IEnums::MemoryType memoryType, UInt64 numBytes)=0
	Decrease the internal number of allocated resource bytes. More...

virtual void	IncreaseNumberOfObjectsSuspended ()=0
	Increase the internal suspended object count by 1. More...

virtual void	DecreaseNumberOfObjectsSuspended ()=0
	Decrease the internal suspended object count by 1. More...

Public Member Functions inherited from Murl::IFactoryObject< IRenderer >
	~IFactoryObject () override
	The destructor.

virtual const ClassInfo *	GetObjectClassInfo () const=0
	Get the object instance's class info, if present. More...

virtual void	ResetObjectProperties ()=0
	Reset the object instance's properties to their default values.

Public Member Functions inherited from Murl::Audio::IRendererRegistry
virtual Bool	RegisterObjectClass (const IObject::ClassInfo &classInfo)=0
	Register an object class. More...

virtual Bool	UnregisterObjectClass (const IObject::ClassInfo &classInfo)=0
	Unregister a previously registered object class. More...

virtual SInt32	GetRegisteredObjectClassInfoIndex (const IObject::ClassInfo &classInfo) const =0
	Query the index of a registered object class, by its ClassInfo structure. More...

virtual SInt32	GetRegisteredObjectClassInfoIndex (const String &className) const =0
	Query the index of a registered object class, by its class name. More...

virtual UInt32	GetNumberOfRegisteredObjectClassInfos () const =0
	Get the total number of registered object classes. More...

virtual const IObject::ClassInfo *	GetRegisteredObjectClassInfo (UInt32 index) const =0
	Get the ClassInfo structure of a registered object class. More...

Additional Inherited Members
Public Types inherited from Murl::IFactoryObject< IRenderer >
using	ClassInfoArray = Array< const ClassInfo * >
	Definition of an array of ClassInfo objects.

Static Public Member Functions inherited from Murl::IFactoryObject< IRenderer >
static const PropertyInfo *	GetPropertyInfo ()
	Get the class' property info struct. More...

static const AttributeInfo *	GetAttributeInfo ()
	Get the class' attribute info struct. More...

static void	ResetProperties (IFactoryObject< IRenderer > *object)
	Reset an object instance's properties to their default values. More...

Member Function Documentation

◆ GetApi()

virtual IEnums::AudioApi Murl::Audio::IRenderer::GetApi ( ) const

pure virtual

Get the underlying audio API.

Returns: The used audio API.

◆ Init()

virtual Bool Murl::Audio::IRenderer::Init	(	IEngine *	engine,
		const IAppConfiguration *	appConfig,
		IFeatureSet *	features,
		IAudioInterface *	audioInterface
	)

pure virtual

Initialize the renderer.

Parameters

engine	The engine to attach to.
appConfig	The application configuration object.
features	The feature set to possibly update according to this renderer' capabilities.
audioInterface	An interface to the platform front end's audio interface for managing contexts etc.

Returns: true if successful.

◆ DeInit()

virtual Bool Murl::Audio::IRenderer::DeInit ( )

pure virtual

Deinitialize the renderer.

Returns: true if successful.

◆ Start()

virtual Bool Murl::Audio::IRenderer::Start ( )

pure virtual

Start the renderer after it has been initialized.

Returns: true if successful.

◆ Stop()

virtual Bool Murl::Audio::IRenderer::Stop ( )

pure virtual

Stop the renderer before it gets deinitialized.

Returns: true if successful.

◆ Pause()

virtual Bool Murl::Audio::IRenderer::Pause ( )

pure virtual

Pause the renderer if it is running.

Returns: true if successful.

◆ Continue()

virtual Bool Murl::Audio::IRenderer::Continue ( )

pure virtual

Continue the renderer if it is paused.

Returns: true if successful.

◆ Suspend()

virtual Bool Murl::Audio::IRenderer::Suspend ( )

pure virtual

Suspend the renderer.

Returns: true if successful.

◆ Resume()

virtual Bool Murl::Audio::IRenderer::Resume ( )

pure virtual

Resume the renderer.

Returns: true if successful.

◆ GetFeatures()

virtual const IFeatureSet* Murl::Audio::IRenderer::GetFeatures ( ) const

pure virtual

Get the available features.

Returns: The set of available features.

◆ CreateObject()

virtual IObject* Murl::Audio::IRenderer::CreateObject ( const String & className )

pure virtual

Create a renderer object.

Parameters

className The class name of the renderer object to create.

Returns: The newly created object, or null if failed.

◆ DestroyObject()

virtual Bool Murl::Audio::IRenderer::DestroyObject ( IObject *& object )

pure virtual

Destroy an object that was created by this renderer.

Parameters

object A reference to a pointer containing the object to destroy.

Returns: true if successful.

◆ BeginSubmission()

virtual Bool Murl::Audio::IRenderer::BeginSubmission ( )

pure virtual

Begin submission of renderer objects for the next frame.

Any calls to SetCurrentListener() and SetCurrentTransform(), as well as PushObjectForUpdate() and PushObjectForRendering() must happen between a call to this method and the corresponding EndSubmission() call.

Returns: true if successful.

◆ EndSubmission()

virtual Bool Murl::Audio::IRenderer::EndSubmission ( )

pure virtual

End submission of renderer objects for the next frame.

Returns: true if successful.

◆ BeginRendering()

virtual Bool Murl::Audio::IRenderer::BeginRendering ( IEnums::SuspendTrigger trigger )

pure virtual

Start the actual rendering process after all current objects have been submitted.

Parameters

trigger The suspend trigger to apply. If set to a value other than IEnums::SUSPEND_TRIGGER_NONE, all objects registered for that trigger type (manual or emergency) are commanded to release any resources that are not currently needed.

Returns: true if successful.

◆ EndRendering()

virtual Bool Murl::Audio::IRenderer::EndRendering ( )

pure virtual

Wait for the current rendering process to complete, after calling BeginRendering().

Returns: true if successful.

◆ RegisterRenderThread()

virtual Bool Murl::Audio::IRenderer::RegisterRenderThread ( UInt64 threadId )

pure virtual

Register a render (main) thread with the renderer.

Parameters

threadId The thread ID of the main thread.

Returns: true if successful.

◆ RegisterLogicThread()

virtual Bool Murl::Audio::IRenderer::RegisterLogicThread ( UInt64 threadId )

pure virtual

Register a logic processing thread with the renderer.

Parameters

threadId The thread ID of the logic thread.

Returns: true if successful.

◆ RegisterLoaderThread()

virtual Bool Murl::Audio::IRenderer::RegisterLoaderThread ( UInt64 threadId )

pure virtual

Register a background loader thread with the renderer.

Parameters

threadId The thread ID of the loader thread.

Returns: true if successful.

◆ UnregisterRenderThread()

virtual Bool Murl::Audio::IRenderer::UnregisterRenderThread ( UInt64 threadId )

pure virtual

Unregister a render (main) thread from the renderer.

Parameters

threadId The thread ID of the main thread.

Returns: true if successful.

◆ UnregisterLogicThread()

virtual Bool Murl::Audio::IRenderer::UnregisterLogicThread ( UInt64 threadId )

pure virtual

Unregister a logic processing thread from the renderer.

Parameters

threadId The thread ID of the logic thread.

Returns: true if successful.

◆ UnregisterLoaderThread()

virtual Bool Murl::Audio::IRenderer::UnregisterLoaderThread ( UInt64 threadId )

pure virtual

Unregister a background loader thread from the renderer.

Parameters

threadId The thread ID of the loader thread.

Returns: true if successful.

◆ RegisterAutomaticallySuspendableObject()

virtual Bool Murl::Audio::IRenderer::RegisterAutomaticallySuspendableObject ( IObject * object )

pure virtual

Register an object for automatic resource suspension.

Parameters

object The object to register.

Returns: true if successful.

◆ UnregisterAutomaticallySuspendableObject()

virtual Bool Murl::Audio::IRenderer::UnregisterAutomaticallySuspendableObject ( IObject * object )

pure virtual

Unregister an object from automatic resource suspension.

Parameters

object The object to unregister.

Returns: true if successful.

◆ RegisterManuallySuspendableObject()

virtual Bool Murl::Audio::IRenderer::RegisterManuallySuspendableObject ( IObject * object )

pure virtual

Register an object for manual resource suspension.

Parameters

object The object to register.

Returns: true if successful.

◆ UnregisterManuallySuspendableObject()

virtual Bool Murl::Audio::IRenderer::UnregisterManuallySuspendableObject ( IObject * object )

pure virtual

Unregister an object from manual resource suspension.

Parameters

object The object to unregister.

Returns: true if successful.

◆ RegisterEmergencySuspendableObject()

virtual Bool Murl::Audio::IRenderer::RegisterEmergencySuspendableObject ( IObject * object )

pure virtual

Register an object for emergency resource suspension.

Parameters

object The object to register.

Returns: true if successful.

◆ UnregisterEmergencySuspendableObject()

virtual Bool Murl::Audio::IRenderer::UnregisterEmergencySuspendableObject ( IObject * object )

pure virtual

Unregister an object from emergency resource suspension.

Parameters

object The object to unregister.

Returns: true if successful.

◆ SetCurrentListener()

virtual void Murl::Audio::IRenderer::SetCurrentListener ( IListener * listener )

pure virtual

Set the current listener affecting subsequent playables.

This method must only be called between BeginSubmission() and EndSubmission().

Parameters

listener The listener to set.

◆ SetCurrentTransform()

virtual void Murl::Audio::IRenderer::SetCurrentTransform ( const Matrix * transform )

pure virtual

Set the current world transform affecting subsequent playables.

This method must only be called between BeginSubmission() and EndSubmission().

Parameters

transform The world transform to set.

◆ PushObjectForUpdate()

virtual void Murl::Audio::IRenderer::PushObjectForUpdate	(	IObject *	object,
		Real	localTime = `0.0`
	)

pure virtual

Queue up an object for updating.

This method must only be called between BeginSubmission() and EndSubmission().

Parameters

object	The object to queue up.
localTime	The time stamp.

◆ PushObjectForRendering()

virtual void Murl::Audio::IRenderer::PushObjectForRendering	(	IPlayable *	object,
		Real	localTime
	)

pure virtual

Queue up a playable object for rendering.

This method must only be called between BeginSubmission() and EndSubmission().

Parameters

object	The playable object to queue up.
localTime	The time stamp.

◆ LockStatistics()

virtual Bool Murl::Audio::IRenderer::LockStatistics ( )

pure virtual

Lock the module statistics.

Returns: true if successful.

◆ UnlockStatistics()

virtual Bool Murl::Audio::IRenderer::UnlockStatistics ( )

pure virtual

Unlock the module statistics.

Returns: true if successful.

◆ GetAllocatedResourceByteSize()

virtual UInt64 Murl::Audio::IRenderer::GetAllocatedResourceByteSize ( IEnums::MemoryType memoryType ) const

pure virtual

Query the total number of allocated resource bytes.

Must be called after EndRendering().

Parameters

memoryType The type of memory.

Returns: The number of allocated bytes.

◆ GetNumberOfObjectsCreated()

virtual UInt32 Murl::Audio::IRenderer::GetNumberOfObjectsCreated ( ) const

pure virtual

Query the number objects created after the most recent cycle.

Must be called after EndRendering().

Returns: The number of created objects.

◆ GetNumberOfObjectsSuspended()

virtual UInt32 Murl::Audio::IRenderer::GetNumberOfObjectsSuspended ( ) const

pure virtual

Query the number objects suspended after the most recent cycle.

Must be called after EndRendering().

Returns: The number of suspended objects.

◆ GetNumberOfObjectsRendered()

virtual UInt32 Murl::Audio::IRenderer::GetNumberOfObjectsRendered ( ) const

pure virtual

Query the number of most recently rendered objects.

Must be called after EndRendering().

Returns: The number of objects renderered.

◆ GetNumberOfBatchesRendered()

virtual UInt32 Murl::Audio::IRenderer::GetNumberOfBatchesRendered ( ) const

pure virtual

Query the number of most recently rendered object batches.

Must be called after EndRendering().

Returns: The number of batches renderered.

◆ CollectStatisticsObjects()

virtual Bool Murl::Audio::IRenderer::CollectStatisticsObjects ( Index< const IStatisticsObject * > & objects ) const

pure virtual

Populate a given index with all objects currently present in the renderer.

For this method to successfully return all the present objects, the method IEngineConfiguration::SetExtendedObjectStatisticsEnabled(true) must be called in the app's Configure() method.

Parameters

objects An index to receive all the present objects.

Returns: true if successful.

◆ IncreaseNumberOfResourceBytesAllocated()

virtual void Murl::Audio::IRenderer::IncreaseNumberOfResourceBytesAllocated	(	IEnums::MemoryType	memoryType,
		UInt64	numBytes
	)

pure virtual

Increase the internal number of allocated resource bytes.

Called by an object whenever it allocates a new memory resource.

Parameters

memoryType	The type of memory.
numBytes	The number of newly allocated bytes.

◆ DecreaseNumberOfResourceBytesAllocated()

virtual void Murl::Audio::IRenderer::DecreaseNumberOfResourceBytesAllocated	(	IEnums::MemoryType	memoryType,
		UInt64	numBytes
	)

pure virtual

Decrease the internal number of allocated resource bytes.

Called by an object whenever it releases a memory resource.

Parameters

memoryType	The type of memory.
numBytes	The number of freed bytes.

◆ IncreaseNumberOfObjectsSuspended()

virtual void Murl::Audio::IRenderer::IncreaseNumberOfObjectsSuspended ( )

pure virtual

Increase the internal suspended object count by 1.

Called by an object entering the suspended state.

◆ DecreaseNumberOfObjectsSuspended()

virtual void Murl::Audio::IRenderer::DecreaseNumberOfObjectsSuspended ( )

pure virtual

Decrease the internal suspended object count by 1.

Called by an object leaving the suspended state.

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

murl_audio_i_renderer.h

Detailed Description

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ GetApi()

◆ Init()

◆ DeInit()

◆ Start()

◆ Stop()

◆ Pause()

◆ Continue()

◆ Suspend()

◆ Resume()

◆ GetFeatures()

◆ CreateObject()

◆ DestroyObject()

◆ BeginSubmission()

◆ EndSubmission()

◆ BeginRendering()

◆ EndRendering()

◆ RegisterRenderThread()

◆ RegisterLogicThread()

◆ RegisterLoaderThread()

◆ UnregisterRenderThread()

◆ UnregisterLogicThread()

◆ UnregisterLoaderThread()

◆ RegisterAutomaticallySuspendableObject()

◆ UnregisterAutomaticallySuspendableObject()

◆ RegisterManuallySuspendableObject()

◆ UnregisterManuallySuspendableObject()

◆ RegisterEmergencySuspendableObject()

◆ UnregisterEmergencySuspendableObject()

◆ SetCurrentListener()

◆ SetCurrentTransform()

◆ PushObjectForUpdate()

◆ PushObjectForRendering()

◆ LockStatistics()

◆ UnlockStatistics()

◆ GetAllocatedResourceByteSize()

◆ GetNumberOfObjectsCreated()

◆ GetNumberOfObjectsSuspended()

◆ GetNumberOfObjectsRendered()

◆ GetNumberOfBatchesRendered()

◆ CollectStatisticsObjects()

◆ IncreaseNumberOfResourceBytesAllocated()

◆ DecreaseNumberOfResourceBytesAllocated()

◆ IncreaseNumberOfObjectsSuspended()

◆ DecreaseNumberOfObjectsSuspended()