Table of Contents

Class DispEngine

Namespace
Hi.Disp
Assembly
HiDisp.dll

HiAPI display engine.

public class DispEngine : IDisposable, IGetDispEngine
Inheritance
DispEngine
Implements
Inherited Members
Extension Methods

Remarks

The DispEngine is the core rendering and interaction engine for HiAPI applications.

The DispEngine provides a unified API for handling rendering, user interaction, and touch gestures across different UI frameworks.

Constructors

DispEngine(IDisplayee)

Ctor. The SetViewToHomeView() is called in this function.

public DispEngine(IDisplayee displayee)

Parameters

displayee IDisplayee

The displayee to render.

DispEngine(params IDisplayee[])

Ctor.

public DispEngine(params IDisplayee[] displayees)

Parameters

displayees IDisplayee[]

displayees to render.

Fields

CoreDll

Core dll path.

public const string CoreDll = "core.dll"

Field Value

string

defaultFontFile

Sentinel selecting the embedded default font (Noto Sans CJK TC, SIL Open Font License 1.1). Passing this value (or null) to Init(string) loads the embedded font from memory without writing any file to disk. This is not a path; no file of this name is looked up or created.

public const string defaultFontFile = "(embedded)"

Field Value

string

Properties

BackgroundColor

Background color

public vec3d_t BackgroundColor { get; set; }

Property Value

vec3d_t

BackgroundOpacity

Background opacity. Range is from 0 to 1.

public double BackgroundOpacity { get; set; }

Property Value

double

ContextProjDepth

Gets the projection depth of the current context.

public static double ContextProjDepth { get; }

Property Value

double

CursorOffsetX

Internal Use.

public int CursorOffsetX { get; }

Property Value

int

CursorOffsetY

Internal Use.

public int CursorOffsetY { get; }

Property Value

int

CursorX

Internal Use.

public int CursorX { get; set; }

Property Value

int

CursorY

Internal Use.

public int CursorY { get; set; }

Property Value

int

Displayee

Displayee to be rendered in the rendering loop. The SetViewToHomeView() is called in this function.

public IDisplayee Displayee { get; set; }

Property Value

IDisplayee

Get or Set to Enable Suppress Default Logo.

public static bool EnableSuppressDefaultLogo { get; set; }

Property Value

bool

Exceptions

InvalidOperationException

Thrown when SuppressDefaultLogo license is not logged in.

FontFile

Font file. Null while the embedded default font (loaded from memory) is in use; setting null goes back to the embedded font, as Init(string) does.

public static string FontFile { get; set; }

Property Value

string

GlRenderer

The OpenGL renderer string (GL_RENDERER) of the context this process got, for example GDI Generic for Microsoft software OpenGL or the name of the graphics card.

public static string GlRenderer { get; }

Property Value

string

Remarks

Null when unknown, for the same reasons as GlVendor: before Init(string), when no OpenGL could be loaded, when the driver answered nothing for this query, or with a core.dll older than the query.

GlVendor

The OpenGL vendor string (GL_VENDOR) of the context this process got, for example Microsoft Corporation for Microsoft software OpenGL.

public static string GlVendor { get; }

Property Value

string

Remarks

Captured by core.dll as soon as OpenGL has loaded and before the 3.3 version check, so it is known also when IsGlAvailable is false because the context is too old; that is the case it exists for, telling the user which OpenGL the 3D view was refused on. Null when unknown: before Init(string) has run, when no OpenGL could be loaded at all, when the driver answered nothing for this query (so this one can be null while GlVersion is known), and when the core.dll in use is older than the query (the core.dll every machine runs is replaced only by a deploy, so this assembly meets an older one for a while).

GlVersion

The OpenGL version string (GL_VERSION) of the context this process got, for example 1.1.0 for Microsoft software OpenGL. The renderer needs 3.3 or newer.

public static string GlVersion { get; }

Property Value

string

Remarks

