Sixth 3D - Realtime 3D engine

The rendering loop is the heart of the engine, continuously generating frames at a target rate (typically 60 FPS). Each frame transforms 3D shapes through a multi-stage pipeline before displaying them on screen.

The render loop runs on a dedicated background daemon thread managed by ViewPanel, which can optionally sleep between frames to maintain a target FPS or run unlimited for benchmarking.

For a detailed walkthrough of each phase with diagrams and code examples, see the dedicated page: Rendering loop.

Sixth 3D uses a left-handed coordinate system with X pointing right and Y pointing down, matching standard 2D screen coordinates. This coordinate system should feel intuitive for people with preexisting 2D graphics background.

Practical Examples

• A point at (0, 0, 0) is at the origin.
• A point at (100, 50, 200) is: 100 units right, 50 units down visually, 200 units away from the camera.
• To place object A "above" object B, give A a smaller Y value than B.

Coordinates in this system are stored using the Point3D class — a mutable container with public x, y, z fields supporting vector operations like distance, rotation, and translation. Vertices (see below) are positioned within this coordinate system.

The sixth-3d-demos project includes an interactive coordinate system reference showing X, Y, Z axes as colored arrows with a grid plane for spatial context.

Every 3D object is built from vertices — corner points that define the shape's geometry. A triangle has 3 vertices, a cube has 8, and complex meshes have thousands. The engine uses two related classes to represent points in 3D space, each serving a different purpose.

An edge is a straight line segment connecting two vertices. Edges form the wireframe skeleton of a 3D model — the structural framework visible when surfaces are not rendered. A triangle has 3 edges, a cube has 12 edges, and complex meshes have thousands.

In Sixth 3D, the Line class implements edges as renderable shapes. Each Line connects two Vertex endpoints and stores two properties: a width in world units (adjusted for perspective during rendering) and a color with alpha transparency. The rendering algorithm switches between two modes based on the projected screen width: thin lines below the threshold are drawn as single pixels with alpha-adjusted coloring, while thicker lines are rendered as filled rectangles with perspective-correct edge fading using four LineInterpolator scanline boundaries.

Wireframe shapes are composite objects built from multiple Line instances. For example, WireframeBox creates 12 Line objects — four edges parallel to each axis — using a LineAppearance factory to ensure consistent styling across all edges. The WireframeCube convenience subclass provides a center-point constructor. See the Shape Gallery demo for a visual comparison of wireframe (edges only) versus solid polygon (surfaces with lighting) rendering modes.

A face is a flat surface enclosed by edges — the visible skin of a 3D object. While faces can theoretically have any number of sides, 3D engines standardize on triangles because three points always define a flat plane. A quad (4 vertices) or pentagon (5 vertices) might be non-planar depending on vertex positions, causing rendering artifacts. Triangles avoid this problem entirely.

A normal is a vector perpendicular to a surface. It tells the renderer which direction a face is pointing. Normals are critical for lighting — the angle between the light direction and the normal determines how bright a surface appears.

Use cases:

Implementation notes:

• Plane.computeNormal(): shared zero-allocation helper for computing normals from three points
• Plane: stores normals in Hesse normal form (normal + distance) for BSP spatial partitioning
• Vertex.normal: optional field for CSG polygon splitting (not used for rendering)

Sixth 3D implements flat shading — one normal per polygon, computed from the first three vertices. Each polygon receives a single color based on its orientation relative to light sources.

To understand lighting and shading, read more about shading & lighting.

A mesh is a collection of vertices, edges, and faces that together define the shape of a 3D object. Even curved surfaces like spheres are approximated by many small triangles — more triangles means a smoother appearance. A cube has 8 vertices forming 12 triangular faces, while a smooth sphere requires hundreds or thousands of triangles depending on the desired quality.

In Sixth 3D, meshes are built through composition rather than monolithic vertex/index buffers. The AbstractCoordinateShape class is the foundation for primitive shapes — each instance stores its own List<Vertex> directly. This includes SolidPolygon (N-vertex convex polygons, not limited to triangles), TexturedTriangle (UV-mapped triangles), and Line (wireframe edges). The AbstractCompositeShape class groups multiple shapes into a single object with its own position, rotation, and transform — useful for complex models that move or rotate together.

Complex meshes are constructed procedurally by adding primitive shapes during initialization. For example, SolidPolygonSphere generates triangles using a latitude-longitude grid: with 16 segments, it creates approximately 900 SolidPolygon triangles by looping through rings and sectors, calling addShape() for each. The generic SolidPolygonMesh accepts any list of triangles, allowing custom geometry from procedural generation or external sources.

