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.WpfPlus 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 purpose of DispEngine is to render IDisplayee objects.

graph TD
    A[IDisplayee Objects] -->|Rendered by| B
    B[DispEngine] <--> C[RenderingCanvas UI Component]

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);
        }
    }
}

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

Basic Usage

Apply Hi.WinForm

// 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);

Apply Hi.WPF

// Create a new instance
using Hi.WpfPlus.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:

  • Handles buffer swapping and image generation
  • Mouse/pointer events
  • Keyboard navigation
  • Touch gestures
  • Zoom, pan, and rotate operations
  • Resize and Visibility changed.
  • Camera positioning and orientation
  • Standard views (front, top, isometric, etc.)
  • Renders IDisplayee implementations

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.

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