Null when unknown: before Init(string), when no OpenGL could be loaded, or with a core.dll older than the query. Unlike the other two strings it is never missing once OpenGL has loaded, because the OpenGL loader refuses a context that does not answer GL_VERSION; so a known version while IsGlAvailable is false means OpenGL loaded and was refused as older than 3.3.

IdleBackoffHeartbeat

Idle backoff heartbeat. While the rendered image stays identical, no input arrives and progressive refinement has converged, the engine re-renders only once per this interval instead of every RefreshingPeriod. Zero (the default) disables the backoff. Any input, scene invalidation or an explicit ClearCache() restores the full refresh rate immediately.

public TimeSpan IdleBackoffHeartbeat { set; }

Property Value

TimeSpan

IsDisposed

Gets a value indicating whether this engine has been disposed. All native-backed members become no-ops afterwards (value getters return neutral defaults).

public bool IsDisposed { get; }

Property Value

bool

IsGlAvailable

Whether this process has a usable OpenGL context, i.e. whether 3D rendering is available at all.

public static bool IsGlAvailable { get; }

Property Value

bool

Remarks

False when this process has no usable GL: either no OpenGL could be loaded at all, or the one the process got is older than the OpenGL 3.3 the renderer needs. On Windows the usual case is Microsoft software OpenGL (renderer “GDI Generic”, version 1.1), which a process can be handed when it is started inside a Remote Desktop session (for example after the session's display driver has crashed or the session was disconnected, or on a multi-user Windows Server), runs as a Windows service, or finds no graphics vendor driver. It is a property of how the process was started as much as of the computer: the same computer can give a process started on its own desktop the graphics card's OpenGL. On Linux it is a driver whose kernel module and userspace disagree, a container started without /dev/dri, a VM with no 3D pass-through. GlRenderer and GlVersion name the OpenGL the process got, when one was loaded. The process still runs: NC play, physics, training and every non-rendering API are unaffected, because none of them touch the display engine. What is not available is the engine itself, so callers must not construct or ask for a DispEngine while this is false rather than guarding individual draw calls. Meaningful only after Init(string) has run; it is false before that for the same reason it is false on a broken host, so read it only from code that runs after application start-up.

IsOnDispThread

Gets a value indicating whether the current thread is the display thread.

public static bool IsOnDispThread { get; }

Property Value

bool

IsVisible

The anime stop running if the value is false; otherwise, the anime starts or keeps running.

public bool IsVisible { get; set; }

Property Value

bool

Model 

public mat4d_t Model { get; set; }

Property Value

mat4d_t

Model matrix in MVP convention. This Model matrix is the first matrix in Hi.Disp.Bind.modelMatStack.

PixelProj 

public mat4d_t PixelProj { get; set; }

Property Value

mat4d_t

Pixel part of Projection matrix in MVP convention. Projection matrix = ScaleProj * PixelProj;

PreCursorX

Internal Use.

public int PreCursorX { get; set; }

Property Value

int

PreCursorY

Internal Use.

public int PreCursorY { get; set; }

Property Value

int

PrincipleView 

public mat4d_t PrincipleView { get; set; }

Property Value

mat4d_t

view = PrincipleView * SketchView. Where view matrix is in MVP convention.

Remarks

The default value is new mat4d_t(new vec3d_t(1, 0, 0), -Math.PI / 2). This make the 2D plane from xy plane to xz plane. The xz plane is much suit for 3D engineering display.

RefreshingPeriod

Image refreshing period.

public TimeSpan RefreshingPeriod { get; set; }

Property Value

TimeSpan

ScaleProj 

public mat4d_t ScaleProj { get; set; }

Property Value

mat4d_t

Scale part of Projection matrix in MVP convention. Projection matrix = ScaleProj * PixelProj;

SketchView

view = PrincipleView * SketchView. Where view matrix is in MVP convention.

public mat4d_t SketchView { get; set; }

Property Value

mat4d_t

SuppressHoverPickWhileDragging

When true, mouse moves with a button held do not trigger the hover pick pass (which re-renders the whole scene in picking mode). Enable this for hosts whose drags are pure camera transforms; keep the default (false) when API users drag a picked object via Pickable events.

public bool SuppressHoverPickWhileDragging { set; }

Property Value

bool

Methods

ClearCache()

Clears the display engine cache.

public void ClearCache()

DeleteDispContext()

Deletes the current display context.

public static void DeleteDispContext()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool) 

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

