DotNetElements.DebugDraw 0.2.0

DotNetElements.DebugDraw

A high-performance debug rendering library for .NET, providing an immediate-mode API for drawing debug primitives in OpenGL based 3D applications.

Features

• Immediate-mode debug drawing API
• Modern OpenGL GPU-driven instanced rendering with minimal CPU overhead
• No runtime allocations during rendering
• Support for common 3D debug primitives: boxes, spheres, lines, cylinders, cones, capsules, arrows, and grids (wireframe and solid)
• Custom mesh registration support
• Backend implementations for OpenTK and Silk.NET (easy to extend to other OpenGL bindings)

Requirements

• .NET 9.0 or later
• OpenTK 4.9.4+ or Silk.NET 2.22.0+ (depending on chosen backend)
• OpenGL 4.6 compatible GPU

Installation

Choose the backend that matches your application:

OpenTK Backend

dotnet package add DotNetElements.DebugRenderer.OpenTk

Silk.NET Backend

dotnet package add DotNetElements.DebugRenderer.Silk.Net

Quick Start

OpenTK Example

using System.Numerics;
using DotNetElements.DebugRenderer.Core;
using DotNetElements.DebugRenderer.Core.Primitives;
using DotNetElements.DebugRenderer.OpenTk;

// Initialize the renderer (make sure you have a valid OpenGL context initialized first)
DebugDrawRenderer<OpenTkContext> debugDrawRenderer = new(new OpenTkContext());

// In your render loop
void OnRender()
{
    debugDrawRenderer.BeginRender(viewProjectionMatrix);

    // Draw primitives
    DebugDraw.Origin(Vector3.Zero, 0.5f);

    DebugDraw.Box(new Vector3(2, 0, 2), Quaternion.Identity, 1f, 1f, 1f, DebugColor.Green);

    DebugDraw.Line(Vector3.Zero, Vector3.UnitX, DebugColor.Red);

    DebugDraw.Sphere(new Vector3(-1, 1, 3), 0.5f, DebugColor.Cyan);

    debugDrawRenderer.EndRender();
}

// Cleanup
debugDrawRenderer.Dispose();

Silk.NET Example

using System.Numerics;
using DotNetElements.DebugRenderer.Core;
using DotNetElements.DebugRenderer.Core.Primitives;
using DotNetElements.DebugRenderer.Silk.Net;

// Initialize the renderer (glApi is your Silk.NET GL instance >>> needs to be initialized first)
DebugDrawRenderer<SilkNetContext> debugDrawRenderer = new(new SilkNetContext(glApi));

// In your render loop
void OnRender()
{
    debugDrawRenderer.BeginRender(viewProjectionMatrix);

    // Draw primitives
    DebugDraw.Origin(Vector3.Zero, 0.5f);

    DebugDraw.Box(new Vector3(2, 0, 2), Quaternion.Identity, 1f, 1f, 1f, DebugColor.Green);

    DebugDraw.Line(Vector3.Zero, Vector3.UnitX, DebugColor.Red);

    DebugDraw.Sphere(new Vector3(-1, 1, 3), 0.5f, DebugColor.Cyan);

    debugDrawRenderer.EndRender();
}

// Cleanup
debugDrawRenderer.Dispose();

Available Primitives

• Box - Solid or wireframe boxes with rotation
• AxisAlignedBox - Axis-aligned bounding boxes
• Sphere - Solid or wireframe spheres
• Line - Single line between two points
• Cylinder - Cylinders with customizable orientation
• Cone - Cones pointing in any direction
• Capsule - Capsules (by default non accurate end-caps, use custom mesh registration for best results)
• Arrow - Directional arrows with customizable scale
• Grid - Grid meshes (need to be registered first)
• Origin - Common coordinate system axes indicator

Custom Meshes

To render custom meshes, you first need to register them with the DebugDraw.RegisterCustomMesh method (this can be only done during initialization). Once registered, you can draw them using the DebugDraw.CustomMesh method.

void OnLoad()
{
    DebugDrawRenderer<OpenTkContext> renderer = new(new OpenTkContext(), OnRegisterCustomMeshes);
}

void OnRegisterCustomMeshes()
{
    // Register a grid mesh
    DebugDraw.RegisterGridMesh(meshId: 1, width: 10f, height: 10f, spacing: 1f);

	// Register other custom mesh

	Vector3[] vertices = ...; // Your vertex data
	uint[] indices = ...; // Your index data

	DebugDraw.RegisterCustomMesh(meshId: 2, Topology.TriangleList, vertices, indices)
}

void OnRender()
{
	// Draw the custom mesh
	DebugDraw.Grid(meshId: 1, center: Vector3.Zero, GridPlane.XZ, DebugColor.White);

	Matrix4x4 model = Matrix4x4.Identity;
	DebugDraw.CustomMesh(meshId: 2, model, DebugColor.Yellow);
}

Examples

Complete examples are available in the examples folder:

• DotNetElements.DebugRenderer.Examples.OpenTk - Full OpenTK integration with camera controls
• DotNetElements.DebugRenderer.Examples.SilkNet - Full Silk.NET integration with camera controls

Compatibility

Tested on the following GPU drivers

• Intel(R) Iris(R) Xe Graphics OpenGL 4.6.0 - Build 32.0.101.6556
• NVIDEA GeForce RTX 3060 OpenGL 4.6.0 - Build 560.94
• AMD Radeon (TM) Graphics OpenGL 4.6.0 - Build 23.19.21.11.250530

Contributing

Contributions are welcome! Please open issues to report bugs or suggest features. Pull requests are welcome, make sure to let me know if you plan to work on something specific.

License

This library is released under the MIT License. See the LICENSE file for more details.