Kryon3D Hardware Engine
Hardware-accelerated 3D graphics pipeline reference for KryonOS, featuring double-buffered rasterization, camera matrices, lighting, mesh batching, and 2D HUD compositing.
Kryon3D Hardware Engine
The Kryon3D Engine is a native C++ 3D transformation and rasterization engine exposed to the JavaScript runtime via the Kryon3D (or System.graphics3d) global object. It delivers high-framerate, flicker-free 3D graphics directly to SPI TFT displays.
Full C++ rasterizer source code is accessible in the KryonOS GitHub Repository.
1. Hardware Architecture & Memory Requirements
Rendering double-buffered 3D scenes requires allocating an off-screen frame buffer:
| Resolution | Color Depth | RAM Footprint | Hardware Recommendation |
|---|---|---|---|
| 240 x 320 (Full Screen) | 16-bit RGB565 | ~153.6 KB | ESP32-S3 DevKitC-1 N16R8 (with Octal/Quad PSRAM) |
| 240 x 210 (Game Viewport) | 16-bit RGB565 | ~100.8 KB | ESP32-S3 or ESP32 with PSRAM |
| 160 x 120 (Compact Viewport) | 16-bit RGB565 | ~38.4 KB | Standard ESP32 (Non-PSRAM SRAM) |
| 240 x 160 (8-bit Low-RAM) | 8-bit Color | ~38.4 KB | Standard ESP32 (Non-PSRAM SRAM) |
PSRAM Recommendation: For high-resolution 16-bit 3D gaming, external PSRAM is recommended. For boards without PSRAM (e.g. esp32doit-devkit-v1), initialize a compact viewport such as Kryon3D.begin(160, 120, 16).
2. Coordinate System & Camera Model
Kryon3D uses a standard Right-Handed 3D World Coordinate System:
- +X: Right
- +Y: Up
- +Z: Towards the viewer (out of screen)
- -Z: Forward (into the screen / away from camera)
Euler rotation angles $(\theta_x, \theta_y, \theta_z)$ are specified in radians.
3. Core Engine Lifecycle
Kryon3D.begin(width, height, colorDepth)
Allocates an off-screen double-buffer in PSRAM or internal SRAM.
- Parameters:
width(Integer): Viewport width in pixels (e.g.240or160).height(Integer): Viewport height in pixels (e.g.210or120).colorDepth(Integer, optional):16for RGB565 or8for 8-bit color. Defaults to16.
- Returns:
Boolean(trueif memory allocation succeeded).
Kryon3D.clear(color)
Clears the 3D frame buffer with the specified 16-bit background color.
- Parameters:
color(Integer, default0x0000)
Kryon3D.directDraw(enabled)
Toggles whether standard 2D System drawing commands write directly to the physical display glass (true) or into the off-screen 3D double buffer (false, default).
- Parameters:
enabled(Boolean)
Kryon3D.render(destX, destY)
Flushes the completed off-screen framebuffer directly to the TFT glass via high-speed SPI DMA in a single burst. Guarantees zero visual tearing.
- Parameters:
destX(Integer, optional, default0)destY(Integer, optional, default0)
Kryon3D.end()
Frees the allocated 3D frame buffer memory back to the heap.
- Parameters: None
4. Camera, Lighting & Fog
Kryon3D.setCamera(posX, posY, posZ, targetX, targetY, targetZ, fov)
Configures the 3D camera position, look-at target, and vertical field of view.
- Parameters:
posX, posY, posZ(Float): Camera position in 3D world space.targetX, targetY, targetZ(Float): Look-at target coordinates.fov(Float, optional, default60.0): Vertical Field of View in degrees.
Kryon3D.setLight(dirX, dirY, dirZ, ambient, diffuse)
Configures the directional lighting source and intensity coefficients.
- Parameters:
dirX, dirY, dirZ(Float): Normalized direction vector pointing to the light source.ambient(Float, optional, default0.3): Ambient coefficient (0.0 to 1.0).diffuse(Float, optional, default0.7): Diffuse coefficient (0.0 to 1.0).
Kryon3D.setFog(enabled, fogColor, nearDist, farDist)
Enables atmospheric distance fog blending.
- Parameters:
enabled(Boolean)fogColor(Integer): 16-bit color to blend into.nearDist, farDist(Float): Distance range where fog transitions from 0% to 100%.
5. 3D Primitives & Batch Meshes
Kryon3D.drawLine(x0, y0, z0, x1, y1, z1, color)
Draws a 3D line connecting two world space coordinates.
Kryon3D.fillTriangle(x0, y0, z0, x1, y1, z1, x2, y2, z2, color, enableLighting)
Renders a solid filled triangle with automatic face normal computation, backface culling, and directional shading.
- Parameters:
x0..z2(Float): Vertices 0, 1, and 2.color(Integer): 16-bit base surface color.enableLighting(Boolean, optional, defaulttrue).
Kryon3D.drawCube(x, y, z, sizeX, sizeY, sizeZ, rotX, rotY, rotZ, color, enableLighting)
Hardware primitive for rendering a 3D box with Euler rotation angles in radians.
Kryon3D.drawBillboard(x, y, z, width, height, color)
Renders a camera-facing 2D billboard sprite scaled automatically with camera distance.
Kryon3D.drawMesh(verticesArray, facesArray, modelMatrix, baseColor, enableLighting)
Transforms, culls, and rasterizes an entire 3D model (e.g. spaceships, characters, terrain) in native C++ at maximum hardware speed.
6. Composite 2D + 3D Rendering (HUDs & UI)
When Kryon3D is active, 2D System primitives automatically render directly into the off-screen buffer before calling Kryon3D.render():
// Initialize 3D viewport
Kryon3D.begin(240, 320, 16);
Kryon3D.setCamera(0, 3, 6, 0, 0, 0, 60);
Kryon3D.setLight(0.5, 1.0, 0.5, 0.3, 0.7);
var angle = 0;
while (true) {
Kryon3D.clear(0x0821); // Dark navy background
// 1. Render 3D Scene
Kryon3D.drawCube(0, 0, 0, 2, 2, 2, angle, angle * 0.7, 0, 0x00FFC2, true);
// 2. Render 2D UI / HUD elements on top (Composite layer)
System.drawRect(10, 10, 220, 30, 0xFFFFFF);
System.drawString("KryonOS 3D Demo", 20, 18, 2);
System.drawString("FPS: 30", 180, 18, 2);
// 3. Flush composite frame to display glass
Kryon3D.render(0, 0);
angle += 0.05;
System.delay(10);
}