Developer Guide

This page contains technical information for developers.

Technical Overview

To get an overview of the Tinman 3D SDK, please refer to the following documentation:

  • Software Architecture
    Explains common code constructs as well as the overall structure and design of the SDK

  • Terrain Overview
    Explains concepts and building blocks that are specific to the realtime terrain processing, visualization and analysis features of the SDK

  • Scene Overview
    Explains how to create interactive 3D scenes that are based on the terrain features of the SDK

  • Scripting Overview
    Explains how to use the scripting language of the SDK

  • Geodata Processing
    Explains how to setup and run geodata processing pipelines

  • Streaming and Caching
    Explains how to setup data streaming from external source, backed by efficient data caching

  • User Interface
    Explains the built-in user interface framework of the SDK

Tutorials and Examples

To find the tutorial and example source code in the Tinman 3D SDK, please have a look at these places:

GUI Widgets

The Tinman 3D SDK contains several GUI widgets, which can be used as plug-and-play components for other applications.

Every widget implements the IWidget interface. Widgets are assembled into an IApplication object, which is then run by an application-defined host.

The following built-in application hosts are available:

  • Native window
    The application object is run in an own application window (see IApplication.Run).

  • WinForms Host
    The application uses the ApplicationControl class of the Tinman.AddOns.WinForms component.

  • WPF Host
    The application uses the ApplicationControlWpf class of the Tinman.AddOns.WPF component. This WPF Control is provided as source code.

  • MFC Host
    The application uses the CApplicationControlMfc class of the Tinman.AddOns.MFC component.

If you get errors when loading one of the above controls into the GUI designer of your IDE, please build and run the corresponding demo first (e.g. Tinman.Demo.WinForms). This usually fixes the problem.

The Workshop Application lets the user configure an App object, uses the ConfigScript class to create an IApplication object from the script source code and finally runs the resulting widget(s) in its WPF host.

Please refer to the help browser in the Demo Application for details on available GUI widgets.

Hello World

This is the "Hello World!" example of the Tinman 3D SDK:

using CodeX;
using Tinman.AddOns.DirectX11;
using Tinman.Core;
using Tinman.Core.Config;
using Tinman.Core.IO;
using Tinman.Core.Licensing;
using Tinman.Core.Math.Vectors;
using Tinman.Core.Util;
using Tinman.Engine;
using Tinman.Engine.Application;
using Tinman.Engine.Drawing;
using Tinman.Engine.Rendering;

namespace Tinman.Demo.Examples
{
  public sealed class Example_HelloWorld : ApplicationBase
  {
    public override ConfigValue ToConfig()
    {
      // This means our application is not exposed to the Config API.
      return ConfigValue.Invalid;
    }

    [ThrowAny]
    public static void Main(Path repository)
    {
      // Before initializing the Tinman 3D library, at least one valid licence
      // key must be given.
      LicenceDomain.Tinman.LicenceKey("Add licence key(s) here, if necessary.");

      // To initialize the Tinman 3D library, this method must be called on the
      // root module(s) that are being used by the application.
      TinmanEngineModule.Instance.PleaseIncludeInBinaryThanks();

      // The Tinman 3D library can now be initialized. Licence checking will be
      // performed here.
      TinmanModule.Initialize();
      try
      {
        IGraphicsContextFactory factory;
        IApplicationWindow window; // [!]
        IApplication application; // [!]
        TinmanError error;

        // Setup the graphics context factory, which will be used to create a
        // rendering context for the client area of the application window.
        factory = new DirectX11ContextFactory();
        factory.ShaderRepository = repository.AppendName("src.fx");

        // Create a new top-level application window.
        window = ApplicationWindow.Create("Hello World!", new Vec2I(1280, 768));

        // Create the application.
        application = new Example_HelloWorld();

        // Create the application loop and run it.
        error = application.Run("Example_HelloWorld.Main", factory, window,
          true);

        if (error != null)
          throw TinmanException.Error("Example_HelloWorld.Main",
            "Hello World has crashed.", error);
      }
      finally
      {
        // Shut down the Tinman 3D library.
        TinmanModule.Shutdown();
      }
    }

    public override void Render()
    {
      Graphics g; // [!]

      // Acquire reference to graphics object and release it when done.
      g = context.Graphics;
      try
      {
        g.Begin();
        try
        {
          // Draw "Hello World!" at the center of the screen.
          g.Fullscreen();
          g.DrawString((PixelFont) g.Cache.GetNull(PixelFont.HandleDefault),
            "Hello World!",
            g.ScreenWidth / 2, g.ScreenHeight / 2,
            Colors.White, Anchor.Center);
        }
        finally
        {
          g.End();
        }
      }
      finally
      {
        g.Dispose();
      }
    }

    #endregion
  }
}