EnqueueDispose(IDisposable)

Enqueues a disposable object to be disposed on the display thread.

public static Task EnqueueDispose(IDisposable disposable)

Parameters

disposable IDisposable

The disposable object to be disposed

Returns

Task

A task representing the disposal operation

EnqueueTask(Task)

Enqueues a task to be executed on the display thread.

public static Task EnqueueTask(Task task)

Parameters

task Task

The task to be executed

Returns

Task

The enqueued task

EnqueueTask<T>(Task<T>)

Enqueues a task to be executed on the display thread.

public static Task<T> EnqueueTask<T>(Task<T> task)

Parameters

task Task<T>

The task to be executed

Returns

Task<T>

The enqueued task

Type Parameters

T

The type of the task result

~DispEngine() 

protected ~DispEngine()

FinishDisp()

Ends the rendering core for the rest of the process: disposes every live engine, raises FinishingDisp, stops the display thread. Call it once, after everything that renders has been stopped.

public static void FinishDisp()

GetDispEngine()

Get DispEngine.

public DispEngine GetDispEngine()

Returns

DispEngine

DispEngine

Init(string)

Initializes the display engine system.

public static void Init(string fontFile = null)

Parameters

fontFile string

The font file to use. If null, the embedded default font is loaded from memory and no file is written to disk.

IsKeyPressed(string)

Checks if a specific keyboard key is currently pressed. Delegates to IsKeyPressed(string).

public bool IsKeyPressed(string key)

Parameters

key string

Key string (W3C KeyboardEvent.key value, e.g. “Alt”, “ArrowLeft”). A null key is never pressed.

Returns

bool

True if the specified key is pressed; otherwise, false.

IsMouseButtonPressed(long)

Checks if a specific mouse button is currently pressed. Delegates to IsMouseButtonPressed(long).

public bool IsMouseButtonPressed(long mouseButton)

Parameters

mouseButton long

The mouse button to check, typically a value from the HiMouseButton enumeration.

Returns

bool

True if the specified mouse button is pressed; otherwise, false.

KeyDown(string)

Key down. This function is typically called in the GUI implementation for keyboard interaction.

public void KeyDown(string key)

Parameters

key string

Key string (W3C KeyboardEvent.key value, e.g. “Alt”, “ArrowLeft”, “a”). A null key is ignored.

KeyDownTransform(string, key_table__transform_view_by_key_pressing_t)

Transform SketchView by key. Home, F1, F2, F3, F4 call SetViewToHomeView(), SetViewToFrontView(), SetViewToRightView(), SetViewToTopView(), SetViewToIsometricView() respectively. PageDown and PageUp scale the SketchView. Left, Right, Down, Up translate the SketchView; Press Shift make these keys to rotate the SketchView.

public void KeyDownTransform(string key, key_table__transform_view_by_key_pressing_t table)

Parameters

key string

The key that was pressed, typically a value from the HiKey enumeration.

table key_table__transform_view_by_key_pressing_t

A table defining which keys trigger different transformation operations.

Remarks

This method is typically called from key down event handlers in the GUI implementation.

KeyUp(string)

Key up. This function is typically called in the GUI implementation for keyboard interaction.

public void KeyUp(string key)

Parameters

key string

Key string (W3C KeyboardEvent.key value). A null key is ignored.

LockGlContext()

Lock a opengl context. The function is only used for native OpenGL rendering. After lock the gl context, It should be unlock by UnlockGlContext(nint).

public static nint LockGlContext()

Returns

nint

Remarks

If any other lock requires LockGlContext, the lock should better set inside LockGlContext. or it is easy to occur race condition. see design pattern of “Solid” class for reference.

MouseButtonDown(long)