During rendering, several automatic optimizations occur. N-vertex polygons (quads, pentagons, etc.) are triangulated using fan triangulation in AbstractCompositeShape.retessellate(), converting an N-vertex polygon into N-2 triangles. Textured polygons undergo level-of-detail tessellation — distant triangles are subdivided into smaller pieces for perspective-correct texture mapping. Composites perform view frustum culling to skip rendering when entirely off-screen. Sub-shapes can be organized into named groups via SubShape wrappers, allowing showGroup() and hideGroup() to toggle visibility of entire sections. Composite shapes also support CSG boolean operations — see the Constructive Solid Geometry documentation for union, subtract, and intersect operations.

The Shape Gallery demo showcases all primitive shapes available in Sixth 3D, rendered in both wireframe mode (edges only via WireframeBox and similar) and solid polygon mode (filled surfaces with dynamic lighting).

Sixth 3D tries to do perspective-correct texture rendering. Read more about perspective-correct texture implementation.

Sixth 3D implements view frustum culling.

To understand frustum culling and object-level visibility optimization, read more about frustum & view frustum culling.

Sixth 3D allows performing boolean operations against geometry shapes. So one can subtract, unionize or intersect shapes.

To understand CSG boolean operations, read more about Constructive Solid Geometry.

The order in which a triangle's vertices are listed determines its winding order. In Sixth 3D, screen coordinates have Y-axis pointing down, which inverts the apparent winding direction compared to standard mathematical convention (Y-up). Counter-clockwise (CCW) in screen space means front-facing. Backface culling skips rendering triangles that face away from the camera — a major performance optimization.

• CCW winding (in screen space) → front face (visible)
• CW winding (in screen space) → back face (culled)
• When viewing a polygon from outside: define vertices in counter-clockwise order as seen from the camera
• Saves ~50% of triangle rendering
• Implementation uses signed area: signedArea < 0 means front-facing (in Y-down screen coordinates, negative signed area corresponds to visually CCW winding)

In Sixth 3D, backface culling is optional and disabled by default. Enable it per-shape:

• SolidPolygon.setBackfaceCulling(true)
• TexturedTriangle.setBackfaceCulling(true)
• AbstractCompositeShape.setBackfaceCulling(true) (applies to all sub-shapes)

See the Winding Order demo for an interactive visualization.

Sixth 3D uses its own Color class instead of java.awt.Color. This custom implementation is designed specifically for the engine's software rasterizer, where avoiding object allocation during rendering is critical for performance. When rendering thousands of polygons per frame, creating new Color instances for each one would generate excessive garbage and trigger frequent garbage collection pauses. Instead, the engine's Color class uses mutable fields that can be reused across frames.

The class stores RGBA components as public integer fields in the range 0–255. This format matches the engine's pixel buffer layout and avoids costly float-to-int conversions during rasterization. The r, g, b, and a fields are accessible directly, allowing lighting calculations and alpha blending to modify colors in-place without allocating new objects. For example, the SolidPolygon class maintains a reusable shadedColor field that gets updated during each frame's lighting calculation instead of creating a new Color instance per polygon.

Color provides several constructors for different input formats. The most common approach is using hex strings via Color.hex(String) or the String constructor, which support formats like "F80" (3-digit RGB), "FF8800" (6-digit RGB), "F808" (4-digit RGBA), and "FF8800CC" (8-digit RGBA). You can also create colors from integer RGBA components (0–255) using new Color(r, g, b, a), from floating-point components (0.0–1.0) via new Color(double r, double g, double b, double a), or from a packed RGB integer like 0xFF8800 using new Color(int rgb). The class also provides predefined constants for common colors: Color.RED, Color.GREEN, Color.BLUE, Color.YELLOW, Color.CYAN, Color.MAGENTA, Color.WHITE, Color.BLACK, and Color.TRANSPARENT.

The set(int r, int g, int b, int a) method modifies a Color in-place and returns this for method chaining, which is essential for performance during rendering. For example, the LightingManager calculates lighting contributions from all light sources and stores the final shaded color directly into a reusable Color instance via set(), avoiding any allocation. The toAwtColor() method converts a Sixth 3D Color to a java.awt.Color when needed for Java2D graphics operations, caching the result to avoid repeated conversion. The toInt() method packs the color into an ARGB integer suitable for the engine's pixel buffer, used during rasterization to write pixels directly.

import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
import static eu.svjatoslav.sixth.e3d.renderer.raster.Color.hex;

// Using predefined color constants
Color red = Color.RED;
Color transparent = Color.TRANSPARENT;

