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

class ApplicationBase in Tinman.Engine.Application

Abstract base class for IApplication implementations.

abstract class ApplicationBase extends Disposable
  implements IApplication
  base of LogoApplication
  TestApplication
  WidgetApplication

Remarks

The default implementation of Render calls ClearRenderTarget, passing all clear flags and default clear values. Omit the base method call if you need to do the clear in another way.

Configuration

ToConfig

Returns the configuration value that describes this object.

public abstract method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
implements 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.

Exceptions:

Public / Attributes

FrameRateLimit

Optional limit for rendering frames.

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

Remarks:

Defaults to 100.

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

RunningOperations

Returns the running background operations that have been started in the context of the application.

public property RunningOperations { get }
type IVectorConst<RunningOperation>
value [not-null] The list of running background operations.
implements IApplicationInfo.RunningOperations

See also:

IApplication.RunOperation

Public / Methods

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method Acquire (bool allowNull = false)
type IApplication
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.
implements IDisposableGeneric.Acquire

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this 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.

Exceptions:

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:

ConsumeInput

Consumes the given user input event.

public virtual method ConsumeInput (InputEvent inputEvent)
type bool
params inputEvent The user input event.
returns true if the input event has been consumed, false if not.
implements 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:
  3. Mouse events:
    1. MouseEnter
    2. Mouse events:
    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]
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.

GraphicsContextAttach

Attaches the application to its graphics context.

public virtual method GraphicsContextAttach (IGraphicsContext context)
params context [not-null] The graphics context.
implements IApplication.GraphicsContextAttach

GraphicsContextDetach

Detaches the application from its graphics context.

public virtual method GraphicsContextDetach ()
implements IApplication.GraphicsContextDetach

IsDown

Is the given keyboard key pressed down?

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

Is the given mouse button pressed down?

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

ProfilerAttach

Attaches this object to the given profiler.

public virtual method ProfilerAttach (IProfiler profiler)
params profiler [not-null] The profiler to attach to.
implements IProfilerConsumer.ProfilerAttach

ProfilerDetach

Detaches this object from its IProfiler object.

public virtual method ProfilerDetach ()
implements IProfilerConsumer.ProfilerDetach

Render

Performs rendering of the next frame.

public virtual method Render ()
implements 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.

It is not guaranteed that the GPU will have processed all render commands of the last frame when this method is called, in order to render the next one.

See also:

IApplication.GraphicsContextAttach
IGraphicsComponent.GraphicsAttach

RenderPrepare

Prepares rendering of the next frame.

public virtual method RenderPrepare ()
implements 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.

It is expected that the GPU is busy processing the render commands of the last frame, while this method prepares the next one.

RequestClose

Requests to close the application by feeding it with an Closing input event.

public virtual method RequestClose ()
implements IRequestClose.RequestClose

RunnerAttach

Provides the enclosing IApplicationRunner.

public virtual method RunnerAttach (IApplicationRunner runner)
params runner [not-null] The application runner.
implements IApplicationRunnerConsumer.RunnerAttach

Remarks:

Calling of this method is optional. Implementations of IApplication should not depend on the availability of an IApplicationRunner context object.

RunnerDetach

Clears the reference to the enclosing IApplicationRunner.

public virtual method RunnerDetach ()
implements IApplicationRunnerConsumer.RunnerDetach

RunOperation

Runs the given operation within the lifecycle of this application.

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

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.

UpdateFrameTime

This method is called once per application frame.

public virtual 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.
implements IUpdateableFrameTime.UpdateFrameTime

WindowAttach

Attaches the application to its window.

public virtual method WindowAttach (IApplicationWindow window)
params window [not-null] The application window.
implements IApplication.WindowAttach

Remarks:

This is always the first callback that the application receives.

WindowSize

Informs the application about the client size of its window.

public virtual method WindowSize (Vec2I clientSize)
params clientSize The client size of the application window.
implements IApplication.WindowSize

Protected / Attributes

context

The graphics context for custom rendering.

protected field context
type IGraphicsContext

See also:

GraphicsContextAttach
GraphicsContextDetach

profiler

The profiler or null.

protected field profiler
type IProfiler

See also:

ProfilerAttach
ProfilerDetach

runner

The application runner.

protected field runner
type IApplicationRunner

See also:

RunnerAttach

window

The application window.

protected field window
type IApplicationWindow

See also:

WindowAttach

Protected / Methods

DisposeResources

Disposes the resources held by a concrete subclass. This method will be called exactly once per instance.

protected override method DisposeResources ()
overrides Disposable.DisposeResources

Remarks:

This method will be called as soon as all ownership references to this instance have been relinquished by calls to the Dispose method.

The system may garbage collect an instance of IDisposable iff there are no more references to it. In this case, the DisposeResources will be called, in order to avoid dangling resources. However, it is not advisable to rely on the garbage collection of the system, as the behaviour may differ significantly between environments. Instead, ownership rules should be obeyed, which effectively removes the need for automatic garbage collection.

Overriding methods must call the DisposeResources method of their base class. The base call should be the last statement.