interface IApplication in Tinman.AddOns.Application

Base interface for interactive real-time applications that are run by an ApplicationLoop.

interface	IApplication	extends	IConfigurable
			IDisposable
			IInputConsumer
			IInputState
			IRenderable
			IUpdateableFrameTime
		base of	ApplicationBase

Remarks

The following methods will never be called from more than one thread at a time.

• WindowAttach: once at application startup
• One or more iterations of the following loop:
  • GraphicsContextAttach
  • One iteration of the main loop per frame:
    • ConsumeInput: for each input event
    • UpdateFrameTime: once
    • WindowSize: if window size has changed since last frame.
    • RenderPrepare
    • Render
  • GraphicsContextDetach
• Dispose: once at application shutdown

The main loop will be run only if there is a valid graphics context.

Attributes

FrameRateLimit

Optional limit for rendering frames.

property	FrameRateLimit { get }
type	int32
value	[>=0]	The frame rate limit, in Hz. If 0 the limit will be disabled.

Remarks:

Defaults to 100.

LifecycleState

Returns the lifecycle state of this object.

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

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	IDisposable.AcquireTry

Remarks:

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

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

ConsumeInput

Consumes the given user input event.

method	ConsumeInput (InputEvent inputEvent)
type	bool
params	inputEvent		The user input event.
returns			true if the input event has been consumed, false if not.
inherited	IInputConsumer.ConsumeInput

Remarks:

Input events are provided to an IInputConsumer object only if it has the input focus (see FocusGained and FocusLost). Mouse events are provided when the mouse cursor is inside of the input bounds (MouseEnter and MouseLeave). The Closing event can be provided at any time.

1. FocusGained: gained input focus
2. Keyboard events:
   • Pressed: key has been pressed down.
   • Released: key has been released.
   • Clicked: key has been clicked.
   • Character: a character has been typed.
3. Mouse events:
   1. MouseEnter
   2. Mouse events:
      • Pressed
      • Released
      • Clicked
      • MouseMove
   3. MouseLeave
4. FocusLost: lost input focus
5. Closing: user request to shut down

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]
method	Dispose ()
inherited	IDisposable.Dispose

Remarks:

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

GraphicsContextAttach

Attaches the application to its graphics context.

method	GraphicsContextAttach (IGraphicsContext context)
params	context	[not-null]	The graphics context.

GraphicsContextDetach

Detaches the application from its graphics context.

method

GraphicsContextDetach ()

IsDown

Is the given keyboard key pressed down?

[Pure]
method	IsDown (KeyboardKey key)
type	bool
params	key		The keyboard key.
returns			true if the key is pressed down, false if not.
inherited	IInputState.IsDown

---

Is the given mouse button pressed down?

[Pure]
method	IsDown (MouseButton button)
type	bool
params	button		The mouse button.
returns			true if the button is pressed down, false if not.
inherited	IInputState.IsDown

Render

Performs rendering.

method	Render ()
inherited	IRenderable.Render

Remarks:

Implementing methods must not assume that any specific render state is in place when being called. Instead, the implementing method is responsible for setting up all state that is required for rendering.

Usually, implementing classes receive their current graphics context directly or indirectly from GraphicsContextAttach or GraphicsAttach.

In order to maximize parallelism between the CPU and GPU, only actual rendering (using the current graphics context) should be performed here. All other preparation resp. setup should be done in RenderPrepare instead.

See also:

GraphicsContextAttach
IGraphicsComponent.GraphicsAttach

RenderPrepare

Prepares rendering.

method	RenderPrepare ()
inherited	IRenderPreparable.RenderPrepare

Remarks:

This method is called before Render, when the graphics context has not yet begun to render the scene.

All setup work that does not require a graphics context (e.g. matrix computation, per-frame visibility determination) should be done here. This can help to maximize parallelism between the CPU and the GPU.

RunOperation

Runs the given operation within the lifecycle of this application.

method	RunOperation ([Owner] IOperation operation)
type	RunningOperation
params	operation	[not-null]	The operation to run.
returns		[not-null]	The running operation.

Remarks:

The Update method is called from within the applications UpdateFrameTime method.

The returned RunningOperation can be used to track progress resp. errors and to cancel the running operation.

When the application is disposed, all running operations are canceled (see Cancel) and then disposed.

Statistics

Provides runtime performance statistics to the application.

method	Statistics (ApplicationStats stats)
params	stats		The performance statistic values.

Remarks:

This information is gathered by the application loop which is running the application.

Calling this method is optional. Implementations of IApplication must never depend on the availability of ApplicationStats values.

ToConfig

Returns the configuration value that describes this object.

method	ToConfig ()
type	ConfigValue
returns		[not-null]	The configuration value.
inherited	IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

UpdateFrameTime

This method is called once per application frame.

method	UpdateFrameTime (float32 time)
type	bool
params	time	[>0]	The amount of time that has elapsed since the last frame, in seconds.
returns			true if the object needs to be presented again, false if the current presentation is still valid.
inherited	IUpdateableFrameTime.UpdateFrameTime

WindowAttach

Attaches the application to its window.

method	WindowAttach (IApplicationWindow window)
params	window	[not-null]	The application window.

Remarks:

This is always the first callback that the application receives.

WindowSize

Informs the application about the client size of its window.

method	WindowSize (Vec2I clientSize)
params	clientSize		The client size of the application window.

Extensions

Run

Runs this application.

[OwnerThis]
method	Run (string source, IGraphicsContextFactory context, [Owner] IApplicationWindow window)
type	TinmanError
params	source	[not-empty]	The error source to use in case an exception is thrown.
	context	[not-null]	The graphics context factory to use.
	window	[not-null]	The application window to use.
returns			The error in case of a crash, null if the application has ended normally.

---

Runs this application.

[OwnerThis]
method	Run (string source, IVectorConst<IGraphicsContextFactory> contexts, [Owner] IApplicationWindow window)
type	TinmanError
params	source	[not-empty]	The error source to use in case an exception is thrown.
	contexts	[not-empty]	The graphics context factories to use.
	window	[not-null]	The application window to use.
returns			The error in case of a crash, null if the application has ended normally.

---

Runs this application.

[OwnerThis]
method	Run (string source, IGraphicsContextFactory context, string windowTitle = null, Vec2I windowSize = default(Vec2I))
type	TinmanError
params	source	[not-empty]	The error source to use in case an exception is thrown.
	context	[not-null]	The graphics context factory to use.
	windowTitle		The window title.
	windowSize		The window size. If zero, a full-screen window will be created.
returns			The error in case of a crash, null if the application has ended normally.

---

Runs this application.

[OwnerThis]
method	Run (string source, IVectorConst<IGraphicsContextFactory> contexts, string windowTitle = null, Vec2I windowSize = default(Vec2I))
type	TinmanError
params	source	[not-empty]	The error source to use in case an exception is thrown.
	contexts	[not-empty]	The graphics context factories to use.
	windowTitle		The window title.
	windowSize		The window size. If zero, a full-screen window will be created.
returns			The error in case of a crash, null if the application has ended normally.