class Tutorial in Tinman.Demo.Tutorials.Framework

This is the base class for Tinman 3D tutorials.

abstract class	Tutorial	extends	Widget
		base of	Tutorial_00_Engine
			Tutorial_01_Conway
			Tutorial_02_Mandelbrot
			Tutorial_03_Widget
			Tutorial_10_Tinman

Remarks

Basically each tutorial is a mini application that is run by the DemoApplication. The Tutorial class provides some useful standard functionality.

For an example on how to use Tinman 3D outside of the DemoApplication context, please have a look at the Example_Application.

The tutorials Tutorial_0* explain basic usage of Tinman 3D that is unrelated to terrain visualization.

The tutorials Tutorial_1* cover the Low-level Terrain API, which is intended for use-cases where an existing terrain engine is being replaced with Tinman 3D. In this case, the various low-level objects can be used directly to implement the required terrain features.

The tutorials Tutorial_2* cover the High-level Terrain API, which is designed to add new terrain features to an application that already has some kind of 3D scene visualization.

The tutorials Tutorial_3* demonstrate the Scene API, which is suitable for building new applications from scratch resp. adding 2D/3D scene visualization features to an existing application.

The tutorials Tutorial_4* focus on data import, processing and export.

The tutorials Tutorial_5* showcase some of the ready-to-use IWidget s in Tinman 3D, for example pixel-perfect 2D rendering of raster data or smooth 2D map rendering with scrolling, zooming and rotation.

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):
   Initialize
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:
            DoConsumeInput
         2. Once:
            UpdateFrameTime
         3. Once:
            RenderPrepare
         4. Once:
            Render
   3. GraphicsDetach
3. Once (shutdown):
   DisposeResources

Configuration

ToConfig

Returns the configuration value that describes this object.

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

• ConfigException:
  If an unexpected error has occurred while building the config value.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger

Protected / Attributes

components

General purpose list of child components.

protected field	components
type	ObjectList
inherited	Widget.components

Remarks:

Subclasses are responsible for initializing this object list.

context

The current IGraphicsContext object or null.

protected field	context
type	IGraphicsContext
inherited	Widget.context

See also:

Widget.GraphicsAttach
Widget.GraphicsDetach

graphics

The current Graphics object or null.

protected field	graphics
type	Graphics
inherited	Widget.graphics

Remarks:

Use this Graphics object only during rendering (see Graphics for details), i.e. from within one of the following methods:

• Render
• Render2D

Use screenSize to query the current screen size.

See also:

Widget.GraphicsAttach
Widget.GraphicsDetach

input

The input state object or null.

protected field	input
type	IInputState
inherited	Widget.input

See also:

Widget.InputAttach
Widget.InputDetach

inputModifiers

The current input modifiers.

protected field	inputModifiers
type	InputModifiers
inherited	Widget.inputModifiers

Remarks:

These flags are maintained when ConsumeInput is called.

IsUpdatingGui

Is UpdateGui being called?

protected property	IsUpdatingGui { get }
type	bool
value		true if UpdateGui is being called, false if not.
inherited	Widget.IsUpdatingGui

mouse

Current position of mouse cursor.

protected field	mouse
type	Vec2I
inherited	Widget.mouse

profiler

The provided IProfiler object or null if none.

protected field	profiler
type	IProfiler
inherited	Widget.profiler

See also:

Widget.ProfilerAttach
Widget.ProfilerDetach

runner

The provided IApplicationRunner object or null.

protected field	runner
type	IApplicationRunner
inherited	Widget.runner

See also:

Widget.RunnerAttach
Widget.RunnerDetach

screenSize

The current screen size.

protected field	screenSize
type	Vec2I
inherited	Widget.screenSize

See also:

Widget.GraphicsResize

widgetGui

The provided IWidgetGui object or null if none.

protected field	widgetGui
type	IWidgetGui
inherited	Widget.widgetGui

See also:

Widget.WidgetGuiAttach
Widget.WidgetGuiDetach

Protected / Constructors

Tutorial

Creates a new instance of Tutorial.

protected constructor

Tutorial ()

Protected / Methods

Dirty

Marks the widget as dirty.

protected method	Dirty ()
inherited	Widget.Dirty

Remarks:

When a widget is dirty, the next call to UpdateFrameTime will always return true and the dirty flag will be cleared.

DisposeResources

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

protected override method	DisposeResources ()
overrides	Widget.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.

DoConsumeInput

Consumes the given user input event.

[EmptyBody]
protected virtual method	DoConsumeInput (InputEvent inputEvent)
type	bool
params	inputEvent		The user input event.
returns			true if the input event has been consumed, false if not.
inherited	Widget.DoConsumeInput

Remarks:

The given inputEvent has already been translated to the current widget bounds (see BoundedInput).

DoUpdateGui

Performs the work of UpdateGui.

[EmptyBody]
protected virtual method	DoUpdateGui (bool valuesOnly)
params	valuesOnly		true to update values in the existing GUI structure, false to rebuild the GUI structure before updating values.
inherited	Widget.DoUpdateGui

Remarks:

During the invocation of this method, IsUpdatingGui will return true.

InitializeBegin

Begins to initialize this object.

protected method	InitializeBegin ()
type	bool
returns			true if initialization must be performed, false if initialization has already been performed.
inherited	Disposable.InitializeBegin

InitializeRequired

Has this object been initialized?

protected method	InitializeRequired ()
type	bool
returns			true if Initialize has already been called, false if not.
inherited	Disposable.InitializeRequired

KeyboardMode

[EmptyBody]
protected virtual method	KeyboardMode (bool azerty)
params	azerty

LoadBegin

Begins to load a dataset.

protected method	LoadBegin (string path)
params	path	[not-null]	Engine path to the dataset.

Remarks:

Calls to LoadBegin and LoadEnd*() must be performed in the same order.

See also:

LoadEndHeightmapDataset

Exceptions:

• IOException:
  If the dataset file denoted by path is not supported.

LoadEndHeightmapDataset

Returns a loaded heightmap dataset.

[OwnerReturn]
protected method	LoadEndHeightmapDataset ()
type	IHeightmapDataset
returns		[not-null]	The loaded dataset.

See also:

LoadBegin

Exceptions:

• PoolingException:
  If the background task has failed.

LoadEndShape

Returns a loaded vector shape.

protected method	LoadEndShape ()
type	IShape
returns		[not-null]	The loaded vector shape.

See also:

LoadBegin

Exceptions:

• PoolingException:
  If the background task has failed.

SetName

Specifies the name of this tutorial.

protected virtual method	SetName (string name)
params	name		The tutorial name.

Settings

Returns the path to the settings directory of this widget, creating parent directories if necessary.

protected method	Settings ()
type	Path
returns		[not-null]	The canonical settings path.
inherited	Widget.Settings

Exceptions:

• IOException:
  If a parent directory failed to be created (DirectoryCreate).

---

Returns a path into the settings directory of this widget, creating parent directories if necessary.

protected method	Settings (string path)
type	Path
params	path	[not-empty]	Relative path into settings directory.
returns		[not-null]	The canonical settings path.
inherited	Widget.Settings

Exceptions:

• IOException:
  If a parent directory failed to be created (DirectoryCreate).

---

Returns a path into the settings directory of this widget, creating parent directories if necessary.

protected method	Settings (Path path)
type	Path
params	path	[not-null]	Relative path into settings directory.
returns		[not-null]	The canonical settings path.
inherited	Widget.Settings

Exceptions:

• IOException:
  If no settings path has been specified via SettingsPath or if a parent directory failed to be created (DirectoryCreate).

SizeChanged

The pixel size of this widget has changed.

[EmptyBody]
protected virtual method	SizeChanged (Vec2I size)
params	size		The new pixel size.
inherited	Widget.SizeChanged

Remarks:

This method is called in these cases:

• When GraphicsResize is called.
• When the Bounds property is changed while attached and the resulting pixel bounds have a different size.
• When the UpdateFrameTime method is called while attached and the widget bounds version (see Version) has changed.

Public / Attributes

ActualBounds

Returns the actual pixel bounds of this widget.

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

Bounds

The pixel bounds of this widget.

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

Remarks:

Defaults to FullScreen.

HelpId

A machine-readable unique identifier for the user help of this component.

public virtual property	HelpId { get }
type	string
value		The help ID or null if none.
inherited	Widget.HelpId

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 AcquireThrow).
inherited	Disposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

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

MouseCursor

The mouse cursor to show for this widget.

public virtual property	MouseCursor { get }
type	MouseCursor
value		The mouse cursor
inherited	Widget.MouseCursor

Name

Machine-friendly name of this tutorial.

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

Remarks:

The name is used to create the settings path.

NonUserInterfaceBounds

Returns the screen region that is not occluded by any opaque user-interface components.

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

Remarks:

If there is not user-interface, the screen region is returned.

SettingsPath

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

Remarks:

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

See also:

IWidget.SettingsLoadTry
IWidget.SettingsSaveTry

ShouldCaptureMouse

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:

IApplicationWindow.MouseCaptured

Public / Methods

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method	AcquireBase ()
type	IDisposable
returns			The strong reference to this disposable object or null iff 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.

AcquireThrow

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method	AcquireThrow ()
type	IDisposable
returns		[not-null]	The strong reference to this disposable object.
inherited	Disposable.AcquireThrow

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.

