Table of Contents

Using RenderingCanvas with DispEngine

The RenderingCanvas is the primary UI component for displaying and interacting with 3D content across different platforms. This section explains how to use it with the DispEngine to create cross-platform applications.

Overview

The RenderingCanvas class is available in frameworks:

  • Hi.WinForm for Windows Forms applications
  • Hi.Wpf for WPF applications

All implementations share a common architecture centered around the DispEngine class, enabling consistent rendering and interaction across platforms.

Core Concept: DispEngine and IDisplayee

At the heart of the rendering system is the relationship between DispEngine and IDisplayee:

  • DispEngine: The rendering engine that manages the OpenGL context and handles user interaction
  • IDisplayee: The interface that defines objects that can be rendered by the DispEngine

This relationship is fundamental - the primary purpose of DispEngine is to render IDisplayee objects.

graph TD
    A[RenderingCanvas UI Component] --> B[DispEngine]
    B --> C[Rendering Pipeline]
    B --> D[Input Handling]
    B --> E[View Manipulation]
    F[IDisplayee Objects] -->|Rendered by| B

Working with IDisplayee

Objects implementing IDisplayee define what gets rendered. Typically, you'll use Drawing objects or compose multiple IDisplayee objects together:

// Create a composite displayee
public class MyCompositeDisplayee : IDisplayee
{
    private List<IDisplayee> _displayees = new List<IDisplayee>();
    
    public MyCompositeDisplayee()
    {
        // Add various displayees
        _displayees.Add(new AxesDisplayee());
        _displayees.Add(new ModelDisplayee());
    }
    
    public void Display(Bind bind)
    {
        // Render all contained displayees
        foreach (var displayee in _displayees)
        {
            displayee.Display(bind);
        }
    }
    
    public void ExpandToBox3d(Box3d box)
    {
        // Update bounding box based on all displayees
        foreach (var displayee in _displayees)
        {
            displayee.ExpandToBox3d(box);
        }
    }
}

Multiple displayees can be combined using DispList:

// Combine multiple displayees
var displayList = new DispList();
displayList.Add(myModel);
displayList.Add(myAnnotations);
displayList.Add(myCoordinateSystem);

// Pass to DispEngine
engine.Displayee = displayList;

For more detailed information on creating displayees with Drawing, see the Drawing section.

Basic Usage

WinForm Implementation

// Create a new instance with displayee objects
using Hi.WinForm.Disp;

// Create displayee object
var displayee = new MyCompositeDisplayee();

// Initialize canvas with the displayee
var canvas = new RenderingCanvas(displayee);

// Access the DispEngine for direct manipulation
DispEngine engine = canvas.DispEngine;

// Add to a form
myForm.Controls.Add(canvas);

WPF Implementation

// Create a new instance
using Hi.Wpf.Disp;

// Create displayee object
var displayee = new MyCompositeDisplayee();

// Initialize the canvas
var canvas = new RenderingCanvas();

// Set displayee objects through the DispEngine
canvas.DispEngine.Displayee = displayee;

// Add to a container
myGrid.Children.Add(canvas);

Switching Displayees at Runtime

You can dynamically change what's being displayed:

// Switch to a different displayee
renderingCanvas.DispEngine.Displayee = alternativeDisplayee;

// Or update a DispList
var displayList = new DispList();
if (showModel) displayList.Add(modelDisplayee);
if (showGrid) displayList.Add(gridDisplayee);
renderingCanvas.DispEngine.Displayee = displayList;

Key Features of DispEngine

The DispEngine provides cross-platform support for:

  1. Rendering Pipeline Management

    • Handles buffer swapping and image generation
    • Manages GPU resources efficiently

  2. Input Handling

    • Mouse/pointer events (move, click, drag)
    • Keyboard navigation
    • Touch gestures (pinch, rotate, pan)

  3. View Manipulation

    • Camera positioning and orientation
    • Standard views (front, top, isometric, etc.)
    • Zoom, pan, and rotate operations

  4. DisplayeeObjects Management

    • Renders IDisplayee implementations
    • Manages visibility and drawing state

Touch and Gesture Support

The DispEngine centralizes touch handling across all platforms with a unified API that supports:

  • Single-finger pan
  • Two-finger rotate and scale
  • Multi-finger specialized operations

The touch API is designed to be simple for UI implementations to use. Platform-specific UI components only need to capture touch events and forward them to the DispEngine.

Basic Touch API Example

// When a touch point is detected
DispEngine.TouchDown(touchId, x, y);

// When a touch point moves
DispEngine.TouchMove(touchId, x, y);

// When a touch point is released
DispEngine.TouchUp(touchId);

Common Operations

// Accessing DispEngine (works on all platforms)
var engine = renderingCanvas.DispEngine;

// Set to standard views
engine.SetViewToHomeView();
engine.SetViewToFrontView();

// Manual camera manipulation
engine.Translate(dx, dy);
engine.Rotate(deltaX, deltaY);

// Resize handling
engine.Resize(width, height);

Implementation Details

For detailed implementation information, including:

  • Full source code examples
  • Implementation details for each platform
  • Advanced touch handling
  • Custom implementation guidance

See the Building Your Own RenderingCanvas guide.

See Also