TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual
Base interface for general-purpose application widgets.
Usually, an IApplication hosts one or more IWidget objects. Application input events are forwarded to widgets unmodified, i.e. the widget is responsible for translating them to its Bounds as necessary (e.g. using a BoundedInput object). Widgets are not required to limit their rendering to their bounds.
See also:
InitializeReturns the actual pixel bounds of this widget.
property
|
ActualBounds
{
get
}
|
||
type
|
Box2I
|
||
value
|
The actual pixel bounds or Empty. | ||
The pixel bounds of this widget.
property
|
Bounds
{
get
set
}
|
||
type
|
IWidgetBounds
|
||
value
|
|
The pixel bounds. | |
Remarks:
Defaults to FullScreen.
A machine-readable unique identifier for the user help of this component.
property
|
HelpId
{
get
}
|
||
type
|
string
|
||
value
|
The
help
ID
or
null
if
none. |
||
inherited
|
IHelpProvider.HelpId
|
||
Will this object be disposed upon the next call to Dispose?
[ThreadSafe]
|
||||
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
|
IDisposable.IsSoleOwnership
|
|||
Returns the lifecycle state of this object.
property
|
LifecycleState
{
get
}
|
||
type
|
LifecycleState
|
||
value
|
The lifecycle state. | ||
inherited
|
ILifecycleState.LifecycleState
|
||
The mouse cursor to show for this widget.
property
|
MouseCursor
{
get
}
|
||
type
|
MouseCursor
|
||
value
|
The mouse cursor | ||
Returns the screen region that is not occluded by any opaque user-interface components.
property
|
NonUserInterfaceBounds
{
get
}
|
||
type
|
Box2I
|
||
value
|
The non-UI pixel bounds. | ||
inherited
|
INonUserInterfaceBounds.NonUserInterfaceBounds
|
||
Remarks:
If there is not user-interface, the screen region is returned.
Path to a directory that this widget can use to store own data and settings.
property
|
SettingsPath
{
get
set
}
|
||
type
|
Path
|
||
value
|
Canonical
path
to
the
settings
directory
or
null. |
||
Remarks:
The settings path may only be set before Initialize is called on the widget. Afterwards, the settings path cannot be changed.
See also:
SettingsLoadTryShould the mouse be captured, because this input consumer only processes relative input?
property
|
ShouldCaptureMouse
{
get
}
|
||
type
|
bool
|
||
value
|
true
if
the
mouse
should
be
captured,
false
if
not. |
||
inherited
|
IInputConsumerEx.ShouldCaptureMouse
|
||
See also:
IApplicationWindow.MouseCapturedRuns this IWidget in a separate window.
[OwnerThis]
|
||||
method
|
Run
(string source,
IGraphicsContextFactory context,
[Owner]
IApplicationWindow window,
int32 frameRateLimit = 100,
bool sleepOnIdle = true)
|
|||
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. | ||
frameRateLimit
|
Frame
rate
limit
(see
FrameRateLimit).
Defaults
to
100.
|
|||
sleepOnIdle
|
Honor
Idle
by
sleeping
for
a
short
time?
Defaults
to
true.
|
|||
returns
|
The
error
in
case
of
a
crash,
null
if
the
application
has
ended
normally.
|
|||
Loads the settings of this widget.
method
|
SettingsLoad
(string name = null)
|
||
type
|
Path
|
||
params
|
name
|
Name
of
the
JSON
configuration
file.
If
null
or
empty,
'Settings.json'
will
be
used.
Defaults
to
null.
|
|
returns
|
Canonical
path
of
the
settings
file
that
has
been
loaded
or
null
if
there
were
no
previously
saved
settings
or
if
the
widget
does
not
have
a
settings
directory.
|
||
Exceptions:
Saves the settings of this widget.
method
|
SettingsSave
(string name = null)
|
||
type
|
Path
|
||
params
|
name
|
Name
of
the
JSON
configuration
file.
If
null
or
empty,
'Settings.json'
will
be
used.
Defaults
to
null.
|
|
returns
|
Canonical
path
of
the
settings
file
that
has
been
loaded
or
null
if
the
widget
does
not
have
a
settings
directory.
|
||
Exceptions:
Wraps this IWidget in an IApplication object.
[OwnerReturn, OwnerThis]
|
||||
method
|
ToApplication
(int32 frameRateLimit = 100)
|
|||
type
|
WidgetApplication
|
|||
params
|
frameRateLimit
|
Frame
rate
limit
(see
FrameRateLimit).
Defaults
to
100.
|
||
returns
|
|
The application object. | ||
Acquires a strong reference to this disposable object.
[OwnerReturn, Pure]
|
||||
method
|
AcquireBase
()
|
|||
type
|
IDisposable
|
|||
returns
|
The
strong
reference
to
this
disposable
object
or
null
iff
this
object
is
no
longer
valid.
|
|||
inherited
|
IDisposable.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.
Acquires a strong reference to this disposable object.
[OwnerReturn, Pure]
|
||||
method
|
AcquireThrow
()
|
|||
type
|
IDisposable
|
|||
returns
|
|
The strong reference to this disposable object. | ||
inherited
|
IDisposable.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:
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.
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.
Implementing methods must not throw any exceptions.
Attaches this component to the given Graphics context.
method
|
GraphicsAttach
(Graphics graphics)
|
||
params
|
graphics
|
[not-null]
|
The graphics context. |
inherited
|
IGraphicsComponent.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:
Detaches this user interface component from its Graphics context.
method
|
GraphicsDetach
()
|
||
inherited
|
IGraphicsComponent.GraphicsDetach
|
||
Remarks:
All graphics-related resources should be disposed here.
The screen size has changed.
method
|
GraphicsResize
(Vec2I screenSize)
|
||
params
|
screenSize
|
The new screen size, in pixels. | |
inherited
|
IGraphicsComponent.GraphicsResize
|
||
Initializes the object, if necessary.
[ThrowAny]
|
||||
method
|
Initialize
()
|
|||
type
|
bool
|
|||
returns
|
true
if
the
object
has
been
initialized,
false
if
the
object
has
already
been
initialized
before.
|
|||
Attaches this input consumer to the given input state object.
method
|
InputAttach
(IInputState input)
|
||
params
|
input
|
[not-null]
|
The input state object. |
inherited
|
IInputConsumerEx.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.
Detached this input consumer from its input state object.
method
|
InputDetach
()
|
||
inherited
|
IInputConsumerEx.InputDetach
|
||
Restores the object state from the given JSON value.
method
|
JsonDeserialize
(JsonValue value)
|
||
params
|
value
|
[not-null]
|
The input JSON value. |
inherited
|
IJsonizable.JsonDeserialize
|
||
Remarks:
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.
method
|
JsonSerialize
(JsonValue value)
|
||
params
|
value
|
[not-null]
|
The output JSON value. |
inherited
|
IJsonizable.JsonSerialize
|
||
Attaches this object to the given profiler.
method
|
ProfilerAttach
(IProfiler profiler)
|
||
params
|
profiler
|
[not-null]
|
The profiler to attach to. |
inherited
|
IProfilerConsumer.ProfilerAttach
|
||
Detaches this object from its IProfiler object.
method
|
ProfilerDetach
()
|
||
inherited
|
IProfilerConsumer.ProfilerDetach
|
||
Performs rendering of the next frame.
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.
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.GraphicsContextAttachPerforms 2D rendering.
method
|
Render2D
(Graphics g)
|
||
params
|
g
|
[not-null]
|
The graphics object to use. |
inherited
|
IRenderable2D.Render2D
|
||
Remarks:
When this method is called, the given Graphics object has already been initialized for 2D rendering:
(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.
Prepares rendering of the next frame.
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.
It is expected that the GPU is busy processing the render commands of the last frame, while this method prepares the next one.
Provides the enclosing IApplicationRunner.
method
|
RunnerAttach
(IApplicationRunner runner)
|
||
params
|
runner
|
[not-null]
|
The application runner. |
inherited
|
IApplicationRunnerConsumer.RunnerAttach
|
||
Remarks:
Calling of this method is optional. Implementations of IApplication should not depend on the availability of an IApplicationRunner context object.
Clears the reference to the enclosing IApplicationRunner.
method
|
RunnerDetach
()
|
||
inherited
|
IApplicationRunnerConsumer.RunnerDetach
|
||
Takes a screenshot the next time this widget is rendered.
method
|
Screenshot
(WidgetScreenshotDelegate result)
|
||
params
|
result
|
[not-null]
|
The screenshot pixels will be passed to this delegate. |
Tries to load the settings of this widget, ignoring errors.
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. |
||
See also:
SettingsPathTries to save the settings of this widget, ignoring errors.
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. |
||
See also:
SettingsPathReturns the configuration value that describes this object.
method
|
ToConfig
()
|
||
type
|
ConfigValue
|
||
returns
|
|
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.
Exceptions:
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
|
||
Updates GUI components, according to current values in the data model.
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
|
IUpdateableGui.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.
Attaches this object to the given WidgetGui instance.
method
|
WidgetGuiAttach
(IWidgetGui widgetGui)
|
||
params
|
widgetGui
|
[not-null]
|
The WidgetGui instance. |
inherited
|
IWidgetGuiConsumer.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.
Detaches this object from its WidgetGui instance.
method
|
WidgetGuiDetach
()
|
||
inherited
|
IWidgetGuiConsumer.WidgetGuiDetach
|
||
Remarks:
Implementing classes must remove all panels via PanelRemove that they have added to the widget GUI.
info@tinman3d.com
| Copyright © 2012 - 2022 Matthias Englert, Fulda (Germany)