場實戰(zhàn)：用 @hyperframes/shader-transitions 在 GSAP 時間線上接入 GPU 著色器過渡)
HyperFrames 場景轉(zhuǎn)場實戰(zhàn)用 hyperframes/shader-transitions 在 GSAP 時間線上接入 GPU 著色器過渡【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 遵循Write HTML. Render video.的理念頁面即時間線場景scene即 DOM。hyperframes/shader-transitions正是為這種架構(gòu)補齊最后一環(huán)的獨立子包——它用 WebGL 片元著色器fragment shader在相鄰場景之間渲染 GPU 加速轉(zhuǎn)場并通過捕獲場景動畫采樣幀與 GSAP 時間線結(jié)合驅(qū)動。閱讀本文后你將掌握在 HyperFrames 組合composition中安裝、配置與擴展著色器轉(zhuǎn)場理解預(yù)捕獲 著色器合成的瀏覽器預(yù)覽管線、引擎確定性渲染管線的差異以及降級與緩存等工程細(xì)節(jié)。本文檔與源碼位于倉庫 packages/shader-transitions當(dāng)前版本 0.8.29見 package.json。一、包定位與核心思想hyperframes/shader-transitions解決的問題很具體在一個由多個 HTML 場景如intro、demo、outro組成的 HyperFrames 視頻中相鄰場景之間需要一個持續(xù)的、在動的轉(zhuǎn)場而不是硬切。包的核心思路可以概括為三步入口實現(xiàn)見 hyper-shader.ts預(yù)捕獲pre-capture為每個轉(zhuǎn)場在其開始前的時刻捕獲出境場景的動畫采樣幀同時捕獲入境場景從轉(zhuǎn)場起點繼續(xù)推進(jìn)的采樣幀合成composite播放進(jìn)入轉(zhuǎn)場窗口時把兩套緩存幀作為紋理texture上傳到 WebGL交給片元著色器按u_progress混合輸出時間線timelineinit()返回一個 GSAP 時間線。轉(zhuǎn)場期間場景動畫依然持續(xù)向前推進(jìn)但播放循環(huán)中不再有 DOM 捕獲開銷轉(zhuǎn)場結(jié)束后由原本的場景動畫無縫接管。由此帶來的關(guān)鍵收益是轉(zhuǎn)場過程是真正在動的captured animation keeps advancing且 WebGL 渲染發(fā)生在 GPU 上如果瀏覽器沒有 WebGL包會自動回退為普通時間線播放不做著色器合成。源碼中對應(yīng)回退邏輯會打印[HyperShader] WebGL unavailable — shader transitions disabled.并直接返回注冊好的時間線hyper-shader.ts 的init()內(nèi)。二、安裝與三種加載方式推薦通過 npm 安裝npm install hyperframes/shader-transitions或者通過 CDN 以script標(biāo)簽直接加載 IIFE 產(chǎn)物script srchttps://cdn.jsdelivr.net/npm/hyperframes/shader-transitions/dist/index.global.js/script該包設(shè)計上自包含、可獨立分發(fā)源碼注釋明確指出它作為獨立 CDN bundle 發(fā)布不依賴hyperframes/engine相關(guān)說明見 hyper-shader.ts。其唯一運行時依賴是html2canvas^1.4.1見 package.json并在構(gòu)建時通過noExternal: [html2canvas]打進(jìn)了產(chǎn)物。產(chǎn)物由 tsup.config.ts 生成三種格式及適用場景如下表格式文件適用場景全局變量ESMdist/index.js打包器Vite、webpack 等—CJSdist/index.cjsNode.js /require()—IIFEdist/index.global.jsscript標(biāo)簽、CDNHyperShader所有格式均包含 source map并隨包發(fā)布 TypeScript 類型聲明tsup開啟了dts: true。IIFE 場景下請注意源碼注釋提到的一點當(dāng)通過script手工加載 bundle 后從 vanilla JS 傳入顯式的空字符串shader: 不會被當(dāng)作省略而會走到著色器注冊表并拋出明確的 unknown shader 錯誤這是刻意的嚴(yán)格行為見 registry.ts 的getFragSource()。三、核心 APIinit(config): GsapTimeline所有能力都收斂到init()一個函數(shù)。基本用法import { init } from hyperframes/shader-transitions; const tl init({ bgColor: #0a0a0a, // 場景捕獲時的兜底背景色 accentColor: #ff6b2b, // 著色器輝光效果強調(diào)色 scenes: [scene-1, scene-2, scene-3], transitions: [ { time: 3, shader: domain-warp, duration: 0.8 }, { time: 8, shader: light-leak, duration: 0.7 }, ], });3.1 配置項全表選項類型必填說明bgColorstring是場景捕獲時的兜底背景色hex。應(yīng)使用組合的 body/canvas 背景色——每個場景通過 CSS 自行設(shè)置各自的background-coloraccentColorstring否著色器輝光效果的強調(diào)色hexscenesstring[]是各場景元素的 ID按順序排列transitionsTransitionConfig[]是轉(zhuǎn)場定義數(shù)組見下文timelineGsapTimeline否已有的 GSAP 時間線把轉(zhuǎn)場疊加到它上面compositionIdstring否覆蓋data-composition-id用于時間線注冊previewCaptureFpsnumber否瀏覽器預(yù)覽模式每秒鐘為每個轉(zhuǎn)場預(yù)捕獲的采樣幀數(shù)。默認(rèn)30渲染模式則改為確定性的逐幀合成不使用此值3.2 底層行為印證對照 hyper-shader.ts 的init()實現(xiàn)可以確認(rèn)以下細(xì)節(jié)組合畫布尺寸優(yōu)先讀取根元素帶data-composition-id的元素上的data-width/data-height屬性缺失或非法時回退到1920 × 1080常量DEFAULT_WIDTH/DEFAULT_HEIGHT定義于 webgl.ts。compositionId的解析順序是config.compositionId→ 根元素data-composition-id→main。強調(diào)色三檔化單個accentColor會在內(nèi)部被推導(dǎo)成三檔 RGB 用于片元著色器 uniformu_accent、u_accent_dark約乘 0.35與u_accent_bright約1.5x0.2后截斷到 1。未提供時使用默認(rèn)橙色三檔[1, 0.6, 0.2]/[0.4, 0.15, 0]/[1, 0.85, 0.5]。預(yù)覽采樣速率previewCaptureFps默認(rèn) 30并在取值上被鉗制到1 ~ 60之間非法值NaN/非正數(shù)回退到默認(rèn)值。WebGL 畫布包會在組合根元素或body下創(chuàng)建一個idgl-canvas的透明覆蓋 canvas樣式為position:absolute; top:0; left:0; z-index:100; pointer-events:none尺寸與組合一致WebGL 上下文開啟preserveDrawingBuffer以便后續(xù)讀取。著色器程序所有用到的著色器會按名稱去重編譯并緩存到programsMap單個著色器編譯失敗只打印[HyperShader] Failed to compile ...不影響其他轉(zhuǎn)場。著色器間插值由于捕獲幀是離散的兩個相鄰采樣幀之間由包內(nèi)置的一個mix(texture2D(u_a), texture2D(u_b), u_mix)混合程序blend program做線性插值配合紋理交錯機制保證預(yù)覽中的轉(zhuǎn)場依然連續(xù)。3.3 組合到已有時間線如果你的頁面已經(jīng)有自己的 GSAP 時間線例如已寫好每個場景的進(jìn)入/退出動畫可以把時間線傳入轉(zhuǎn)場會被疊到上面而不是另起爐灶import { init } from hyperframes/shader-transitions; import { gsap } from gsap; const tl gsap.timeline({ paused: true }); // ... add your scene animations ... init({ bgColor: #000, scenes: [intro, demo, outro], transitions: [ { time: 5, shader: cinematic-zoom }, // duration/ease 走默認(rèn)值 { time: 12, shader: glitch, duration: 0.5 }, ], timeline: tl, });傳入timeline時包不會把返回值重新注冊到全局window.__timelines[compositionId]注冊只發(fā)生在由包自建時間線的情況下見 hyper-shader.ts 的registerTimeline()。四、TransitionConfig與SHADER_NAMES每個轉(zhuǎn)場由TransitionConfig描述選項類型默認(rèn)值說明timenumber—轉(zhuǎn)場開始時間秒shaderShaderName—上表中的著色器名。注意源碼類型中它是可選的省略undefined時該轉(zhuǎn)場退化為 CSS 交叉淡入淡出不依賴 WebGLdurationnumber0.7轉(zhuǎn)場持續(xù)時長秒easestringpower2.inOutGSAP 緩動函數(shù)默認(rèn)值0.7與power2.inOut在兩個模式瀏覽器預(yù)覽、引擎確定性渲染和元數(shù)據(jù)寫入中共用同一組常量DEFAULT_DURATION/DEFAULT_EASE保證預(yù)覽里怎么動、引擎 seek 時怎么動、producer 讀取元數(shù)據(jù)時按什么參數(shù)合成三者完全一致。SHADER_NAMES導(dǎo)出全部著色器名字符串?dāng)?shù)組可用于參數(shù)校驗或構(gòu)建下拉 UIimport { SHADER_NAMES } from hyperframes/shader-transitions; // [domain-warp, ridged-burn, whip-pan, ...]它在源碼中由注冊表對象的鍵推導(dǎo)而來ShaderName keyof typeof shaders查找未知名稱會拋出[HyperShader] Unknown shader: xxx. Available: ...見 registry.ts。4.1 可用著色器一覽著色器描述domain-warp基于噪聲的有機扭曲帶發(fā)光邊緣ridged-burn脊?fàn)顁idged噪聲灼燒帶火花與熱輝光whip-pan水平運動模糊模擬快速甩鏡sdf-iris圓形光圈擦除iris wipe帶發(fā)光環(huán)邊ripple-waves從中心輻射的同心漣漪扭曲gravitational-lens引力透鏡式扭曲帶色差cinematic-zoom徑向縮放模糊帶色邊chromatic-split從中心向外的 RGB 通道分離glitch數(shù)字故障塊狀位移 掃描線swirl-vortex基于噪聲扭曲的螺旋旋轉(zhuǎn)thermal-distortion從畫面底部升騰的熱浪擾動flash-through-white閃白后揭示下一場景cross-warp-morph噪聲驅(qū)動的雙場景形變混合light-leak暖色電影漏光 鏡頭光暈4.2 共享著色器基礎(chǔ)設(shè)施所有片元著色器并非憑空獨立而是拼接自公共頭部理解這一點有助于二次開發(fā)頂點著色器把a_pos-1..1的四邊形映射為v_uv并做 Y 軸翻轉(zhuǎn)適配 WebGL 坐標(biāo)系見 common.ts每個片元著色器頭部H常量統(tǒng)一聲明了這些 uniformu_from/u_to出境/入境兩張紋理、u_progress0→1 進(jìn)度、u_resolution分辨率、u_accent/u_accent_dark/u_accent_bright三檔強調(diào)色需要噪聲的著色器會拼入NQ常量——基于 hash 的 value noise 五次平滑插值 旋轉(zhuǎn)各向異性的 5 層 FBM。也就是說紋理對u_from、u_to 一個進(jìn)度標(biāo)量是所有轉(zhuǎn)場的通用數(shù)據(jù)契約gl_FragColor的寫法是按進(jìn)度/噪聲混合兩幀再疊加強調(diào)色效果。均勻值由 webgl.ts 的renderShader()統(tǒng)一寫入采樣器綁定 TEXTURE0/TEXTURE1進(jìn)度、分辨率、三檔顏色逐一uniform*程序與 uniform 位置都做了緩存以省去重復(fù)查詢。五、運行架構(gòu)預(yù)捕獲 → 著色器合成 → GSAP 時間線瀏覽器預(yù)覽模式下一次轉(zhuǎn)場周期的數(shù)據(jù)流如下對應(yīng)init()后半段邏輯見 hyper-shader.ts初始化時按scenes.length transitions.length 1校驗例如 3 個場景配 2 個轉(zhuǎn)場違反會直接拋錯隨后逐個檢查場景 ID 存在于 DOM 中且?guī)?sceneclass兩類問題會分別拋出清晰錯誤scene ids not found in DOM: .../elements found but missing .scene class: ...。為每個轉(zhuǎn)場預(yù)編譯對應(yīng)的 GLSL 程序。轉(zhuǎn)場前開始預(yù)捕獲對出境場景與入境場景按previewCaptureFps采樣動畫幀。捕獲結(jié)果先以 PNG Blob 形式寫入 IndexedDB見第六節(jié)播放前按需把 Blob 解碼成ImageBitmap/Image再上傳為 WebGL 紋理。播放進(jìn)入轉(zhuǎn)場窗口時u_progress隨時間線推進(jìn)映射到duration與ease著色器每幀對兩張紋理做混合結(jié)果直接繪制到覆蓋在頁面上的gl-canvas。播放經(jīng)過轉(zhuǎn)場窗口后隱藏 GL 畫布露出持續(xù)推進(jìn)中的入境場景 DOM畫面無縫銜接。整個過程里init()返回的GsapTimeline才是組合時間線的真相來源——無論轉(zhuǎn)場是著色器合成還是 CSS 交叉淡入淡出都可以被暫停、seek、play與 HyperFrames 的既有播放體系兼容。5.1 WebGL 不可用與 CSS 交叉淡入淡出降級兩條獨立的降級路徑需要分清無 WebGL 環(huán)境createContext()返回空init()打印警告并直接返回普通時間線轉(zhuǎn)場退化為硬切場景動畫完全正常。某項轉(zhuǎn)場未指定shadershader undefined該轉(zhuǎn)場以 CSS opacity 交叉淡入淡出執(zhí)行不需要 WebGL。在引擎渲染模式下這樣的條目會被安排成真實的 opacity tween詳見第七節(jié)保證單幀截圖里就包含正確的混合結(jié)果。六、場景捕獲管線從 html2canvas 到原生 HTML-in-Canvas把 DOM 場景變成紋理是整套方案最脆弱也最關(guān)鍵的部分。包支持兩條捕獲路徑策略代碼見 capture.ts。原生 HTML-in-Canvas首選當(dāng)瀏覽器暴露 Chrome 實驗性的 CanvasDrawElement API 時使用layoutSubtreecanvas drawElementImage()直接繪制 DOM。實現(xiàn)細(xì)節(jié)包括把場景克隆進(jìn)一個position:fixed; z-index:-9999; opacity:0的 layoutsubtree canvas等待兩個requestAnimationFrame讓瀏覽器完成布局/繪制用bgColor填充底色再drawElementImage讀出畫面并復(fù)制到結(jié)果 canvas。該路徑失敗時自動回退到 html2canvas。html2canvas 回退html2canvas抓取時為避免 Safari 的畫布污染SecurityError: The operation is insecure固定開啟useCORS: true與allowTaint: true。這里有一個值得注意的工程取舍t(yī)ainted canvas 無法被gl.texImage2D上傳WebGL 規(guī)范強制 SecurityError所以allowTaint的實際作用是把失敗點從 html2canvas 內(nèi)部挪到更可控的紋理上傳處由調(diào)用方統(tǒng)一兜底。此外還提供foreignObjectRendering嘗試開關(guān)失敗自動回退到常規(guī)渲染、onclone中把帶 transform 的box-shadow抽取成獨立 shim 元素因為變換會破壞陰影柵格化、強制克隆場景可見等處理。用isHtmlInCanvasCaptureSupported()可以自行做特性檢測源碼判定存在layoutSubtree屬性 2D 上下文具備drawElementImage函數(shù)對應(yīng)測試見 capture.test.ts驗證了非瀏覽器環(huán)境返回 false、能力齊備返回 true、缺drawElementImage返回 false 三種情況。另外捕獲對零尺寸 pattern 有個 Safari 相關(guān)防御補丁重寫CanvasRenderingContext2D.prototype.createPattern當(dāng)傳入 0×0 的 canvas 時返回null而不是讓瀏覽器拋錯initCapture()。6.1 瀏覽器預(yù)覽快照的 IndexedDB 緩存每次刷新頁面都重新捕獲幾十上百幀顯然不劃算因此瀏覽器預(yù)覽的快照會被持久化數(shù)據(jù)庫名為hyper-shader-preview-cacheobject store 名為framesschema 版本v1常量見 hyper-shader.ts。緩存鍵由composition ID、場景 DOM/樣式簽名、轉(zhuǎn)場時序、捕獲 FPS、縮放與畫布尺寸綜合推導(dǎo)。DOM/樣式簽名不是簡單 hash它基于文檔內(nèi)所有style文本、link relstylesheet及腳本特征的stableHash場景自身的簽名還會在計算前剔除播放過程中被運行時改寫的opacity/visibility/pointer-events等內(nèi)聯(lián)樣式從而讓緩存身份追蹤作者寫的內(nèi)容而非上次預(yù)覽的播放頭狀態(tài)。刷新后若鍵匹配快照直接加載為 WebGL 紋理不再重捕。運行中編輯場景或樣式表時只會把相鄰轉(zhuǎn)場的緩存標(biāo)記為 dirty重捕推遲到真正播放到那個轉(zhuǎn)場時才發(fā)生保證編輯器操作期間交互不卡頓。緩存總量上限為 1200 條MAX_SNAPSHOT_CACHE_ENTRIES寫入時按updatedAt淘汰最舊條目并清理當(dāng)前 composition 的失效鍵。6.2 預(yù)捕獲階段的加載反饋首次播放前的快照準(zhǔn)備可能需要一段時間包內(nèi)置了一套全屏加載反饋覆蓋層包含品牌圖形、進(jìn)度短語與逐 transition / 逐 frame 的進(jìn)度數(shù)字短語按進(jìn)度切換Preparing scene transitions、Sampling outgoing scene motion 等。該覆蓋層帶data-hyperframes-ignore、data-no-capture、data-no-pick等標(biāo)記確保它不會污染捕獲與拾取邏輯。播放器接管 vs 內(nèi)置加載 UI當(dāng)頁面由hyperframes-player承載時瀏覽器預(yù)覽的捕獲縮放與轉(zhuǎn)場預(yù)加載 UI 的所有權(quán)歸屬播放器對應(yīng)屬性shader-capture-scale、shader-loading而不是組合代碼非播放器的直接預(yù)覽則保留內(nèi)置的全保真加載兜底。實現(xiàn)上捕獲縮放系數(shù)讀取全局變量__HF_SHADER_CAPTURE_SCALE或查詢參數(shù)__hf_shader_capture_scale解析后鉗制在0.25 ~ 1默認(rèn) 1加載模式讀取__HF_SHADER_LOADING或__hf_shader_loading取值player/true→ 播放器接管、none/false/off→ 關(guān)閉、其余 →internal內(nèi)置覆蓋層。七、引擎渲染模式確定性逐幀輸出瀏覽器里人眼看 30fps 預(yù)捕獲足夠但視頻渲染引擎要求每一幀都精確確定。init()會探測window.__HF_VIRTUAL_TIME__標(biāo)記引擎在渲染模式注入的虛擬時間 shim見 hyper-shader.ts一旦檢測到就切換到initEngineMode()完全跳過所有 GL / canvas / html2canvas 分支只構(gòu)建一條確定性的透明度翻轉(zhuǎn)時間線非首場景初始全部opacity: 0用tl.set(..., 0)掛進(jìn)時間線開頭保證逆向 seek 也能恢復(fù)正確初態(tài)。對著色器轉(zhuǎn)場轉(zhuǎn)場窗口內(nèi)from/to 兩場景都保持opacity: 1出境場景在time duration時刻降到 0——這樣引擎的 Node 端分層合成器能分別獨立捕獲兩場景再自行混合。對 CSS 交叉淡入淡出安排真實的 opacity tweenfromTo保證單幀頁面截圖本身已包含正確的混合結(jié)果。使用tl.set()零時長 tween而不是tl.call()因為tl.call只在運動方向上觸發(fā)引擎 warmup 會正向 seek 到各轉(zhuǎn)場起點、隨后又反向 seek 回 t0回調(diào)態(tài)會卡住而set可隨反向 seek 正確還原。引擎讀取合成的依據(jù)是init()同步寫入window.__hf.transitions的元數(shù)據(jù)數(shù)組每項含time、duration、shader、ease、fromScene、toScene缺省 duration/ease 時同樣使用 0.7 /power2.inOut。該結(jié)構(gòu)刻意在包內(nèi)本地重聲明不 import engine 的類型以保持 CDN 獨立并與 engine 的HfTransitionMeta保持同步注釋中明確說明。7.1 可選的頁面端合成器engine-mode page compositing當(dāng) producer 以EngineConfig.enablePageSideCompositing: true啟動并注入window.__HF_PAGE_SIDE_COMPOSITING__哨兵時引擎模式還會安裝一個頁面端 WebGL 合成器installPageSideCompositor()導(dǎo)出見 index.ts實現(xiàn)見 engineModePageComposite.ts讓單次整頁截圖也能得到與預(yù)覽路徑一致的原生保真捕獲。它采用兩階段協(xié)議Phase 1seek 包裝包裝window.__hf.seek。進(jìn)入轉(zhuǎn)場窗口時把 FROM/TO 場景克隆進(jìn)兩個常駐的 layoutsubtree staging canvas并設(shè)window.__hf_page_composite_pending。Paint force引擎?zhèn)纫鏅z測到 pending 標(biāo)記后觸發(fā)一次微型的Page.captureScreenshot強制瀏覽器合成器把 staging canvas 的克隆繪制出來。Phase 2resolve引擎調(diào)用window.__hf_page_composite_resolve用drawElementImage從已繪制克隆讀出畫面、上傳紋理、跑著色器并顯示 GL 覆蓋層最后清理 staging?？寺r會把各自getBoundingClientRect()實測到的盒模型left/top/width/height固定到克隆上——這是為了規(guī)避僅靠inset:0定位的場景克隆進(jìn) layout subtree 后坍縮成 0×0的已知問題同時強制克隆可見、解碼 contenteditable="false">【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 HyperFrames 場景轉(zhuǎn)場實戰(zhàn)：用 @hyperframes/shader-transitions 在 GSAP 時間線上接入 GPU 著色器過渡
HyperFrames 場景轉(zhuǎn)場實戰(zhàn)用 hyperframes/shader-transitions 在 GSAP 時間線上接入 GPU 著色器過渡【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 遵循Write HTML. Render video.的理念頁面即時間線場景scene即 DOM。hyperframes/shader-transitions正是為這種架構(gòu)補齊最后一環(huán)的獨立子包——它用 WebGL 片元著色器fragment shader在相鄰場景之間渲染 GPU 加速轉(zhuǎn)場并通過捕獲場景動畫采樣幀與 GSAP 時間線結(jié)合驅(qū)動。閱讀本文后你將掌握在 HyperFrames 組合composition中安裝、配置與擴展著色器轉(zhuǎn)場理解預(yù)捕獲 著色器合成的瀏覽器預(yù)覽管線、引擎確定性渲染管線的差異以及降級與緩存等工程細(xì)節(jié)。本文檔與源碼位于倉庫 packages/shader-transitions當(dāng)前版本 0.8.29見 package.json。一、包定位與核心思想hyperframes/shader-transitions解決的問題很具體在一個由多個 HTML 場景如intro、demo、outro組成的 HyperFrames 視頻中相鄰場景之間需要一個持續(xù)的、在動的轉(zhuǎn)場而不是硬切。包的核心思路可以概括為三步入口實現(xiàn)見 hyper-shader.ts預(yù)捕獲pre-capture為每個轉(zhuǎn)場在其開始前的時刻捕獲出境場景的動畫采樣幀同時捕獲入境場景從轉(zhuǎn)場起點繼續(xù)推進(jìn)的采樣幀合成composite播放進(jìn)入轉(zhuǎn)場窗口時把兩套緩存幀作為紋理texture上傳到 WebGL交給片元著色器按u_progress混合輸出時間線timelineinit()返回一個 GSAP 時間線。轉(zhuǎn)場期間場景動畫依然持續(xù)向前推進(jìn)但播放循環(huán)中不再有 DOM 捕獲開銷轉(zhuǎn)場結(jié)束后由原本的場景動畫無縫接管。由此帶來的關(guān)鍵收益是轉(zhuǎn)場過程是真正在動的captured animation keeps advancing且 WebGL 渲染發(fā)生在 GPU 上如果瀏覽器沒有 WebGL包會自動回退為普通時間線播放不做著色器合成。源碼中對應(yīng)回退邏輯會打印[HyperShader] WebGL unavailable — shader transitions disabled.并直接返回注冊好的時間線hyper-shader.ts 的init()內(nèi)。二、安裝與三種加載方式推薦通過 npm 安裝npm install hyperframes/shader-transitions或者通過 CDN 以script標(biāo)簽直接加載 IIFE 產(chǎn)物script srchttps://cdn.jsdelivr.net/npm/hyperframes/shader-transitions/dist/index.global.js/script該包設(shè)計上自包含、可獨立分發(fā)源碼注釋明確指出它作為獨立 CDN bundle 發(fā)布不依賴hyperframes/engine相關(guān)說明見 hyper-shader.ts。其唯一運行時依賴是html2canvas^1.4.1見 package.json并在構(gòu)建時通過noExternal: [html2canvas]打進(jìn)了產(chǎn)物。產(chǎn)物由 tsup.config.ts 生成三種格式及適用場景如下表格式文件適用場景全局變量ESMdist/index.js打包器Vite、webpack 等—CJSdist/index.cjsNode.js /require()—IIFEdist/index.global.jsscript標(biāo)簽、CDNHyperShader所有格式均包含 source map并隨包發(fā)布 TypeScript 類型聲明tsup開啟了dts: true。IIFE 場景下請注意源碼注釋提到的一點當(dāng)通過script手工加載 bundle 后從 vanilla JS 傳入顯式的空字符串shader: 不會被當(dāng)作省略而會走到著色器注冊表并拋出明確的 unknown shader 錯誤這是刻意的嚴(yán)格行為見 registry.ts 的getFragSource()。三、核心 APIinit(config): GsapTimeline所有能力都收斂到init()一個函數(shù)。基本用法import { init } from hyperframes/shader-transitions; const tl init({ bgColor: #0a0a0a, // 場景捕獲時的兜底背景色 accentColor: #ff6b2b, // 著色器輝光效果強調(diào)色 scenes: [scene-1, scene-2, scene-3], transitions: [ { time: 3, shader: domain-warp, duration: 0.8 }, { time: 8, shader: light-leak, duration: 0.7 }, ], });3.1 配置項全表選項類型必填說明bgColorstring是場景捕獲時的兜底背景色hex。應(yīng)使用組合的 body/canvas 背景色——每個場景通過 CSS 自行設(shè)置各自的background-coloraccentColorstring否著色器輝光效果的強調(diào)色hexscenesstring[]是各場景元素的 ID按順序排列transitionsTransitionConfig[]是轉(zhuǎn)場定義數(shù)組見下文timelineGsapTimeline否已有的 GSAP 時間線把轉(zhuǎn)場疊加到它上面compositionIdstring否覆蓋data-composition-id用于時間線注冊previewCaptureFpsnumber否瀏覽器預(yù)覽模式每秒鐘為每個轉(zhuǎn)場預(yù)捕獲的采樣幀數(shù)。默認(rèn)30渲染模式則改為確定性的逐幀合成不使用此值3.2 底層行為印證對照 hyper-shader.ts 的init()實現(xiàn)可以確認(rèn)以下細(xì)節(jié)組合畫布尺寸優(yōu)先讀取根元素帶data-composition-id的元素上的data-width/data-height屬性缺失或非法時回退到1920 × 1080常量DEFAULT_WIDTH/DEFAULT_HEIGHT定義于 webgl.ts。compositionId的解析順序是config.compositionId→ 根元素data-composition-id→main。強調(diào)色三檔化單個accentColor會在內(nèi)部被推導(dǎo)成三檔 RGB 用于片元著色器 uniformu_accent、u_accent_dark約乘 0.35與u_accent_bright約1.5x0.2后截斷到 1。未提供時使用默認(rèn)橙色三檔[1, 0.6, 0.2]/[0.4, 0.15, 0]/[1, 0.85, 0.5]。預(yù)覽采樣速率previewCaptureFps默認(rèn) 30并在取值上被鉗制到1 ~ 60之間非法值NaN/非正數(shù)回退到默認(rèn)值。WebGL 畫布包會在組合根元素或body下創(chuàng)建一個idgl-canvas的透明覆蓋 canvas樣式為position:absolute; top:0; left:0; z-index:100; pointer-events:none尺寸與組合一致WebGL 上下文開啟preserveDrawingBuffer以便后續(xù)讀取。著色器程序所有用到的著色器會按名稱去重編譯并緩存到programsMap單個著色器編譯失敗只打印[HyperShader] Failed to compile ...不影響其他轉(zhuǎn)場。著色器間插值由于捕獲幀是離散的兩個相鄰采樣幀之間由包內(nèi)置的一個mix(texture2D(u_a), texture2D(u_b), u_mix)混合程序blend program做線性插值配合紋理交錯機制保證預(yù)覽中的轉(zhuǎn)場依然連續(xù)。3.3 組合到已有時間線如果你的頁面已經(jīng)有自己的 GSAP 時間線例如已寫好每個場景的進(jìn)入/退出動畫可以把時間線傳入轉(zhuǎn)場會被疊到上面而不是另起爐灶import { init } from hyperframes/shader-transitions; import { gsap } from gsap; const tl gsap.timeline({ paused: true }); // ... add your scene animations ... init({ bgColor: #000, scenes: [intro, demo, outro], transitions: [ { time: 5, shader: cinematic-zoom }, // duration/ease 走默認(rèn)值 { time: 12, shader: glitch, duration: 0.5 }, ], timeline: tl, });傳入timeline時包不會把返回值重新注冊到全局window.__timelines[compositionId]注冊只發(fā)生在由包自建時間線的情況下見 hyper-shader.ts 的registerTimeline()。四、TransitionConfig與SHADER_NAMES每個轉(zhuǎn)場由TransitionConfig描述選項類型默認(rèn)值說明timenumber—轉(zhuǎn)場開始時間秒shaderShaderName—上表中的著色器名。注意源碼類型中它是可選的省略undefined時該轉(zhuǎn)場退化為 CSS 交叉淡入淡出不依賴 WebGLdurationnumber0.7轉(zhuǎn)場持續(xù)時長秒easestringpower2.inOutGSAP 緩動函數(shù)默認(rèn)值0.7與power2.inOut在兩個模式瀏覽器預(yù)覽、引擎確定性渲染和元數(shù)據(jù)寫入中共用同一組常量DEFAULT_DURATION/DEFAULT_EASE保證預(yù)覽里怎么動、引擎 seek 時怎么動、producer 讀取元數(shù)據(jù)時按什么參數(shù)合成三者完全一致。SHADER_NAMES導(dǎo)出全部著色器名字符串?dāng)?shù)組可用于參數(shù)校驗或構(gòu)建下拉 UIimport { SHADER_NAMES } from hyperframes/shader-transitions; // [domain-warp, ridged-burn, whip-pan, ...]它在源碼中由注冊表對象的鍵推導(dǎo)而來ShaderName keyof typeof shaders查找未知名稱會拋出[HyperShader] Unknown shader: xxx. Available: ...見 registry.ts。4.1 可用著色器一覽著色器描述domain-warp基于噪聲的有機扭曲帶發(fā)光邊緣ridged-burn脊?fàn)顁idged噪聲灼燒帶火花與熱輝光whip-pan水平運動模糊模擬快速甩鏡sdf-iris圓形光圈擦除iris wipe帶發(fā)光環(huán)邊ripple-waves從中心輻射的同心漣漪扭曲gravitational-lens引力透鏡式扭曲帶色差cinematic-zoom徑向縮放模糊帶色邊chromatic-split從中心向外的 RGB 通道分離glitch數(shù)字故障塊狀位移 掃描線swirl-vortex基于噪聲扭曲的螺旋旋轉(zhuǎn)thermal-distortion從畫面底部升騰的熱浪擾動flash-through-white閃白后揭示下一場景cross-warp-morph噪聲驅(qū)動的雙場景形變混合light-leak暖色電影漏光 鏡頭光暈4.2 共享著色器基礎(chǔ)設(shè)施所有片元著色器并非憑空獨立而是拼接自公共頭部理解這一點有助于二次開發(fā)頂點著色器把a_pos-1..1的四邊形映射為v_uv并做 Y 軸翻轉(zhuǎn)適配 WebGL 坐標(biāo)系見 common.ts每個片元著色器頭部H常量統(tǒng)一聲明了這些 uniformu_from/u_to出境/入境兩張紋理、u_progress0→1 進(jìn)度、u_resolution分辨率、u_accent/u_accent_dark/u_accent_bright三檔強調(diào)色需要噪聲的著色器會拼入NQ常量——基于 hash 的 value noise 五次平滑插值 旋轉(zhuǎn)各向異性的 5 層 FBM。也就是說紋理對u_from、u_to 一個進(jìn)度標(biāo)量是所有轉(zhuǎn)場的通用數(shù)據(jù)契約gl_FragColor的寫法是按進(jìn)度/噪聲混合兩幀再疊加強調(diào)色效果。均勻值由 webgl.ts 的renderShader()統(tǒng)一寫入采樣器綁定 TEXTURE0/TEXTURE1進(jìn)度、分辨率、三檔顏色逐一uniform*程序與 uniform 位置都做了緩存以省去重復(fù)查詢。五、運行架構(gòu)預(yù)捕獲 → 著色器合成 → GSAP 時間線瀏覽器預(yù)覽模式下一次轉(zhuǎn)場周期的數(shù)據(jù)流如下對應(yīng)init()后半段邏輯見 hyper-shader.ts初始化時按scenes.length transitions.length 1校驗例如 3 個場景配 2 個轉(zhuǎn)場違反會直接拋錯隨后逐個檢查場景 ID 存在于 DOM 中且?guī)?sceneclass兩類問題會分別拋出清晰錯誤scene ids not found in DOM: .../elements found but missing .scene class: ...。為每個轉(zhuǎn)場預(yù)編譯對應(yīng)的 GLSL 程序。轉(zhuǎn)場前開始預(yù)捕獲對出境場景與入境場景按previewCaptureFps采樣動畫幀。捕獲結(jié)果先以 PNG Blob 形式寫入 IndexedDB見第六節(jié)播放前按需把 Blob 解碼成ImageBitmap/Image再上傳為 WebGL 紋理。播放進(jìn)入轉(zhuǎn)場窗口時u_progress隨時間線推進(jìn)映射到duration與ease著色器每幀對兩張紋理做混合結(jié)果直接繪制到覆蓋在頁面上的gl-canvas。播放經(jīng)過轉(zhuǎn)場窗口后隱藏 GL 畫布露出持續(xù)推進(jìn)中的入境場景 DOM畫面無縫銜接。整個過程里init()返回的GsapTimeline才是組合時間線的真相來源——無論轉(zhuǎn)場是著色器合成還是 CSS 交叉淡入淡出都可以被暫停、seek、play與 HyperFrames 的既有播放體系兼容。5.1 WebGL 不可用與 CSS 交叉淡入淡出降級兩條獨立的降級路徑需要分清無 WebGL 環(huán)境createContext()返回空init()打印警告并直接返回普通時間線轉(zhuǎn)場退化為硬切場景動畫完全正常。某項轉(zhuǎn)場未指定shadershader undefined該轉(zhuǎn)場以 CSS opacity 交叉淡入淡出執(zhí)行不需要 WebGL。在引擎渲染模式下這樣的條目會被安排成真實的 opacity tween詳見第七節(jié)保證單幀截圖里就包含正確的混合結(jié)果。六、場景捕獲管線從 html2canvas 到原生 HTML-in-Canvas把 DOM 場景變成紋理是整套方案最脆弱也最關(guān)鍵的部分。包支持兩條捕獲路徑策略代碼見 capture.ts。原生 HTML-in-Canvas首選當(dāng)瀏覽器暴露 Chrome 實驗性的 CanvasDrawElement API 時使用layoutSubtreecanvas drawElementImage()直接繪制 DOM。實現(xiàn)細(xì)節(jié)包括把場景克隆進(jìn)一個position:fixed; z-index:-9999; opacity:0的 layoutsubtree canvas等待兩個requestAnimationFrame讓瀏覽器完成布局/繪制用bgColor填充底色再drawElementImage讀出畫面并復(fù)制到結(jié)果 canvas。該路徑失敗時自動回退到 html2canvas。html2canvas 回退html2canvas抓取時為避免 Safari 的畫布污染SecurityError: The operation is insecure固定開啟useCORS: true與allowTaint: true。這里有一個值得注意的工程取舍t(yī)ainted canvas 無法被gl.texImage2D上傳WebGL 規(guī)范強制 SecurityError所以allowTaint的實際作用是把失敗點從 html2canvas 內(nèi)部挪到更可控的紋理上傳處由調(diào)用方統(tǒng)一兜底。此外還提供foreignObjectRendering嘗試開關(guān)失敗自動回退到常規(guī)渲染、onclone中把帶 transform 的box-shadow抽取成獨立 shim 元素因為變換會破壞陰影柵格化、強制克隆場景可見等處理。用isHtmlInCanvasCaptureSupported()可以自行做特性檢測源碼判定存在layoutSubtree屬性 2D 上下文具備drawElementImage函數(shù)對應(yīng)測試見 capture.test.ts驗證了非瀏覽器環(huán)境返回 false、能力齊備返回 true、缺drawElementImage返回 false 三種情況。另外捕獲對零尺寸 pattern 有個 Safari 相關(guān)防御補丁重寫CanvasRenderingContext2D.prototype.createPattern當(dāng)傳入 0×0 的 canvas 時返回null而不是讓瀏覽器拋錯initCapture()。6.1 瀏覽器預(yù)覽快照的 IndexedDB 緩存每次刷新頁面都重新捕獲幾十上百幀顯然不劃算因此瀏覽器預(yù)覽的快照會被持久化數(shù)據(jù)庫名為hyper-shader-preview-cacheobject store 名為framesschema 版本v1常量見 hyper-shader.ts。緩存鍵由composition ID、場景 DOM/樣式簽名、轉(zhuǎn)場時序、捕獲 FPS、縮放與畫布尺寸綜合推導(dǎo)。DOM/樣式簽名不是簡單 hash它基于文檔內(nèi)所有style文本、link relstylesheet及腳本特征的stableHash場景自身的簽名還會在計算前剔除播放過程中被運行時改寫的opacity/visibility/pointer-events等內(nèi)聯(lián)樣式從而讓緩存身份追蹤作者寫的內(nèi)容而非上次預(yù)覽的播放頭狀態(tài)。刷新后若鍵匹配快照直接加載為 WebGL 紋理不再重捕。運行中編輯場景或樣式表時只會把相鄰轉(zhuǎn)場的緩存標(biāo)記為 dirty重捕推遲到真正播放到那個轉(zhuǎn)場時才發(fā)生保證編輯器操作期間交互不卡頓。緩存總量上限為 1200 條MAX_SNAPSHOT_CACHE_ENTRIES寫入時按updatedAt淘汰最舊條目并清理當(dāng)前 composition 的失效鍵。6.2 預(yù)捕獲階段的加載反饋首次播放前的快照準(zhǔn)備可能需要一段時間包內(nèi)置了一套全屏加載反饋覆蓋層包含品牌圖形、進(jìn)度短語與逐 transition / 逐 frame 的進(jìn)度數(shù)字短語按進(jìn)度切換Preparing scene transitions、Sampling outgoing scene motion 等。該覆蓋層帶data-hyperframes-ignore、data-no-capture、data-no-pick等標(biāo)記確保它不會污染捕獲與拾取邏輯。播放器接管 vs 內(nèi)置加載 UI當(dāng)頁面由hyperframes-player承載時瀏覽器預(yù)覽的捕獲縮放與轉(zhuǎn)場預(yù)加載 UI 的所有權(quán)歸屬播放器對應(yīng)屬性shader-capture-scale、shader-loading而不是組合代碼非播放器的直接預(yù)覽則保留內(nèi)置的全保真加載兜底。實現(xiàn)上捕獲縮放系數(shù)讀取全局變量__HF_SHADER_CAPTURE_SCALE或查詢參數(shù)__hf_shader_capture_scale解析后鉗制在0.25 ~ 1默認(rèn) 1加載模式讀取__HF_SHADER_LOADING或__hf_shader_loading取值player/true→ 播放器接管、none/false/off→ 關(guān)閉、其余 →internal內(nèi)置覆蓋層。七、引擎渲染模式確定性逐幀輸出瀏覽器里人眼看 30fps 預(yù)捕獲足夠但視頻渲染引擎要求每一幀都精確確定。init()會探測window.__HF_VIRTUAL_TIME__標(biāo)記引擎在渲染模式注入的虛擬時間 shim見 hyper-shader.ts一旦檢測到就切換到initEngineMode()完全跳過所有 GL / canvas / html2canvas 分支只構(gòu)建一條確定性的透明度翻轉(zhuǎn)時間線非首場景初始全部opacity: 0用tl.set(..., 0)掛進(jìn)時間線開頭保證逆向 seek 也能恢復(fù)正確初態(tài)。對著色器轉(zhuǎn)場轉(zhuǎn)場窗口內(nèi)from/to 兩場景都保持opacity: 1出境場景在time duration時刻降到 0——這樣引擎的 Node 端分層合成器能分別獨立捕獲兩場景再自行混合。對 CSS 交叉淡入淡出安排真實的 opacity tweenfromTo保證單幀頁面截圖本身已包含正確的混合結(jié)果。使用tl.set()零時長 tween而不是tl.call()因為tl.call只在運動方向上觸發(fā)引擎 warmup 會正向 seek 到各轉(zhuǎn)場起點、隨后又反向 seek 回 t0回調(diào)態(tài)會卡住而set可隨反向 seek 正確還原。引擎讀取合成的依據(jù)是init()同步寫入window.__hf.transitions的元數(shù)據(jù)數(shù)組每項含time、duration、shader、ease、fromScene、toScene缺省 duration/ease 時同樣使用 0.7 /power2.inOut。該結(jié)構(gòu)刻意在包內(nèi)本地重聲明不 import engine 的類型以保持 CDN 獨立并與 engine 的HfTransitionMeta保持同步注釋中明確說明。7.1 可選的頁面端合成器engine-mode page compositing當(dāng) producer 以EngineConfig.enablePageSideCompositing: true啟動并注入window.__HF_PAGE_SIDE_COMPOSITING__哨兵時引擎模式還會安裝一個頁面端 WebGL 合成器installPageSideCompositor()導(dǎo)出見 index.ts實現(xiàn)見 engineModePageComposite.ts讓單次整頁截圖也能得到與預(yù)覽路徑一致的原生保真捕獲。它采用兩階段協(xié)議Phase 1seek 包裝包裝window.__hf.seek。進(jìn)入轉(zhuǎn)場窗口時把 FROM/TO 場景克隆進(jìn)兩個常駐的 layoutsubtree staging canvas并設(shè)window.__hf_page_composite_pending。Paint force引擎?zhèn)纫鏅z測到 pending 標(biāo)記后觸發(fā)一次微型的Page.captureScreenshot強制瀏覽器合成器把 staging canvas 的克隆繪制出來。Phase 2resolve引擎調(diào)用window.__hf_page_composite_resolve用drawElementImage從已繪制克隆讀出畫面、上傳紋理、跑著色器并顯示 GL 覆蓋層最后清理 staging?？寺r會把各自getBoundingClientRect()實測到的盒模型left/top/width/height固定到克隆上——這是為了規(guī)避僅靠inset:0定位的場景克隆進(jìn) layout subtree 后坍縮成 0×0的已知問題同時強制克隆可見、解碼 contenteditable="false">【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考