Software Development Kit - User Manual

class Tutorial_00_Engine in Tinman.Demo.Tutorials

Tinman 3D tutorial #0 : Engine

sealed class Tutorial_00_Engine extends Tutorial


This tutorial renders 'Hello Engine!' onto the screen. While doing so, it explains the purpose of the Tinman 3D application engine callbacks. All IWidget s and hence all Tutorial s make use of the application engine. All terrain features of Tinman 3D can of course be used without the application engine.

This is the order of callbacks provided by the Tinman 3D application engine:

  1. Once (start-up):
  2. Repeatedly (for each graphics context, e.g. lost device after locking screen):
    1. GraphicsAttach
    2. Repeatedly (when widget bounds change, e.g. after screen resize):
      1. SizeChanged
      2. Repeatedly (when the widget becomes the foreground one):
        1. InputAttach
        2. InputDetach
      3. Repeatedly (once per frame):
        1. Zero or more times:
        2. Once:
        3. Once:
        4. Once:
    3. GraphicsDetach
  3. Once (shutdown):



Returns the configuration value that describes this object.

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


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.

Public / Attributes


Returns the actual pixel bounds of this widget.

public property ActualBounds { get }
type Box2I
value The actual pixel bounds or Empty.
inherited Widget.ActualBounds


The pixel bounds of this widget.

public virtual property Bounds { get set }
type IWidgetBounds
value [not-null] The pixel bounds.
inherited Widget.Bounds


Defaults to FullScreen.


Returns the lifecycle state of this object.

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


The mouse cursor to show for this widget.

public override property MouseCursor { get }
type MouseCursor
value The mouse cursor
overrides Widget.MouseCursor


Machine-friendly name of this tutorial.

public property Name { get }
type string
value [not-null] The name.
inherited Tutorial.Name


The name is used to create the settings path.


Returns the central part of the actual pixel bounds of this widget which is not occluded by the widget user interface.

public property NonUserInterfaceBounds { get }
type Box2I
value The non-UI pixel bounds.
inherited Widget.NonUserInterfaceBounds

See also:



Specifies the behaviour for automatically loading and saving of widget settings.

public property SettingsAuto { get set }
type int32
value A combination of the following bit flags:
1: load settings when after widget has been initialized.
2: save settings when widget consumes Closing.
inherited Widget.SettingsAuto


Defaults to 3.


Path to a directory that this widget can use to store own data and settings.

public property SettingsPath { get set }
type Path
value Canonical path to the settings directory or null.
inherited Widget.SettingsPath


The settings path must be set before Initialize is called on the widget. Afterwards, the settings path cannot be changed.


Should the mouse be captured, because this input consumer only processes relative input?

public virtual property ShouldCaptureMouse { get }
type bool
value true if the mouse should be captured, false if not.
inherited Widget.ShouldCaptureMouse

See also:



Computes an offset for the screen center that can be used to compensate for the GUI overlay of this widget.

public property UserInterfaceCenterOffset { get }
type Vec2F
value The screen center offset, in pixels.
inherited Widget.UserInterfaceCenterOffset

See also:


Public / Constructors


Creates a new instance of Tutorial_00_Engine.

public constructor Tutorial_00_Engine ()

Public / Methods


Acquires a strong reference to this disposable object.

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


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.


Adds a GUI panel to this widget.

public method AddUserInterface (WidgetSlot slot, [Owner] Panel panel)
params slot The widget GUI slot where the given GUI panel will be put.
  panel [not-null] The GUI panel to add.
inherited Widget.AddUserInterface


Consumes the given user input event.

public 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 Widget.ConsumeInput


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


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


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


Attaches this component to the given Graphics context.

public override method GraphicsAttach (Graphics graphics)
params graphics [not-null] The graphics context.
overrides Widget.GraphicsAttach


All graphics-related resources should be created here.


Detaches this user interface component from its Graphics context.

public override method GraphicsDetach ()
overrides Tutorial.GraphicsDetach


All graphics-related resources should be disposed here.


The screen size has changed.

public method GraphicsResize (Vec2I screenSize)
params screenSize The new screen size, in pixels.
inherited Widget.GraphicsResize


The given screen size is equal to the value of ScreenSize of the Graphics object that has been passed to GraphicsAttach earlier.


Initializes the object, if necessary

public method Initialize ()
inherited Initializable.Initialize


The Initialize method returns silently if the object is already in the state Initialized.


Attaches this input consumer to the given input state object.

public override method InputAttach (IInputState input)
params input [not-null] The input state object.
overrides Widget.InputAttach


The input state object provides a snapshot of the input keys and buttons. It should not be used to detect up/down/click events.


Detached this input consumer from its input state object.

public override method InputDetach ()
overrides Widget.InputDetach


Restores the object state from the given JSON value.

public virtual method JsonDeserialize (JsonValue value)
params value [not-null] The input JSON value.
inherited Widget.JsonDeserialize


Implementations of this method must be able to consume malformed JSON values, without corrupting the object state.


Serializes the object state to an JSON value.

public virtual method JsonSerialize (JsonValue value)
params value [not-null] The output JSON value.
inherited Widget.JsonSerialize


Performs rendering.

public override method Render ()
overrides Widget.Render


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:



Performs 2D rendering.

public override method Render2D (Graphics g)
params g [not-null] The graphics object to use.
overrides Widget.Render2D


When this method is called, the given Graphics object has already been initialized for 2D rendering:

Usually, Render2D is called from within Render.


Prepares rendering.

public override method RenderPrepare ()
overrides Widget.RenderPrepare


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.


Takes a screenshot the next time this widget is rendered.

public virtual method Screenshot (WidgetScreenshotDelegate result)
params result [not-null] The screenshot pixels will be passed to this delegate.
inherited Widget.Screenshot


This method is called once per application frame.

public override 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.
overrides Widget.UpdateFrameTime


public virtual method UpdateGui ()
inherited Widget.UpdateGui


This method is used as a DatasetFileCacheDelegate in order to provide the default file cache for dataset.

public method UseCacheIfWeb (IFile file)
type DatasetFileCache
params file The dataset file.
returns The file cache or null.
inherited Tutorial.UseCacheIfWeb


The method will return the shared dataset file cache if the given file is streamed from the internet.