Mouse button down. This function is typically called in the GUI implementation for mouse interaction.

public void MouseButtonDown(long button)

Parameters

button long

button

MouseButtonUp(long)

Mouse button up. This function is typically called in the GUI implementation for mouse interaction.

public void MouseButtonUp(long button)

Parameters

button long

button

MouseDragTransform(int, int, mouse_button_table__transform_view_by_mouse_drag_t)

Transform the view by mouse drag. If drag by left mouse button, Translate(double, double) is performed; If drag by right mouse button, Rotate(double, double) is performed.

public void MouseDragTransform(int x, int y, mouse_button_table__transform_view_by_mouse_drag_t mouse_button_table)

Parameters

x int

The current x-coordinate of the mouse cursor.

y int

The current y-coordinate of the mouse cursor.

mouse_button_table mouse_button_table__transform_view_by_mouse_drag_t

A table defining which mouse buttons trigger different transformation operations.

Remarks

The mouse_button_table__transform_view_by_mouse_drag_t structure allows you to configure which mouse buttons perform which transformations:

var buttonTable = new mouse_button_table__transform_view_by_mouse_drag_t
{
    LEFT_BUTTON = (long)HiMouseButton.Left,    // For translation
    RIGHT_BUTTON = (long)HiMouseButton.Right   // For rotation
};

This method is typically called from mouse move event handlers when buttons are pressed.

MouseLeave()

The cursor left the canvas, e.g. onto an element laid over it. The next pick pass sends Hi.Disp.PickEvent Mouse_Exited to the hovered pickable, if any; the cursor position and the drag state are untouched, so a drag that returns to the canvas continues normally.

public void MouseLeave()

MouseMove(int, int)

Mouse move. This function is typically called in the GUI implementation for mouse interaction.

public void MouseMove(int x, int y)

Parameters

x int

cursor X position

y int

cursor Y position

MouseWheel(int, int)

Mouse wheel move. This function is typically called in the GUI implementation for mouse interaction.

public void MouseWheel(int deltaX, int deltaY)

Parameters

deltaX int

mouse wheel delta X

deltaY int

mouse wheel delta Y. The traditional mouse wheel.

MouseWheelTransform(int, int, double)

Scale SketchView by mouse wheel.

public void MouseWheelTransform(int deltaX, int deltaY, double zooming_ratio = 0.2)

Parameters

deltaX int

mouse wheel delta X

deltaY int

mouse wheel delta Y. The traditional mouse wheel.

zooming_ratio double

The ratio used for zooming. Default is 0.2.

Resize(int, int)

Resize the opengl context.

public void Resize(int w, int h)

Parameters

w int

width of the viewport

h int

height of the viewport

Rotate(double, double)

Rotate the SketchView. Usually used by mouse drag on window. The rotation axis is along (delta_y, 0, delta_x). The rotation rad is 5 * Math.Sqrt(delta_y * delta_y + delta_x * delta_x) / window_height.

public void Rotate(double delta_x, double delta_y)

Parameters

delta_x double

delta x in window coordinate

delta_y double

delta y in window coordinate

RotateAndScaleByTouchPad(vec2d_t, vec2d_t, vec2d_t, vec2d_t)

Rotate and scale the SketchView based on touch pad gestures.

public void RotateAndScaleByTouchPad(vec2d_t prePosA, vec2d_t curPosA, vec2d_t prePosB, vec2d_t curPosB)

Parameters

prePosA vec2d_t

The previous position of the first touch point.

curPosA vec2d_t

The current position of the first touch point.

prePosB vec2d_t

The previous position of the second touch point.

curPosB vec2d_t

The current position of the second touch point.

Remarks

The method detects two types of gestures:

  1. Pinch gesture: When the distance between touch points changes, it triggers zooming via MouseWheelTransform(int, int, double)
  2. Rotation/Pan gesture: When touch points move together, it triggers rotation via Rotate(double, double)

This method is typically used to implement touchpad or multi-touch gestures in custom UI implementations.

RotateWithoutHeightAdjustment(double, double)

