Communitygithub.com

webgl-cinematic-engine

在瀏覽器中以原始 WebGL2(或 Three.js)實現電影級即時渲染:全螢幕光線步進、測地線/光線追蹤場景、時間性反鋸齒、動態解析度、物理基礎的泛光、ACES色調映射、顆粒感、天空烘焙、多尺度場景,以及針對 Windows/ANGLE 的著色器編譯時間優化。適用於任何 3D/WebGL/GLSL/著色器/Three.js 場景工作、黑洞、體積渲染,或當場景看起來平淡、鋸齒、閃爍、緩慢或「像 CG」時。

webgl-cinematic-engine 是什麼?

這是一個專為瀏覽器設計的電影級即時渲染引擎技能,支援原始 WebGL2 和 Three.js。它提供了一整套高品質畫面管線:從動態內部解析度的場景渲染、時間性反鋸齒(TAA)、基於物理的泛光、ACES 色調映射,到顆粒感和動態解析度調節,全部以嚴格的渲染順序執行。技能特別針對 Windows/ANGLE 平台上的著色器編譯瓶頸提供了創新解決方案——透過引入偽裝成變數的常數來防止 D3D 迴圈展開,將編譯時間從 7 秒降至 0.9 秒。此外,它還包含了黑洞、體積渲染、3D 星域等多種光線步進食譜,並提出了一種無縫的雙座標系統(星系/行星)來實現 10⁸ 倍的連續縮放。引擎內建效能調試工具(透過 ?debug 參數啟用),可測量幀時間並偵測 NaN 像素。此技能適用於 Claude Code、Cursor、Codex 等 AI 代理,尤其適合需要即時高品質渲染的 WebGL 專案開發。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/forpc1428-eng/cosmic-forge/tree/HEAD/skills/webgl-cinematic-engine

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

WebGL 電影級渲染引擎

參考實作:templates/event-horizon/js/blackhole.js(約 1300 行,無依賴)。 閱讀它。重複使用它。以下管線已在桌上型 GPU 和中階手機上驗證。

1. 幀管線(嚴格維持此順序)

  1. 場景 Pass → 以動態內部解析度(僅視口——絕不重新分配)輸出到 raw RGBA16F 目標。 在投影上使用子像素 Halton(2,3) 抖動,8 幀循環。
  2. TAA 解析 → 歷史幀乒乓緩衝。在色調映射空間中進行 3×3 鄰域鉗制 (c/(1+luma)),混合係數 0.86 − motion*6,下限 0.3。在解析度改變或場景切換時重置歷史。 消除星光閃爍、條紋、階梯鋸齒,並允許你減少 30–50% 的取樣數。
  3. 升頻至全畫布解析度,使用輕微的 4-tap 銳化(0.08 + 0.35*(1−scale))。
  4. 泛光:6 層 mip 鏈。第一個降頻為 13-tap CoD 濾波器,搭配 Karis 平均 + 軟膝 閾值(~1.6–1.8 HDR);升頻為 9-tap tent,累加。強度 0.05–0.08。絕不對 UI 進行泛光。
  5. 合成:微小色差(≤ 0.004 — 更多會抹掉星光),曝光 ~0.95–1.05,ACES 擬合, Gamma,暗角 0.7–1.0,三角顆粒 0.025(同時抖動 8-bit 條帶),可選淡入淡出。

當 EXT_color_buffer_float 存在時使用 RGBA16F 渲染目標,否則使用 RGBA8。使用全螢幕三角形,而非四邊形。

2. 最重要的速度規則

  • Windows/ANGLE 編譯陷阱:D3D 會展開迴圈並內聯所有內容 → 連結時間超過 7 秒。 添加 uniform int uZero;(永遠為 0)並將每個迴圈寫成 for(int i=uZero; i<N; i++)。 實測:黑洞著色器連結從 7 秒降至 0.9 秒。
  • KHR_parallel_shader_compile:立即啟動所有 linkProgram,輪詢 COMPLETION_STATUS_KHR 並使用 setTimeout(rAF 在隱藏分頁中會暫停),僅等待 第一個畫面所需的程式。在背景編譯後續場景。
  • 烘焙不動的內容:僅方向相關的天空(星雲、遙遠星系、從內部看到的銀河系)→ 在載入時 一次性生成到立方貼圖(384–768 像素/面)。逐像素的 fbm 是 GPU 成本的第一大來源。
  • 動態解析度:每 0.6 秒測量平均幀毫秒數;>19.5 毫秒 → 將解析度係數 −0.06 並設定上限 (係數−0.02)以防止震盪;<17.6 毫秒持續 4 個視窗 → +0.04。範圍 0.42–1.0。
  • 像素上限:桌上型 maxPixels 3.2 MP,手機 1.0 MP;DPR 上限:桌上型 1.5 / 手機 1.25。
  • 無逐幀記憶體分配(JavaScript);幀循環中無佈局讀取(在縮放時快取偏移量)。
  • 在 visibilitychange 時暫停;處理 webglcontextlost(preventDefault)/ restored(重新載入)。
  • 暖機:在載入器後方渲染 2–3 幀第一個場景,gl.finish(),然後顯示。

