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

Profile​Application​Cpu​Rate


public static readonly attribute ProfileApplicationCpuRate → (ProfilerValue)

CPU frame rate.

Profile​Application​Cpu​Total


public static readonly attribute ProfileApplicationCpuTotal → (ProfilerValue)

CPU usage of system.

Profile​Application​Cpu​Used


public static readonly attribute ProfileApplicationCpuUsed → (ProfilerValue)

CPU usage of application.

Profile​Application​Gpu​Rate


public static readonly attribute ProfileApplicationGpuRate → (ProfilerValue)

GPU frame rate.

Profile​Application​Gpu​Time


public static readonly attribute ProfileApplicationGpuTime → (ProfilerValue)

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

Profile​Application​Memory


public static readonly attribute ProfileApplicationMemory → (ProfilerValue)

Relative amount of memory used by application.

Profile​Cpu​Time​Input


public static readonly attribute ProfileCpuTimeInput → (ProfilerValue)

CPU time spent calling IInputConsumer.ConsumeInput, in milliseconds.

Profile​Cpu​Time​Prepare


public static readonly attribute ProfileCpuTimePrepare → (ProfilerValue)

CPU time spent calling IRenderPreparable.RenderPrepare, in milliseconds.

Profile​Cpu​Time​Present


public static readonly attribute ProfileCpuTimePresent → (ProfilerValue)

CPU time spent calling ISwapChain.Present, in milliseconds.

Profile​Cpu​Time​Render


public static readonly attribute ProfileCpuTimeRender → (ProfilerValue)

CPU time spent calling IRenderable.Render, in milliseconds.

Profile​Cpu​Time​Update


public static readonly attribute ProfileCpuTimeUpdate → (ProfilerValue)

CPU time spent calling IUpdateableFrameTime.UpdateFrameTime, in milliseconds.

Profile​Cpu​Time​Wait


public static readonly attribute ProfileCpuTimeWait → (ProfilerValue)

CPU time spent with house-keeping while beginning / ending render cycles with IGraphicsContext (milli-seconds).

Profile​Memory​Total


public static readonly attribute ProfileMemoryTotal → (ProfilerValue)

Amount of available system memory.

Profile​Memory​Used


public static readonly attribute ProfileMemoryUsed → (ProfilerValue)

Amount of memory used by application.

Public / Constructors

Application​Loop

2 overloads


public constructor ApplicationLoop1 → (3)

application in : IApplication own

[not-null]
The application to run.

window in : IApplicationWindow own

[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 own

[not-null]
The application to run.

window in : IApplicationWindow own

[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

Main​Loop


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

Honour 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

Context​Factories


public attribute ContextFactories → (set)

value : IVectorConst<IGraphicsContextFactory>

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

Specifies the graphics context factories to use.

Context​Factory


public attribute ContextFactory → (set)

value : IGraphicsContextFactory

[not-null]
The graphics context factory.

Specifies the graphics context factory to use.

Current​Context


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.

Frame​Index


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.

Time​Index


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.