329 lines
19 KiB
HTML
329 lines
19 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Documentation - 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="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">
|
|
|
|
<!-- 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>
|
|
|
|
<!-- Provide site root to javascript -->
|
|
<script>
|
|
var path_to_root = "../";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="body-container">
|
|
<!-- 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; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
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';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div style="display:flex;align-items:center;justify-content:center">
|
|
<img class="flogo" src="../images/filament_logo_small.png"></img>
|
|
</div>
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<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>
|
|
<!-- Filament: disable themes because the markdeep part does not look good for dark themes -->
|
|
<!--
|
|
<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="https://github.com/google/filament" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></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="documentation"><a class="header" href="#documentation">Documentation</a></h1>
|
|
<p>Filament's documentation (which you are reading) is a collection of pages created with <a href="https://rust-lang.github.io/mdBook/"><code>mdBook</code></a>.</p>
|
|
<h2 id="how-to-create"><a class="header" href="#how-to-create">How the book is created and updated</a></h2>
|
|
<h3 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h3>
|
|
<ul>
|
|
<li>Install <a href="https://rust-lang.github.io/mdBook/"><code>mdBook</code></a> for your platform
|
|
<ul>
|
|
<li>There is a script <code>docs_src/build/install_mdbook.sh</code> that might help.</li>
|
|
</ul>
|
|
</li>
|
|
<li>It is best practice to install the python dependencies in a virtual python environment. You can
|
|
start such an environment by
|
|
<pre><code class="language-shell">python3 -m venv venv
|
|
. venv/bin/activate
|
|
</code></pre>
|
|
After that you may install deps and run the build script.</li>
|
|
<li><code>selenium</code> package for python
|
|
<pre><code class="language-shell">python3 -m pip install selenium
|
|
</code></pre>
|
|
</li>
|
|
</ul>
|
|
<h3 id="how-to-generate"><a class="header" href="#how-to-generate">Generate</a></h3>
|
|
<p>We wrote a python script to gather and transform the different documents in the project tree into a
|
|
single book. This script can be found in <a href="https://github.com/google/filament/blob/main/docs_src/build/run.py"><code>docs_src/build/run.py</code></a>. In addition,
|
|
<a href="https://github.com/google/filament/blob/main/docs_src/build/duplicates.json"><code>docs_src/build/duplicates.json</code></a> is used to describe the markdown files that are copied and
|
|
transformed from the source tree. These copies are placed into <code>docs_src/src_mdbook/src/dup</code>.</p>
|
|
<p>To collect the pages and generate the book, run the following</p>
|
|
<pre><code class="language-shell">cd docs_src
|
|
python3 build/run.py
|
|
</code></pre>
|
|
<h3 id="copy-to-docs"><a class="header" href="#copy-to-docs">Copy to <code>docs</code></a></h3>
|
|
<p><code>docs</code> is the github-specfic directory for producing a web frontend (i.e. documentation) for a
|
|
project.</p>
|
|
<p>(To be completed)</p>
|
|
<h2 id="document-sources"><a class="header" href="#document-sources">Document sources</a></h2>
|
|
<p>We list the different document sources and how they are copied and processed into the collection
|
|
of markdown files that are then processed with <code>mdBook</code>.</p>
|
|
<h3 id="introductory-doc"><a class="header" href="#introductory-doc">Introductory docs</a></h3>
|
|
<p>The <a href="https://google.github.io/filament">github landing page</a> for Filament displays an extensive introduction to Filament. It
|
|
links to <code>BUILDING.md</code> and <code>CONTRIBUTING.md</code>, which are conventional pages for building or
|
|
contributing to the project. We copy these pages from their respective locations in the project
|
|
tree into <code>docs_src/src_mdbook/src/dup</code>. Moreover, to restore valid linkage between the pages,
|
|
we need to perform a number of URL replacements in addition to the copy. These replacements are
|
|
described in <a href="https://github.com/google/filament/blob/main/docs_src/build/duplicates.json"><code>docs_src/build/duplicates.json</code></a>.</p>
|
|
<h3 id="core-concept-docs"><a class="header" href="#core-concept-docs">Core concept docs</a></h3>
|
|
<p>The primary design of Filament as a physically-based renderer and details of its materials
|
|
system are described in <code>Filament.md.html</code> and <code>Materials.md.html</code>, respectively. These two
|
|
documents are written in <a href="https://casual-effects.com/markdeep/"><code>markdeep</code></a>. To embed them into our book, we</p>
|
|
<ol>
|
|
<li>Convert the markdeep into html</li>
|
|
<li>Embed the html output in a markdown file</li>
|
|
<li>Place the markdown file in <code>docs_src/src_mdbook/src/main</code></li>
|
|
</ol>
|
|
<p>We describe step 1 in detail for the sake of record:</p>
|
|
<ul>
|
|
<li>Start a local-only server to serve the markdeep file (e.g. <code>Filament.md.html</code>)</li>
|
|
<li>Start a <code>selenium</code> driver (essentially run chromium in headless mode)</li>
|
|
<li>Visit the local page through the driver (i.e. open url
|
|
<code>http://localhost:xx/Filament.md.html?export</code>)</li>
|
|
<li>Parse out the exported output in the retrieved html (note that the output of the markdeep
|
|
export is an html with the output captured in a <code><pre></code> tag).</li>
|
|
<li>Replace css styling in the exported output as needed (so they don't interfere with the
|
|
book's css.</li>
|
|
<li>Replace resource urls to refer to locations relative to the mdbook structure.</li>
|
|
</ul>
|
|
<p>Any <code>markdeep</code> doc can be placed in <code>docs_src/src_markdeep/</code> and they will be parsed to html and
|
|
included in the book as above.</p>
|
|
<h3 id="readmes"><a class="header" href="#readmes">READMEs</a></h3>
|
|
<p>Filament depends on a number of libraries, which reside in the directory <code>libs</code>. These individual
|
|
libaries often have README.md in their root to describe itself. We collect these descriptions into
|
|
our book. In addition, client usage of Filament also requires using a set of binary tools, which are
|
|
located in <code>tools</code>. Some of tools also have README.md as description. We also collect them into the
|
|
book.</p>
|
|
<p>The process for copying and processing these READMEs is outlined in
|
|
<a href="#introductory-doc">Introductory docs</a>.</p>
|
|
<h3 id="web-examples-and-tutorials"><a class="header" href="#web-examples-and-tutorials">Web Examples and Tutorials</a></h3>
|
|
<p>Filament provides a number of WebGL tutorials and examples in the <code>web/</code> directory. These are
|
|
compiled during the WebGL CMake build and are integrated into the documentation via
|
|
<code>duplicates.json</code>. The process is entirely automated:</p>
|
|
<ol>
|
|
<li><code>run.py</code> maps the <code>.html</code> and <code>.md</code> WebGL outputs from the <code>out/cmake-webgl-release/...</code>
|
|
directory into <code>docs_src/src_mdbook/src/samples/web/</code> using the instructions in <code>duplicates.json</code>.</li>
|
|
<li>While transferring <code>.html</code> to <code>.md</code>, <code>run.py</code> strips away the <code><!DOCTYPE html></code>, <code><head></code>, and
|
|
<code><html></code> tags. By retaining only the <code><style></code> and <code><body></code> elements, the HTML samples can be
|
|
embedded cleanly into the <code>mdbook</code> site template without corrupting the DOM. It additionally
|
|
collapses double-newlines (<code>\n\n</code>) because Markdown parsers will mistakenly fragment and wrap
|
|
multi-line HTML tags into <code><p></code> blocks.</li>
|
|
<li>After <code>mdbook build</code> concludes, <code>docs_src/build/copy_web_docs.py</code> is invoked. This script creates
|
|
<code>web/lib</code> and <code>web/assets</code> directories inside the final <code>book/</code> output directory, copying in the
|
|
compiled WebAssembly engine (<code>filament.wasm</code>/<code>filament.js</code>) and any necessary assets
|
|
(<code>.filamat</code>, <code>.glb</code>, <code>.ktx</code>, etc.).</li>
|
|
<li>Finally, <code>copy_web_docs.py</code> performs a regex pass over all HTML pages in <code>book/samples/web/</code> and
|
|
<code>book/remote/</code> to rewrite their inline resource URLs to securely point to the shared <code>web/lib</code> and
|
|
<code>web/assets</code> directories. It also dynamically overrides the <code>asset.loadResources()</code> Javascript call
|
|
with an absolute URL (<code>new URL(..., window.location.href)</code>) so that <code>.glb</code>/<code>.gltf</code> assets fetch
|
|
their internal <code>.bin</code> chunks correctly.</li>
|
|
</ol>
|
|
<h3 id="other-technical-notes"><a class="header" href="#other-technical-notes">Other technical notes</a></h3>
|
|
<p>These are technical documents that do not fit into a library, tool, or directory of the
|
|
Filament source tree. We collect them into the <code>docs_src/src_mdbook/src/notes</code> directory. No
|
|
additional processing is needed for these documents.</p>
|
|
<h3 id="raw-source-files"><a class="header" href="#raw-source-files">Raw source files</a></h3>
|
|
<p>These are files that are not part of the <code>mdbook</code> generation, but should be included output in
|
|
<code>/docs</code> to point to standalone pages or components (for example, the remote page for Android's
|
|
<code>gltf_viewer</code>). These files are stored in <code>docs_src/src_raw</code>.</p>
|
|
<h2 id="adding-more-documents"><a class="header" href="#adding-more-documents">Adding more documents</a></h2>
|
|
<p>To add any documentation, first consider the type of the document you like to add. If it
|
|
belongs to any of the above sources, then simply place the document in the appropriate place,
|
|
add a link in <code>SUMMARY.md</code>, and perform the steps outlined in
|
|
<a href="#how-to-create">how-to create section</a>.</p>
|
|
<p>For example, if you are adding a general technical note, then you would</p>
|
|
<ul>
|
|
<li>Place the document (file with extension <code>.md</code>) in <code>docs_src/src_mdbook/src/notes</code></li>
|
|
<li>Add a link in <a href="https://github.com/google/filament/blob/main/docs_src/src_mdbook/src/SUMMARY.md"><code>docs_src/src_mdbook/src/SUMMARY.md</code></a></li>
|
|
<li>Run the commands in the <a href="#how-to-generate">Generate</a> section</li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../release/branching.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="../notes/debugging.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="../release/branching.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="../notes/debugging.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>
|
|
|
|
|
|
|
|
|
|
<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>
|