398 lines
21 KiB
HTML
398 lines
21 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Investigating SPIRV Issues - Filament</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="highlight.css">
|
|
<link rel="stylesheet" href="tomorrow-night.css">
|
|
<link rel="stylesheet" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
<!-- MathJax -->
|
|
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
|
</head>
|
|
<body class="sidebar-visible no-js">
|
|
<div id="body-container">
|
|
<!-- Provide site root to javascript -->
|
|
<script>
|
|
var path_to_root = "";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
|
</script>
|
|
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
var html = document.querySelector('html');
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
var body = document.querySelector('body');
|
|
body.classList.remove('no-js')
|
|
body.classList.add('js');
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
var body = document.querySelector('body');
|
|
var sidebar = null;
|
|
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
body.classList.remove('sidebar-visible');
|
|
body.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div class="sidebar-scrollbox">
|
|
<ol class="chapter"><li class="chapter-item expanded "><a href="core.html"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html" class="active"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
|
|
</div>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
|
</nav>
|
|
|
|
<!-- Track and set sidebar scroll position -->
|
|
<script>
|
|
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
|
|
sidebarScrollbox.addEventListener('click', function(e) {
|
|
if (e.target.tagName === 'A') {
|
|
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
|
|
}
|
|
}, { passive: true });
|
|
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
|
|
sessionStorage.removeItem('sidebar-scroll');
|
|
if (sidebarScrollTop) {
|
|
// preserve sidebar scroll position when navigating via links within sidebar
|
|
sidebarScrollbox.scrollTop = sidebarScrollTop;
|
|
} else {
|
|
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
|
|
var activeSection = document.querySelector('#sidebar .active');
|
|
if (activeSection) {
|
|
activeSection.scrollIntoView({ block: 'center' });
|
|
}
|
|
}
|
|
</script>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Filament</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="investigating-spirv-cross--spirv-tools-issues"><a class="header" href="#investigating-spirv-cross--spirv-tools-issues">Investigating SPIRV-Cross / SPIRV-Tools issues</a></h1>
|
|
<p>There are 4 repositories at play here:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/KhronosGroup/glslang">KhronosGroup/glslang</a></li>
|
|
<li><a href="https://github.com/KhronosGroup/SPIRV-Tools">KhronosGroup/spirv-tools</a></li>
|
|
<li><a href="https://github.com/KhronosGroup/SPIRV-Cross">KhronosGroup/spirv-cross</a></li>
|
|
<li><a href="https://github.com/KhronosGroup/SPIRV-Headers">KhronosGroup/SPIRV-Headers</a></li>
|
|
</ul>
|
|
<p>Typically, the bug is present either in spirv-tools or spirv-cross.</p>
|
|
<h2 id="build-and-install-command-line-tools-on-path"><a class="header" href="#build-and-install-command-line-tools-on-path">Build and install command-line tools on PATH</a></h2>
|
|
<p>The goal is to replicate the bug outside of Filament, so we're going to use command-line versions of
|
|
the SPIRV tools.</p>
|
|
<h3 id="clone-and-build-each-repo"><a class="header" href="#clone-and-build-each-repo">Clone and build each repo</a></h3>
|
|
<p>Note: Filament checks-out versions of these repositories inside <code>third_party/</code>; however, I've found
|
|
it easiser to check out fresh copies separately so I can simply <code>git pull</code> to get the latest
|
|
versions. Furthermore, Filament has modified some of these repositories locally for its own use
|
|
case. Checking them out separately "proves" that the issue isn't Filament-specific.</p>
|
|
<pre><code>git clone git@github.com:KhronosGroup/SPIRV-Tools.git
|
|
git clone git@github.com:KhronosGroup/SPIRV-Cross.git
|
|
git clone git@github.com:KhronosGroup/glslang.git
|
|
git clone git@github.com:KhronosGroup/SPIRV-Headers.git SPIRV-Tools/external/SPIRV-Headers
|
|
|
|
cd SPIRV-Tools/
|
|
mkdir build && cmake . -G Ninja -B build
|
|
ninja -C build
|
|
cd ..
|
|
|
|
cd SPIRV-Cross/
|
|
mkdir build && cmake . -G Ninja -B build
|
|
ninja -C build
|
|
cd ..
|
|
|
|
cd glslang/
|
|
mkdir build && cmake . -G Ninja -B build
|
|
ninja -C build
|
|
cd ..
|
|
</code></pre>
|
|
<h3 id="add-directories-to-path"><a class="header" href="#add-directories-to-path">Add directories to PATH</a></h3>
|
|
<pre><code>export PATH=`pwd`/SPIRV-Tools/build/tools:$PATH
|
|
export PATH=`pwd`/glslang/build/StandAlone:$PATH
|
|
export PATH=`pwd`/spirv-cross/build:$PATH
|
|
</code></pre>
|
|
<p>Ensure the following tools now exist on your PATH:</p>
|
|
<ol>
|
|
<li><code>glslangValidator</code></li>
|
|
<li><code>spiv-opt</code></li>
|
|
<li><code>spirv-val</code></li>
|
|
<li><code>spirv-cross</code></li>
|
|
</ol>
|
|
<h2 id="isolate-the-problematic-glsl-shader"><a class="header" href="#isolate-the-problematic-glsl-shader">Isolate the problematic GLSL shader</a></h2>
|
|
<p>First determine the Filament material and variant that causes the problem.</p>
|
|
<p>What we want is the "raw" GLSL version of the shader, before any optimizations / cross-compilation
|
|
happens.</p>
|
|
<p>The easiest way I've found to do this is by adding a <code>std::cout</code> statement inside <code>MaterialBuilder</code>,
|
|
right after <code>sg.createFragmentProgram</code> or <code>sg.createVertexProgram</code> is called. For example,</p>
|
|
<pre><code>if (v.variant.key == 8u) { std::cout << shader << std::endl; }
|
|
</code></pre>
|
|
<p>Then, I invoke <code>matc</code> and redirect stdout to a .frag or .vert file.</p>
|
|
<p>Note that gltfio material "templates" first go through a build step. After building gltfio, the
|
|
gltfio Filament materials are output to:</p>
|
|
<pre><code>out/cmake-release/libs/gltfio/*.mat
|
|
</code></pre>
|
|
<p>One of these materials can be compiled with the following command:</p>
|
|
<pre><code>matc \
|
|
-TCUSTOM_PARAMS="// no custom params" \
|
|
-TCUSTOM_VERTEX="// no custom vertex" \
|
|
-TCUSTOM_FRAGMENT="// no custom fragment" \
|
|
-TDOUBLESIDED=false \
|
|
-TTRANSPARENCY=default \
|
|
-TSHADINGMODEL=unlit \
|
|
-TBLENDING=opaque \
|
|
--platform mobile --api metal -o temp.filamat \
|
|
unlit_opaque.mat
|
|
</code></pre>
|
|
<h2 id="reproduce-the-compilation-error"><a class="header" href="#reproduce-the-compilation-error">Reproduce the compilation error</a></h2>
|
|
<p>The goal is to generate a .spv file that doesn't pass validation (through the spirv-val tool).</p>
|
|
<p>Reproducing the error usually involves a few steps:</p>
|
|
<ol>
|
|
<li>Compile the raw GLSL shader into SPIR-V.</li>
|
|
</ol>
|
|
<pre><code>glslangValidator -V -o unoptimized.spv in.frag
|
|
</code></pre>
|
|
<ol start="2">
|
|
<li>Optimize for performance.</li>
|
|
</ol>
|
|
<pre><code>spirv-opt -Oconfig=optimizations.cfg unoptimized.spv -o optimized.spv
|
|
</code></pre>
|
|
<p>See <a href="optimizations.cfg">optimizations.cfg</a> for a template. This file should contain the same list of optimizations that
|
|
Filament employs. This should match the same optimizations specified in <code>GLSLPostProcessor</code>, for
|
|
example, <code>GLSLPostProcessor::registerPerformancePasses</code> or <code>GLSLPostProcessor::registerSizePasses</code>.</p>
|
|
<ol start="3">
|
|
<li>For shaders targeting Metal, convert relaxed ops to half.</li>
|
|
</ol>
|
|
<pre><code>spirv-opt \
|
|
--convert-relaxed-to-half \
|
|
--simplify-instructions \
|
|
--redundancy-elimination \
|
|
--eliminate-dead-code-aggressive \
|
|
optimized.spv \
|
|
-o half.spv
|
|
</code></pre>
|
|
<ol start="4">
|
|
<li>Finally, validate the final SPIR-V.</li>
|
|
</ol>
|
|
<pre><code>spirv-val half.spv
|
|
</code></pre>
|
|
<ol start="5">
|
|
<li>Sometimes validation will still pass, but still generate invalid shaders after cross-compiling.
|
|
In these cases, you'll need to cross compile to the target language and manually pick out errors
|
|
in the generated shader.</li>
|
|
</ol>
|
|
<pre><code># for OpenGL
|
|
spirv-cross optimized.spv > optimized.frag
|
|
|
|
# for OpenGL ES
|
|
spirv-cross --es optimized.spv > optimized.frag
|
|
|
|
# for MSL
|
|
spirv-cross --msl optimized.spv > optimized.metal
|
|
</code></pre>
|
|
<p>To invoke Apple's compiler to compile MSL, you can run:</p>
|
|
<pre><code>xcrun -sdk macosx metal -c optimized.metal -o /dev/null
|
|
</code></pre>
|
|
<h2 id="clean-up-the-shader-for-a-bug-report"><a class="header" href="#clean-up-the-shader-for-a-bug-report">Clean up the shader for a bug report</a></h2>
|
|
<p>These commands will run the preprocessor only on <code>in.frag</code>, and remove any empty lines.</p>
|
|
<pre><code>glslangValidator -E in.frag > preprocessed.frag
|
|
sed '/^$/d' preprocessed.frag > preprocessed_small.frag
|
|
</code></pre>
|
|
<p>You can also run <code>clang-format</code> on the preprocessed shader to make it easier to read:</p>
|
|
<pre><code>clang-format -i preprocessed_small.frag
|
|
</code></pre>
|
|
<p>I always try to "whittle down" the shader to a smaller version that still reproduces the error. This
|
|
might make it a bit easier on the Khronos team to diagnose the issue. I typically follow these steps
|
|
in a loop until I'm satisfied:</p>
|
|
<ol>
|
|
<li>Delete an unnecessary part of the shader</li>
|
|
<li>Run the steps to reproduce the error</li>
|
|
<li>If the error still reproduces, repeat</li>
|
|
<li>Otherwise, undo the change and make a smaller change</li>
|
|
</ol>
|
|
<p>There's also a <a href="https://github.com/KhronosGroup/SPIRV-Tools#reducer">Reducer</a> tool that's part of
|
|
SPIRV-Tools which can be used to automate these steps. I haven't experimented much with this, but it
|
|
seems promising.</p>
|
|
<h2 id="submit-an-issue-with-the-relevant-khronos-repository"><a class="header" href="#submit-an-issue-with-the-relevant-khronos-repository">Submit an Issue with the relevant Khronos repository</a></h2>
|
|
<p>See some example issues that have been filed in the past:</p>
|
|
<ul>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Cross/issues/1935</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Cross/issues/1088</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Cross/issues/1026</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Tools/issues/4452</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Tools/issues/3406</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Tools/issues/3099</li>
|
|
<li>https://github.com/KhronosGroup/SPIRV-Tools/issues/5044</li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="dev-debugging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="dev-versioning.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="dev-debugging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="dev-versioning.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
<!-- Livereload script (if served using the cli tool) -->
|
|
<script>
|
|
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
|
const socket = new WebSocket(wsAddress);
|
|
socket.onmessage = function (event) {
|
|
if (event.data === "reload") {
|
|
socket.close();
|
|
location.reload();
|
|
}
|
|
};
|
|
|
|
window.onbeforeunload = function() {
|
|
socket.close();
|
|
}
|
|
</script>
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="elasticlunr.min.js"></script>
|
|
<script src="mark.min.js"></script>
|
|
<script src="searcher.js"></script>
|
|
|
|
<script src="clipboard.min.js"></script>
|
|
<script src="highlight.js"></script>
|
|
<script src="book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|