Rotate the SketchView. Usually used by keyboard command. The rotation axis is along (delta_y, 0, delta_x). The rotation rad is Math.ToRad(Math.Sqrt(delta_y * delta_y + delta_x * delta_x)).

public void RotateWithoutHeightAdjustment(double delta_x, double delta_y)

Parameters

delta_x double

delta x in window coordinate

delta_y double

delta y in window coordinate

SetViewToFrontView()

Set the SketchView to front view.

public void SetViewToFrontView()

SetViewToHomeView()

Set the SketchView to home view(front view). This is the same as SetViewToFrontView().

public void SetViewToHomeView()

SetViewToIsometricView()

Set the SketchView to isometric view.

public void SetViewToIsometricView()

SetViewToRightView()

Set the SketchView to side view.

public void SetViewToRightView()

SetViewToTopView()

Set the SketchView to top view.

public void SetViewToTopView()

Snapshot(string)

Snapshot to BMP file with current canvas size.

public void Snapshot(string filePath)

Parameters

filePath string

Snapshot(string, int, int)

Snapshot to BMP file.

public void Snapshot(string filePath, int panelWidth, int panelHeight)

Parameters

filePath string
panelWidth int
panelHeight int

Start(int, int)

Start a thread of keeping Swapping buffers of OpenGL context. If the thread has running, this function does nothing.

public void Start(int panelWidth, int panelHeight)

Parameters

panelWidth int

panel width

panelHeight int

panel height

Terminate()

Terminate the opengl context swapping buffers thread from Start(int, int). If the thread has not running, this function does nothing.

public void Terminate()

TouchDown(int, int, int)

Tracks a new touch point in the DispEngine's touch gesture system.

public void TouchDown(int touchId, int x, int y)

Parameters

touchId int

A unique identifier for the touch point.

x int

The x-coordinate of the touch point in screen coordinates.

y int

The y-coordinate of the touch point in screen coordinates.

Remarks

When a touch point is added, the method:

  1. Stores the touch point in the internal tracking dictionary
  2. If this is the first touch point, simulates a mouse move and left button press

TouchMove(int, int, int)

Updates the position of an existing touch point.

public void TouchMove(int touchId, int x, int y)

Parameters

touchId int

The unique identifier of the touch point to update.

x int

The new x-coordinate of the touch point in screen coordinates.

y int

The new y-coordinate of the touch point in screen coordinates.

Remarks

The method handles different gestures based on the number of active touch points:

  • Single touch: Performs panning (translation) like mouse dragging
  • Two touches: Performs pinch-to-zoom and rotation gestures

TouchUp(int)

Removes a touch point from tracking when the touch is released.

public void TouchUp(int touchId)

Parameters

touchId int

The unique identifier of the touch point to remove.

Remarks

When a touch point is released, the method:

  1. Removes the touch point from internal tracking dictionaries
  2. If all touch points are released, simulates a mouse button release
  3. If transitioning from multi-touch to single-touch, updates the mouse position to prevent “teleportation”

Translate(double, double)

Translate the SketchView. Usually used by mouse drag on window. The translation is (delta_x * 2.0 / h, 0, -delta_y* 2.0 / h). Where h is window height.

public void Translate(double delta_x, double delta_y)

Parameters

delta_x double

delta x in window coordinate

delta_y double

delta y in window coordinate

TurnBackView()

Rotate view 180 degrees around Z axis to switch to back view.

public void TurnBackView()

UnlockGlContext(nint)

Unlock opengl context. The function is only used for native OpenGL rendering. The function unlock the opengl context for LockGlContext().

public static void UnlockGlContext(nint disp_torch_p)

Parameters

disp_torch_p nint

Events

FinishingDisp

Event at the begining of FinishDisp()

public static event Action FinishingDisp

Event Type

Action

FrameReady

Triggered on the render thread after every frame whose pixels or pin table changed. Handlers must not touch the engine's GL state and must not block.

public event DispEngine.FrameReadyDelegate FrameReady

Event Type

DispEngine.FrameReadyDelegate