ApplicationLoop

Description

sealed class Tinman.Engine.Application.ApplicationLoop

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

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 IEventListenerGeneric.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


public static readonly attribute ProfileCpuRate → (ProfilerValue)

CPU frame rate.

ProfileCpuTime


public static readonly attribute ProfileCpuTime → (ProfilerValue)

The frame time that has been passed to IUpdateableFrameTime.UpdateFrameTime.

ProfileCpuTotal


public static readonly attribute ProfileCpuTotal → (ProfilerValue)

CPU usage of system.

ProfileCpuUsed


public static readonly attribute ProfileCpuUsed → (ProfilerValue)

CPU usage of application.

ProfileGpuRate


public static readonly attribute ProfileGpuRate → (ProfilerValue)

GPU frame rate.

ProfileGpuTime


public static readonly attribute ProfileGpuTime → (ProfilerValue)

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

ProfileInput


public static readonly attribute ProfileInput → (ProfilerValue)

CPU time spent calling IInputConsumer.ConsumeInput, in milliseconds.

ProfileMemory


public static readonly attribute ProfileMemory → (ProfilerValue)

Relative amount of memory used by application.

ProfileMemoryTotal


public static readonly attribute ProfileMemoryTotal → (ProfilerValue)

Amount of available system memory.

ProfileMemoryUsed


public static readonly attribute ProfileMemoryUsed → (ProfilerValue)

Amount of memory used by application.

ProfilePrepare


public static readonly attribute ProfilePrepare → (ProfilerValue)

CPU time spent calling IRenderPreparable.RenderPrepare, in milliseconds.

ProfilePresent


public static readonly attribute ProfilePresent → (ProfilerValue)

CPU time spent calling ISwapChain.Present, in milliseconds.

ProfileRender


public static readonly attribute ProfileRender → (ProfilerValue)

CPU time spent calling IRenderable.Render, in milliseconds.

ProfileUpdate


public static readonly attribute ProfileUpdate → (ProfilerValue)

CPU time spent calling IUpdateableFrameTime.UpdateFrameTime, in milliseconds.

ProfileWait


public static readonly attribute ProfileWait → (ProfilerValue)

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

Public / Constructors

ApplicationLoop

2 overloads


public constructor ApplicationLoop1 → (3)

application in : IApplication

[not-null]
The application to run.

window in : IApplicationWindow

[not-null]
The application window to use.

graphicsContextFactory in : IGraphicsContextFactory

[not-null]
The graphics context factory to use.

Creates a new instance of ApplicationLoop.


public constructor ApplicationLoop2 → (3)

application in : IApplication

[not-null]
The application to run.

window in : IApplicationWindow

[not-null]
The application window to use.

graphicsContextFactories in : IVectorConst<IGraphicsContextFactory>

[not-empty]
The graphics context factories to use.

Creates a new instance of ApplicationLoop.

Public / Methods

MainLoop


public method MainLoop → ()

returns → ApplicationLoopResult

The result code.

Runs a single iteration of the application main loop.

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:

  • I: IInputConsumer.ConsumeInput
    U: IUpdateableFrameTime.UpdateFrameTime
    The application consumes external stimuli and updates its internal state accordingly. Usually, a new frame will only be rendered if the application state has changed.

  • RP: IRenderPreparable.RenderPrepare
    The application performs all pre-rendering work that does not require GPU interaction.

  • R: IRenderable.Render
    The application renders the current frame by issuing render commands, which are processed asynchronously by the GPU.

  • F: IRenderTarget.Finish
    The application finishes rendering to the render target of its swap chain for the current frame. The GPU may now prepare presentation of the current frame asynchronously, for example by resolving a multi-sampled render target into a backbuffer.

  • P: ISwapChain.Present
    The current frame is ready and may be presented. Presentation will be performed asynchronously, for example by flipping back buffers after waiting for vertical synchronization.

The CPU and GPU timelines are allowed to progress independently on each other. When using GpuUpdateFlag.NoOverwrite to update GPU resources, it may be necessary to synchronize with the GPU, using IGraphicsFence objects (see sync in the above figure).

Run


[OwnerThis]
public method Run → (1)

sleepOnIdle in : bool

Honor ApplicationLoopResult.Idle by sleeping for a short time?

Runs the application loop until the application terminates.

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

Public / Attributes

ContextFactories


public attribute ContextFactories → (set)

value : IVectorConst<IGraphicsContextFactory>

[not-null]
The list of graphics context factories.

Specifies the graphics context factories to use.

ContextFactory


public attribute ContextFactory → (set)

value : IGraphicsContextFactory

[not-null]
The graphics context factory.

Specifies the graphics context factory to use.

CurrentContext


public attribute CurrentContext → (get,set)

value : int32

[>=0]
The graphics context factory index.

The current graphics context.

Setting this property will also trigger a graphics context reset.

FrameIndex


public attribute FrameIndex → (get)

value : int32

[>=0]
The frame index.

Returns the current frame index.

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

TimeIndex


public attribute TimeIndex → (get)

value : float64

[>=0]
The running time, in seconds.

Returns the current time index.

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

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.