WebGPU Geliştirme Kılavuzu

Bu kılavuz, projenizde 3DGS sahnelerini görüntülemek için WebGPU'nun nasıl kullanılacağını ve WebGL entegrasyonundan farklarını açıklar.

Motor Desteği

WebGPU işleme hattı yalnızca Three.js motorunu destekler. CesiumJS, WebGPU ile görüntülemeyi desteklemez.

Sürüm Gereksinimleri

SDK sürümü: SDK v0.6.4+

Veri Formatı Sınırlamaları

WebGPU işleme hattı şu anda yalnızca .lcc2 formatını destekler. .lcc formatı henüz WebGPU ile görüntülemeyi desteklemez; destek gelecek sürümlerde eklenecektir.

Bir .lcc veri yolu sağlanırsa WebGL görüntüleyicisine geri dönmeniz gerekir. Örnek kod bu mantığı forceWebGL parametresiyle uygular:

const forceWebGL = new URL(dataPath, location.origin).pathname.endsWith('.lcc');
const renderer = await createRenderer(canvas, forceWebGL);

WebXR Sınırlamaları

SDK şu anda WebXR'ı yalnızca WebGL işleme hattında destekler. WebGPU işleme hattı WebXR'ı desteklemez.

Mobil Sınırlamalar

Mobil cihazlarda WebGPU önerilmez. SDK'nın WebGL işleme hattı şu anda mobilde daha iyi performans sunar.

Three.js Görüntüleme Yolları

Three.js'in üç görüntüleme yolu vardır. SDK'yı doğru entegre etmek için aralarındaki farkları anlamak gerekir.

Yol 1: Klasik WebGLRenderer (yaygın olarak kullanılır)

WebGLRenderer, Three.js oluşturulduğundan beri çekirdek görüntüleyici olmuştur ve en yaygın kullanılan seçenek olmaya devam etmektedir. Doğrudan WebGL 2 API'si üzerine kurulmuştur ve malzeme sistemi GLSL shader'larını kullanır.

İçe aktarma:

import * as THREE from 'three';
const renderer = new THREE.WebGLRenderer();

SDK bu yolu destekler; hem .lcc hem de .lcc2 formatları kullanılabilir.

Yol 2: Yeni Mimari WebGPURenderer + WebGPU Backend

WebGPURenderer, Three.js için yeni nesil görüntüleme motorudur ve yeni bir soyut backend mimarisi sunar. Düğüm tabanlı bir materyal sistemi (Node Material) ve TSL (Three.js Shading Language) getirir. TSL ile yazılan shader'lar, backend'e bağlı olarak otomatik olarak WGSL veya GLSL'ye derlenir. Tarayıcı WebGPU'yu desteklediğinde WebGPURenderer, yerel WebGPU backend'ini kullanır.

İçe aktarma:

import * as THREE from 'three';
import * as THREE_WEBGPU from 'three/webgpu';
import * as THREE_TSL from 'three/tsl';

const renderer = new THREE_WEBGPU.WebGPURenderer({ canvas });
await renderer.init();

SDK bu yolu destekler, ancak yalnızca .lcc2 formatı için.

Yol 3: Yeni Mimari WebGPURenderer + WebGL 2 Backend

WebGPURenderer, yedek olarak yerleşik bir WebGL 2 backend'i içerir. Tarayıcı WebGPU'yu desteklemediğinde WebGPURenderer otomatik olarak WebGL 2 backend'ine geçer. Hâlâ WebGL 2 kullanılsa da materyal sistemi ve shader hattı Yol 2 ile aynıdır (Node Material + TSL); son derleme hedefi GLSL'dir.

SDK bu yolu desteklemez.

Yol Karşılaştırması

WebGPU ve WebGL Entegrasyonu Arasındaki Farklar

WebGL entegrasyonuna kıyasla WebGPU değişiklikleri aşağıdaki alanlarda toplanır. Diğer tüm iş kodları (kamera kontrolleri, performans parametreleri, görüntüleme döngüsü vb.) aynı kalır.

1. Ek İçe Aktarmalar: three/webgpu ve three/tsl

WebGL yalnızca three modülünü gerektirir. WebGPU için iki ek modül gerekir:

<!-- importmap -->
<script type="importmap">
{
    "imports": {
        "three": "./engine/three/three.module.js",
        "three/webgpu": "./engine/three/three.webgpu.js",
        "three/tsl": "./engine/three/three.tsl.js",
        "three/addons/": "./engine/three/jsm/"
    }
}
</script>

import * as THREE from 'three';
import * as THREE_WEBGPU from 'three/webgpu';
import * as THREE_TSL from 'three/tsl';

2. Asenkron Renderer Oluşturma

WebGL renderer'ı eşzamanlı olarak oluşturulur. WebGPU renderer'ı ise asenkron başlatma gerektirir:

// WebGL (synchronous)
const renderer = new THREE.WebGLRenderer({ canvas, antialias: false });

// WebGPU (asynchronous)
const renderer = new THREE_WEBGPU.WebGPURenderer({ canvas, antialias: false });
await renderer.init();

SDK örneklerinde sunulan createRenderer yardımcı işlevini kullanmanızı öneririz. Bu işlev, eksiksiz bir yedekleme zinciri uygular:

