TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class ApplicationLoop in Tinman.Engine.Application

The ApplicationLoop class implements the main loop of an interactive real-time application.

sealed class ApplicationLoop extends Disposable
  implements IEventListenerGeneric<InputEvent>

Remarks

To run a real-time application, only three steps are necessary:

  1. Create an ApplicationLoop object.
  2. Repeatedly call MainLoop until it returns false.
  3. Dispose the ApplicationLoop loop object.
Proper callbacks to the IApplication object will be made automatically.

The NotifyEvent method can be used to manually inject input events to the application loop. The events will be processed the next time MainLoop is called.

Public / Constants

ProfileCpuRate

CPU frame rate.

public static readonly field ProfileCpuRate
type ProfilerValue

ProfileCpuTime

The frame time that has been passed to UpdateFrameTime.

public static readonly field ProfileCpuTime
type ProfilerValue

ProfileCpuTotal

CPU usage of system.

public static readonly field ProfileCpuTotal
type ProfilerValue

ProfileCpuUsed

CPU usage of application.

public static readonly field ProfileCpuUsed
type ProfilerValue

ProfileGpuRate

GPU frame rate.

public static readonly field ProfileGpuRate
type ProfilerValue

ProfileGpuTime

GPU time spent for the last frame (see Result).

public static readonly field ProfileGpuTime
type ProfilerValue

ProfileInput

CPU time spent calling ConsumeInput, in milliseconds.

public static readonly field ProfileInput
type ProfilerValue

ProfileMemory

Relative amount of memory used by application.

public static readonly field ProfileMemory
type ProfilerValue

ProfileMemoryTotal

Amount of available system memory.

public static readonly field ProfileMemoryTotal
type ProfilerValue

ProfileMemoryUsed

Amount of memory used by application.

public static readonly field ProfileMemoryUsed
type ProfilerValue

ProfilePrepare

CPU time spent calling RenderPrepare, in milliseconds.

public static readonly field ProfilePrepare
type ProfilerValue

ProfilePresent

CPU time spent calling Present, in milliseconds.

public static readonly field ProfilePresent
type ProfilerValue

ProfileRender

CPU time spent calling Render, in milliseconds.

public static readonly field ProfileRender
type ProfilerValue

ProfileUpdate

CPU time spent calling UpdateFrameTime, in milliseconds.

public static readonly field ProfileUpdate
type ProfilerValue

ProfileWait

The CPU is waiting for the GPU to finish (milli-seconds).

public static readonly field ProfileWait
type ProfilerValue

See also:

IRenderable.Render

Public / Attributes

ContextFactories

Specifies the graphics context factories to use.

public property ContextFactories { set }
type IVectorConst<IGraphicsContextFactory>
value [not-null] The list of graphics context factories.

Exceptions:

ContextFactory

Specifies the graphics context factory to use.

public property ContextFactory { set }
type IGraphicsContextFactory
value [not-null] The graphics context factory.

Exceptions:

CurrentContext

The current graphics context.

public property CurrentContext { get set }
type int32
value [>=0] The graphics context factory index.

Remarks:

Setting this property will also trigger a graphics context reset.

FrameIndex

Returns the current frame index.

public property FrameIndex { get }
type int32
value [>=0] The frame index.

Remarks:

The frame index counts the number of calls to Present that have been made from inside the MainLoop. Frames that do not require rendering are counted, too.

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
public property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireBase).
inherited Disposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

public property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited Disposable.LifecycleState

TimeIndex

Returns the current time index.

public property TimeIndex { get }
type float32
value [>=0] The running time, in seconds.

Remarks:

The time index is the update time that has been accumulated in the MainLoop. This value correlates to the calls to UpdateFrameTime.

Public / Constructors

ApplicationLoop

Creates a new instance of ApplicationLoop.

public constructor ApplicationLoop ([Owner] IApplication application, [Owner] IApplicationWindow window, IGraphicsContextFactory graphicsContextFactory)
params application [not-null] The application to run.
  window [not-null] The application window to use.
  graphicsContextFactory [not-null] The graphics context factory to use.

Creates a new instance of ApplicationLoop.

public constructor ApplicationLoop ([Owner] IApplication application, [Owner] IApplicationWindow window, IVectorConst<IGraphicsContextFactory> graphicsContextFactories)
params application [not-null] The application to run.
  window [not-null] The application window to use.
  graphicsContextFactories [not-empty] The graphics context factories to use.

Public / Methods

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method AcquireBase (bool allowNull = false)
type IDisposable
params allowNull Depicts what to do when this object is no longer valid:
true: return null
false: throw an exception
returns The strong reference to this disposable object or null iff allowNull is true and this object is no longer valid.
inherited Disposable.AcquireBase

Remarks:

The object will not be actually disposed by calls to IDisposable when there is at least one strong reference left. Code that calls this method is responsible for calling the IDisposable method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

Exceptions:

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method Dispose ()
inherited Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Implementing methods must not throw any exceptions.

MainLoop

Runs a single iteration of the application main loop.

public method MainLoop ()
type ApplicationLoopResult
returns The result code.

Remarks:

Repeatedly calling the MainLoop method according to the returned ApplicationLoopResult values will establish the following CPU/GPU timelines:

     frame #0         frame #1         frame #2         frame #3
CPU: [I U RP R F P]   [I U RP R F P]   [I U RP R F P]   [I U RP R F P] ...
                _____sync_____/  _____sync_____/  _____sync_____/
               /                /                /
GPU:          [R   F   P  ]    [R   F   P  ]    [R   F   P  ] ...
              frame #0         frame #1         frame #2
where the mnemonic have the following meaning: The CPU and GPU timelines are allowed to progress independently on each other. When using NoOverwrite to update GPU resources, it may be necessary to synchronize with the GPU, using IGraphicsFence objects (see sync in the above figure).

NotifyEvent

The event has been triggered.

public method NotifyEvent (InputEvent argument)
params argument The event argument.
implements IEventListenerGeneric.NotifyEvent

Run

Runs the application loop until the application terminates.

[OwnerThis]
public method Run (bool sleepOnIdle)
params sleepOnIdle Honor Idle by sleeping for a short time?

Remarks:

This ApplicationLoop object will have been disposed when this method returns.

Logging

Logger

The logger object of this class.

public static readonly field Logger
type ILogger