cinder · sortofsleepy · Dec 13, 2018 · Dec 13, 2018 · Dec 14, 2018 · Dec 14, 2018
diff --git a/.gitignore b/.gitignore
@@ -71,5 +71,11 @@ cinderConfig.cmake
 blocks/
 !blocks/[__AppTemplates,Box2D,Cairo,FMOD,LocationManager,MotionManager,OSC,QuickTime,TUIO]
 
+# Emscripten 
+lib/emscripten/libcinder_d.bc
+#lib/emscripten/libboost_system.bc
+#lib/emscripten/libboost_filesystem.bc
+.vscode/settings.json
+node_modules
 #ImGui stored settings
-imgui.ini
+imgui.ini
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -33,6 +33,8 @@ elseif( CINDER_ANDROID )
 	include( "${CINDER_CMAKE_DIR}/platform_android.cmake" )
 elseif( CINDER_MSW )
 	include( "${CINDER_CMAKE_DIR}/platform_msw.cmake" )
+elseif( CINDER_EMSCRIPTEN )
+	include( "${CINDER_CMAKE_DIR}/platform_emscripten.cmake" )
 else()
 	message( FATAL_ERROR "no target defined for system: '${CMAKE_SYSTEM_NAME}.'" )
 endif()

diff --git a/docs/htmlsrc/guides/emscripten/config.json b/docs/htmlsrc/guides/emscripten/config.json
@@ -0,0 +1,83 @@
+{
+	"data":{
+		"metadata":
+		{
+			"keywords": ["guide, emscripten"]
+		},
+		"nav":[
+			{
+				"label": "Introduction",
+				"link": "index.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Installation",
+				"link": "part1.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Getting started",
+				"link": "part2.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Possible issues",
+				"link": "part3.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Deployment",
+				"link": "part4.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Working with the Web",
+				"link": "part5.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Interesting Web technologies",
+				"link": "part6.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label": "Tips",
+				"link": "part7.html",
+				"pagenav":[
+
+				]
+			},
+			{
+				"label":"FAQs",
+				"link":"part8.html"
+			},
+			{
+				"label":"ci_emscripten_app",
+				"link":"part9.html"
+			},
+			{
+				"label":"emscripten::val",
+				"link":"part9.5.html"
+			}
+		],
+		"seealso":
+		{
+
+		}
+	}
+
+}
diff --git a/docs/htmlsrc/guides/emscripten/index.html b/docs/htmlsrc/guides/emscripten/index.html
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<!-- Update title -->
+		<title>Cinder with Emscripten</title>
+
+		<!-- keywords used for searching -->
+		<meta name="keywords" content="guide, emscripten, cinder">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+
+		<!-- reference to Cinder classes -->
+   		<!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->
+
+   		<!-- master stylesheet - these links will be replaced when compiled -->
+		<link rel="stylesheet" href="../../_assets/css/foundation.css">
+		<link rel="stylesheet" href="../../_assets/css/prism.css">
+		<link rel="stylesheet" href="../../_assets/css/style.css">
+		<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>
+
+		<!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
+
+	</head>
+
+	<body id="guide-contents" class="language-c++">
+
+		<!-- CONTENT STARTS HERE -->
+
+        <section id="intro">
+
+
+            <h1><a id="Cinder_Emscripten_Guide_1"></a>Cinder Emscripten Guide</h1>
+            <p>Cinder now supports building for Emscripten as of version (todo : add version number ). This allows users to open up their Cinder applications to the world wide web!</p>
+
+			<h1><a id="But_what_is_Emscripten_exactly_5"></a>But what is Emscripten exactly?</h1>
+            <p>Emscripten is a toolchain for compiling to asm.js and WebAssembly, built using LLVM, that lets you run C and C++ on the web at near-native speed without plugins.</p>
+            <p>In essence, it's simply a tool that lets you treat the web as another compilation target. A large chunk of the work was already done thanks to the efforts of <a href="https://github.com/chaoticbob/Cinder-Emscripten">Hai Nguyen</a> (<a href="https://github.com/chaoticbob">@chaoticbob</a>), this latest version builds on top of that by adding some additional features such as video support.</p>
+
+			<h1><a id="How_it_works_10"></a>How it works</h1>
+            <p>You can treat your Emscripten project pretty much like any other CMake based Cinder project, you just need to run a slightly different command than what you might be used to.</p>
+
+			<h1><a id="Whats_known_to_notwork_13"></a>Whats known to (not)work</h1>
+            <p>A large chunk of what you know about Cinder should mostly be transferable directly when building with Emscripten in mind, so with that said, it is perhaps easier to instead list all currently known un-supported features</p>
+            <ul>
+                <li>Threads (there is some experimentation with adatpting pthread but due to the Spectre vulnerability, support of this does depend a little on browser builders)</li>
+                <li>PBOs</li>
+                <li>Multi-window support (with some trickery you could perhaps simulate multi-screen support but given the strictness with how things are sandboxed on the web the possibility remains very low.)</li>
+				<li>Compute shaders are currently not useable in WebGL</li>
+				<li>SSBOs</li>
+				<li>It is also currently not possible to bind buffers for use in shaders for uses other than Transform Feedback or UBOs.</li>
+			</ul>
+            <h1><a id="Demos_22"></a>Demos</h1>
+            <p>You can find some of the original demos <a href="http://chaoticbob.github.io/Cinder-Emscripten/">here</a></p>
+            <p>To get started continue on to <a href="/part1.html">installation instructions.</a></p>
+        </section>
+
+		<!-- END CONTENT -->
+
+		<!-- Scripts -->
+		<script src="../../_assets/js/prism.js" type="text/javascript"></script>
+		<!-- Place additional scripts here (optional) -->
+		<!-- <script type="text/javascript"></script> -->
+
+	</body>
+</html>
diff --git a/docs/htmlsrc/guides/emscripten/part1.html b/docs/htmlsrc/guides/emscripten/part1.html
@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<!-- Update title -->
+		<title>Cinder with Emscripten</title>
+
+		<!-- keywords used for searching -->
+		<meta name="keywords" content="guide, emscripten, cinder">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+
+		<!-- reference to Cinder classes -->
+   		<!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->
+
+   		<!-- master stylesheet - these links will be replaced when compiled -->
+		<link rel="stylesheet" href="../../_assets/css/foundation.css">
+		<link rel="stylesheet" href="../../_assets/css/prism.css">
+		<link rel="stylesheet" href="../../_assets/css/style.css">
+		<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>
+
+		<!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
+
+	</head>
+
+	<body id="guide-contents" class="language-c++">
+
+		<!-- CONTENT STARTS HERE -->
+
+        <section id="install">
+            <h1><a id="Getting_things_set_up_0"></a>Getting things set up</h1>
+            <p>There are number of things you'll need to do in order to get things set up to build with Emscripten. If you're already familiar with CMake projects and how those work, then this will likely not be new for you as the process for running an Emscripten project is nearly identical.</p>
+            <h1><a id="System_requirements_3"></a>System requirements</h1>
+            <p>In terms of hardware requirements, this should work on any system that supports Cinder and Emscripten.</p>
+
+            <h1><a id="Browser_support_43"></a>Browser support</h1>
+            <p>Browser support can be a little tricker. You technically just need a browser that can support WebGL 2 but even if there is support, sometimes different browser developers enable/disable different things. That being said the recommended browsers are Firefox or Chrome.</p>
+            <p>
+                <strong>When running your application</strong><br>
+                To run your Cinder applications, while not strictly necessary, it's recommended to host on a server that can serve files with the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">mime type</a> <code>application/wasm</code>
+            </p>
+            <p>If your server does not support that mime type, you will still be able to run your app, but your bundle won't be able to compile things as efficiently.</p>
+
+
+            <h1><a id="Downloading_the_essentials_6"></a>Downloading the essentials</h1>
+            <ul>
+                <li>Install <a target="_blank" href="https://cmake.org/">Cmake</a> (at least version 3.10 but may work on older versions as well)</li>
+                <li>
+                    You'll also need a *nix style terminal window as well as <code>make</code> or something similar if you happen to be on Windows
+                    <ul>
+                        <li>This has been tested on WSL, specifically using Ubuntu as the backend</li>
+                        <li>Emscripten has been known to work with Git bash; though as of version 1.39.16 of Emscripten, support seems suspect. Some things work fine, some things seem to fail. That said, assuming you can get things built, you will also need 
+                            a make program and things have been known to work with MinGW64. </li>
+                    </ul>
+                </li>
+                <li>Of course, you'll need to install Emscripten. <a target="_blank" href="http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html">Make sure to follow the directions found on the official site</a> as the method of installation has changed since Emscripten was originally conceived.</li>
+            </ul>
+
+            <p>Once you have all that...</p>
+
+            <h1><a id="Building_Cinder_16"></a>Building Cinder</h1>
+            <ul>
+                <li>First, run <code>emsdk activate latest</code>, then run <code>source emsdk_env.sh</code></li>
+                <li>
+
+                    Just like you would on the desktop if you were building Cinder for Linux, make a build folder at the root of your Cinder 
+                    installation and run <br/>
+                    <code>emcmake cmake ..</code> (plus any other CMake flags you'd like to set)
+                </li>
+            </ul>
+
+            <h1><a id="Updating_your_systems_PATH_variable_28"></a>Updating your systems <code>PATH</code> variable</h1>
+            <p>This isn't entirely necessary it will be useful to add the path to your <code>emsdk</code> folder to your system's <code>PATH</code> variable to make it easier to run commands.</p>
+            <p><a href="/part2.html">Now we can start on to building an actual projecct.</a></p>
+
+
+            <h1>Known working configurations</h1>
+            <p>This has been tested with the following configuration</p>
+            <ul>
+                <li>
+                    Windows 10
+                </li>
+                <li>
+                    WSL 
+                </li>
+                <li>Emscripten version 1.39.16</li>
+            </ul>
+
+            <p>In the initial explorations of the Emscripten codebase, an older version was used; as of roughly 10/2019, a newer compilation engine was developed and integrated.</p>
+            <p>If you would like to try the older version, remember to add <code>-fastcomp</code> to your <code>emsdk</code> commands</p>
+            <p>The <code>emsdk</code> help command will mention <code>fastcomp</code> as well. </p>
+        </section>
+
+		<!-- END CONTENT -->
+
+		<!-- Scripts -->
+		<script src="../../_assets/js/prism.js" type="text/javascript"></script>
+		<!-- Place additional scripts here (optional) -->
+		<!-- <script type="text/javascript"></script> -->
+
+
+        <!--
+            Legacy stuff, keeping around in case it might be helpful.
+
+
+
+              <h1><a id="If_you_gotta_build_Boost_this_is_optional_21"></a>If you gotta build Boost (this is optional)</h1>
+            <p>Emscripten support relies on Boost system and filesystem libraries which should be included. If for some reason you need to rebuild. Note that you will definitely need a Unix-y terminal for this, Git Bash won't work.</p>
+            <ul>
+                <li>Download Boost. Note that it appears that the set of headers used needs to match the version of the library built. The current version of Boost being used is 1.60. When it's downloaded cd into the Boost directory.</li>
+                <li>run <a target="_blank" href="http://bootstrap.sh">bootstrap.sh</a>. It should produce 2 executables but we're only interested in one called b2.</li>
+                <li>Next you can run b2 --with-system --with-filesystem toolset=emscripten link=static. If for some reason you get an error, you can try replacing emscripten with clang-emscripten</li>
+                <li>In your Cinder folder, drop the output in lib/emscripten</li>
+            </ul>
+        -->
+	</body>
+</html>
diff --git a/docs/htmlsrc/guides/emscripten/part2.html b/docs/htmlsrc/guides/emscripten/part2.html
@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<!-- Update title -->
+		<title>Cinder with Emscripten</title>
+
+		<!-- keywords used for searching -->
+		<meta name="keywords" content="guide, emscripten, cinder">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+
+		<!-- reference to Cinder classes -->
+   		<!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->
+
+   		<!-- master stylesheet - these links will be replaced when compiled -->
+		<link rel="stylesheet" href="../../_assets/css/foundation.css">
+		<link rel="stylesheet" href="../../_assets/css/prism.css">
+		<link rel="stylesheet" href="../../_assets/css/style.css">
+		<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>
+
+		<!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
+
+	</head>
+
+	<body id="guide-contents" class="language-c++">
+
+		<!-- CONTENT STARTS HERE -->
+
+		<section id="started">
+      <h1><a id="Building_an_Emscripten_project_0"></a>Building an Emscripten project.</h1>
+      <p>Building a project that targets Emscripten is a lot like building a project that builds with CMake. That being said, there are some very subtle differences.</p>
+
+	  <h1><a id="Creating_a_project_structure_4"></a>Creating a project structure.</h1>
+      <p>You can start off by generating your project with Tinderbox, like you might already be doing. Now if you haven't worked with Cmake before, you'll also have to make some kind of "build" folder, basically a place where your compiled files will get output to; the common practice is to just have a folder called build at the root of your project(note you can name it something other than build if you want)</p>
+	  <p>Next, you'll need a CMakeLists.txt file that will describe how to build your project. If you've never worked with CMake before, you can check out any of the samples in <code>samples/_emscripten</code> which will have CMake files available. If you're familiar
+		with CMake and want to write everything by hand, grabbing the CMakeLists file that builds Cinder is a good starting point to see what flags and settings need to applied to build for Emscripten. </p>
+     <p>Now we can move onto actually building a project. </p>
+
+	  <h1><a id="Building_a_project_16"></a>Building a project</h1>
+      <p>To build your project, from within your build folder(note I'm assuming it's within the root of your project)</p>
+      <ul>
+	  <li>run <code>emcmake cmake ..</code></li>
+	  <li>run <code>make</code> (or <code>mingw32-make</code> etc if on Windows or not using WSL)</li>
+      <li>When the build is done, everything you need to upload will end up in your build folder. </li>
+
+
+		<li>
+			<!-- TODO I believe we can probably address this issue with CMake -JC -->
+			Note that resource and asset bundling/copying is not automatically done because builds will fail if the compiler can't find the 
+			resources directory. To add your asset folders :
+			<br/>
+			<p><b>For Resources</b></p>
+			<p>If you're not using ci_emscripten_app(which will be talked about later on) you can add the flag</p>
+			<p><code>--preload-file ../(path to your resources folder)@</code></p>
+
+			<p><b>For Assets</b></p>
+			<p>If you're not using ci_emscripten_app, unless your CMake file is already set up to copy it over, you will have to manually copy your assets folder into your output directory.</p>
+			<p>Otherwise your assets will be copied automatically.</p>
+
+		</li>
+	</ul>
+
+      <h1><a id="Running_your_project_24"></a>Running your project</h1>
+	  <p>Running your project is fairly straightforward. You'll need to serve your project from a server somehow, one that can support the mime type <code>application/wasm</code>(though note this kind of server is not strictly necessary but it may provide better performance)</p>
+	  <p>There are a multitude of ways to do so, but perhaps the simplist solution is to borrow the built-in server on good ol' Python</p>
+
+	  <ul>
+		<li>if on Python 2, from within your build directory, run <code>python -m SimpleHTTPServer</code></li>
+		<li>if on Python 3, your command is <code>python -m http.server</code></li>
+		<li>Note that for both commands you can specify a port after typing in the command, otherwise things will default to port 8000</li>
+		<li>Currently, while your project should still run, it won't technically be running in it's WebAssembly form since the python server does not support WebAssembly at the moment.
+			There is a provided alternative server you can use called <a href="https://www.npmjs.com/package/wasm-server" target="_blanke">wasm-server</a>. You can of course choose to roll your own as well if you wish. 
+		</li>
+	 </ul>
+
+
+
+	  <h1><a id="ci_emscripten_app"></a>ci_emscripten_app</h1>
+      <p> See the <a href="/part9.html">ci_emscripten_app section</a> for a more in-depth look as to the options and other functionality
+		it can provide. </p>
+	  <p>If you've been using <code>ci_make_app</code>, the functionality and usage is very similar. 
+		Check out <code>/proj/cmake/cinderEmscriptenApp.cmake</code> to see what the function looks like. All options have comments describing what they are for. </p>
+
+	</section>
+
+		<!-- END CONTENT -->
+
+		<!-- Scripts -->
+		<script src="../../_assets/js/prism.js" type="text/javascript"></script>
+		<!-- Place additional scripts here (optional) -->
+		<!-- <script type="text/javascript"></script> -->
+
+	</body>
+</html>