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

The default font file path used by the display engine.

public const string defaultFontFile = "Font/WCL06.ttf"

Field Value

string

Properties

BackgroundColor

Background color

public Vec3d BackgroundColor { get; set; }

Property Value

Vec3d

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. The set take no effect if the license SuppressDefaultLogo is not login.

public static bool EnableSuppressDefaultLogo { get; set; }

Property Value

bool

FontFile

Font file.

public static string FontFile { get; set; }

Property Value

string

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 Model { get; set; }

Property Value

Mat4d

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

PixelProj 

public Mat4d PixelProj { get; set; }

Property Value

Mat4d

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 PrincipleView { get; set; }

Property Value

Mat4d

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

Remarks

The default value is new Mat4d(new Vec3d(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 ScaleProj { get; set; }

Property Value

Mat4d

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 SketchView { get; set; }

Property Value

Mat4d

Methods

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()

Elegantly end the rendering core. Probably not essential.

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 default font file will be used.

IsMouseButtonPressed(long)

Checks if a specific mouse button is currently pressed.

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.

Remarks

This method is useful for implementing conditional UI behaviors based on mouse button state:

// Check if left mouse button is pressed
if (dispEngine.IsMouseButtonPressed((long)HiMouseButton.Left))
{
    // Perform special action while left button is held down
}

KeyDown(long)

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

public void KeyDown(long key)

Parameters

key long

key

KeyDownTransform(long, key_table__transform_view_by_key_pressing_t)

Transform SketchView by key. Home, F1, F2, F3, F4 call SetViewToHomeView(), SetViewToFrontView(), SetViewToSideView(), 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(long key, key_table__transform_view_by_key_pressing_t table)

Parameters

key long

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(long)

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

public void KeyUp(long key)

Parameters

key long

key

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.

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, Vec2d, Vec2d, Vec2d)

Rotate and scale the SketchView based on touch pad gestures.

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

Parameters

prePosA Vec2d

The previous position of the first touch point.

curPosA Vec2d

The current position of the first touch point.

prePosB Vec2d

The previous position of the second touch point.

curPosB Vec2d

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()

SetViewToSideView()

Set the SketchView to side view.

public void SetViewToSideView()

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

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

ImageRequestAfterBufferSwapped

Triggered after swap buffer of gl context.

public event DispEngine.ImageRequestedDelegate ImageRequestAfterBufferSwapped

Event Type

DispEngine.ImageRequestedDelegate