g3d

Pure Go 3D rendering library
Scene graph, PBR materials, forward renderer. Zero CGO.
Built on gogpu/wgpu (Vulkan/Metal/DX12/GLES/Software).

---

What is g3d?

g3d is a 3D rendering library — not a game engine. It provides the building blocks (scene graph, cameras, lights, materials, geometry primitives) that game engines, CAD viewers, data visualizers, and AR/VR applications build upon.

Think of it like Three.js for Go: simple API, powerful rendering, zero opinion about your application architecture.

package main

import (
    "log"

    "github.com/gogpu/g3d"
    "github.com/gogpu/gogpu"
)

func main() {
    app := gogpu.NewApp(gogpu.DefaultConfig().
        WithTitle("g3d Hello Cube").
        WithSize(800, 600))

    scene := g3d.NewScene()
    scene.SetBackground(g3d.RGB(0.1, 0.1, 0.15))

    // Ambient light (no spatial properties — attached via UserData on a container node)
    ambient := g3d.NewAmbientLight(g3d.WithLightColor(g3d.White), g3d.WithLightIntensity(0.3))
    ambientNode := g3d.NewNode()
    ambientNode.SetUserData(ambient)
    scene.Add(ambientNode)

    // Directional light (sun-like, from upper-right)
    sun := g3d.NewDirectionalLight(g3d.WithLightColor(g3d.White), g3d.WithLightIntensity(1.0))
    sun.LightNode().SetRotation(g3d.Euler{X: g3d.Radians(-45), Y: g3d.Radians(30)})
    scene.Add(sun.LightNode())

    // Cube mesh with PBR material
    cube := g3d.NewMesh(
        g3d.NewBoxGeometry(1, 1, 1),
        g3d.NewStandardMaterial(
            g3d.WithColor(g3d.RGB(0.4, 0.7, 1.0)),
            g3d.WithRoughness(0.6),
        ),
    )
    scene.Add(cube.MeshNode())

    // Camera
    camera := g3d.NewPerspectiveCamera(75, 800.0/600.0, 0.1, 1000)
    camera.CameraNode().SetPosition(g3d.Vec3{X: 0, Y: 0.5, Z: 3})

    var renderer *g3d.Renderer

    app.OnUpdate(func(dt float64) {
        r := cube.MeshNode().Rotation
        r.Y += float32(dt)
        cube.MeshNode().SetRotation(r)
    })
    app.OnDraw(func(ctx *gogpu.Context) {
        if renderer == nil {
            var err error
            renderer, err = g3d.NewRenderer(app.GPUContextProvider())
            if err != nil {
                log.Fatal(err)
            }
        }
        fbW, fbH := ctx.FramebufferSize()
        renderer.SetSize(uint32(fbW), uint32(fbH))
        if view := ctx.SurfaceView(); view != nil {
            _ = renderer.Render(scene, camera, view)
        }
    })
    app.OnClose(func() {
        if renderer != nil {
            renderer.Release()
        }
    })
    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

Features

Core (v0.1.0)

• Scene graph — hierarchical Node tree with parent-child transform propagation and dirty flags
• Cameras — Perspective and Orthographic with frustum extraction
• Geometries — Box, Sphere, Plane + custom BufferGeometry
• Forward renderer — 4-bucket sorting (background, opaque, transmissive, transparent)
• Frustum culling — automatic AABB visibility testing against camera frustum

Materials (v0.1.0)

• BasicMaterial — unlit, for prototyping and data visualization
• StandardMaterial — PBR metallic-roughness with Blinn-Phong shading

Lighting (v0.1.0)

• AmbientLight — uniform environment lighting
• DirectionalLight — sun-like parallel light

Performance (v0.1.0)

• Zero-alloc render path — no GC pressure during frame rendering
• Pipeline cache — compile shader variants once, reuse forever
• 3-key opaque sort — PipelineKey → MaterialID → Distance (minimizes GPU state changes)
• MappedAtCreation — zero-copy GPU buffer upload (WebGPU compliant)

Planned

• Full PBR — Cook-Torrance BRDF, shadow mapping, normal maps (Phase 2)
• GLTF 2.0 — binary (.glb) and JSON (.gltf) with PBR materials, animations (Phase 3)
• Instance batching — thousands of objects with minimal draw calls (Phase 4)
• Post-processing — bloom, tone mapping, FXAA (Phase 4)

Not a Game Engine

g3d deliberately does not include:

Feature	Why Not	Where to Get It
Entity Component System	Game engine concern	Build on top, or use external ECS
Physics	Simulation concern	Integrate Bullet, ODE, or Pure Go physics
Audio	Unrelated to rendering	Use gogpu/audio or Oto
Networking	Unrelated to rendering	Use net/http, gRPC, WebSocket
Scripting	Engine concern	Use Lua/Wasm/Yaegi on top
Scene editor	Tool concern	Build with gogpu/ui + g3d

This separation means g3d is reusable everywhere — game engines, CAD tools, scientific visualizations, AR/VR, data dashboards.

GPU Backends

g3d renders through gogpu/wgpu, which supports:

Backend	Platforms	Status
Vulkan	Windows, Linux	Stable
Metal	macOS	Stable
DirectX 12	Windows	Stable
OpenGL ES	Windows, Linux	Stable
Software	All	Fallback (CI/testing)

All backends are Pure Go — zero CGO, single binary deployment.

# Select backend via environment variable
GOGPU_GRAPHICS_API=vulkan   go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=dx12     go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=software go run ./examples/hello-cube/

Standalone Usage

g3d works without the gogpu application framework. Bring your own window and GPU device:

// Use g3d with any wgpu.Device — no gogpu dependency required
renderer, err := g3d.NewRendererFromDevice(device, queue, surfaceFormat)

scene := g3d.NewScene()
// ... build your scene
renderer.Render(scene, camera, targetView)

Architecture

Your Application (game engine, CAD viewer, data viz, AR/VR)
         |
    gogpu/g3d  — Scene Graph + Materials + Render Pipeline
         |
    gogpu/wgpu — Pure Go WebGPU (Vulkan/Metal/DX12/GLES/Software)
         |
    gogpu/naga — Shader Compiler (WGSL → SPIR-V/MSL/GLSL/HLSL)

g3d depends down (wgpu, naga), never up (gogpu, gg, ui). This ensures it can be used in any context.

See docs/ARCHITECTURE.md for full architecture documentation.

Installation

go get github.com/gogpu/g3d

Requirements: Go 1.25+

Roadmap

Phase	Features	Status
Phase 1	Scene graph, cameras, materials, box/sphere/plane, forward renderer	Complete
Phase 2	Full PBR (Cook-Torrance), shadows, normal maps, textures	Planned
Phase 3	GLTF 2.0 loader, skeletal animation, morph targets	Planned
Phase 4	Instance batching, environment maps, post-processing, skybox	Planned
Phase 5	Frustum culling BVH, LOD, SIMD math	Planned

Design Principles

1. Simple API — rotating lit cube in ~20 lines. Progressive complexity.
2. Zero CGO — Pure Go on all platforms. Single binary deployment.
3. Reusable — rendering library, not a framework. No opinions about your architecture.
4. PBR from day one — metallic-roughness workflow, GLTF standard.
5. Zero-alloc rendering — no GC pressure in the hot path.
6. All GPU backends — Vulkan, Metal, DX12, GLES, Software through wgpu.

Contributing

See CONTRIBUTING.md for development workflow, code standards, and priority areas.

Part of the GoGPU Ecosystem

g3d is part of GoGPU — a Pure Go GPU computing ecosystem with 800K+ lines of code.

Library	Purpose
gogpu	Application framework, windowing
wgpu	Pure Go WebGPU (Vulkan/Metal/DX12/GLES)
naga	Shader compiler (WGSL → SPIR-V/MSL/GLSL/HLSL)
gg	2D graphics with GPU acceleration
g3d	3D rendering (this library)
ui	GUI toolkit (22+ widgets, 4 themes)
systray	System tray (Win32/macOS/Linux)
audio	Pure Go audio engine (WASAPI)

License

MIT License — see LICENSE for details.