3. 光線步進食譜

黑洞(史瓦西半徑,rs = 1) — 使用速度 Verlet 積分光子路徑: a = −1.5·h²·p/r⁵,h = |p × v|,步長 dt = clamp(0.075·r, 0.008, 2.6),第一步使用交錯梯度雜訊抖動。 在 r < 1 時捕獲;當 r > 遠處且向外移動時逃逸。 薄盤:偵測 y 符號變化,插值交叉點,由前向後 alpha 合成。 盤面著色 → 參見 space-realism §黑洞。桌上型 220 步,手機 150 步。

體積(星系、星雲、雲):相交一個包圍盒/球體,步進 36(桌上型)/ 24(手機)個取樣點,使用二次間距 t = t0 + (t1−t0)·f²(靠近眼睛處更密集), 每像素每幀抖動;累積 col += T·emission·dt; T *= exp(−extinction·dt); 當 T < 0.02 時提前退出。TAA 將雜訊轉變為平滑的漸層。

具有真實視差的 3D 星域:通過網格單元進行 3D-DDA(22 步),每個單元一顆經過哈希的恆星, 亮度 ∝ 1/t²(鉗制),高斯覆蓋區域 ≥ 0.75 像素,密度來自場景的質量分布。 隨著縮放等級縮小單元大小,使恆星持續流過。

解析物體(行星、環、衛星):sph() 光線-球體相交,環 = 平面碰撞 + 半徑帶, 陰影透過第二條光線朝向光源。對於球體來說,比網格更便宜且更銳利。

4. 無縫的多尺度世界(星系 → 行星,無中斷)

Float32 無法在一個座標系中同時容納「星系」和「行星」。使用兩個共用同一個相機方向的影格: 星系單位和系統單位,其中 K = 1e5。 在 JS doubles 中計算兩個眼睛位置:eyeS = (eyeG − sunG)·K。 從 eyeG 渲染星系,從 eyeS 渲染行星。當距離遠時,太陽是一個星狀點,其通量遵循 (角半徑/像素)² — 它會自然地變成可解析的圓盤。一旦進入銀河系內部,將體積星系交叉淡入 真實的全景(或烘焙的立方體)。結果:一個不間斷的 10⁸× 縮放。

5. 紋理

  • 等距柱狀投影地圖,使用 eqUV(n) = (0.5 + atan(n.z,n.x)/2π, 0.5 − asin(n.y)/π) 取樣。
  • 無接縫:使用 textureLod 搭配來自像素足跡的分析 LOD (log2(texW·0.159·pixAng·t/R/μ) − 0.5),絕不在分支中使用帶有導數的 texture()。
  • 每幀從佇列上傳一個紋理(使用 createImageBitmap 在離線執行緒解碼), 顏色使用 SRGB8_ALPHA8,資料使用 RGBA8(雲、Alpha),包含 mipmap + 8× 非等向性。
  • 在所有取樣器上綁定 1×1 虛擬紋理,直到真實紋理到達(避免類型衝突錯誤)。
  • 從照片產生浮雕:有限差分反照率亮度 → 擾動法線(岩石 k≈5,氣體 ≈1)。

6. Three.js 移植(當用戶堅持時)

相同的規則:WebGLRenderer({antialias:false, powerPreference:'high-performance'}), 使用 HalfFloat 目標的 EffectComposer,你自己的 TAA 或 TAARenderPass,UnrealBloomPass (threshold ≥ 1.5,strength ≤ 0.6),帶 ACES 的 OutputPass。全螢幕光線步進效果作為 全螢幕三角形上的 ShaderMaterial。不要在手機上混合 50 個網格 + 後置特效。

7. 除錯工具(附帶出貨,透過 ?debug 啟用)

暴露 window.__engine。計時一個場景:渲染一次,gl.finish(),渲染 ×4 次,readPixels 1 像素以強制同步,然後除法。透過在目標上 readPixels(FLOAT) 探測 NaN——一個 NaN 像素 會透過泛光傳播並使整個影格變黑。常見 NaN 來源:pow(neg, x),smoothstep(e,e,x), ACES 中的 Inf。鉗制輸入。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能