Exceptions:

• TinmanException:
  If this object is no longer valid.

ClearCaches

Clears the caches of this tutorial.

public virtual method

ClearCaches ()

Remarks:

This method clears the following caches:

• GPU resource cache (see ClearCache)
• Raster dataset cache (see Clear) for streamed data (see UseCacheIfWeb).

Subclasses may override this method to clear additional caches.

Exceptions:

• IOException:
  If an I/O error has occurred.

ConsumeInput

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

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

GraphicsAttach

Attaches this component to the given Graphics context.

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

Remarks:

All graphics-related resources should be created here.

Do not use the screen size of graphics here, as it may not be valid (see Graphics for details). Instead, use the screen size that is provided by GraphicsResize.

Exceptions:

• RenderException:
  If a graphics subsystem error has occurred.

GraphicsDetach

Detaches this user interface component from its Graphics context.

public override method	GraphicsDetach ()
overrides	Widget.GraphicsDetach

Remarks:

All graphics-related resources should be disposed here.

GraphicsResize

The screen size has changed.

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

Initialize

Initializes the object, if necessary.

[ThrowAny]
public override method	Initialize ()
type	bool
returns			true if the object has been initialized, false if the object has already been initialized before.
overrides	Widget.Initialize

InputAttach

Attaches this input consumer to the given input state object.

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

Remarks:

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

InputDetach

Detached this input consumer from its input state object.

public virtual method	InputDetach ()
inherited	Widget.InputDetach

JsonDeserialize

Restores the object state from the given JSON value.

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

Remarks:

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

JsonSerialize

Serializes the object state to an JSON value.

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

ProfilerAttach

Attaches this object to the given profiler.

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

ProfilerDetach

Detaches this object from its IProfiler object.

public virtual method	ProfilerDetach ()
inherited	Widget.ProfilerDetach

Render

Performs rendering of the next frame.

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

Render2D

Performs 2D rendering.

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

Remarks:

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

• The render bounds have been specified (see Bounds).
• The Begin method has already been called.
• Clipping and translation have been applied, so that (0|0) refers to the top-left pixel of the target rectangle and ScreenSize returns the target rectangle size. The target rectangle and the clipping rectangle can be different.

Usually, Render2D is called from within Render.

RenderPrepare

Prepares rendering of the next frame.

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

ResetView

Resets the current view to default values.

[EmptyBody]
public virtual method	ResetView ()

RunnerAttach

Provides the enclosing IApplicationRunner.

public virtual method	RunnerAttach (IApplicationRunner runner)
params	runner	[not-null]	The application runner.
inherited	Widget.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 ()
inherited	Widget.RunnerDetach

Screenshot

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

SettingsLoadTry

Tries to load the settings of this widget, ignoring errors.

public method	SettingsLoadTry (string name = null)
type	bool
params	name		Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns			true if the settings have been loaded, false if not.
inherited	Widget.SettingsLoadTry

See also:

IWidget.SettingsPath

SettingsSaveTry

Tries to save the settings of this widget, ignoring errors.

public method	SettingsSaveTry (string name = null)
type	bool
params	name		Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns			true if the settings have been saved, false if not.
inherited	Widget.SettingsSaveTry

See also:

IWidget.SettingsPath

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.
inherited	Widget.UpdateFrameTime

UpdateGui

Updates GUI components, according to current values in the data model.

public method	UpdateGui (bool valuesOnly)
params	valuesOnly		true to update values in the existing GUI structure, false to rebuild the GUI structure before updating values.
inherited	Widget.UpdateGui

Remarks:

Implementing method are expected to be fail-safe, i.e. their behaviour is well-defined, even if there is not GUI or the data model is empty. Thus, the UpdateGui method may be called at any time.

This method may be called repeatedly when valuesOnly is true. Implementing methods are expected to perform efficient in this case.

UseCacheIfWeb

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.

Remarks:

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

WidgetGuiAttach

Attaches this object to the given WidgetGui instance.

public virtual method	WidgetGuiAttach (IWidgetGui widgetGui)
params	widgetGui	[not-null]	The WidgetGui instance.
inherited	Widget.WidgetGuiAttach

Remarks:

As best practice, implementing classes should create their user interface components in this method and call PanelAdd accordingly.

The calls to WidgetGuiAttach resp. WidgetGuiDetach may be omitted, for example when running without a widget GUI overlay. Implementing classes must take this into account and should not rely on the premise that this method is always called.

WidgetGuiDetach

Detaches this object from its WidgetGui instance.

public virtual method	WidgetGuiDetach ()
inherited	Widget.WidgetGuiDetach

Remarks:

Implementing classes must remove all panels via PanelRemove that they have added to the widget GUI.