剛接觸bgfx的開(kāi)發(fā)者十有八九會(huì)卡在shader編譯這一步。明明寫(xiě)的是HLSL在Visual Studio里也能正常調(diào)可一進(jìn)bgfx工程就報(bào)一堆莫名錯(cuò)誤或者干脆編譯出來(lái)渲染黑屏。這篇文章我就專(zhuān)門(mén)聊“bgfx shader編譯Windows下HLSL為例”這件事從工具鏈搭建、shader編寫(xiě)規(guī)范、shaderc命令解析到運(yùn)行時(shí)加載和問(wèn)題排查完整走一遍。準(zhǔn)備入坑bgfx圖形開(kāi)發(fā)、或者已經(jīng)在用但想徹底搞懂shader鏈路的朋友都可以參考。我不會(huì)把命令參數(shù)全列一遍而是把“為什么這么編譯”背后的邏輯講清楚這樣你換到Linux、Android甚至Vulkan后端時(shí)也能自己推斷該用什么參數(shù)。1. 先搞懂bgfx的shader編譯流水線(xiàn)1.1 一份著色器源碼是怎么變成DXBC的bgfx的shader編譯和普通DirectX工程最大的區(qū)別在于它不是直接把HLSL編譯成你能丟給D3D的字節(jié)碼就完事。bgfx要同時(shí)支持D3D11、D3D12、OpenGL、Vulkan、Metal這些后端它自己的runtime不可能為每種后端維護(hù)一套完全不同的shader加載邏輯所以它做了一個(gè)抽象層。你在bgfx工程里寫(xiě)的shader本質(zhì)上是“bgfx方言”的HLSL/GLSL。源碼頂部要么寫(xiě)著#include bgfx_shader.sh要么使用了$input、$output這種以美元符號(hào)開(kāi)頭的預(yù)處理器指令。這些語(yǔ)法真正的HLSL編譯器不認(rèn)識(shí)它認(rèn)識(shí)的是bgfx附帶的那套頭文件。整個(gè)編譯鏈路大致是這樣源文件先由shaderc工具做預(yù)處理把bgfx_shader.sh里的宏展開(kāi)再根據(jù)目標(biāo)平臺(tái)生成對(duì)應(yīng)的語(yǔ)言形態(tài)最終翻譯成目標(biāo)后端需要的字節(jié)碼。以Windows D3D11為例最終輸出的.bin文件內(nèi)部負(fù)載就是DXBC字節(jié)碼。但要注意這個(gè)bin并不等同于你用fxc.exe編譯出來(lái)的.cso或.dxbc文件bgfx在bin文件外層還包了一個(gè)自己定義的文件頭包含了版本號(hào)、校驗(yàn)信息、shader長(zhǎng)度等字段。加載時(shí)runtime會(huì)先檢查這個(gè)文件頭確認(rèn)格式和當(dāng)前renderer匹配才會(huì)把里面的DXBC負(fù)載交給D3D。這就回答了一個(gè)新手常問(wèn)的問(wèn)題能不能把我在VS里右鍵編譯出來(lái)的HLSL字節(jié)碼直接拿過(guò)來(lái)用答案是不能因?yàn)閎gfx的runtime根本不認(rèn)識(shí)那種裸格式。你得經(jīng)過(guò)shaderc重新走一遍抽象層流程輸出bgfx定義的封裝格式。1.2 為什么要做這么一層抽象而不是各平臺(tái)各寫(xiě)一份很多從Unity、Unreal轉(zhuǎn)過(guò)來(lái)的人會(huì)有一個(gè)直覺(jué)跨平臺(tái)shader不就是用#ifdef寫(xiě)分支嗎寫(xiě)個(gè)#ifdef D3D11、#ifdef VULKAN然后分別調(diào)不同語(yǔ)法不就行了。問(wèn)題在于HLSL和GLSL的差異不只是幾個(gè)函數(shù)名而是從變量聲明、語(yǔ)義綁定、資源綁定位一直到矩陣運(yùn)算順序都不同。靠手工#ifdef維護(hù)shader越多維護(hù)成本越高。bgfx的做法是提供一套公用的“詞匯表”把兩邊都有的概念統(tǒng)一命名vec3、vec4、mat4、texture2D、gl_Position、gl_FragColor、mul。然后bgfx_shader.sh針對(duì)不同后端把這些詞映射成真正HLSL或GLSL的寫(xiě)法和內(nèi)置函數(shù)。你可以把bgfx_shader.sh當(dāng)成一本“方言詞典”。shaderc在解析源碼時(shí)會(huì)自動(dòng)根據(jù)--platform windows和-p vs_5_0/ps_5_0這類(lèi)參數(shù)定義BGFX_SHADER_LANGUAGE_HLSL宏于是一份源碼在不同的編譯參數(shù)下會(huì)產(chǎn)生完全不同的實(shí)際代碼。真正做到了“源碼一份多端復(fù)用”。這在工程上的價(jià)值非常大尤其是你手里有幾十個(gè)shader的時(shí)候不必為每個(gè)平臺(tái)維護(hù)一份拷貝。1.3 平臺(tái)、編譯參數(shù)和runtime后端的對(duì)應(yīng)關(guān)系理解平臺(tái)、profile和runtime后端的關(guān)系是避開(kāi)“編譯通過(guò)卻黑屏”的關(guān)鍵。shaderc的--platform參數(shù)不是最終決定輸出格式的唯一條件真正決定輸出格式的是-p后面的profile。常用對(duì)應(yīng)關(guān)系如下運(yùn)行時(shí)后端編譯參數(shù)舉例輸出內(nèi)容Direct3D11 / Direct3D12--platform windows -p vs_5_0/ps_5_0DXBC字節(jié)碼封裝在bgfx bin內(nèi)OpenGL--platform linux -p glslGLSL文本以C字符串形式存在bin負(fù)載里Vulkan--platform windows -p spirv15SPIR-V字節(jié)碼Metal--platform osx -p metalMetal后端可識(shí)別的字節(jié)碼這里最容易踩的坑是你編譯shader時(shí)一切正常但運(yùn)行時(shí)用的是另一個(gè)renderer。比如你在Windows上默認(rèn)初始化了D3D11后端卻加載了一份用-p glsl編譯的binruntime會(huì)直接拒絕使用表現(xiàn)就是物體不渲染或者控制臺(tái)出現(xiàn)backend mismatch的日志。我在實(shí)際項(xiàng)目里的習(xí)慣是明確調(diào)用bgfx::init時(shí)傳入指定的renderer類(lèi)型比如bgfx::RendererType::Direct3D11然后編譯shader時(shí)嚴(yán)格按這個(gè)renderer選profile。Windows上一般用vs_5_0/ps_5_0最穩(wěn)因?yàn)镈3D11和D3D12后端都接受DXBC而且vs_5_0對(duì)硬件要求已經(jīng)不高兼容性比vs_4_0更好。2. 環(huán)境準(zhǔn)備拿到能用的shaderc2.1 兩種獲取shaderc的方式編譯bgfx shader離不開(kāi)shaderc這個(gè)命令行工具。獲取方式有兩種直接使用官方預(yù)編譯的二進(jìn)制或者自己從源碼構(gòu)建。預(yù)編譯的好處是省事適合只想跑通流程的讀者版本一般也比較穩(wěn)定。但如果你修改了bgfx源碼、或者需要跟進(jìn)最新主分支的特性就必須自己編譯。自己編譯需要準(zhǔn)備三個(gè)倉(cāng)庫(kù)bgfx本身依賴(lài)bx和bimg。這三個(gè)倉(cāng)庫(kù)要放在同級(jí)目錄下比如libs/bgfx、libs/bx、libs/bimg。整個(gè)構(gòu)建工作如果用premake5大概是這樣cd bgfx premake5.exe --with-tools vs2022然后打開(kāi)生成的Visual Studio解決方案找到Tools文件夾下的shaderc工程編譯Release版本。輸出通常在tools/bin/windows/下文件名是shaderc.exe。如果不想手動(dòng)打開(kāi)VSbgfx倉(cāng)庫(kù)的scripts目錄下還提供了一些現(xiàn)成腳本比如build_vs2022.bat運(yùn)行后會(huì)自動(dòng)把依賴(lài)?yán)饋?lái)并編譯工具鏈。我第一次自己構(gòu)建時(shí)就是直接用這個(gè)腳本比手敲premake命令省心不少。還有一種方式是cmake新版bgfx支持直接配置cmake -S . -B build -DBGFX_BUILD_TOOLSON cmake --build build --target shaderc --config Release兩條路都通喜歡哪個(gè)用哪個(gè)。個(gè)人建議第一次跑通流程可以走premake因?yàn)楣俜绞纠臀臋n基本都是這個(gè)姿勢(shì)。2.2 把運(yùn)行環(huán)境一次配好include路徑和d3dcompiler拿到shaderc.exe之后第一件事不是急著編譯自己的shader而是確認(rèn)它能找到bgfx的公共頭文件。編譯任何bgfx shader都需要bgfx_shader.sh這個(gè)文件的路徑?jīng)Q定了你-i參數(shù)要指向哪里。我見(jiàn)過(guò)有些版本它放在include/目錄有些工程示例里又直接引用src/目錄下的文件穩(wěn)妥的辦法是編譯命令里把兩個(gè)目錄都加進(jìn)include搜索路徑shaderc.exe -f input.sc -o output.bin -i C:\libs\bgfx\include -i C:\libs\bgfx\src -i C:\libs\bgfx\examples\common ...反正-i可以重復(fù)指定多給一個(gè)目錄只會(huì)有益無(wú)害。如果源碼里還include了example里的公共shader頭文件比如common.sh那就必須加上examples/common。Windows下還有第二個(gè)坑shaderc生成DXBC字節(jié)碼時(shí)運(yùn)行時(shí)需要?jiǎng)討B(tài)加載d3dcompiler_47.dll。絕大多數(shù)Windows系統(tǒng)自帶這個(gè)DLL但某些精簡(jiǎn)版系統(tǒng)、或者CI容器里會(huì)缺失。表現(xiàn)是編譯命令一跑就報(bào)類(lèi)似“failed to load D3DCompiler”的錯(cuò)誤。解決方式也簡(jiǎn)單從安裝了DirectX SDK或者帶D3D的機(jī)器上找到d3dcompiler_47.dll放到shaderc.exe同目錄下即可。驗(yàn)證環(huán)境是否就緒最省事的方法是找bgfx官方examples里的某個(gè)shader源文件用examples自帶的那組編譯參數(shù)試跑一次。如果examples里的shader能正常編譯出bin說(shuō)明你的include路徑和DLL環(huán)境都沒(méi)問(wèn)題接下來(lái)才值得繼續(xù)往下折騰。3. 用HLSL寫(xiě)bgfx shader時(shí)必須知道的規(guī)范3.1 bgfx_shader.sh到底替你做了什么很多人第一次打開(kāi)bgfx的shader源文件會(huì)覺(jué)得自己看的是“長(zhǎng)得像GLSL但是又有點(diǎn)HLSL影子”的奇怪代碼。比如gl_Position、gl_FragColor、texture2D這些名字在真正的HLSL里根本不存在。這些其實(shí)都是bgfx抽象層提供的“替身”。bgfx_shader.sh內(nèi)部按BGFX_SHADER_LANGUAGE_*宏劃分了好幾個(gè)分支。當(dāng)你用--platform windows -p vs_5_0編譯時(shí)shaderc會(huì)自動(dòng)定義BGFX_SHADER_LANGUAGE_HLSL于是頭文件里所有抽象符號(hào)都會(huì)被映射成HLSL的對(duì)應(yīng)物。例如vec3映射成float3texture2D(s_tex, uv)映射成s_tex.Sample(s_tex##_sampler, uv)這類(lèi)寫(xiě)法gl_Position映射成SV_Positiongl_FragColor映射成SV_Target0這層翻譯不是運(yùn)行時(shí)發(fā)生的而是在編譯期就已經(jīng)完成。所以你寫(xiě)shader時(shí)要遵守bgfx的“方言”而不是想當(dāng)然地直接寫(xiě)原生HLSL關(guān)鍵字。比如你在shader里寫(xiě)了一個(gè)return float4(1,0,0,1);當(dāng)像素輸出這在純HLSL里合法但在bgfx抽象層里不會(huì)識(shí)別成最終輸出正確姿勢(shì)是給gl_FragColor賦值。3.2 $input/$output和varying.def.sc的聯(lián)動(dòng)關(guān)系bgfx的shader有一個(gè)獨(dú)立的“變量定義文件”通常叫varying.def.sc。它的作用相當(dāng)于一份跨平臺(tái)協(xié)議定義頂點(diǎn)shader的輸入屬性a_前綴、頂點(diǎn)shader輸出到像素shader的varyingv_前綴并規(guī)定語(yǔ)義綁定。一個(gè)典型的varying.def.sc長(zhǎng)這樣vec3 a_position : POSITION; vec4 a_color0 : COLOR0; vec2 v_texcoord0 : TEXCOORD0;而shader源文件頂部會(huì)有對(duì)應(yīng)的聲明$input a_position, a_color0 $output v_texcoord0 #include bgfx_shader.sh$input和$output是shaderc的預(yù)處理器指令。$input a_position表示這個(gè)shader會(huì)使用頂點(diǎn)屬性a_position$output v_texcoord0表示頂點(diǎn)shader要輸出一個(gè)名為v_texcoord0的varying給像素shader。shaderc會(huì)把這兩行指令和varying.def.sc里的定義自動(dòng)拼成合適的結(jié)構(gòu)體代碼再參與后續(xù)編譯。如果varying.def.sc里沒(méi)定義某個(gè)v_texcoord1但shader里寫(xiě)了$output v_texcoord1編譯會(huì)直接報(bào)錯(cuò)。反過(guò)來(lái)定義了卻沒(méi)用到一般不會(huì)報(bào)錯(cuò)但會(huì)有冗余。這就是為什么在調(diào)shader時(shí)報(bào)錯(cuò)信息里會(huì)出現(xiàn)v_texcoord0、a_position這些名字因?yàn)檫@些名字是跨C頂點(diǎn)布局和shader代碼之間的“合同”。3.3 uniform和采樣器的聲明方式bgfx的uniform聲明和原生HLSL也不一樣。在bgfx shader里你會(huì)看到這樣的代碼uniform vec4 u_color; uniform mat4 u_mvp; SAMPLER2D(s_texColor, 0);uniform vec4 u_color并不是真的向D3D暴露一個(gè)cbuffer成員而是bgfx抽象層的寫(xiě)法。編譯成HLSL后端時(shí)shaderc會(huì)把它們打包進(jìn)一個(gè)名為uniform的cbuffer里并且給每個(gè)變量分配register。SAMPLER2D(s_texColor, 0)的第二個(gè)參數(shù)0是bind point也就是紋理的注冊(cè)槽位。這帶來(lái)一個(gè)非常容易踩的坑C端createUniform傳的字符串名字必須和shader里的變量名完全一致大小寫(xiě)都不能錯(cuò)。bgfx運(yùn)行時(shí)是靠名字去查找shader里的uniform而不是靠register索引。所以shader里寫(xiě)u_colorC端就要bgfx::createUniform(u_color, ...)寫(xiě)成U_COLOR或者ucolor都會(huì)導(dǎo)致uniform綁定不上shader在驅(qū)動(dòng)里用的是默認(rèn)值0最終渲染結(jié)果就是黑的或者全透明的。采樣器也是這樣SAMPLER2D(s_texColor, 0)對(duì)應(yīng)C端bgfx::createUniform(s_texColor, bgfx::UniformType::Sampler)。名字對(duì)不上紋理采樣結(jié)果就是全0。3.4 HLSL語(yǔ)法在bgfx抽象層里的幾個(gè)易錯(cuò)點(diǎn)第一個(gè)易錯(cuò)點(diǎn)是矩陣乘法。HLSL的mul(a, b)和GLSL的a * b的運(yùn)算順序習(xí)慣不同。bgfx在bgfx_shader.sh里統(tǒng)一提供了mul宏你在shader里應(yīng)該一直用mul(u_mvp, vec4(pos, 1.0))而不是自己用*符號(hào)去乘矩陣和向量。否則同一份shader在D3D后端正常切到GL后端就出現(xiàn)矩陣錯(cuò)亂物體全部變形。第二個(gè)易錯(cuò)點(diǎn)是函數(shù)名差異。GLSL的fract對(duì)應(yīng)HLSL的fracGLSL的texture對(duì)應(yīng)HLSL的Texture2D.Sample。bgfx抽象層統(tǒng)一采用fract、texture2D這類(lèi)寫(xiě)法。你如果在shader里隨手寫(xiě)了frac用D3D后端編譯沒(méi)問(wèn)題但換到GL后端時(shí)bgfx_shader.sh找不到這個(gè)宏直接報(bào)編譯錯(cuò)誤。第三個(gè)易錯(cuò)點(diǎn)是充分理解gl_FragColor的抽象。寫(xiě)顏色輸出時(shí)不要試圖在同一個(gè)shader里既用gl_FragColor又用HLSL的SV_Target語(yǔ)義。尤其在fragment shader里老老實(shí)實(shí)用gl_FragColor vec4(...)這一套讓抽象層去處理。這東西有點(diǎn)像程序員寫(xiě)跨平臺(tái)UI代碼不要試圖繞開(kāi)框架層去直接操作底層窗口句柄框架會(huì)替你處理差異前提是你得遵循它的規(guī)則。4. 完整實(shí)操?gòu)膶?xiě)代碼到運(yùn)行全程走一遍4.1 準(zhǔn)備一個(gè)編譯用的shader工程目錄我建議從一開(kāi)始就建一個(gè)固定目錄結(jié)構(gòu)方便后續(xù)自動(dòng)化構(gòu)建。我自己的習(xí)慣是這樣的myproject/ shaders/ varying.def.sc vs_simple.sc fs_simple.sc build_shaders.bat bin/build_shaders.bat用來(lái)批量執(zhí)行編譯命令bin/專(zhuān)門(mén)存生成的bin文件?，F(xiàn)在寫(xiě)一個(gè)最簡(jiǎn)單的帶紋理的shader。varying.def.scvec3 a_position : POSITION; vec2 v_texcoord0 : TEXCOORD0;頂點(diǎn)shadervs_simple.sc$input a_position $output v_texcoord0 #include bgfx_shader.sh uniform mat4 u_mvp; SAMPLER2D(s_texColor, 0); void main() { gl_Position mul(u_mvp, vec4(a_position, 1.0)); v_texcoord0 a_position.xy * 0.5 0.5; }這里我把頂點(diǎn)坐標(biāo)簡(jiǎn)單映射到UV坐標(biāo)方便預(yù)覽。像素shaderfs_simple.sc$input v_texcoord0 #include bgfx_shader.sh uniform vec4 u_color; SAMPLER2D(s_texColor, 0); void main() { vec4 tex texture2D(s_texColor, v_texcoord0); gl_FragColor tex * u_color; }注意fragment shader頂部只需要聲明$input v_texcoord0不需要$output因?yàn)閎gfx固定用gl_FragColor作為輸出變量已經(jīng)在bgfx_shader.sh里定義好了。4.2 用shaderc編譯出bin的完整命令拆解編譯頂點(diǎn)shader的命令C:\libs\bgfx\tools\bin\windows\shaderc.exe -f vs_simple.sc -o ../bin/vs_simple.bin -i C:\libs\bgfx\include -i C:\libs\bgfx\src -i . --type vertex --platform windows -p vs_5_0 --varyingdef varying.def.sc --verbose編譯像素shader的命令C:\libs\bgfx\tools\bin\windows\shaderc.exe -f fs_simple.sc -o ../bin/fs_simple.bin -i C:\libs\bgfx\include -i C:\libs\bgfx\src -i . --type fragment --platform windows -p ps_5_0 --varyingdef varying.def.sc --verbose逐參數(shù)過(guò)一遍-f指定輸入shader源文件。-o指定輸出bin文件路徑。-i指定include目錄可以重復(fù)寫(xiě)多個(gè)。前面提到的bgfx_shader.sh能不能找到就靠這個(gè)參數(shù)。--type告訴shaderc這是vertex還是fragment。一個(gè)常見(jiàn)的低級(jí)錯(cuò)誤是頂點(diǎn)shader用了--type fragment或者fragment shader用了vs_5_0的profile。頂點(diǎn)shader用vs_開(kāi)頭像素shader用ps_開(kāi)頭。--platform windows指定目標(biāo)平臺(tái)。這個(gè)參數(shù)會(huì)影響shaderc自動(dòng)定義的平臺(tái)宏。-p vs_5_0 / ps_5_0是profile。Windows D3D11/12后端推薦用vs_5_0和ps_5_0。--varyingdef指到varying.def.sc的路徑。shaderc靠它來(lái)解析$input/$output指令。--verbose打開(kāi)詳細(xì)輸出能看到shaderc實(shí)際怎么處理宏分支排錯(cuò)很好用。把這兩條命令寫(xiě)進(jìn)build_shaders.bat以后每次改shader雙擊運(yùn)行一下就能批量生成bin文件。4.3 在C運(yùn)行時(shí)加載和使用編譯好的shaderC端的加載流程分三步。第一步讀文件第二步創(chuàng)建bgfx的ShaderHandle第三步把頂點(diǎn)和像素shader綁定成ProgramHandle。讀文件的方式很多核心是把二進(jìn)制內(nèi)容拷貝進(jìn)bgfx::Memory結(jié)構(gòu)。最簡(jiǎn)單的手寫(xiě)讀取const bgfx::Memory* loadShader(const char* path) { FILE* f fopen(path, rb); if (!f) return nullptr; fseek(f, 0, SEEK_END); long sz ftell(f); fseek(f, 0, SEEK_SET); const bgfx::Memory* mem bgfx::alloc((uint32_t)sz); fread(mem-data, 1, sz, f); fclose(f); return mem; }然后創(chuàng)建programbgfx::ShaderHandle vs bgfx::createShader(loadShader(bin/vs_simple.bin)); bgfx::ShaderHandle fs bgfx::createShader(loadShader(bin/fs_simple.bin)); if (!bgfx::isValid(vs) || !bgfx::isValid(fs)) { // 處理shader創(chuàng)建失敗比如renderer不匹配、bin文件損壞 } bgfx::ProgramHandle program bgfx::createProgram(vs, fs, true);createProgram的第三個(gè)參數(shù)傳true表示program創(chuàng)建成功后會(huì)銷(xiāo)毀兩個(gè)shader handle不需要再手動(dòng)調(diào)bgfx::destroy。這個(gè)函數(shù)是bgfx提供的重載版本實(shí)際項(xiàng)目里非常常用。如果你不想把bin文件放在磁盤(pán)上想直接打進(jìn)可執(zhí)行文件里可以先用bgfx自帶的bin2c工具把bin轉(zhuǎn)成C數(shù)組然后在代碼里用bgfx::makeRef創(chuàng)建Memory對(duì)象extern const uint8_t vs_simple_bin[]; bgfx::ShaderHandle vs bgfx::createShader( bgfx::makeRef(vs_simple_bin, sizeof(vs_simple_bin)) );這種方式對(duì)移動(dòng)端和發(fā)布工程很友好不用考慮工作目錄和資源路徑問(wèn)題。4.4 把shader編譯嵌進(jìn)自動(dòng)構(gòu)建流程手動(dòng)雙擊build腳本的方式只適合前期調(diào)試項(xiàng)目一旦上了規(guī)模shader幾十個(gè)甚至上百個(gè)就必須把編譯流程嵌進(jìn)自動(dòng)構(gòu)建里。最簡(jiǎn)單的方案是Visual Studio的pre-build event。在工程設(shè)置里添加命令call $(ProjectDir)shaders\build_shaders.bat也可以走CMake用add_custom_command精確控制依賴(lài)關(guān)系add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/bin/vs_simple.bin COMMAND ${BGFS_SHADERC} -f vs_simple.sc -o ${CMAKE_CURRENT_BINARY_DIR}/bin/vs_simple.bin -i ${BGFS_ROOT}/include -i ${BGFS_ROOT}/src -i ${CMAKE_CURRENT_SOURCE_DIR}/shaders --type vertex --platform windows -p vs_5_0 --varyingdef varying.def.sc DEPENDS vs_simple.sc varying.def.sc WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/shaders )這樣shader源文件一改動(dòng)重新編譯工程時(shí)shader的bin會(huì)自動(dòng)更新。能對(duì)構(gòu)建過(guò)程做增量管理是工程化的關(guān)鍵一步比每次手動(dòng)跑命令靠譜太多。5. 編譯報(bào)錯(cuò)與渲染黑屏常見(jiàn)問(wèn)題排查記錄5.1 高頻編譯ErrorMessage對(duì)照表shaderc的報(bào)錯(cuò)信息本身比較直白但很多錯(cuò)誤背后的原因首次接觸時(shí)容易抓瞎。我把實(shí)際中碰到的高頻報(bào)錯(cuò)整理成一張表方便對(duì)照排查報(bào)錯(cuò)特征常見(jiàn)原因解決方案fatal error: cant open file bgfx_shader.sh-i參數(shù)沒(méi)包含bgfx頭文件目錄把bgfx/include和bgfx/src加進(jìn)include搜索路徑unknown type vec4 / float4x4源碼文件忘了include bgfx_shader.sh或者宏分支沒(méi)生效檢查源碼開(kāi)頭有沒(méi)有#include bgfx_shader.sh確認(rèn)--platform和-p參數(shù)匹配varying variable v_texcoord0 is not definedvarying.def.sc里沒(méi)有定義這個(gè)v_變量在varying.def.sc里補(bǔ)全vec2 v_texcoord0 : TEXCOORD0;Invalid profile vs_5_0 for fragment像素shader用了頂點(diǎn)shader的profilefragment shader要用ps_5_0vertex再用vs_5_0Failed to load d3dcompiler_47.dll系統(tǒng)缺少D3D編譯器DLL手動(dòng)把d3dcompiler_47.dll放到shaderc.exe同目錄DXBC compile failed源碼在翻譯成HLSL后語(yǔ)法不合法加--preprocess看預(yù)處理后的代碼定位具體錯(cuò)誤行5.2 編譯通過(guò)但畫(huà)面不對(duì)問(wèn)題多半出在varying和uniform編譯通過(guò)只代表語(yǔ)法沒(méi)問(wèn)題不代表渲染結(jié)果正確。我調(diào)了這么久bgfx遇到最多的一類(lèi)問(wèn)題是“shader編譯成功、Program創(chuàng)建成功、物體就是畫(huà)不出來(lái)”。第一種典型情況是C頂點(diǎn)布局和varying.def.sc不一致。比如你C端頂點(diǎn)數(shù)據(jù)只有位置和顏色但varying.def.sc里聲明了a_texcoord0shader里也用了$input a_texcoord0那么頂點(diǎn)數(shù)據(jù)會(huì)被錯(cuò)誤解釋三角形可能直接消失或者變成奇怪形狀。排查方法是用RenderDoc截一幀看vertex shader輸入的頂點(diǎn)位置數(shù)據(jù)是否合理。如果數(shù)據(jù)位置全在零點(diǎn)附近基本就是布局錯(cuò)位。第二種典型情況是uniform名字不一致。shader里叫u_colorC端創(chuàng)建uniform時(shí)打成u_Color運(yùn)行時(shí)不會(huì)報(bào)錯(cuò)但uniform全部上了默認(rèn)0。尤其當(dāng)你的顏色是黑色或者alpha為0時(shí)整個(gè)物體直接不可見(jiàn)。排查時(shí)可以給uniform設(shè)一個(gè)明顯的非零初值如果畫(huà)面出現(xiàn)表現(xiàn)變化說(shuō)明這個(gè)名字對(duì)齊了。第三種典型情況是矩陣變換問(wèn)題。在Windows D3D后端下mul(u_mvp, vec4(pos,1.0))如果寫(xiě)反了渲染結(jié)果通常不是黑屏而是物體位置錯(cuò)亂。這個(gè)問(wèn)題和DX與GL的坐標(biāo)系習(xí)慣有關(guān)嚴(yán)重依賴(lài)你C端MVP矩陣的生成方式。建議在shader里把所有矩陣乘法統(tǒng)一寫(xiě)成bgfx的mul宏不要在部分shader里用*符號(hào)。5.3 用--preprocess和RenderDoc一層層定位問(wèn)題遇到shader編譯報(bào)錯(cuò)第一步不是盯著錯(cuò)誤信息猜而是加--preprocess參數(shù)讓shaderc輸出預(yù)處理后的展開(kāi)代碼shaderc.exe -f vs_simple.sc -o preprocessed.hlsl -i ... --type vertex --platform windows -p vs_5_0 --varyingdef varying.def.sc --preprocess打開(kāi)preprocessed.hlsl你會(huì)看到bgfx_shader.sh的宏分支到底把你寫(xiě)的源碼翻譯成了什么。如果某個(gè)變量名變成了未定義符號(hào)或者某個(gè)函數(shù)展開(kāi)后明顯不對(duì)問(wèn)題一眼就出來(lái)了。這個(gè)技巧在排查“為什么D3D能過(guò)GL不能過(guò)”這種跨平臺(tái)問(wèn)題時(shí)特別有用。如果編譯、加載全都沒(méi)問(wèn)題但渲染結(jié)果不對(duì)下一步就是上RenderDoc。截幀后重點(diǎn)看三件事Program是不是有效、VS輸出的頂點(diǎn)的位置是否符合預(yù)期、綁定的紋理和uniform是不是有內(nèi)容。一般來(lái)說(shuō)RenderDoc里如果某個(gè)繪制調(diào)用的VS/FS綁定失敗會(huì)直接高亮報(bào)錯(cuò)比盲猜Shader問(wèn)題要快得多。另外bgfx允許注冊(cè)一個(gè)回調(diào)接口把驅(qū)動(dòng)層的日志接出來(lái)。啟動(dòng)時(shí)設(shè)置bgfx::setPlatformData時(shí)可以順手掛一個(gè)回調(diào)把traceV里收到的信息打到自己的日志系統(tǒng)。驅(qū)動(dòng)編譯shader失敗、資源綁定出問(wèn)題往往在你自己的控制臺(tái)還一片安靜的時(shí)候驅(qū)動(dòng)已經(jīng)吐了一堆錯(cuò)誤。養(yǎng)成看驅(qū)動(dòng)日志的習(xí)慣排查效率能提高一個(gè)檔次。6. 從Windows走向全平臺(tái)的一點(diǎn)經(jīng)驗(yàn)6.1 換到其他平臺(tái)時(shí)只要改兩個(gè)參數(shù)理解了前面的編譯流水線(xiàn)你會(huì)發(fā)現(xiàn)一份源碼要輸出到其他平臺(tái)其實(shí)改動(dòng)量很小。編譯命令里主要改--platform和-pshader源碼本身盡量保持平臺(tái)無(wú)關(guān)。比如目標(biāo)平臺(tái)編譯參數(shù)Android OpenGL ES--platform android -p essl桌面Linux OpenGL--platform linux -p glslWindows Vulkan--platform windows -p spirv15macOS/iOS Metal--platform osx -p metal這里有個(gè)前提就是你的shader代碼沒(méi)有自己偷偷寫(xiě)原生平臺(tái)API。如果你在shader里用#ifdef BGFX_SHADER_LANGUAGE_HLSL分支出了一大段原生HLSL代碼換到GL后端時(shí)這段分支不會(huì)走但你能不能保證GL分支的代碼同樣正確所以我的建議是除非遇到極其特殊的平臺(tái)能力差異否則盡量別寫(xiě)平臺(tái)分支讓bgfx的抽象層去處理。6.2 跨平臺(tái)shader代碼的素養(yǎng)真正跨平臺(tái)的shader寫(xiě)起來(lái)有章法可循。變量命名保持一致uniform統(tǒng)一用u_前綴采樣器用s_前綴varying用v_前綴頂點(diǎn)屬性用a_前綴。這不僅是bgfx社區(qū)的慣例也方便你跨shader文件復(fù)用代碼。矩陣運(yùn)算統(tǒng)一走mul宏。顏色輸出固定用gl_FragColor。紋理采樣統(tǒng)一用texture2D。這些“統(tǒng)一”會(huì)讓你在換平臺(tái)時(shí)幾乎不用改代碼。我見(jiàn)過(guò)最省心的項(xiàng)目CI腳本里對(duì)每個(gè)平臺(tái)跑一遍shaderc命令輸出的bin文件直接按平臺(tái)路徑上傳源碼里完全沒(méi)有#ifdef跨平臺(tái)切換就是換一條編譯命令的事。說(shuō)實(shí)話(huà)我用bgfx這幾年最耗時(shí)的shader問(wèn)題往往不是“編譯不過(guò)”而是“編譯過(guò)了渲染不對(duì)”。所以給剛上手的朋友一個(gè)忠告先把varying.def.sc、頂點(diǎn)布局、uniform命名這三樣焊死在規(guī)范里再談性能優(yōu)化。有了這套底子Windows和Android之間切換shader基本就是改一條命令行參數(shù)的事。希望這篇隨筆能幫你少踩幾個(gè)坑。