1. Tarayıcı navigator.gpu özelliğini desteklemiyorsa → WebGLRenderer'a geçilir
2. GPU adaptörü alınamıyorsa → WebGLRenderer'a geçilir
3. WebGPURenderer başlatmadan sonra sessizce WebGL 2 backend'ine geçerse (GPUDevice yoksa) → yok edilir ve WebGLRenderer'a geçilir
4. Tüm kontroller başarılı olursa → gerçek bir WebGPU renderer'ı döndürülür

import { createRenderer } from './engine/three/util.js';

const renderer = await createRenderer(canvas, forceWebGL);
const isWebGPU = renderer.isWebGPURenderer === true;

3. sRGB Çıkışını ve Ton Eşlemeyi Devre Dışı Bırakma

WebGPU modunda Three.js'in varsayılan sRGB çıkış dönüşümünü ve ton eşlemesini devre dışı bırakmanız gerekir. Varsayılan sRGB çıkışı, doğrusal → sRGB için ek bir dönüşüm geçişi ekler. Bu geçiş, 3DGS'nin önceden çarpılmış alfa karıştırmasıyla çakışır ve renklerin hatalı görünmesine neden olur:

if (isWebGPU) {
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.toneMapping = THREE.NoToneMapping;
}

WebGL modunda bu işlem gerekmez.

4. LCCRender.load Parametreleri

WebGPU için ek olarak renderLibWebgpu ve renderLibTSL parametreleri gerekir:

// WebGL
LCCRender.load({
    camera, scene, renderer,
    dataPath,
    renderLib: THREE,
    canvas: renderer.domElement,
    // ...
});

// WebGPU
LCCRender.load({
    camera, scene, renderer,
    dataPath,
    renderLib: THREE,
    renderLibWebgpu: THREE_WEBGPU,  // new
    renderLibTSL: THREE_TSL,        // new
    canvas: renderer.domElement,
    // ...
});

GPU Aygıt Sınırları Yapılandırması

Bir WebGPURenderer oluştururken GPU adaptörünün gerçek sınırlarını sorgulamanız ve aygıt yeteneklerinden tam olarak yararlanmak için requiredLimits değerini iletmeniz önerilir:

const adapter = await navigator.gpu.requestAdapter();
const requiredLimits = {
    maxBufferSize: adapter.limits.maxBufferSize,
    maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
    maxTextureDimension2D: adapter.limits.maxTextureDimension2D
};

const renderer = new THREE_WEBGPU.WebGPURenderer({
    canvas,
    antialias: false,
    requiredLimits
});
await renderer.init();

Eksiksiz WebGPU Örneği

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>LCC Three.js WebGPU Demo</title>
    <style>
        html, body { margin: 0; padding: 0; height: 100%; overflow: hidden; }
        canvas { display: block; }
    </style>
</head>
<body>
    <script type="importmap">
    {
        "imports": {
            "three": "./engine/three/three.module.js",
            "three/webgpu": "./engine/three/three.webgpu.js",
            "three/tsl": "./engine/three/three.tsl.js",
            "three/addons/": "./engine/three/jsm/"
        }
    }
    </script>
    <script type="module">
        import * as THREE from 'three';
        import * as THREE_WEBGPU from 'three/webgpu';
        import * as THREE_TSL from 'three/tsl';
        import { createRenderer } from './engine/three/util.js';
        import { LCCRender } from '../sdk/lcc-sdk-three.js';

        const dataPath = 'https://your-server.com/assets/scene/meta.lcc2';

        // WebGPU only supports .lcc2; force WebGL for .lcc assets
        const forceWebGL = new URL(dataPath, location.origin).pathname.endsWith('.lcc');

        const scene = new THREE.Scene();
        const canvas = document.createElement('canvas');
        document.body.appendChild(canvas);

        // Create renderer with automatic WebGPU → WebGL fallback
        const renderer = await createRenderer(canvas, forceWebGL);
        const isWebGPU = renderer.isWebGPURenderer === true;
        renderer.setSize(window.innerWidth, window.innerHeight);
        renderer.setPixelRatio(window.devicePixelRatio);
        renderer.setClearColor(0x000000);

        // Disable sRGB output for WebGPU to avoid color space conflicts with 3DGS
        if (isWebGPU) {
            renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
            renderer.toneMapping = THREE.NoToneMapping;
        }

        const camera = new THREE.PerspectiveCamera(
            45, window.innerWidth / window.innerHeight, 0.1, 150000
        );
        camera.position.set(0, 2, 0);

        // Load 3DGS scene
        const lccObj = LCCRender.load({
            camera, scene, renderer,
            dataPath,
            renderLib: THREE,
            renderLibWebgpu: THREE_WEBGPU,
            renderLibTSL: THREE_TSL,
            canvas: renderer.domElement,
            useEnv: true,
            useIndexDB: true,
            useLoadingEffect: true,
            appKey: null  // replace with your key
          },
          (mesh) => { console.log('Loaded', mesh); },
          (percent) => { console.log('Loading ' + (percent * 100).toFixed(1) + '%'); },
          () => { console.log('Loading failed'); }
        );

        // Configure performance parameters
        lccObj.setStartLod(0);
        lccObj.setMaxSplats(8000000);
        lccObj.setMaxNodeSplats(4000000);
        lccObj.setMaxDistance(200);

        window.addEventListener('resize', () => {
            camera.aspect = window.innerWidth / window.innerHeight;
            camera.updateProjectionMatrix();
            renderer.setSize(window.innerWidth, window.innerHeight);
        });

        renderer.setAnimationLoop(() => {
            LCCRender.update();
            renderer.render(scene, camera);
        });
    </script>
</body>
</html>