// Create from hex string (recommended for clarity)
Color orange = hex("FF8800");           // RGB, fully opaque
Color semiTransparent = hex("FF880080"); // RGBA, 50% transparent

// Create from integer components (0-255)
Color custom = new Color(255, 128, 64, 200);

// Create from packed RGB integer
Color packed = new Color(0xFF8800);

// Modify existing color in-place (no allocation)
Color reusable = new Color();
reusable.set(100, 200, 50, 255);

// Convert to AWT color for Java2D operations
java.awt.Color awtColor = custom.toAwtColor();

// Use in lighting calculations (LightingManager modifies in-place)
// See the Shading & Lighting documentation for details

The alpha component controls transparency during rendering. A value of 0 makes the color fully transparent, while 255 makes it fully opaque. The rasterizer implements alpha blending during the paint phase: when drawing a semi-transparent pixel, the engine blends the source color with the existing background pixel proportionally based on the alpha value. The TextureBitmap.drawPixel() method handles this blending, multiplying source colors by alpha and background colors by (255 - alpha), then combining them. You can test whether a color is fully transparent using isTransparent(), which returns true when alpha equals zero.

For lighting calculations, the LightSource class uses Color to represent the color and intensity of emitted light. Multiple light sources contribute to the final shaded color of each polygon, as described in the Shading & Lighting documentation. The ambient light provides base illumination that affects all surfaces equally, regardless of orientation. Colors are also used for wireframe rendering via the Line class, where the color field determines the line's appearance.

When enabled, each TexturedTriangle draws yellow outlines around its three edges after rendering its texture content. This overlays the geometric structure of tessellated textured surfaces onto the final image.

The feature exists primarily to visualize adaptive tessellation — the recursive subdivision of large triangles into smaller pieces for perspective-correct texture mapping. When you enable this option on a scene with tessellation active, you can see how the TexturedPolygonTessellator has split each original triangle. Dense yellow lines indicate high tessellation (many small triangles), while sparse lines show low tessellation or triangles that were small enough to render without subdivision.

Use this visualization when investigating:

• Tessellation behavior: verify that near surfaces are subdivided more densely
• Texture distortion: compare the tessellation density against visible warping in the texture

Renders only even-numbered horizontal segments (0, 2, 4, 6) while leaving odd segments (1, 3, 5, 7) black.

The engine divides the screen into 8 horizontal segments for parallel multi-threaded rendering. This toggle helps detect overdraw (threads writing outside their allocated segment).

If you see rendering artifacts in the black segments, it indicates that threads are writing pixels outside their assigned area — a clear sign of a bug.

Draws visible lines between horizontal rendering segments to show where the screen is divided for parallel multi-threaded rendering.

The engine divides the screen into 8 horizontal segments for parallel rendering. This toggle draws boundary lines between segments, making it easy to see exactly where each thread's rendered area begins and ends.

Useful for:

• Verifying correct segment division
• Debugging segment-related rendering issues
• Understanding the parallel rendering architecture visually

Displays the current camera coordinates and orientation in real-time:

The Copy button copies the full camera position string to the clipboard in a format ready to paste into bug reports or configuration files.

Use this for:

• Reporting exact camera positions when filing bugs
• Saving interesting viewpoints for later reference
• Understanding camera movement during navigation
• Sharing specific views with other developers

Example copied format:

500.00, -300.00, -800.00, 0.60, -0.50, -0.00

Shows real-time statistics about composite shape frustum culling efficiency:

What is frustum culling?

Frustum culling is an optimization that skips rendering objects outside the camera's view. Before rendering each composite shape, the engine tests its bounding box against the view frustum. If the bounding box is completely outside the visible area, the entire composite (and all its children) are skipped.

How to interpret the numbers:

• High cull % (60-90%): Excellent — most objects are being correctly culled
• Medium cull % (20-60%): Moderate — some optimization benefit
• Low cull % (0-20%): Limited benefit — either all objects are visible, or scene needs restructuring

Example:

Total: 473  Culled: 425 (89.9%)

This means 473 composite shapes were tested, 425 were outside the view and skipped entirely, and only 48 composites (with all their children) actually needed to be rendered. This is excellent culling efficiency.

The statistics update every 200ms while the panel is open. Note that the root composite is never frustum-tested (it's always rendered), so the "Total" count excludes it.

The scrollable text area shows captured debug output in real-time:

• Green text on black background for readability
• Auto-scrolls to show latest entries
• Updates every 500ms while panel is open
• Captures logs even when panel is closed (replays when reopened)

Use the Clear Logs button to reset the log buffer for fresh diagnostic captures.