diff --git a/emscripten-version.txt b/emscripten-version.txt index 6c13ae0d09f3e..5b3a48eab21e4 100644 --- a/emscripten-version.txt +++ b/emscripten-version.txt @@ -1,2 +1,2 @@ -1.21.9 +1.21.10 diff --git a/emscripten.py b/emscripten.py index a8a4dbe783f83..faf41c409a1fb 100755 --- a/emscripten.py +++ b/emscripten.py @@ -14,6 +14,7 @@ from tools import shared from tools import jsrun, cache as cache_module, tempfiles from tools.response_file import read_response_file +from tools.shared import WINDOWS __rootpath__ = os.path.abspath(os.path.dirname(__file__)) def path_from_root(*pathelems): @@ -708,13 +709,15 @@ def fix(m): funcs_js[i] = None funcs_js_item = indexize(funcs_js_item) funcs_js_item = blockaddrsize(funcs_js_item) + if WINDOWS: funcs_js_item = funcs_js_item.replace('\r\n', '\n') # Normalize to UNIX line endings, otherwise writing to text file will duplicate \r\n to \r\r\n! outfile.write(funcs_js_item) funcs_js = None - outfile.write(indexize(post)) - if DEBUG: logging.debug(' emscript: phase 3 took %s seconds' % (time.time() - t)) - + indexized = indexize(post) + if WINDOWS: indexized = indexized.replace('\r\n', '\n') # Normalize to UNIX line endings, otherwise writing to text file will duplicate \r\n to \r\r\n! + outfile.write(indexized) outfile.close() + if DEBUG: logging.debug(' emscript: phase 3 took %s seconds' % (time.time() - t)) # emscript_fast: emscript'en code using the 'fast' compilation path, using # an LLVM backend @@ -1316,9 +1319,11 @@ def fix(m): outfile.write("var SYMBOL_TABLE = %s;" % json.dumps(symbol_table).replace('"', '')) for i in range(len(funcs_js)): # do this loop carefully to save memory + if WINDOWS: funcs_js[i] = funcs_js[i].replace('\r\n', '\n') # Normalize to UNIX line endings, otherwise writing to text file will duplicate \r\n to \r\r\n! outfile.write(funcs_js[i]) funcs_js = None + if WINDOWS: post = post.replace('\r\n', '\n') # Normalize to UNIX line endings, otherwise writing to text file will duplicate \r\n to \r\r\n! outfile.write(post) outfile.close() diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html b/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html index 668c9f8566ac0..d331c5abb713b 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html @@ -29,8 +29,9 @@ ('https://groups.google.com/forum/#!forum/emscripten-discuss', 'Mailing list', 'Mailing list'), ('https://github.com/kripken/emscripten/wiki', 'Wiki', 'Wiki'), ('https://plus.google.com/100622854474489221138', 'Google+', 'Google+'), - ('docs/getting_started/release_notes', 'Release notes', 'Release notes'), - ('docs/site/blogs', 'Blogs', 'Blogs'), + ('docs/introducing_emscripten/release_notes', 'Release notes', 'Release notes'), + ('docs/introducing_emscripten/community', 'Blogs', 'Blogs'), + ('docs/introducing_emscripten/community', 'Help', 'Contact'), ] -%}
@@ -41,6 +42,8 @@ {{ shorttext }}{{ longtext }} {%- elif document | truncate(4, True, end='') == 'http' %} {{ shorttext }}{{ longtext }} + {%- else %} + {{ shorttext }} {%- endif %} {% endfor %} diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html index 86306b04710b3..2315ad930aaaf 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html @@ -7,7 +7,7 @@ {%- set titlesuffix = "" %} {%- endif %} - + @@ -129,7 +129,7 @@ {% set navigation_bar = [ ('docs/index', 'Docs', 'Documentation'), ('docs/getting_started/downloads', 'SDK', 'Downloads'), - ('docs/introducing_emscripten/contact', 'Help', 'Contact'), + ('docs/introducing_emscripten/community', 'Help', 'Community'), ('https://github.com/kripken/emscripten', 'Github', 'Github Project') ] -%} diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css index ec711b0bedfd9..300680f9fcfae 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css @@ -23,7 +23,25 @@ table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromefra .wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap} -a{color:#2980b9;text-decoration:none}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%;overflow-x:hidden}body{font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;font-weight:normal;color:#404040;min-height:100%;overflow-x:hidden;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22 !important}a.wy-text-warning:hover{color:#eb9950 !important}.wy-text-info{color:#2980b9 !important}a.wy-text-info:hover{color:#409ad5 !important}.wy-text-success{color:#27ae60 !important}a.wy-text-success:hover{color:#36d278 !important}.wy-text-danger{color:#e74c3c !important}a.wy-text-danger:hover{color:#ed7669 !important}.wy-text-neutral{color:#404040 !important}a.wy-text-neutral:hover{color:#595959 !important}h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif}p{line-height:24px;margin:0;font-size:16px;margin-bottom:24px}h1{font-size:175%}h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}code,.rst-content tt{white-space:nowrap;max-width:100%;background:#fff;border:solid 1px #e1e4e5;font-size:75%;padding:0 5px;font-family:"Incosolata","Consolata","Monaco",monospace;color:#e74c3c;overflow-x:auto}code.code-large,.rst-content tt.code-large{font-size:90%}.wy-plain-list-disc,.rst-content .section ul,.rst-content .toctree-wrapper ul,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.wy-plain-list-disc li,.rst-content .section ul li,.rst-content .toctree-wrapper ul li,article ul li{list-style:disc;margin-left:24px}.wy-plain-list-disc li ul,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li ul,article ul li ul{margin-bottom:0}.wy-plain-list-disc li li,.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,article ul li li{list-style:circle}.wy-plain-list-disc li li li,.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,article ul li li li{list-style:square}.wy-plain-list-decimal,.rst-content .section ol,.rst-content ol.arabic,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.wy-plain-list-decimal li,.rst-content .section ol li,.rst-content ol.arabic li,article ol li{list-style:decimal;margin-left:24px}.codeblock-example{border:1px solid #e1e4e5;border-bottom:none;padding:24px;padding-top:48px;font-weight:500;background:#fff;position:relative}.codeblock-example:after{content:"Example";position:absolute;top:0px;left:0px;background:#9b59b6;color:#fff;padding:6px 12px}.codeblock-example.prettyprint-example-only{border:1px solid #e1e4e5;margin-bottom:24px}.codeblock,pre.literal-block,.rst-content .literal-block,.rst-content pre.literal-block,div[class^='highlight']{border:1px solid #e1e4e5;padding:0px;overflow-x:auto;background:#fff;margin:1px 0 24px 0}.codeblock div[class^='highlight'],pre.literal-block div[class^='highlight'],.rst-content .literal-block div[class^='highlight'],div[class^='highlight'] div[class^='highlight']{border:none;background:none;margin:0}div[class^='highlight'] td.code{width:100%}.linenodiv pre{border-right:solid 1px #e6e9ea;margin:0;padding:12px 12px;font-family:"Incosolata","Consolata","Monaco",monospace;font-size:12px;line-height:1.5;color:#d9d9d9}div[class^='highlight'] pre{white-space:pre;margin:0;padding:12px 12px;font-family:"Incosolata","Consolata","Monaco",monospace;font-size:12px;line-height:1.5;display:block;overflow:auto;color:#404040}@media print{.codeblock,pre.literal-block,.rst-content .literal-block,.rst-content pre.literal-block,div[class^='highlight'],div[class^='highlight'] pre{white-space:pre-wrap}}.hll{background-color:#ffc;margin:0 -12px;padding:0 12px;display:block}.c{color:#998;font-style:italic}.err{color:#a61717;background-color:#e3d2d2}.k{font-weight:bold}.o{font-weight:bold}.cm{color:#998;font-style:italic}.cp{color:#999;font-weight:bold}.c1{color:#998;font-style:italic}.cs{color:#999;font-weight:bold;font-style:italic}.gd{color:#000;background-color:#fdd}.gd .x{color:#000;background-color:#faa}.ge{font-style:italic}.gr{color:#a00}.gh{color:#999}.gi{color:#000;background-color:#dfd}.gi .x{color:#000;background-color:#afa}.go{color:#888}.gp{color:#555}.gs{font-weight:bold}.gu{color:purple;font-weight:bold}.gt{color:#a00}.kc{font-weight:bold}.kd{font-weight:bold}.kn{font-weight:bold}.kp{font-weight:bold}.kr{font-weight:bold}.kt{color:#458;font-weight:bold}.m{color:#099}.s{color:#d14}.n{color:#333}.na{color:teal}.nb{color:#0086b3}.nc{color:#458;font-weight:bold}.no{color:teal}.ni{color:purple}.ne{color:#900;font-weight:bold}.nf{color:#900;font-weight:bold}.nn{color:#555}.nt{color:navy}.nv{color:teal}.ow{font-weight:bold}.w{color:#bbb}.mf{color:#099}.mh{color:#099}.mi{color:#099}.mo{color:#099}.sb{color:#d14}.sc{color:#d14}.sd{color:#d14}.s2{color:#d14}.se{color:#d14}.sh{color:#d14}.si{color:#d14}.sx{color:#d14}.sr{color:#009926}.s1{color:#d14}.ss{color:#990073}.bp{color:#999}.vc{color:teal}.vg{color:teal}.vi{color:teal}.il{color:#099}.gc{color:#999;background-color:#eaf2f5} +a{color:#2980b9;text-decoration:none}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%;overflow-x:hidden}body{font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;font-weight:normal;color:#404040;min-height:100%;overflow-x:hidden;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22 !important}a.wy-text-warning:hover{color:#eb9950 !important}.wy-text-info{color:#2980b9 !important}a.wy-text-info:hover{color:#409ad5 !important}.wy-text-success{color:#27ae60 !important}a.wy-text-success:hover{color:#36d278 !important}.wy-text-danger{color:#e74c3c !important}a.wy-text-danger:hover{color:#ed7669 !important}.wy-text-neutral{color:#404040 !important}a.wy-text-neutral:hover{color:#595959 !important}h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif}p{line-height:24px;margin:0;font-size:16px;margin-bottom:24px}h1{font-size:175%}h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}code,.rst-content tt{white-space:nowrap;max-width:100%;background:#fff;border:solid 1px #e1e4e5;font-size:75%;padding:0 5px;font-family:"Incosolata","Consolata","Monaco",monospace;color:#e74c3c;overflow-x:auto}code.code-large,.rst-content tt.code-large{font-size:90%}.wy-plain-list-disc,.rst-content .section ul,.rst-content .toctree-wrapper ul,article ul{list-style:disc;line-height:24px;margin-bottom:24px} +.wy-plain-list-disc li,.rst-content .section ul li,.rst-content .toctree-wrapper ul li,article ul li { + list-style:disc;margin-left:24px} + +.wy-plain-list-disc li ul,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li ul,article ul li ul{margin-bottom:0}.wy-plain-list-disc li li,.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,article ul li li{list-style:circle}.wy-plain-list-disc li li li,.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,article ul li li li{list-style:square}.wy-plain-list-decimal,.rst-content .section ol,.rst-content ol.arabic,article ol{list-style:decimal;line-height:24px;margin-bottom:24px} + +/* .wy-plain-list-decimal li,.rst-content .section ol li,.rst-content ol.arabic li,article ol li { */ +.wy-plain-list-decimal ol li,.rst-content .section ol li,.rst-content ol.arabic li,article ol li { + list-style:decimal;margin-left:24px + } + +/* HamishW - add to fix unordered bullets inside decimal lists */ +.rst-content ol.arabic ul li { + list-style:disc; + } + + + +.codeblock-example{border:1px solid #e1e4e5;border-bottom:none;padding:24px;padding-top:48px;font-weight:500;background:#fff;position:relative}.codeblock-example:after{content:"Example";position:absolute;top:0px;left:0px;background:#9b59b6;color:#fff;padding:6px 12px}.codeblock-example.prettyprint-example-only{border:1px solid #e1e4e5;margin-bottom:24px}.codeblock,pre.literal-block,.rst-content .literal-block,.rst-content pre.literal-block,div[class^='highlight']{border:1px solid #e1e4e5;padding:0px;overflow-x:auto;background:#fff;margin:1px 0 24px 0}.codeblock div[class^='highlight'],pre.literal-block div[class^='highlight'],.rst-content .literal-block div[class^='highlight'],div[class^='highlight'] div[class^='highlight']{border:none;background:none;margin:0}div[class^='highlight'] td.code{width:100%}.linenodiv pre{border-right:solid 1px #e6e9ea;margin:0;padding:12px 12px;font-family:"Incosolata","Consolata","Monaco",monospace;font-size:12px;line-height:1.5;color:#d9d9d9}div[class^='highlight'] pre{white-space:pre;margin:0;padding:12px 12px;font-family:"Incosolata","Consolata","Monaco",monospace;font-size:12px;line-height:1.5;display:block;overflow:auto;color:#404040}@media print{.codeblock,pre.literal-block,.rst-content .literal-block,.rst-content pre.literal-block,div[class^='highlight'],div[class^='highlight'] pre{white-space:pre-wrap}}.hll{background-color:#ffc;margin:0 -12px;padding:0 12px;display:block}.c{color:#998;font-style:italic}.err{color:#a61717;background-color:#e3d2d2}.k{font-weight:bold}.o{font-weight:bold}.cm{color:#998;font-style:italic}.cp{color:#999;font-weight:bold}.c1{color:#998;font-style:italic}.cs{color:#999;font-weight:bold;font-style:italic}.gd{color:#000;background-color:#fdd}.gd .x{color:#000;background-color:#faa}.ge{font-style:italic}.gr{color:#a00}.gh{color:#999}.gi{color:#000;background-color:#dfd}.gi .x{color:#000;background-color:#afa}.go{color:#888}.gp{color:#555}.gs{font-weight:bold}.gu{color:purple;font-weight:bold}.gt{color:#a00}.kc{font-weight:bold}.kd{font-weight:bold}.kn{font-weight:bold}.kp{font-weight:bold}.kr{font-weight:bold}.kt{color:#458;font-weight:bold}.m{color:#099}.s{color:#d14}.n{color:#333}.na{color:teal}.nb{color:#0086b3}.nc{color:#458;font-weight:bold}.no{color:teal}.ni{color:purple}.ne{color:#900;font-weight:bold}.nf{color:#900;font-weight:bold}.nn{color:#555}.nt{color:navy}.nv{color:teal}.ow{font-weight:bold}.w{color:#bbb}.mf{color:#099}.mh{color:#099}.mi{color:#099}.mo{color:#099}.sb{color:#d14}.sc{color:#d14}.sd{color:#d14}.s2{color:#d14}.se{color:#d14}.sh{color:#d14}.si{color:#d14}.sx{color:#d14}.sr{color:#009926}.s1{color:#d14}.ss{color:#990073}.bp{color:#999}.vc{color:teal}.vg{color:teal}.vi{color:teal}.il{color:#099}.gc{color:#999;background-color:#eaf2f5} .wy-breadcrumbs li{display:inline-block} .wy-breadcrumbs li.wy-breadcrumbs-aside { float:right; @@ -322,6 +340,14 @@ width:inherit; font-size:0.8em; } + +/* HamishW - fix bullet lists inside arabic decimal lists not rendering properly */ +/* .wy-plain-list-decimal li, .rst-content .section ol li, .rst-content ol.arabic li, article ol li +.wy-plain-list-decimal ul .simple li { + list-style:disc; + margin-left:24px + } + */ /* HamishW - some CSS for the breadcrumb (make elements inline blocks) */ diff --git a/site/source/docs/api_reference/advanced-apis.rst b/site/source/docs/api_reference/advanced-apis.rst index 2bf0125edfa19..704579a8ae52a 100644 --- a/site/source/docs/api_reference/advanced-apis.rst +++ b/site/source/docs/api_reference/advanced-apis.rst @@ -1,8 +1,8 @@ ========================================== -Advanced/Internal APIs (ready-for-review) +Advanced APIs (ready-for-review) ========================================== -This section lists APIs which are not considered suitable for general use, but which may be useful to some developers in some circumstances. These include APIs that are difficult or complicated to use, or which are intended primarily for Emscripten developers. +This section lists APIs that are not suitable for general use, but which may be useful to developers in some circumstances. These include APIs that are difficult or complicated to use, or which are intended primarily for Emscripten developers. .. contents:: Table of Contents :local: @@ -10,22 +10,22 @@ This section lists APIs which are not considered suitable for general use, but w - settings.js ============ `settings.js `_ contains default values and options used in various places by the compiler. -.. Warning :: Many **settings.js** options are highly brittle - certain combination of options and some options used with some source code, can cause Emscripten to fail badly. This is intended for use by "power users", and possibly even only people developing Emscripten itself. +.. Warning :: Many **settings.js** options are highly brittle - certain combinations of options, and combinations of certain options used with some source code, can cause Emscripten to fail badly. This is intended for use by "advanced users", and possibly even only people developing Emscripten itself. + -The options are normally set as command line parameters to *emcc*: :: +The options in **settings.js** are normally set as command line parameters to *emcc*: :: emcc -s OPT=VALUE -While it is possible to edit **settings.js** manually, this is *highly discouraged*. In general **settings.js** defines low-level options that should not be modified. Note also that the compiler changes some options depending on other settings. For example, ``ASSERTIONS`` is disabled in optimized builds (``-O1+``), but enabled by default in default (non-optimized) builds. +While it is possible to edit **settings.js** manually, this is *highly discouraged*. In general **settings.js** defines low-level options that should not be modified. Note also that the compiler changes some options depending on other settings. For example, ``ASSERTIONS`` is enabled by default, but disabled in optimized builds (``-O1+``). -The small number of options that people do need to change should be modified when the tool is invoked. For example, ``EXPORTED_FUNCTIONS``: :: +The small number of options that developers may have cause to change should be modified when the *emcc* tool is invoked. For example, ``EXPORTED_FUNCTIONS``: :: ./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS="['_int_sqrt']" @@ -39,11 +39,7 @@ allocate() Module.Runtime ================ -``Module.Runtime`` gives access to some low-level things in the runtime. Some of these, for example ``Runtime.stackSave()`` and ``Runtime.stackRestore()`` may be useful for advanced users. - - +``Module.Runtime`` gives access to low-level runtime functionality. Some of these, for example ``Runtime.stackSave()`` and ``Runtime.stackRestore()`` may be useful for advanced users. -emscripten_jcache_printf_() -=========================== +.. todo:: **HamishW** It would be useful to expand on what is offered by Module.Runtime -``emscripten_jcache_printf_()`` is an internal API documented in `emscripten.h `_. \ No newline at end of file diff --git a/site/source/docs/api_reference/emscripten.h.rst b/site/source/docs/api_reference/emscripten.h.rst index f43f05db3a946..9b96292634e1c 100644 --- a/site/source/docs/api_reference/emscripten.h.rst +++ b/site/source/docs/api_reference/emscripten.h.rst @@ -1,3 +1,5 @@ +.. _emscripten-h: + ================================ Emscripten.h (ready-for-review) ================================ @@ -18,7 +20,7 @@ Inline assembly/JavaScript Defines ------- -.. COMMENT (not rendered): **HamishW** This should be linked to section "Calling JavaScript From C/C++" when it exists. +.. todo:: **HamishW** This should be linked to section "Calling JavaScript From C/C++" when it exists. .. c:macro:: EM_ASM(...) @@ -26,12 +28,12 @@ Defines This allows you to declare JavaScript in your C code "inline", which is then executed when your compiled code is run in the browser. For example, the following C code would display two alerts if it was compiled with Emscripten and run in the browser: :: - EM_ASM( window.alert(‘hai’)); - window.alert(‘bai’)); ) + EM_ASM( alert(‘hai’)); + alert(‘bai’)); ) .. note:: - Double-quotes (") cannot be used in the inline assembly/JavaScript. Single-quotes (‘) can be used, as shown above. - - Newlines are supported + - Newlines (\\n, \\r etc.) are supported in the inline Javascript. Note that any platform-specific issues with line endings in normal JavaScript also apply to inline JavaScript declared using ``EM_ASM``. - This works with **asm.js** (it outlines the code and does a function call to reach it). - You can’t access C variables with :c:macro:`EM_ASM`, nor receive a value back. Instead use :c:macro:`EM_ASM_INT` or :c:macro:`EM_ASM_DOUBLE`. @@ -177,7 +179,7 @@ Functions :param int fps: Number of frames per second that the JavaScript will call the function. Setting ``int <=0`` (recommended) uses the browser’s ``requestAnimationFrame`` mechanism to call the function. :param int simulate_infinite_loop: If true, this function will throw an exception in order to stop execution of the caller. - .. COMMENT (not rendered): **HamishW** link to "Emscripten Browser Environment" doc when imported. + .. todo:: **HamishW** link to "Emscripten Browser Environment" doc when imported. .. c:function:: void emscripten_set_main_loop_arg(em_arg_callback_func func, void *arg, int fps, int simulate_infinite_loop) @@ -191,7 +193,7 @@ Functions :param int fps: Number of frames per second at which the JavaScript will call the function. Setting ``int <=0`` (recommended) uses the browser’s ``requestAnimationFrame`` mechanism to call the function. :param int simulate_infinite_loop: If true, this function will throw an exception in order to stop execution of the caller. - .. COMMENT (not rendered): **HamishW** link to "Emscripten Browser Environment" doc when imported. + .. todo:: **HamishW** link to "Emscripten Browser Environment" doc when imported. .. c:function:: void _emscripten_push_main_loop_blocker(em_arg_callback_func func, void *arg, const char *name) @@ -203,10 +205,9 @@ Functions In the "counted" version, blockers are counted (internally) and ``Module.setStatus`` is called with some text to report progress (``setStatus`` is a general hook that a program can define in order to show processing updates). - .. COMMENT (not rendered): **HamishW** Remember to cross link to "browser execution environment doc or similar when it exists". + .. todo:: **HamishW** Remember to cross link to "browser execution environment doc or similar when it exists". .. note:: - - When this function is called in a native build it is immediately executed; to keep semantics identical be careful to not push while the queue is being used. - Main loop blockers block the main loop from running, and can be counted to show progress. In contrast, ``emscripten_async_calls`` are not counted, do not block the main loop, and can fire at specific time in the future. :param em_arg_callback_func func: The main loop blocker function. The function signature must have a ``void*`` parameter for passing the ``arg`` value. @@ -445,7 +446,7 @@ Functions :type file: const char* :param requesttype: 'GET' or 'POST'. :type requesttype: const char* - :param param: Request parameters. If the ``requesttype`` is a POST request, this is a POST parameter like ``key=value&key2=value2``. + :param param: Request parameters for POST requests (see ``requesttype``). The parameters are specified in the same way as they would be in the URL for an equivalent GET request: e.g. ``key=value&key2=value2``. :type param: const char* :param void* arg: User-defined data that is passed to the callbacks, untouched by the API itself. This may be be used by a callback to identify the associated call. :param em_async_wget2_onload_func onload: Callback on successful load of the file. The callback function parameter values are: @@ -480,7 +481,7 @@ Functions :type url: const char* :param requesttype: 'GET' or 'POST'. :type requesttype: const char* - :param param: Request parameters. If the ``requesttype`` is a POST request, this is a POST parameter like ``key=value&key2=value2``. + :param param: Request parameters for POST requests (see ``requesttype``). The parameters are specified in the same way as they would be in the URL for an equivalent GET request: e.g. ``key=value&key2=value2``. :type param: const char* :param void* arg: User-defined data that is passed to the callbacks, untouched by the API itself. This may be be used by a callback to identify the associated call. :param const int free: Tells the runtime whether to free the returned buffer after ``onload`` is complete. If ``false`` freeing the buffer is the receiver's responsibility. @@ -621,7 +622,7 @@ Functions The worker function will be called with two parameters: a data pointer, and a size. The data block defined by the pointer and size exists only during the callback: **it cannot be relied upon afterwards**. If you need to keep some of that information outside the callback, then it needs to be copied to a safe location. - The called worker function can return data, by calling :c:func:`emscripten_worker_respond`. When the worker is called, if a callback was given it will be called with three arguments: a data pointer, a size, and an argument that was provided when calling :c:func:`emscripten_call_worker` (to more easily associate callbacks to calls). The data block defined by the data pointer and size behave like the data block in the worker function - it exists only during the callback. + The called worker function can return data, by calling :c:func:`emscripten_worker_respond`. When the worker is called, if a callback was given it will be called with three arguments: a data pointer, a size, and an argument that was provided when calling :c:func:`emscripten_call_worker` (to more easily associate callbacks to calls). The data block defined by the data pointer and size behave like the data block in the worker function — it exists only during the callback. :param worker_handle worker: A handle to the worker to be called. :param funcname: The name of the function in the worker. The function must be a C function (so no C++ name mangling), and must be exported (EXPORTED_FUNCTIONS). @@ -636,7 +637,7 @@ Functions :param void* arg: An argument (user data) to be passed to the callback - .. NOT-RENDERED-COMMENT : **HamishW** - need to add link to ``EXPORTED_FUNCTIONS`` information. There are some links on this around. + .. todo:: **HamishW** — need to add link to ``EXPORTED_FUNCTIONS`` information. There are some links on this around. .. c:function:: void emscripten_worker_respond(char *data, int size) void emscripten_worker_respond_provisionally(char *data, int size) @@ -758,7 +759,7 @@ Functions Gets preloaded image data and the size of the image. - The function returns pointer to loaded image or NULL - the pointer should be ``free()``'d. The width/height of the image are written to the ``w`` and ``h`` parameters if the data is valid. + The function returns pointer to loaded image or NULL — the pointer should be ``free()``'d. The width/height of the image are written to the ``w`` and ``h`` parameters if the data is valid. :param path: Full path/filename to the file containing the preloaded image. :type: const char* diff --git a/site/source/docs/api_reference/html5.h.rst b/site/source/docs/api_reference/html5.h.rst index 72f3cbbfdd220..e12b753cdbc2d 100644 --- a/site/source/docs/api_reference/html5.h.rst +++ b/site/source/docs/api_reference/html5.h.rst @@ -4,6 +4,10 @@ html5.h (ready-for-review) This page documents the C++ APIs provided by `html5.h `_. +.. tip:: The C++ APIs map closely to their equivalent HTML5 JavaScript APIs. The HTML5 specifications listed below provide additional detailed reference "over and above" the information provided in this document. + + In addition, the :ref:`test-example-code-html5-api` can be reviewed to see how the code is used. + These APIs define the Emscripten low-level glue bindings for interfacing with the following HTML5 APIs: - `DOM Level 3 Events: Keyboard, Mouse, Mouse Wheel, Resize, Scroll, Focus `_. @@ -20,6 +24,7 @@ These APIs define the Emscripten low-level glue bindings for interfacing with th + .. contents:: Table of Contents :local: :depth: 1 @@ -27,34 +32,37 @@ These APIs define the Emscripten low-level glue bindings for interfacing with th How to use this API =================== -Most web APIs are event-based; functionality is accessed by registering a callback function that will be called when the event occurs. +Most of these APIs use an event-based architecture; functionality is accessed by registering a callback function that will be called when the event occurs. + +.. note:: The Gamepad API is currently an exception, as only a polling API is available. For some APIs, both an event-based and a polling-based model are exposed. -.. note:: The Gamepad API is currently an exception, as only a polling API is available. For some APIs, both an event-based and a polling-based API are exposed. Registration functions ---------------------- -The typical format of registration functions is as follows (some methods may omit some parameters): :: +The typical format of registration functions is as follows (some methods may omit various parameters): - EMSCRIPTEN_RESULT emscripten_set_some_callback( - const char *target, // Target HTML element id. - void *userData, // User-defined data to be passed to the callback. - EM_BOOL useCapture, // Whether or not to use capture. - em_someevent_callback_func callback // Callback function. - ); + .. code-block:: cpp + + EMSCRIPTEN_RESULT emscripten_set_some_callback( + const char *target, // ID of the target HTML element. + void *userData, // User-defined data to be passed to the callback. + EM_BOOL useCapture, // Whether or not to use capture. + em_someevent_callback_func callback // Callback function. + ); .. _target-parameter-html5-api: -The ``target`` parameter is the HTML Element ID to which the callback registration is to be applied. This field has the following special meanings: +The ``target`` parameter is the ID of the HTML element to which the callback registration is to be applied. This field has the following special meanings: - ``0`` or ``NULL``: A default element is chosen automatically based on the event type, which should be reasonable most of the time. - - ``#window``: The event listener is applied to the JavaScript 'window' object. - - ``#document``: The event listener is applied to the JavaScript 'document' object. - - ``#screen``: The event listener is applied to the JavaScript 'window.screen' object. + - ``#window``: The event listener is applied to the JavaScript ``window`` object. + - ``#document``: The event listener is applied to the JavaScript ``document`` object. + - ``#screen``: The event listener is applied to the JavaScript ``window.screen`` object. - ``#canvas``: The event listener is applied to the Emscripten default WebGL canvas element. - - Any other string without a leading hash "#" sign: The event listener is applied to the element by the given ID on the page. + - Any other string without a leading hash "#" sign: The event listener is applied to the element on the page with the given ID. .. _userdata-parameter-html5-api: @@ -62,9 +70,9 @@ The ``userData`` parameter is a user-defined value that is passed (unchanged) to .. _usecapture-parameter-html5-api: -The ``useCapture`` parameter maps to ``useCapture`` in `EventTarget.addEventListener `_. It indicates whether or not to initiate *capture*: if ``true`` the callback will be invoked only for the DOM capture and target phases, if ``false`` the callback will be triggered during the target and bubbling phases. See `EventTarget.addEventListener `_ and `DOM Level 3 Events `_ for a more detailed explanation. +The ``useCapture`` parameter maps to ``useCapture`` in `EventTarget.addEventListener `_. It indicates whether or not to initiate *capture*: if ``true`` the callback will be invoked only for the DOM capture and target phases; if ``false`` the callback will be triggered during the target and bubbling phases. See `DOM Level 3 Events `_ for a more detailed explanation. -Most functions return the result using the type :c:data:`EMSCRIPTEN_RESULT`. Nonzero and positive values denote success. Negative values signal failure. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value :c:data:`EMSCRIPTEN_RESULT_NOT_SUPPORTED` will be returned at the time the callback is registered. +Most functions return the result using the type :c:data:`EMSCRIPTEN_RESULT`. Non-zero and positive values denote success. Negative values signal failure. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value :c:data:`EMSCRIPTEN_RESULT_NOT_SUPPORTED` will be returned at the time the callback is registered. Callback functions @@ -82,9 +90,9 @@ When the event occurs the callback is invoked with the relevant event "type" (fo .. _callback-handler-return-em_bool-html5-api: -Callback handlers that return an :c:data:`EM_BOOL` may specify ``true`` to signal that the handler *consumed* the event (this suppresses the default action for that event by calling its ``.preventDefault();`` member). Returning ``false`` indicates that the event was not consumed - the default browser event action is carried out and the event is allowed to pass on/bubble up as normal. +Callback handlers that return an :c:data:`EM_BOOL` may specify ``true`` to signal that the handler *consumed* the event (this suppresses the default action for that event by calling its ``.preventDefault();`` member). Returning ``false`` indicates that the event was not consumed — the default browser event action is carried out and the event is allowed to pass on/bubble up as normal. -Calling a registration function with a ``null`` pointer for the callback causes a de-registration of that callback from the given ``target`` element. All event handlers are also automatically unregistered when the C ``exit()`` function is invoked during the ``atexit`` handler pass. Use either the function :c:func:`emscripten_set_main_loop` or set ``Module.noExitRuntime = true;`` to make sure that leaving ``main()`` will not immediately cause an ``exit()`` and clean up the event handlers. +Calling a registration function with a ``null`` pointer for the callback causes a de-registration of that callback from the given ``target`` element. All event handlers are also automatically unregistered when the C ``exit()`` function is invoked during the ``atexit`` handler pass. Either use the function :c:func:`emscripten_set_main_loop` or set ``Module.noExitRuntime = true;`` to make sure that leaving ``main()`` will not immediately cause an ``exit()`` and clean up the event handlers. .. _web-security-functions-html5-api: @@ -100,6 +108,18 @@ When porting code, it may be difficult to ensure that the functions are called i Where possible, the functions should only be called inside appropriate event handlers. Setting ``deferUntilInEventHandler=false`` causes the functions to abort with an error if the request is refused due to a security restriction: this is a useful mechanism for discovering instances where the functions are called outside the handler for a user-generated event. +.. _test-example-code-html5-api: + +Test/Example code +----------------- + +The HTML5 test code demonstrates how to use this API: + + - `test_html5.c `_ + - `test_html5_fullscreen.c `_ + - `test_html5_mouse.c `_ + + General types ============= @@ -111,7 +131,7 @@ General types .. c:macro:: EM_UTF8 - This is the Emscripten type for a UTF8 string (maps to an ``char``). This is used for node names, element ids, etc. + This is the Emscripten type for a UTF8 string (maps to a ``char``). This is used for node names, element ids, etc. @@ -128,11 +148,11 @@ Most functions in this API return a result of type :c:data:`EMSCRIPTEN_RESULT`. .. c:macro:: EMSCRIPTEN_RESULT_SUCCESS - The operation succeeded + The operation succeeded. .. c:macro:: EMSCRIPTEN_RESULT_DEFERRED - The requested operation cannot be completed now for :ref:`web security reasons`. It was deferred for completion in the next event handler. + The requested operation cannot be completed now for :ref:`web security reasons`, and has been deferred for completion in the next event handler. .. c:macro:: EMSCRIPTEN_RESULT_NOT_SUPPORTED @@ -157,7 +177,7 @@ Most functions in this API return a result of type :c:data:`EMSCRIPTEN_RESULT`. .. c:macro:: EMSCRIPTEN_RESULT_FAILED - The operation failed for some generic reason. + Generic failure result message, returned if no specific result is available. .. c:macro:: EMSCRIPTEN_RESULT_NO_DATA @@ -227,7 +247,7 @@ Struct .. c:member:: EM_UTF8 locale - A locale string indicating the configured keyboard locale. This may be the empty string if the browser or device doesn't know the keyboard's locale. + A locale string indicating the configured keyboard locale. This may be an empty string if the browser or device doesn't know the keyboard's locale. Maximum size 32 char (i.e. ``EM_UTF8 locale[32]``). @@ -241,7 +261,7 @@ Struct .. c:member:: unsigned long charCode - The Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char attribute contains multiple characters, this is the Unicode value of the first character in that attribute. + The Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose ``char`` attribute contains multiple characters, this is the Unicode value of the first character in that attribute. .. warning:: This attribute is deprecated, you should use the field ``key`` instead, if available. @@ -264,9 +284,9 @@ Callback functions .. c:type:: em_key_callback_func - Function pointer for the :c:func:`keypress callback functions `. + Function pointer for the :c:func:`keypress callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_key_callback_func)(int eventType, const EmscriptenKeyboardEvent *keyEvent, void *userData); @@ -295,7 +315,7 @@ Functions :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| - :seealso: + :see also: - https://developer.mozilla.org/en/DOM/Event/UIEvent/KeyEvent - http://www.javascriptkit.com/jsref/eventkeyboardmouse.shtml @@ -334,7 +354,7 @@ Struct .. c:member:: long clientX long clientY - The coordinates relative to the viewport associate with the event. + The coordinates relative to the viewport associated with the event. .. c:member:: EM_BOOL ctrlKey @@ -372,7 +392,9 @@ Struct .. c:member:: long padding - Internal, and can be ignored (note for implementers: pad this struct to multiple of 8 bytes to make WheelEvent unambiguously align to 8 bytes). + Internal, and can be ignored. + + .. note:: Implementers only: pad this struct to multiple of 8 bytes to make ``WheelEvent`` unambiguously align to 8 bytes. Callback functions @@ -380,9 +402,9 @@ Callback functions .. c:type:: em_mouse_callback_func - Function pointer for the :c:func:`mouse event callback functions `. + Function pointer for the :c:func:`mouse event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_mouse_callback_func)(int eventType, const EmscriptenMouseEvent *keyEvent, void *userData); @@ -478,9 +500,9 @@ Callback functions .. c:type:: em_wheel_callback_func - Function pointer for the :c:func:`wheel event callback functions `. + Function pointer for the :c:func:`wheel event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_wheel_callback_func)(int eventType, const EmscriptenWheelEvent *keyEvent, void *userData); @@ -537,17 +559,17 @@ Struct .. c:member:: int documentBodyClientWidth int documentBodyClientHeight - The clientWidth/clientHeight of the document.body element. + The clientWidth/clientHeight of the ``document.body`` element. .. c:member:: int windowInnerWidth int windowInnerHeight - The innerWidth/innerHeight of the window element. + The innerWidth/innerHeight of the browser window. .. c:member:: int windowOuterWidth int windowOuterHeight; - The outerWidth/outerHeight of the window element. + The outerWidth/outerHeight of the browser window. .. c:member:: int scrollTop int scrollLeft @@ -560,9 +582,9 @@ Callback functions .. c:type:: em_ui_callback_func - Function pointer for the :c:func:`UI event callback functions `. + Function pointer for the :c:func:`UI event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_ui_callback_func)(int eventType, const EmscriptenUiEvent *keyEvent, void *userData); @@ -622,7 +644,7 @@ Struct .. c:member:: EM_UTF8 id - The HTML Element ID of the target element. + The ID of the target element. Maximum size 128 ``char`` (i.e. ``EM_UTF8 id[128]``). @@ -633,9 +655,9 @@ Callback functions .. c:type:: em_focus_callback_func - Function pointer for the :c:func:`focus event callback functions `. + Function pointer for the :c:func:`focus event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_focus_callback_func)(int eventType, const EmscriptenFocusEvent *keyEvent, void *userData); @@ -707,9 +729,9 @@ Callback functions .. c:type:: em_deviceorientation_callback_func - Function pointer for the :c:func:`orientation event callback functions `. + Function pointer for the :c:func:`orientation event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_deviceorientation_callback_func)(int eventType, const EmscriptenDeviceOrientationEvent *keyEvent, void *userData); @@ -742,7 +764,8 @@ Functions Note that for this function call to succeed, :c:func:`emscripten_set_deviceorientation_callback` must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the ``deviceorientation`` state capture. - :param EmscriptenDeviceOrientationEvent *orientationState: The most recently received deviceorientation event state. + :param orientationState: The most recently received ``deviceorientation`` event state. + :type orientationState: EmscriptenDeviceOrientationEvent* :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| @@ -797,9 +820,9 @@ Callback functions .. c:type:: em_devicemotion_callback_func - Function pointer for the :c:func:`devicemotion event callback functions `. + Function pointer for the :c:func:`devicemotion event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_devicemotion_callback_func)(int eventType, const EmscriptenDeviceMotionEvent *keyEvent, void *userData); @@ -833,7 +856,8 @@ Functions Note that for this function call to succeed, :c:func:`emscripten_set_devicemotion_callback` must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the ``devicemotion`` state capture. - :param EmscriptenDeviceMotionEvent *motionState: The most recently received ``devicemotion`` event state. + :param motionState: The most recently received ``devicemotion`` event state. + :type motionState: EmscriptenDeviceMotionEvent* :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| @@ -881,7 +905,7 @@ Struct .. c:member:: int orientationAngle - Emscripten-specific extension: Some browsers refer to 'window.orientation', so report that as well. + Emscripten-specific extension: Some browsers refer to ``window.orientation``, so report that as well. Orientation angle in degrees. 0: "default orientation", i.e. default upright orientation to hold the mobile device in. Could be either landscape or portrait. @@ -891,9 +915,9 @@ Callback functions .. c:type:: em_orientationchange_callback_func - Function pointer for the :c:func:`orientationchange event callback functions `. + Function pointer for the :c:func:`orientationchange event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_orientationchange_callback_func)(int eventType, const EmscriptenOrientationChangeEvent *keyEvent, void *userData); @@ -923,14 +947,15 @@ Functions Returns the current device orientation state. - :param EmscriptenOrientationChangeEvent *orientationStatus: The most recently received orientation state. + :param orientationStatus: The most recently received orientation state. + :type orientationStatus: EmscriptenOrientationChangeEvent* :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| .. c:function:: EMSCRIPTEN_RESULT emscripten_lock_orientation(int allowedOrientations) - Locks the screen orientation to the given set of allowed orientations. + Locks the screen orientation to the given set of :c:data:`allowed orientations `. :param int allowedOrientations: A bitfield set of :c:data:`EMSCRIPTEN_ORIENTATION_xxx ` flags. :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. @@ -983,7 +1008,7 @@ Struct .. c:member:: EM_UTF8 id - The HTML Element ID of the target HTML element that is in full screen mode. + The ID of the target HTML element that is in full screen mode. Maximum size 128 ``char`` (i.e. ``EM_UTF8 id[128]``). @@ -1005,9 +1030,9 @@ Callback functions .. c:type:: em_fullscreenchange_callback_func - Function pointer for the :c:func:`fullscreen event callback functions `. + Function pointer for the :c:func:`fullscreen event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_fullscreenchange_callback_func)(int eventType, const EmscriptenFullscreenChangeEvent *keyEvent, void *userData); @@ -1040,7 +1065,8 @@ Functions Returns the current page `fullscreen `_ state. - :param EmscriptenFullscreenChangeEvent *fullscreenStatus: The most recently received fullscreen state. + :param fullscreenStatus: The most recently received fullscreen state. + :type fullscreenStatus: EmscriptenFullscreenChangeEvent* :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| @@ -1049,7 +1075,7 @@ Functions Requests the given target element to transition to full screen mode. - .. note:: This function can be called anywhere, but for web security reasons its associated *request* can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of ``deferUntilInEventHandler`` - see :ref:`web-security-functions-html5-api` for more information. + .. note:: This function can be called anywhere, but for web security reasons its associated *request* can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of ``deferUntilInEventHandler`` — see :ref:`web-security-functions-html5-api` for more information. :param target: |target-parameter-doc| :type target: const char* @@ -1099,7 +1125,7 @@ Struct .. c:member:: EM_UTF8 id - The HTML Element ID of the target HTML element that has the pointer lock active. + The ID of the target HTML element that has the pointer lock active. Maximum size 128 ``char`` (i.e. ``EM_UTF8 id[128]``). @@ -1109,9 +1135,9 @@ Callback functions .. c:type:: em_pointerlockchange_callback_func - Function pointer for the :c:func:`pointerlockchange event callback functions `. + Function pointer for the :c:func:`pointerlockchange event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_pointerlockchange_callback_func)(int eventType, const EmscriptenPointerlockChangeEvent *keyEvent, void *userData); @@ -1156,7 +1182,7 @@ Functions Requests the given target element to grab pointerlock. - .. note:: This function can be called anywhere, but for web security reasons its associated *request* can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of ``deferUntilInEventHandler`` - see :ref:`web-security-functions-html5-api` for more information. + .. note:: This function can be called anywhere, but for web security reasons its associated *request* can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of ``deferUntilInEventHandler`` — see :ref:`web-security-functions-html5-api` for more information. :param target: |target-parameter-doc| @@ -1219,7 +1245,7 @@ Struct .. c:member:: int visibilityState - Specifies a more fine-grained state of the current page visibility status. One of the EMSCRIPTEN_VISIBILITY_ values. + Specifies a more fine-grained state of the current page visibility status. One of the :c:type:`EMSCRIPTEN_VISIBILITY_ ` values. Callback functions @@ -1227,14 +1253,14 @@ Callback functions .. c:type:: em_visibilitychange_callback_func - Function pointer for the :c:func:`visibilitychange event callback functions `. + Function pointer for the :c:func:`visibilitychange event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_visibilitychange_callback_func)(int eventType, const EmscriptenVisibilityChangeEvent *keyEvent, void *userData); - :param int eventType: The type of visibilitychange event (:c:data:`EMSCRIPTEN_VISIBILITY_HIDDEN`). - :param keyEvent: Information about the visibilitychange event that occurred. + :param int eventType: The type of ``visibilitychange`` event (:c:data:`EMSCRIPTEN_VISIBILITY_HIDDEN`). + :param keyEvent: Information about the ``visibilitychange`` event that occurred. :type keyEvent: const EmscriptenVisibilityChangeEvent* :param void* userData: The ``userData`` originally passed to the registration function. :returns: |callback-handler-return-value-doc| @@ -1307,11 +1333,11 @@ Struct .. c:member:: EM_BOOL isChanged - Specifies whether this touch point changed during this event. + Specifies whether the touch point changed during this event. .. c:member:: EM_BOOL onTarget - Specifies whether this touch point is still above the original target on which it was initially pressed against. + Specifies whether this touch point is still above the original target on which it was initially pressed. .. c:member:: long canvasX long canvasY @@ -1334,7 +1360,7 @@ Struct EM_BOOL altKey EM_BOOL metaKey - Specifies which modifiers were active during the key event. + Specifies which modifiers were active during the touch event. .. c:member:: EmscriptenTouchPoint touches[32] @@ -1348,9 +1374,9 @@ Callback functions .. c:type:: em_touch_callback_func - Function pointer for the :c:func:`touch event callback functions `. + Function pointer for the :c:func:`touch event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_touch_callback_func)(int eventType, const EmscriptenTouchEvent *keyEvent, void *userData); @@ -1409,7 +1435,7 @@ Struct .. c:member:: int numAxes - The number of valid axes entries in the axis array. + The number of valid axis entries in the ``axis`` array. .. c:member:: int numButtons @@ -1456,9 +1482,9 @@ Callback functions .. c:type:: em_gamepad_callback_func - Function pointer for the :c:func:`gamepad event callback functions `. + Function pointer for the :c:func:`gamepad event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_gamepad_callback_func)(int eventType, const EmscriptenGamepadEvent *keyEvent, void *userData) @@ -1496,7 +1522,7 @@ Functions :rtype: int -.. c:function:: EMSCRIPTEN_RESULT emscripten_get_gamepad_status(int index, EmscriptenGamepadEvent *gamepadState); +.. c:function:: EMSCRIPTEN_RESULT emscripten_get_gamepad_status(int index, EmscriptenGamepadEvent *gamepadState) Returns a snapshot of the current gamepad state. @@ -1541,7 +1567,7 @@ Struct .. c:member:: EM_BOOL charging; - ``true`` if the batter is charging, ``false`` otherwise. + ``true`` if the battery is charging, ``false`` otherwise. Callback functions @@ -1549,14 +1575,14 @@ Callback functions .. c:type:: em_battery_callback_func - Function pointer for the :c:func:`batterymanager event callback functions `. + Function pointer for the :c:func:`batterymanager event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_battery_callback_func)(int eventType, const EmscriptenBatteryEvent *keyEvent, void *userData); - :param int eventType: The type of batterymanager event (:c:data:`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`). - :param keyEvent: Information about the batterymanager event that occurred. + :param int eventType: The type of ``batterymanager`` event (:c:data:`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`). + :param keyEvent: Information about the ``batterymanager`` event that occurred. :type keyEvent: const EmscriptenBatteryEvent* :param void* userData: The ``userData`` originally passed to the registration function. :returns: |callback-handler-return-value-doc| @@ -1583,7 +1609,8 @@ Functions Returns the current battery status. - :param EmscriptenBatteryEvent *batteryState: The most recently received battery state. + :param batteryState: The most recently received battery state. + :type batteryState: EmscriptenBatteryEvent* :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| @@ -1600,7 +1627,7 @@ Functions Produces a `vibration `_ for the specified time, in milliseconds. - :param int msecs: The amount of time for which the vibration is required (milliseconds) + :param int msecs: The amount of time for which the vibration is required (milliseconds). :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. :rtype: |EMSCRIPTEN_RESULT| @@ -1631,13 +1658,13 @@ Callback functions .. c:type:: em_beforeunload_callback - Function pointer for the :c:func:`beforeunload event callback functions `. + Function pointer for the :c:func:`beforeunload event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef const char *(*em_beforeunload_callback)(int eventType, const void *reserved, void *userData); - :param int eventType: The type of beforeunload event (:c:data:`EMSCRIPTEN_EVENT_BEFOREUNLOAD`). + :param int eventType: The type of ``beforeunload`` event (:c:data:`EMSCRIPTEN_EVENT_BEFOREUNLOAD`). :param reserved: Reserved for future use; pass in 0. :type reserved: const void* :param void* userData: The ``userData`` originally passed to the registration function. @@ -1654,7 +1681,7 @@ Functions Registers a callback function for receiving the page `beforeunload `_ event. - Hook onto this event to perform actions immediately prior to page close (for example, to display a notification to ask if the user really wants to leave the page). + Hook into this event to perform actions immediately prior to page close (for example, to display a notification to ask if the user really wants to leave the page). :param void* userData: |userData-parameter-doc| :param em_beforeunload_callback callback: |callback-function-parameter-doc| @@ -1681,9 +1708,9 @@ Callback functions .. c:type:: em_webgl_context_callback - Function pointer for the :c:func:`WebGL Context event callback functions `. + Function pointer for the :c:func:`WebGL Context event callback functions `, defined as: - Defined as: :: + .. code-block:: cpp typedef EM_BOOL (*em_webgl_context_callback)(int eventType, const void *reserved, void *userData); @@ -1719,7 +1746,8 @@ Functions Queries the given canvas element for whether its WebGL context is in a lost state. - :param const char *target: Reserved for future use, pass in 0. + :param target: Reserved for future use, pass in 0. + :type target: const char* :returns: ``true`` if the WebGL context is in a lost state. :rtype: |EM_BOOL| @@ -1738,7 +1766,7 @@ Functions .. |target-parameter-doc| replace:: :ref:`Target HTML element id `. .. |userData-parameter-doc| replace:: :ref:`User-defined data ` to be passed to the callback (opaque to the API). .. |useCapture-parameter-doc| replace:: Set ``true`` to :ref:`use capture `. -.. |callback-handler-return-value-doc| replace:: Return ``true`` (non zero) to indicate that the event was consumed by the :ref:`callback handler `. +.. |callback-handler-return-value-doc| replace:: ``true`` (non zero) to indicate that the event was consumed by the :ref:`callback handler `. .. |callback-function-parameter-doc| replace:: A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return ``true`` if the event is consumed. diff --git a/site/source/docs/api_reference/index.rst b/site/source/docs/api_reference/index.rst index 083250715a035..ac6fcbaf8cb1f 100644 --- a/site/source/docs/api_reference/index.rst +++ b/site/source/docs/api_reference/index.rst @@ -4,16 +4,24 @@ API Reference (under-construction) This section lists Emscripten's public API, organised by header file. At very high level it consists of: -- **emscripten.h**: APIs for integrating with the browser environment. - Specifically: controlling application execution, calling JavaScript from C code, loading files, logging etc. -- **html5.h**: Low level glue bindings for interfacing with HTML5 APIs from your native code. - Includes events of all types, from key, mouse and touch events, through to screen and device orientation events, through to WebGL context events etc. -- **preamble.js**: APIs for working with compiled code. - Includes: calling compiled C functions, accessing memory, converting pointers to JavaScript ``Strings`` and ``Strings`` to pointers (with different encodings/formats), and other convenience functions. +- **emscripten.h**: *APIs for integrating with the browser environment.* + + This includes APIs for: controlling application execution, calling JavaScript from C code, loading files, logging etc. + +- **html5.h**: *Low level glue bindings for interfacing with HTML5 APIs from native code.* + + This includes APIs for registering event callbacks for all types of HTML5 events, ranging from key, mouse and touch events, through to screen and device orientation events, through to WebGL context events etc. -.. todo:: Add text here for the file system (HamishW). Maybe rename the file. +- **preamble.js**: *APIs for working with compiled code.* + + This includes APIs for calling compiled C functions, accessing memory, converting pointers to JavaScript ``Strings`` and ``Strings`` to pointers (with different encodings/formats), and other convenience functions. + +- **Filesystem-API (library_fs.js)**: *APIs for (primarily) synchronous File I/O.* + +- **Advanced APIs**: *APIs for advanced users/core developers* + + In addition to the public APIs listed above, there are additional APIs which are intended only when developing Emscripten itself, or which are complicated to use and hence considered suitable for "advanced users". At time of writing are not documented individually, but are mentioned at high level in :doc:`advanced-apis`. -In addition to the public API, there are additional APIs which are intended only when developing Emscripten itself, or which are complicated to use and hence considered suitable for "advanced users". At time of writing are not documented individually, but are mentioned at high level in :doc:`advanced-apis`. .. toctree:: :maxdepth: 1 diff --git a/site/source/docs/api_reference/preamble.js.rst b/site/source/docs/api_reference/preamble.js.rst index 45c96b682451f..13c5d58cd1c04 100644 --- a/site/source/docs/api_reference/preamble.js.rst +++ b/site/source/docs/api_reference/preamble.js.rst @@ -2,11 +2,9 @@ preamble.js (ready-for-review) ======================================================= -This page documents the public JavaScript APIs provided by `preamble.js `_. +The JavaScript APIs in `preamble.js `_ provide programmatic access for interacting with the compiled C code, including: calling compiled C functions, accessing memory, converting pointers to JavaScript ``Strings`` and ``Strings`` to pointers (with different encodings/formats), and other convenience functions. -The APIs provide programmatic access for working with compiled code, including: calling compiled C functions, accessing memory, converting pointers to JavaScript ``Strings`` and ``Strings`` to pointers (with different encodings/formats), and other convenience functions. - -.. note:: All functions should be called though the ``Module`` object (for example: ``Module.functionName``) because calling the functions directly will fail at higher optimisation levels. This is because at optimisation ``-O2`` (and higher) function names are minified by the closure compiler and the ``Module`` object becomes the only way to access them. +.. note:: All functions should be called though the ``Module`` object (for example: ``Module.functionName``). At optimisation ``-O2`` (and higher) function names are minified by the closure compiler, and calling them directly will fail. .. contents:: Table of Contents @@ -22,7 +20,7 @@ Calling compiled C functions from JavaScript Call a compiled C function from JavaScript. - The function calls/executes a compiled C function from JavaScript and returns the result. The C function can be defined in a C file, or be C-compatible C++ function defined using ``extern "C"`` (to prevent name mangling). + The function executes a compiled C function from JavaScript and returns the result. C++ name mangling means that "normal" C++ functions cannot be called; the function must either be defined in a **.c** file or be a C++ function defined with ``extern "C"``. .. code-block:: javascript @@ -34,14 +32,21 @@ Calling compiled C functions from JavaScript // result is 30 - .. COMMENT (not rendered): There is more complete documentation in the guide: **HamishW** - add link to guide when it exists (currently in wiki at "Interacting with code"). + .. COMMENT (not rendered): There is more complete documentation in the guide: **HamishW** — add link to guide when it exists (currently in wiki at "Interacting with code"). .. note:: - ``ccall`` uses the C stack for temporary values. If you pass a string then it is only "alive" until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data. - - If you need a string to live forever, you can create it, for example, using ``malloc`` and js:func:`writeStringToMemory`. However you must later delete it manually! - - LLVM optimizations can inline and remove functions, after which you will not be able to call them. Closure can also do so. To avoid that, add your function to the exports using something like: :: + - If you need a string to live forever, you can create it, for example, using ``malloc`` and :js:func:`writeStringToMemory`. However, you must later delete it manually! + - LLVM optimizations can inline and remove functions, after which you will not be able to call them. Similarly, function names minified by the *Closure Compiler* are inaccessible. In either case, the solution is to add the functions to the ``EXPORTED_FUNCTIONS`` list when you invoke *emcc* : + + :: - -s EXPORTED_FUNCTIONS='["_main", "_myfunc"]' + -s EXPORTED_FUNCTIONS='["_main", "_myfunc"]' + + Exported functions can be called as normal: :: + + a_result = Module.ccall('myfunc', 'number', ['number'], 10) + :param ident: The name of the C function to be called. :param returnType: The return type of the function. This will be one of the JavaScript types ``number``, ``string`` or ``array`` (use ``number`` for any C pointer, and ``array`` for JavaScript arrays and typed arrays; note that arrays are 8-bit). @@ -56,7 +61,7 @@ Calling compiled C functions from JavaScript Returns a native JavaScript wrapper for a C function. - This is similar to :js:func:`ccall`, but returns a JavaScript function which can be reused as many time as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using ``extern "C"`` (to prevent name mangling). + This is similar to :js:func:`ccall`, but returns a JavaScript function that can be reused as many time as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using ``extern "C"`` (to prevent name mangling). .. code-block:: javascript @@ -70,14 +75,21 @@ Calling compiled C functions from JavaScript console.log(c_javascript_add(10, 20)); // 30 console.log(c_javascript_add(20, 30)); // 50 - .. COMMENT (not rendered): There is more complete documentation in the guide: **HamishW** - add link to guide when it exists (currently in wiki at "Interacting with code"). + .. COMMENT (not rendered): There is more complete documentation in the guide: **HamishW** — add link to guide when it exists (currently in wiki at "Interacting with code"). .. note:: - ``cwrap`` uses the C stack for temporary values. If you pass a string then it is only "alive" until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data. - - If you need a string to live forever, you can create it, for example, using ``malloc`` and :js:func:`writeStringToMemory`. However you must later delete it manually! - - LLVM optimizations can inline and remove functions, after which you will not be able to call them. Closure can also do so. To avoid that, add your function to the exports using something like: :: + - If you need a string to live forever, you can create it, for example, using ``malloc`` and :js:func:`writeStringToMemory`. However, you must later delete it manually! + - LLVM optimizations can inline and remove functions, after which you will not be able to "wrap" them. Similarly, function names minified by the *Closure Compiler* are inaccessible. In either case, the solution is to add the functions to the ``EXPORTED_FUNCTIONS`` list when you invoke *emcc* : + + :: - -s EXPORTED_FUNCTIONS='["_main", "_myfunc"]' + -s EXPORTED_FUNCTIONS='["_main", "_myfunc"]' + + Exported functions can be called as normal: :: + + my_func = Module.cwrap('myfunc', 'number', ['number']) + my_func(12) :param ident: The name of the C function to be called. :param returnType: The return type of the function. This will be one of the JavaScript types ``number``, ``string`` or ``array`` (use ``number`` for any C pointer, and ``array`` for JavaScript arrays and typed arrays; note that arrays are 8-bit). @@ -97,12 +109,12 @@ Accessing memory .. note:: - :js:func:`setValue` and :js:func:`getValue` only do *aligned* writes and reads. - - The ``type` is an LLVM IR type (one of ``i8``,``i16``,``i32``,``i64``,``float``,``double`, or a pointer type like `i8*` or just *), not JavaScript types as used in :js:func:`ccall` or :js:func:`cwrap`. This is a lower-level operation, and we do need to care what specific type is being used. + - The ``type`` is an LLVM IR type (one of ``i8``, ``i16``, ``i32``, ``i64``, ``float``, ``double``, or a pointer type like ``i8*`` or just *), not JavaScript types as used in :js:func:`ccall` or :js:func:`cwrap`. This is a lower-level operation, and we do need to care what specific type is being used. :param ptr: A pointer (number) representing the memory address. :param value: The value to be stored :param type: An LLVM IR type as a string (see "note" above). - :param noSafe: Developers should ignore this variable. It is on used in ``SAFE_HEAP`` compilation mode, where it can be avoid infinite recursion in some specialist use cases. + :param noSafe: Developers should ignore this variable. It is only used in ``SAFE_HEAP`` compilation mode, where it can help avoid infinite recursion in some specialist use cases. :type noSafe: bool @@ -124,14 +136,14 @@ Accessing memory -Conversion functions - strings, pointers and arrays +Conversion functions — strings, pointers and arrays =================================================== .. js:function:: Pointer_stringify(ptr[, length]) Returns a JavaScript String from a pointer, for use in compiled code. - :param ptr: The pointer to be converted to a ``String`. + :param ptr: The pointer to be converted to a ``String``. :param length: The length of the data in the pointer (optional). :returns: A JavaScript ``String`` containing the data from ``ptr``. :rtype: String @@ -151,27 +163,27 @@ Conversion functions - strings, pointers and arrays Copies the given JavaScript ``String`` object ``str`` to the Emscripten HEAP at address ``outPtr``, null-terminated and encoded in UTF16LE form. - The copy will require at most (str.length*2+1)*2 bytes of space in the HEAP. + The copy will require at most ``(str.length*2+1)*2`` bytes of space in the HEAP. :param str: A JavaScript ``String`` object. :type str: String - :param outPtr: Pointer to data copied from ``str``, encoded in encoded in UTF16LE format and null-terminated. + :param outPtr: Pointer to data copied from ``str``, encoded in UTF16LE format and null-terminated. .. js:function:: UTF32ToString(ptr) - Given a pointer ``ptr`` to a null-terminated UTF32LE-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript String object. + Given a pointer ``ptr`` to a null-terminated UTF32LE-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript ``String`` object. - :param ptr: A pointer to a null-terminated UTF16LE-encoded string in the Emscripten HEAP. - :returns: A Javascript ``String`` object + :param ptr: A pointer to a null-terminated UTF32LE-encoded string in the Emscripten HEAP. + :returns: A Javascript ``String`` object. .. js:function:: stringToUTF32(str, outPtr) Copies the given JavaScript ``String`` object ``str`` to the Emscripten HEAP at address ``outPtr``, null-terminated and encoded in UTF32LE form. - The copy will require at most (str.length+1)*4 bytes of space in the HEAP, but can use less, since ``str.length`` does not return the number of characters in the string, but the number of UTF-16 code units in the string. + The copy will require at most ``(str.length+1)*4`` bytes of space in the HEAP, but can use less, since ``str.length`` does not return the number of characters in the string, but the number of UTF-16 code units in the string. :param str: A JavaScript ``String`` object. :type str: String @@ -202,7 +214,7 @@ Conversion functions - strings, pointers and arrays .. js:function:: writeStringToMemory(string, buffer, dontAddNull) - Write a JavaScript string to a specified address in the heap. + Writes a JavaScript string to a specified address in the heap. .. code-block:: javascript @@ -216,7 +228,7 @@ Conversion functions - strings, pointers and arrays :param string: The string to write into memory. :type string: String - :param buffer: The address (number) to write the string. + :param buffer: The address (number) where ``string`` is to be written. :type buffer: Number :param dontAddNull: If ``true``, the new array is not zero-terminated. :type dontAddNull: bool @@ -225,17 +237,17 @@ Conversion functions - strings, pointers and arrays .. js:function:: writeArrayToMemory(array, buffer) - Writes an array to a specified address in the heap. Note that needs to be allocated for this array first. + Writes an array to a specified address in the heap. Note that memory should to be allocated for the array before it is written. :param array: The array to write to memory. - :param buffer: The address (number) to write the array. + :param buffer: The address (number) where ``array`` is to be written. :type buffer: Number .. js:function:: writeAsciiToMemory(str, buffer, dontAddNull) - Writes an ASCII string to a specified address in the heap. Note that space to be allocated for this array first. + Writes an ASCII string to a specified address in the heap. Note that memory should to be allocated for the string before it is written. The string is assumed to only have characters in the ASCII character set. If ASSERTIONS are enabled and this is not the case, it will fail. @@ -248,8 +260,8 @@ Conversion functions - strings, pointers and arrays Module.writeStringToMemory(myString, buffer); :param string: The string to write into memory. - :param buffer: The address to write the string. - :param dontAddNull: If ``true``, the new array is not zero-terminated. + :param buffer: The address where ``string`` is to be written. + :param dontAddNull: If ``true``, the new string is not zero-terminated. :type dontAddNull: bool @@ -277,9 +289,9 @@ Note that generally run dependencies are managed by the file packager and other Removes a specified ``id`` from the list of run dependencies. - .. COMMENT (not rendered): **HamishW** Remember to link to Execution lifecycle in Browser environment or otherwise link to information on using this. + .. todo:: **HamishW** Remember to link to Execution lifecycle in Browser environment or otherwise link to information on using this. - :param id: The identifier for the specific dependency (added with :js:func:`addRunDependency`) that has been met. + :param id: The identifier for the specific dependency to be removed (added with :js:func:`addRunDependency`) :type id: String @@ -301,54 +313,54 @@ Stack trace Type accessors for Typed Arrays Mode 2 ========================================== -When using *Typed Arrays Mode 2* a type array buffer is used to represent memory, with different views into it giving access to the different types. The views for accessing different types of memory are listed below. +When using :ref:`typed-arrays-mode-2` a type array buffer is used to represent memory, with different views into it giving access to the different types. The views for accessing different types of memory are listed below. .. COMMENT (not rendered): **HamishW** Link to TO TYPED ARRAYS MODE2 DOCUMENTATION when this is ported .. js:data:: HEAP8 - View for 8-bit signed memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 8-bit signed memory. .. js:data:: HEAP16 - View for 16-bit signed memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 16-bit signed memory. .. js:data:: HEAP32 - View for 32-bit signed memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 32-bit signed memory. .. js:data:: HEAPU8 - View for 32-bit unsigned memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 32-bit unsigned memory. .. js:data:: HEAPU8 - View for 32-bit unsigned memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 32-bit unsigned memory. .. js:data:: HEAPU16 - View for 16-bit unsigned memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 16-bit unsigned memory. .. js:data:: HEAPU32 - View for 32-bit unsigned memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 32-bit unsigned memory. .. js:data:: HEAPF32 - View for 32-bit float memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 32-bit float memory. .. js:data:: HEAPF64 - View for 64-bit float memory. This is a view into the type array buffer used to represent memory in Typed Arrays Mode 2. + View for 64-bit float memory. @@ -357,7 +369,7 @@ When using *Typed Arrays Mode 2* a type array buffer is used to represent memory .. COMMENT (not rendered) : The following methods are explicitly not part of the public API and not documented. Note that in some case referred to by function name, other cases by Module assignment. - function allocate(slab, types, allocator, ptr) - Internal and use is discouraged. Documentation can remain in source code but not here. + function allocate(slab, types, allocator, ptr) — Internal and use is discouraged. Documentation can remain in source code but not here. associated contants ALLOC_NORMAL, ALLOC_STACK, ALLOC_STATIC, ALLOC_DYNAMIC, ALLOC_NONE function addOnPreRun @@ -400,7 +412,7 @@ When using *Typed Arrays Mode 2* a type array buffer is used to represent memory function CHECK_ALIGN_4(addr) function CHECK_ALIGN_2(addr) function CHECK_OVERFLOW(value, bits, ignore, sig) - Module['PGOMonitor'] = PGOMonitor; - a bit confusing + Module['PGOMonitor'] = PGOMonitor; — a bit confusing Module["preloadedImages"] Module["preloadedAudios"] diff --git a/site/source/docs/compiling/Code-Generation-Modes.rst b/site/source/docs/compiling/Code-Generation-Modes.rst index 40027e5ae075e..a769338debe83 100644 --- a/site/source/docs/compiling/Code-Generation-Modes.rst +++ b/site/source/docs/compiling/Code-Generation-Modes.rst @@ -8,180 +8,80 @@ Code Generation Modes (wiki-import) Code Generation Modes ===================== -One of the reasons for writing Emscripten itself in JavaScript was to be -able to easily test different methods of generating code. As a -consequence, Emscripten currently supports various code generation -modes, each with different features. +One of the reasons for writing Emscripten itself in JavaScript was to be able to easily test different methods of generating code. As a consequence, Emscripten currently supports various code generation modes, each with different features. Typed Arrays ------------ -Typed arrays are currently enabled by default (in mode 2, see below), -because that has the greatest support for arbitrary code. - -There are two modes for typed arrays in Emscripten, 1 and 2. To explain -them, first recall how Emscripten manages memory **without** typed -arrays: It uses ``HEAP`` to represent memory, where ``HEAP`` is a normal -JavaScript array. We write to the first address of multi-byte values to -keep things fast, so writing a 32-bit integer will end up as -``[value, 0, 0, 0]`` - we do not write anything to the upper 3 bytes. We -will also read just from the first location. This is much faster than -splitting things up into bytes and vice versa, but requires that we have -"load-store consistency", which is that if we read a value, we wrote the -same type there. (Otherwise, if we write a 32-bit int and read the -second byte, we won't get what we expect.) ``SAFE_HEAP`` when enabled -will check for violations of load-store consistency. - -Disabling typed arrays can be done with ``USE_TYPED_ARRAYS=0``. This is -safer in the sense that not all browsers support typed arrays. However, -typed arrays can be optimized very well in some cases, and can support -code that does not have load-store consistency. +Typed arrays are currently enabled by default (in mode 2, see below), because that has the greatest support for arbitrary code. + +There are two modes for typed arrays in Emscripten, 1 and 2. To explain them, first recall how Emscripten manages memory **without** typed arrays: It uses ``HEAP`` to represent memory, where ``HEAP`` is a normal JavaScript array. We write to the first address of multi-byte values to keep things fast, so writing a 32-bit integer will end up as ``[value, 0, 0, 0]`` - we do not write anything to the upper 3 bytes. We will also read just from the first location. This is much faster than splitting things up into bytes and vice versa, but requires that we have "load-store consistency", which is that if we read a value, we wrote the same type there. (Otherwise, if we write a 32-bit int and read the second byte, we won't get what we expect.) ``SAFE_HEAP`` when enabled will check for violations of load-store consistency. + +Disabling typed arrays can be done with ``USE_TYPED_ARRAYS=0``. This is safer in the sense that not all browsers support typed arrays. However, typed arrays can be optimized very well in some cases, and can support code that does not have load-store consistency. Typed Arrays Mode 1 ~~~~~~~~~~~~~~~~~~~ -With ``USE_TYPED_ARRAYS=1``, two typed arrays will represent memory. One -will contain integer values, the other float values. When we write an -integer to memory, we write to the first, and when we write a float, we -write to the second. (LLVM is typed, so we always know what values we -are writing/reading.) Otherwise, this mode is identical to without typed -arrays: We still require load-store consistency and so forth. - -The benefit of this mode is that memory is implemented as two typed -arrays, which JavaScript engines can often optimize very well. The -downsides, though are - -- In things like memcpy, where we don't know the types, we must copy - **both** arrays. -- We can take more memory than without typed arrays, since we have two - arrays now for memory, one of which uses 32 bits for each memory - address, and one of which uses 64. -- We cannot dynamically resize these arrays in an easy way. If you try - to use more memory than was originally set up, we need to create new - typed arrays and copy everything into them, which is slow. Setting - the total size of memory (``TOTAL_MEMORY``) can avoid this, but only - if you know in advance the maximum you will need. -- Not all LLVM optimizations are possible, and not all C/C++ code is - compatible with this mode. - -This mode is generally much faster than mode 0, but often slower then -mode 2. +With ``USE_TYPED_ARRAYS=1``, two typed arrays will represent memory. One will contain integer values, the other float values. When we write an integer to memory, we write to the first, and when we write a float, we write to the second. (LLVM is typed, so we always know what values we are writing/reading.) Otherwise, this mode is identical to without typed arrays: We still require load-store consistency and so forth. + +The benefit of this mode is that memory is implemented as two typed arrays, which JavaScript engines can often optimize very well. The downsides, though are + +- In things like memcpy, where we don't know the types, we must copy **both** arrays. +- We can take more memory than without typed arrays, since we have two arrays now for memory, one of which uses 32 bits for each memory address, and one of which uses 64. +- We cannot dynamically resize these arrays in an easy way. If you try to use more memory than was originally set up, we need to create new typed arrays and copy everything into them, which is slow. Setting the total size of memory (``TOTAL_MEMORY``) can avoid this, but only if you know in advance the maximum you will need. +- Not all LLVM optimizations are possible, and not all C/C++ code is compatible with this mode. + +This mode is generally much faster than mode 0, but often slower then mode 2. + +.. _typed-arrays-mode-2: Typed Arrays Mode 2 ~~~~~~~~~~~~~~~~~~~ This is the default mode. -With ``USE_TYPED_ARRAYS=2``, one typed array buffer will represent -memory, while different views into it will allow us to access different -types (:js:data:`HEAPU32` for 32-bit unsigned integers, for example). Because -of that, it is possible to violate the load-store consistency -assumption: The different views show the same data. You can write a -32-bit integer, then read a byte from the middle, and it will work just -like in C or C++. - -The main benefit of this mode is that it uses as much memory on the heap -as C and C++ normally do. We are literally laying things out in memory -as they do. This mode is also quite fast in many cases. Also, you can -successfully run code that does not have load-store consistency. There -are two downsides though, - -- Because of how typed array views work, we must do pointer shifts: To - access a 32-bit value at memory location X, we need to read from the - 32-bit view at index X divided by 4 (since it looks like an array, - whose indexes each represent 4 bytes). So the code ends up filled - with ``<<2``, ``>>2`` and so forth. We can optimize this some more, - but it will remain an overhead. (However, other binary data APIs are - coming to JavaScript which can help here.) -- We currently align the stack and so forth to 4-byte boundaries. This - means that reading 8-byte values is slower (we must read them in two - parts, and combine them, see ``I64_MODE`` and ``DOUBLE_MODE``, - below). - -Note that ``SAFE_HEAP``, in this mode, will ignore load-store -consistency violations, since they don't matter. Alignment of reads and -writes, though, will be checked, which is important since reading -unaligned values will fail as mentioned earlier. +With ``USE_TYPED_ARRAYS=2``, one typed array buffer will represent memory, while different views into it will allow us to access different types (:js:data:`HEAPU32` for 32-bit unsigned integers, for example). Because of that, it is possible to violate the load-store consistency assumption: The different views show the same data. You can write a 32-bit integer, then read a byte from the middle, and it will work just like in C or C++. + +The main benefit of this mode is that it uses as much memory on the heap as C and C++ normally do. We are literally laying things out in memory as they do. This mode is also quite fast in many cases. Also, you can successfully run code that does not have load-store consistency. There are two downsides though, + +- Because of how typed array views work, we must do pointer shifts: To access a 32-bit value at memory location X, we need to read from the 32-bit view at index X divided by 4 (since it looks like an array, whose indexes each represent 4 bytes). So the code ends up filled with ``<<2``, ``>>2`` and so forth. We can optimize this some more, but it will remain an overhead. (However, other binary data APIs are coming to JavaScript which can help here.) +- We currently align the stack and so forth to 4-byte boundaries. This means that reading 8-byte values is slower (we must read them in two parts, and combine them, see ``I64_MODE`` and ``DOUBLE_MODE``, below). + +Note that ``SAFE_HEAP``, in this mode, will ignore load-store consistency violations, since they don't matter. Alignment of reads and writes, though, will be checked, which is important since reading unaligned values will fail as mentioned earlier. 64-bit Integer Modes -------------------- -As mentioned earlier, 64-bit integers cannot be represented directly in -JavaScript, whose numbers are doubles, which cannot contain all 64-bit -integer values. In typed arrays mode 2, we implement 64-bit integers as -pairs of 32-bit values, but we do not emulate addition and -multiplication, instead we perform that as doubles - which is faster. -Bit operations like and and or, however, are done with full precision. +As mentioned earlier, 64-bit integers cannot be represented directly in JavaScript, whose numbers are doubles, which cannot contain all 64-bit integer values. In typed arrays mode 2, we implement 64-bit integers as pairs of 32-bit values, but we do not emulate addition and multiplication, instead we perform that as doubles - which is faster. Bit operations like and and or, however, are done with full precision. -Note that in modes other than typed arrays mode 2, we implement 64-bit -integers entirely as doubles. If you need 64-bit integers to work, use -typed arrays mode 2. +Note that in modes other than typed arrays mode 2, we implement 64-bit integers entirely as doubles. If you need 64-bit integers to work, use typed arrays mode 2. Double Mode ----------- -In every mode but typed arrays mode 2, doubles work fine in a simple -manner. However, in typed arrays mode 2 we cannot read unaligned -doubles, because of the typed array API. Therefore the default behavior -here is ``DOUBLE_MODE=1``, in which we carefully read doubles as two -32-bit values, to not hit alignment problems. This is slower than mode -0, obviously. +In every mode but typed arrays mode 2, doubles work fine in a simple manner. However, in typed arrays mode 2 we cannot read unaligned doubles, because of the typed array API. Therefore the default behavior here is ``DOUBLE_MODE=1``, in which we carefully read doubles as two 32-bit values, to not hit alignment problems. This is slower than mode 0, obviously. -It should be possible to modify clang to always align doubles to 64-bit -boundaries (gcc has ``-malign-double``), this should be investigated - -it would mean we no longer need mode 1 here. +It should be possible to modify clang to always align doubles to 64-bit boundaries (gcc has ``-malign-double``), this should be investigated - it would mean we no longer need mode 1 here. Exceptions ---------- -Exceptions can work in code compiled by emscripten, however due to how -JS engines work they are typically very slow (all JS engines currently -disable most optimizations inside ``try {} catch() {}`` blocks...). For -that reason, in ``-O1`` and above emscripten disables exception catching -by default, because often LLVM generates code that can catch exceptions -even when it isn't needed (in C++, exception catching often has zero -cost unless an exception actually happens, so there is little downside -there, but in JS there is). +Exceptions can work in code compiled by emscripten, however due to how JS engines work they are typically very slow (all JS engines currently disable most optimizations inside ``try {} catch() {}`` blocks...). For that reason, in ``-O1`` and above emscripten disables exception catching by default, because often LLVM generates code that can catch exceptions even when it isn't needed (in C++, exception catching often has zero cost unless an exception actually happens, so there is little downside there, but in JS there is). -To get full exception handling support in ``-O1`` and above, run emcc -with ``-s DISABLE_EXCEPTION_CATCHING=0``. Note that enabling exceptions -will make the code larger due to the additional try-catch blocks (which -cannot be minified very well). +To get full exception handling support in ``-O1`` and above, run emcc with ``-s DISABLE_EXCEPTION_CATCHING=0``. Note that enabling exceptions will make the code larger due to the additional try-catch blocks (which cannot be minified very well). Memory Compression (a.k.a QUANTUM\_SIZE == 1) --------------------------------------------- -By default, Emscripten sets QUANTUM\_SIZE to 4, which means that a -'normal' element - like an int or a pointer - takes 4 'bytes'. That is -the normal behavior on 32-bit systems, and allows Emscripten to properly -compile a great deal of C/C++ code. However, the downside is that each -int or pointer takes 4 places in the HEAP array, which is how Emscripten -models the normal C/C++ memory space. This makes HEAP much bigger than -it needs to be, which takes more memory, and also slows things down (for -example, memset ends up clearing larger areas of memory). - -By setting QUANTUM\_SIZE to 1, memory is 'compressed' - it is not longer -isomorphic to normal C/C++ memory. So for example a structure with an -int, a double, and a pointer would have a size of 3 (one for each -variable), instead of the normal 16 (4 for the int and pointer, 8 for -the double). This leads to significantly more optimized code, both in -terms of speed and memory use. - -However, this is risky, since with QUANTUM\_SIZE of 1, Emscripten -rewrites the .ll, trying to fix all the hardcoded places where it -assumes the normal memory space. So consider this experimental for now. +By default, Emscripten sets QUANTUM\_SIZE to 4, which means that a 'normal' element - like an int or a pointer - takes 4 'bytes'. That is the normal behavior on 32-bit systems, and allows Emscripten to properly compile a great deal of C/C++ code. However, the downside is that each int or pointer takes 4 places in the HEAP array, which is how Emscripten models the normal C/C++ memory space. This makes HEAP much bigger than it needs to be, which takes more memory, and also slows things down (for example, memset ends up clearing larger areas of memory). + +By setting QUANTUM\_SIZE to 1, memory is 'compressed' - it is not longer isomorphic to normal C/C++ memory. So for example a structure with an int, a double, and a pointer would have a size of 3 (one for each variable), instead of the normal 16 (4 for the int and pointer, 8 for the double). This leads to significantly more optimized code, both in terms of speed and memory use. + +However, this is risky, since with QUANTUM\_SIZE of 1, Emscripten rewrites the .ll, trying to fix all the hardcoded places where it assumes the normal memory space. So consider this experimental for now. Notes: -- With QUANTUM\_SIZE == 1, Emscripten will warn you about ptrtoint and - inttoptr operations (in the generated .js file). You should make sure - there are no problems in each of those cases, and perhaps modify the - original C/C++ to avoid generating that kind of code (the changes are - often simple). -- You can **not** use QUANTUM\_SIZE == 1 with typed arrays mode 2. The - reason is that typed arrays mode 2 is C-like memory layout, whereas - in QUANTUM\_SIZE == 1 we radically change the layout (ints take 1 - memory address instead of 4, etc.), and the two can't be mixed. - -The second version of the Bullet demo in Emscripten uses QUANTUM\_SIZE -== 1. It appears to give a speedup of around 25%. +- With QUANTUM\_SIZE == 1, Emscripten will warn you about ptrtoint and inttoptr operations (in the generated .js file). You should make sure there are no problems in each of those cases, and perhaps modify the original C/C++ to avoid generating that kind of code (the changes are often simple). +- You can **not** use QUANTUM\_SIZE == 1 with typed arrays mode 2. The reason is that typed arrays mode 2 is C-like memory layout, whereas in QUANTUM\_SIZE == 1 we radically change the layout (ints take 1 memory address instead of 4, etc.), and the two can't be mixed. + +The second version of the Bullet demo in Emscripten uses QUANTUM\_SIZE == 1. It appears to give a speedup of around 25%. diff --git a/site/source/docs/compiling/Running-html-files-with-emrun.rst b/site/source/docs/compiling/Running-html-files-with-emrun.rst index 5a2e27b6cbee1..b7a910956a608 100644 --- a/site/source/docs/compiling/Running-html-files-with-emrun.rst +++ b/site/source/docs/compiling/Running-html-files-with-emrun.rst @@ -3,69 +3,40 @@ =========================================== Running html files with emrun (wiki-import) =========================================== + .. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! -When you target the web with emscripten via the ``-o out.html`` -directive to emcc, emscripten will generate one or more outfiles with -suffixes ``.html, .js, and .data``. Not all web browsers can run the -.html file via a ``file://`` URL by double-clicking the html file -because of default browser CORS rules (in Chrome, Opera and IE), but you -need to deploy the files to a web server first. To solve this, you can -use the ``emrun`` command line tool to run your page in a locally -launched web server. +When you target the web with emscripten via the ``-o out.html`` directive to emcc, emscripten will generate one or more outfiles with suffixes ``.html, .js, and .data``. Not all web browsers can run the .html file via a ``file://`` URL by double-clicking the html file because of default browser CORS rules (in Chrome, Opera and IE), but you need to deploy the files to a web server first. To solve this, you can use the ``emrun`` command line tool to run your page in a locally launched web server. Features -------- ``emrun`` enables the following uses: -- Launch your html page in a web browser from command line, behaving as - if it was a native executable. -- Capture application stdout and stderr streams during the run, and - print them to terminal or log to file. -- Pass command-line arguments to the application and read them from - ``GET`` parameters in the launched URL, or ``argc`` and ``argv`` in - main. -- Detect when application quits via a call to C function - ``exit(returncode);`` and pass that return code to terminal. -- Use a custom browser to run, or even run a browser on an Android - device connected to the local computer via adb. - -To summarize, ``emrun`` is the tool to use for all kinds of command-line -automation needs, for example when integrating your unit tests to run in -an emscripten environment in your project build farm. +- Launch your html page in a web browser from command line, behaving as if it was a native executable. +- Capture application ``stdout`` and ``stderr`` streams during the run, and print them to terminal or log to file. +- Pass command-line arguments to the application and read them from ``GET`` parameters in the launched URL, or ``argc`` and ``argv`` in main. +- Detect when application quits via a call to C function ``exit(returncode);`` and pass that return code to terminal. +- Use a custom browser to run, or even run a browser on an Android device connected to the local computer via adb. + +To summarize, ``emrun`` is the tool to use for all kinds of command-line automation needs, for example when integrating your unit tests to run in an Emscripten environment in your project build farm. Quick how-to ------------ Using ``emrun`` is simple. Here is how: -1. Rebuild your emscripten application and add the ``--emrun`` linker - flag. This flag injects a piece of code in the generated ``Module`` - that is needed to enable the stdout, stderr and exit() capture to - work. If you skip this step, you can still run any .html file with - ``emrun``, but then the capture will just not work. +1. Rebuild your emscripten application and add the ``--emrun`` linker flag. This flag injects a piece of code in the generated ``Module`` that is needed to enable the ``stdout``, ``stderr`` and ``exit()`` capture to work. If you skip this step, you can still run any .html file with ``emrun``, but then the capture will just not work. -2. Open a terminal, navigate to the build output directory, and run - ``emrun page.html``. This will spawn a new web server to host the - page and launch your default system browser to visit that page. - ``emrun`` will block until the page calls ``exit(returncode);``, - after which it will quit back to shell with the provided process exit - code. +2. Open a terminal, navigate to the build output directory, and run ``emrun page.html``. This will spawn a new web server to host the page and launch your default system browser to visit that page. ``emrun`` will block until the page calls ``exit(returncode);``, after which it will quit back to shell with the provided process exit code. That's all! Choosing the browser to run --------------------------- -``emrun`` provides the ``--browser `` command -line option that allows specifying which browser to run. If that flag is -not specified, the default system browser is launched. If the parameter -to ``--browser`` points to an existing file, then that file is spawned -as the browser process to run. Additionally, to simplify setup, one can -pass predefined alias names of known browsers to ``--browser`` to launch -a specific browser. To enumerate the list of detected browser aliases on -your system, run the ``--list_browsers`` command, like follows: +``emrun`` provides the ``--browser `` command line option that allows specifying which browser to run. If that flag is not specified, the default system browser is launched. If the parameter to ``--browser`` points to an existing file, then that file is spawned +as the browser process to run. Additionally, to simplify setup, one can pass predefined alias names of known browsers to ``--browser`` to launch a specific browser. To enumerate the list of detected browser aliases on your system, run the ``--list_browsers`` command, like follows: :: @@ -82,121 +53,70 @@ your system, run the ``--list_browsers`` command, like follows: - iexplore: Microsoft Internet Explorer 11.0.9600.16384 - opera: Opera 18.0.1284.63 - You can pass the --browser option to launch with the given browser above. - Even if your browser was not detected, you can use --browser /path/to/browser/executable - to launch with that browser. + You can pass the --browser option to launch with the given browser above. Even if your browser was not detected, you can use --browser /path/to/browser/executable to launch with that browser. -For your browser to be detected, it should be installed in a default -install location on the system (``%ProgramFiles%`` on Windows and -``/Applications/`` on OSX) or by adding it to the ``PATH`` for current -user. +For your browser to be detected, it should be installed in a default install location on the system (``%ProgramFiles%`` on Windows and ``/Applications/`` on OSX) or by adding it to the ``PATH`` for current user. -Then for example to run Firefox Nightly, you would launch -``emrun --browser firefox_nightly page.html``. +Then for example to run Firefox Nightly, you would launch ``emrun --browser firefox_nightly page.html``. -If you just want to launch a web server, similar to how -``python -m SimpleHTTPServer`` operates, you can pass the -``--no_browser`` command line flag, in which case ``emrun`` will not -spawn a browser at all, but simply runs a web server. +If you just want to launch a web server, similar to how ``python -m SimpleHTTPServer`` operates, you can pass the ``--no_browser`` command line flag, in which case ``emrun`` will not spawn a browser at all, but simply runs a web server. Controlling web server operation -------------------------------- -``emrun`` spawns its own web server to host the target html file. You -should note the following security implications: - -- The web server is a generic file server that by default serves all - files in the directory where the .html file resides, and all - directories under that directory tree. -- The web server will be visible to other computers on the same - network. - -The following command line flags control how ``emrun`` spawns the web -server: - ``--no_server``: Does not launch a web server at all. The -target file is run via ``file://`` protocol, if possible. - -``--serve_after_close``: Does not quit ``emrun`` after the user was -detected to close the web browser, but keeps serving. Use this flag for -example when you want to visit the page multiple times or with different -browsers during the same run. - ``--serve_after_exit``: Does not quit -``emrun`` after the page finishes with a call to ``exit(returncode);``, -but keeps serving. - ``--serve_root ``: Chooses a custom directory -to use as the root directory for the spawned web server. By default, the -directory where the .html file resides in is used. - -``--port ``: Chooses the TCP port where the web server listens -to. The default port is ``6931``. - ``--silence_timeout ``: If -the application does not print anything to stdout or stderr in this many -seconds, the page/browser is assumed to be hung, and ``emrun`` will -quit. Disabled by default. - ``--timeout ``: If the whole page -run lasts longer than this many seconds, the page/browser is assumed to -be hung, and ``emrun`` will quit. Disabled by default. - -``--timeout_returncode ``: Specifies the process return code that -``emrun`` quits with if a page run timeout occurs. By default ``99999``. +``emrun`` spawns its own web server to host the target html file. You should note the following security implications: + +- The web server is a generic file server that by default serves all files in the directory where the .html file resides, and all directories under that directory tree. +- The web server will be visible to other computers on the same network. + +The following command line flags control how ``emrun`` spawns the web server: + +- ``--no_server``: Does not launch a web server at all. The target file is run via ``file://`` protocol, if possible. +- ``--serve_after_close``: Does not quit ``emrun`` after the user was detected to close the web browser, but keeps serving. Use this flag for example when you want to visit the page multiple times or with different browsers during the same run. +- ``--serve_after_exit``: Does not quit ``emrun`` after the page finishes with a call to ``exit(returncode);``, but keeps serving. +- ``--serve_root ``: Chooses a custom directory to use as the root directory for the spawned web server. By default, the directory where the .html file resides in is used. +- ``--port ``: Chooses the TCP port where the web server listens to. The default port is ``6931``. +- ``--silence_timeout ``: If the application does not print anything to ``stdout`` or ``stderr`` in this many seconds, the page/browser is assumed to be hung, and ``emrun`` will quit. Disabled by default. +- ``--timeout ``: If the whole page run lasts longer than this many seconds, the page/browser is assumed to be hung, and ``emrun`` will quit. Disabled by default. +- ``--timeout_returncode ``: Specifies the process return code that ``emrun`` quits with if a page run timeout occurs. By default ``99999``. Controlling log output ---------------------- The following command line flags affect messaging to logs: -- ``--verbose``: Prints detailed information about ``emrun`` internal - steps, for debugging purposes. -- ``--log_stdout ``: Instead of printing to terminal, writes - all stdout messages from the application to the given file. -- ``--lot_stderr ``: Same as above, but for the stderr - stream. -- ``--system_info``: Before launching, prints detailed information - about the current system. Useful for automated runs to capture - hardware information to logs. -- ``--browser_info``: Before launching, prints information about which - browser is about to be launched. -- ``--log_html``: If specified, application output is reformatted as - html markup friendly. -- ``--no_emrun_detect``: Hides the friendly reminder message that warns - if target .html file is detected to not have been built with - ``--emrun``. +- ``--verbose``: Prints detailed information about ``emrun`` internal steps, for debugging purposes. +- ``--log_stdout ``: Instead of printing to terminal, writes all ``stdout`` messages from the application to the given file. +- ``--lot_stderr ``: Same as above, but for the ``stderr`` stream. +- ``--system_info``: Before launching, prints detailed information about the current system. Useful for automated runs to capture hardware information to logs. +- ``--browser_info``: Before launching, prints information about which browser is about to be launched. +- ``--log_html``: If specified, application output is reformatted as html markup friendly. +- ``--no_emrun_detect``: Hides the friendly reminder message that warns if target .html file is detected to not have been built with ``--emrun``. Cleaning up after the run ------------------------- -Especially when automating operation for build servers, it is important -to be able to clean up properly after each run. The following command -line flags enable this: - -- ``--kill_start``: If specified, all instances of the target browser - process are terminated before starting the run. Pass this flag if you - want to force that no old (hung) instances of the target browser - processes could exist at the time of the launch that could interfere - with the run. By default disabled. -- ``--kill_exit``: If specified, all instances of the target browser - process are terminated when ``emrun`` quits. Pass this flag to force - that browser pages are not left around running when the run is over. - By default disabled. - -It is important to understand that these operations can cause data loss, -since these actions cause processes to be forcibly terminated. Do not -pass these flags when running a browser that could have multiple tabs or -windows open that you do other work in, since they will all be wiped -out. You were warned. +Especially when automating operation for build servers, it is important to be able to clean up properly after each run. The following command line flags enable this: + +- ``--kill_start``: If specified, all instances of the target browser process are terminated before starting the run. Pass this flag if you want to force that no old (hung) instances of the target browser processes could exist at the time of the launch that could interfere with the run. By default disabled. +- ``--kill_exit``: If specified, all instances of the target browser process are terminated when ``emrun`` quits. Pass this flag to force that browser pages are not left around running when the run is over. By default disabled. + +It is important to understand that these operations can cause data loss, since these actions cause processes to be forcibly terminated. Do not pass these flags when running a browser that could have multiple tabs or windows open that you do other work in, since they will all be wiped out. You were warned. Running web pages on an Android device -------------------------------------- -It is also possible to use ``emrun`` to automate web browser runs on -Android. For that to work, you need - An Android phone connected to the -local system via USB and its developer mode enabled. No need to root the -phone. - The ``adb`` tool installed to the system and present in -``PATH`` environment variable. - Check that adb is working by calling -``adb devices`` to see that your device is listed. - Install any browser -apk to the device that you want to be able to run. - -To run on Android, add the ``--android`` command line flag, and use the -``--browser `` command line flag to explicitly choose the browser to -run. Omitting ``--browser`` (to launch a default Android browser) is not -supported. The following browser ids have been tested to work: -``firefox, firefox_beta, firefox_aurora, firefox_nightly, chrome, chrome_beta, opera``. -The following browser ids are also supported, but have known issues: - -``opera_mini``: The browser launches, but for some reason it times out -when trying to load any page. - ``dolphin``: Works, but does not support -WebGL. - -Otherwise, ``emrun`` works as usual, and the other command line flags -can be combined. +It is also possible to use ``emrun`` to automate web browser runs on Android. For that to work, you need + +- An Android phone connected to the local system via USB and its developer mode enabled. No need to root the phone. +- The ``adb`` tool installed to the system and present in ``PATH`` environment variable. +- Check that adb is working by calling ``adb devices`` to see that your device is listed. +- Install any browser apk to the device that you want to be able to run. + +To run on Android, add the ``--android`` command line flag, and use the ``--browser `` command line flag to explicitly choose the browser to run. Omitting ``--browser`` (to launch a default Android browser) is not supported. The following browser ids have been tested to work: ``firefox, firefox_beta, firefox_aurora, firefox_nightly, chrome, chrome_beta, opera``. + +The following browser ids are also supported, but have known issues: +- ``opera_mini``: The browser launches, but for some reason it times out when trying to load any page. +- ``dolphin``: Works, but does not support WebGL. + +Otherwise, ``emrun`` works as usual, and the other command line flags can be combined. diff --git a/site/source/docs/contributing/building_from_source/Getting-started-on-Mac-OS-X.rst b/site/source/docs/contributing/building_from_source/Getting-started-on-Mac-OS-X.rst index 27175a9256e93..376a6580ce911 100644 --- a/site/source/docs/contributing/building_from_source/Getting-started-on-Mac-OS-X.rst +++ b/site/source/docs/contributing/building_from_source/Getting-started-on-Mac-OS-X.rst @@ -5,149 +5,129 @@ Getting started on Mac OS X (wiki-import) ========================================= .. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! -This guide instructs step-by-step on how to setup emscripten on a clean -Mac OS X box. The steps have been tested against OS X version 10.8.2. +This guide instructs step-by-step on how to setup emscripten on a clean Mac OS X box. The steps have been tested against OS X version 10.8.2. Note for `homebrew `__ users: -``brew install emscripten`` does all the steps below for you (including -installation of the llvm fastcomp compiler and patching the python -interpreter). +``brew install emscripten`` does all the steps below for you (including installation of the llvm fastcomp compiler and patching the python interpreter). -1. Install svn if you do not have it yet. It is distributed with XCode - Command Line Tools in OSX App Store. See - http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion +1. Install svn if you do not have it yet. It is distributed with XCode Command Line Tools in OSX App Store. See http://superuser.com/questions/455214/where-is-svn-on-os-x-mountain-lion -- Install XCode from OSX App Store. -- In XCode->Preferences->Downloads, install Command Line Tools. -- Test that svn works from command line: type 'svn --version' in - terminal. + - Install XCode from OSX App Store. + - In XCode->Preferences->Downloads, install Command Line Tools. + - Test that svn works from command line: type 'svn --version' in terminal. 2. Install git if you do not have it yet: -- Allow installation of unsigned packages, or installing git package - won't succeed: - https://www.my-private-network.co.uk/knowledge-base/apple-related-questions/osx-unsigned-apps.html -- Download and install git from http://git-scm.com/ -- Test that git works from command line: type 'git --version' in - terminal. + - Allow installation of unsigned packages, or installing git package won't succeed: https://www.my-private-network.co.uk/knowledge-base/apple-related-questions/osx-unsigned-apps.html + - Download and install git from http://git-scm.com/ + - Test that git works from command line: type 'git --version' in terminal. 3. Install cmake if you do not have it yet: -- Download and install cmake-2.8.10.2-Darwin64-universal.dmg or newer - from http://www.cmake.org/cmake/resources/software.html -- Test that cmake works from command line: type 'cmake --version' in - terminal. + - Download and install cmake-2.8.10.2-Darwin64-universal.dmg or newer from http://www.cmake.org/cmake/resources/software.html + - Test that cmake works from command line: type 'cmake --version' in terminal. -4. Build LLVM+Clang 3.2 from SVN repository: +4. Build LLVM+Clang 3.2 from SVN repository: -- cd ~ -- svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE\_32/final - llvm32 -- cd llvm32/tools -- svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE\_32/final - clang -- cd ../.. -- mkdir llvm32build -- cd llvm32build -- cmake -DCMAKE\_BUILD\_TYPE=Release -G "Unix Makefiles" ../llvm32 -- make + :: -After these steps, Clang 3.2 will be built into ~/llvm32build/bin. The -source tree ~/llvm32 is not needed anymore, if you want to conserve disk -space. + cd ~ + svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE\_32/final llvm32 + cd llvm32/tools + svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE\_32/final clang + cd ../.. + mkdir llvm32build + cd llvm32build + cmake -DCMAKE\_BUILD\_TYPE=Release -G "Unix Makefiles" ../llvm32 + make -Note that XCode ships with a custom version of Clang (3.1svn or 3.2svn -depending on XCode version). It may be possible to omit this step and -just use the version provided by XCode, but the LLVM 3.2 RELEASE version -is preferred, since that is the "officially supported version" the -emscripten OSX unit tests are run against. + After these steps, Clang 3.2 will be built into ~/llvm32build/bin. The source tree ~/llvm32 is not needed anymore, if you want to conserve disk space. -5. Set up Clang 3.2 in PATH: + Note that XCode ships with a custom version of Clang (3.1svn or 3.2svn depending on XCode version). It may be possible to omit this step and just use the version provided by XCode, but the LLVM 3.2 RELEASE version is preferred, since that is the "officially supported version" the Emscripten OSX unit tests are run against. -- cd ~ -- echo "export PATH=~/llvm32build/bin:$PATH" >> .profile +5. Set up Clang 3.2 in PATH: -The above change is permanent and it persists between system restarts. -It only affects the current user. + :: -6. Close all terminal windows, and open a new one. Check that clang - works ok in path: + cd ~ + echo "export PATH=~/llvm32build/bin:$PATH" >> .profile -- cd ~ -- clang --version + The above change is permanent and it persists between system restarts. It only affects the current user. -The command should output: clang version 3.2 (tags/RELEASE\_32/final -176107) Target: x86\_64-apple-darwin12.2.1 Thread model: posix +6. Close all terminal windows, and open a new one. Check that clang works ok in path: -7. Delete old .emscripten file if it happened to exist: + :: -- rm ~/.emscripten -- rm -rf ~/.emscripten\_cache + cd ~ + clang --version + + The command should output: clang version 3.2 (tags/RELEASE\_32/final 176107) Target: x86\_64-apple-darwin12.2.1 Thread model: posix + +7. Delete old .emscripten file if it happened to exist: + + :: + + rm ~/.emscripten + rm -rf ~/.emscripten\_cache 8. Set up node: -- Download and install node from http://nodejs.org/ -- Test that node works from command line: type 'node --version' in - terminal. + - Download and install node from http://nodejs.org/ + - Test that node works from command line: type 'node --version' in terminal. + +9. Obtain Emscripten: + + :: + + cd ~ + git clone https://github.com/kripken/emscripten.git + + By default, git will clone the emscripten 'incoming' branch, which is the branch where the newest developments of Emscripten occur. If you want to use a more stable branch, switch to the 'master' branch: - cd ~/emscripten - git checkout master -9. Obtain emscripten: +10. Setup 'python2': (this step is needed to workaround a bug reported in `#763 `__) -- cd ~ -- git clone https://github.com/kripken/emscripten.git + - In terminal, type 'python2 --version'. If you get a "command not found", type the following: :: + + cd /usr/bin + sudo ln python python2 + sudo ln ../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7 python22.7 + + - Issue 'python2 --version' again. It should now print Python 2.7.2 -By default, git will clone the emscripten 'incoming' branch, which is -the branch where the newest developments of emscripten occur. If you -want to use a more stable branch, switch to the 'master' branch: - cd -~/emscripten - git checkout master +11. Perform emscripten "first run": -10. Setup 'python2': (this step is needed to workaround a bug reported - in `#763 `__) + :: -- In terminal, type 'python2 --version'. If you get a "command not - found", type the following: -- cd /usr/bin -- sudo ln python python2 -- sudo ln - ../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/python2.7 - python22.7 -- Issue 'python2 --version' again. It should now print Python 2.7.2 + cd ~/emscripten + /emcc --help + + - edit the file ~/.emscripten in a text editor to set up any required paths. -11. Perform emscripten "first run": +12. (Optional) Compile a simple test program to check that everything works: -- cd ~/emscripten -- ./emcc --help -- edit the file ~/.emscripten in a text editor to set up any required - paths. + :: -12. (Optional) Compile a simple test program to check that everything - works: + cd ~/emscripten + ./em++ tests/hello\_world.cpp + node a.out.js -- cd ~/emscripten -- ./em++ tests/hello\_world.cpp -- node a.out.js + The first run will most likely pop up an automatic prompt that asks to install java. Proceed, and after installation finishes, rerun the above commands. Running node should output: hello, world! -The first run will most likely pop up an automatic prompt that asks to -install java. Proceed, and after installation finishes, rerun the above -commands. Running node should output: hello, world! +13. (Optional) Compile a simple WebGL program to check that .html output and GLES2/WebGL works: -13. (Optional) Compile a simple WebGL program to check that .html output - and GLES2/WebGL works: + :: -- cd ~/emscripten -- ./emcc tests/hello\_world\_gles.c -o hello\_world\_gles.html -- open hello\_world\_gles.html + cd ~/emscripten + ./emcc tests/hello\_world\_gles.c -o hello\_world\_gles.html + open hello\_world\_gles.html + + .. note:: If the Safari 6 browser pops up with a message "Could not create canvas :(", follow `these instructions `_ to enable WebGL support in Safari -If the Safari 6 browser pops up with a message "Could not create canvas -:(", follow these instructions to enable WebGL support in Safari: -http://support.apple.com/kb/PH11926 -14. (Optional) Run the full battery of tests to check that emscripten is - perfectly operational on the current platform: +14. (Optional) Run the full battery of tests to check that Emscripten is perfectly operational on the current platform: :: -- cd ~/emscripten -- python tests/runner.py -- python tests/runner.py benchmark + cd ~/emscripten + python tests/runner.py + python tests/runner.py benchmark -Note that some tests will likely fail. Cross-reference the results with -https://github.com/kripken/emscripten/issues?labels=tests to see if you -are receiving currently unknown issues. + Note that some tests will likely fail. Cross-reference the results with https://github.com/kripken/emscripten/issues?labels=tests to see if you are receiving currently unknown issues. diff --git a/site/source/docs/contributing/building_from_source/Using-Emscripten-on-Windows.rst b/site/source/docs/contributing/building_from_source/Using-Emscripten-on-Windows.rst index dbfebdf75bdc4..1acd4870a5112 100644 --- a/site/source/docs/contributing/building_from_source/Using-Emscripten-on-Windows.rst +++ b/site/source/docs/contributing/building_from_source/Using-Emscripten-on-Windows.rst @@ -3,6 +3,7 @@ ========================================= Using Emscripten on Windows (wiki-import) ========================================= + .. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! This page describes how to use Emscripten on Windows. @@ -10,207 +11,121 @@ This page describes how to use Emscripten on Windows. Setting up the Emscripten Toolchain on Windows ---------------------------------------------- -This section contains basic instructions on how to start using -Emscripten on a clean Windows box. After these steps, you can invoke -emcc from the command line by calling 'python emcc'. 64-bit versions of -all needed dependencies are preferred, and may be required if you are -building large projects. +This section contains basic instructions on how to start using Emscripten on a clean Windows box. After these steps, you can invoke emcc from the command line by calling 'python emcc'. 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. Installing required tools ~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Install Python 2.x (not 3.x) from http://www.python.org/. -- e.g. - `python-2.7.5.amd64.msi `__ - for a 64-bit install. -- If you plan to use the Visual Studio integration, do NOT install the - 64-bit version. Get the 32-bit version of python from - `python-2.7.5.msi `__. -- Add the Python bin directory to your PATH. (Open up System Settings, - Advanced system properties, click Environment Variables. Add "C:27" - to the PATH, separated by a semicolon.) If on the other hand - ``python.exe`` appears in "C:27" and not under bin, just add "C:27". + - e.g. `python-2.7.5.amd64.msi `_ for a 64-bit install. + - If you plan to use the Visual Studio integration, do NOT install the 64-bit version. Get the 32-bit version of python from `python-2.7.5.msi `_. + - Add the Python bin directory to your PATH. (Open up System Settings, Advanced system properties, click Environment Variables. Add "C:27" to the PATH, separated by a semicolon.) If on the other hand ``python.exe`` appears in "C:27" and not under bin, just add "C:27". 2. Install node.js from http://nodejs.org/ -- e.g. - `node-v0.10.17-x64.msi `__ -- If you plan to use the Visual Studio integration, do NOT install the - 64-bit version. Get the 32-bit version of node.js from - `node-v0.10.17-x86.msi `__. + - e.g. `node-v0.10.17-x64.msi `_ + - If you plan to use the Visual Studio integration, do NOT install the 64-bit version. Get the 32-bit version of node.js from `node-v0.10.17-x86.msi `_. 3. Setup gcc 4.6 and llvm-clang 3.2. -- If you like building the tools yourself or plan to use the Visual - Studio integration (for which you need 32-bit versions of the tools) - see below for how to build LLVM/Clang from source. -- Otherwise download the following 64-bit builds -- - - - - - - `x86\_64-w64-mingw32-gcc-4.6.3-2-release-win64\_rubenvb.7z `__ - -- - - - + - If you like building the tools yourself or plan to use the Visual Studio integration (for which you need 32-bit versions of the tools) see below for how to build LLVM/Clang from source. + - Otherwise download the following 64-bit builds: - - `x86\_64-w64-mingw32-clang-3.2-release-win64\_rubenvb.7z `__ + - `x86\_64-w64-mingw32-gcc-4.6.3-2-release-win64\_rubenvb.7z `_ + - `x86\_64-w64-mingw32-clang-3.2-release-win64\_rubenvb.7z `_ -- Extract both of them using `7zip `__ to the same - location, e.g. C:64 + - Extract both of them using `7zip `__ to the same location, e.g. C:64 -4. If you do not already have a git client, Install `Github for - Windows `__. -5. Clone the ``kripken/emscripten`` repository from github. The - emscripten repository contains the main compiler tool for compiling - C/C++ programs to JavaScript. +4. If you do not already have a git client, Install `Github for Windows `_. +5. Clone the ``kripken/emscripten`` repository from github. The emscripten repository contains the main compiler tool for compiling C/C++ programs to JavaScript. -- Launch the GitHub for Windows Client. You may click "Skip Setup" if - you don't have a github account. -- (optional) Select "Options" from the gear menu, and customize the - default storage directory. A path without spaces can save you lots of - pain down the line. -- In your web browser, open https://github.com/kripken/emscripten and - press the "Clone in Windows" button. -- Note: if you already had a different git client, the repository URL - is ``https://github.com/kripken/emscripten.git`` (e.g. - ``git clone https://github.com/kripken/emscripten.git``) + - Launch the GitHub for Windows Client. You may click "Skip Setup" if you don't have a github account. + - (optional) Select "Options" from the gear menu, and customize the default storage directory. A path without spaces can save you lots of pain down the line. + - In your web browser, open https://github.com/kripken/emscripten and press the "Clone in Windows" button. + + .. note:: If you already had a different git client, the repository URL is ``https://github.com/kripken/emscripten.git`` (e.g. ``git clone https://github.com/kripken/emscripten.git``) + Configuring Emscripten ~~~~~~~~~~~~~~~~~~~~~~ -1. Open up a command prompt, and change to the directory where you - cloned the emscripten repository. By default with the GitHub client, - this will be ``C:\Users\username\Documents\GitHub\emscripten``. +1. Open up a command prompt, and change to the directory where you cloned the Emscripten repository. By default with the GitHub client, this will be ``C:\Users\username\Documents\GitHub\emscripten``. 2. Run ``python emcc --help`` -- You should get a ``Welcome to Emscripten!`` message. Behind the - scenes, emscripten generated a file called ``.emscripten`` in your - Windows home folder. -- If you do not see this message, make sure that python is properly in - your global PATH, and that you are in the emscripten directory. + - You should get a ``Welcome to Emscripten!`` message. Behind the scenes, Emscripten generated a file called ``.emscripten`` in your Windows home folder. + - If you do not see this message, make sure that python is properly in your global PATH, and that you are in the Emscripten directory. 3. Edit ``C:\Users\username\.emscripten``: - 1. Edit the variable ``EMSCRIPTEN_ROOT`` to point to the emscripten - root folder, e.g. - ``EMSCRIPTEN_ROOT = 'C:/Users/username/Documents/GitHub/emscripten'`` - (Note: use forward slashes) - 2. Edit the variable ``LLVM_ROOT`` to point directly to the path - where you installed clang.exe, e.g. + 1. Edit the variable ``EMSCRIPTEN_ROOT`` to point to the Emscripten root folder, e.g. ``EMSCRIPTEN_ROOT = 'C:/Users/username/Documents/GitHub/emscripten'`` (Note: use forward slashes) + 2. Edit the variable ``LLVM_ROOT`` to point directly to the path where you installed clang.exe, e.g. :: + ``LLVM_ROOT = 'C:/mingw64/bin'`` - 3. Edit the variable TEMP\_DIR to point to a valid Windows path on - your local system, e.g. ``TEMP_DIR = 'C:/tmp'``, and create that - folder on the local filesystem if it doesn't exist. - 4. If you are planning on using Cygwin and cygwin make in the future, - copy the .emscripten file to your cygwin home folder as well, e.g. - copy C:.emscripten C: (There is a bug in emscripten that it - currently looks for the file .emscripten in two places (Win7 user - home folder or cygwin user home folder), depending on the - environment it is executed in, so as a current workaround these - files must be present and identical on Windows. (see `issue - #411 `__)) + + 3. Edit the variable TEMP\_DIR to point to a valid Windows path on your local system, e.g. ``TEMP_DIR = 'C:/tmp'``, and create that folder on the local filesystem if it doesn't exist. + 4. If you are planning on using Cygwin and cygwin make in the future, copy the .emscripten file to your cygwin home folder as well, e.g. + copy C:.emscripten C: (There is a bug in Emscripten that it currently looks for the file .emscripten in two places (Win7 user home folder or cygwin user home folder), depending on the environment it is executed in, so as a current workaround these files must be present and identical on Windows. (see `issue #411 `_)) + Integrating Emscripten to Visual Studio 2010 -------------------------------------------- -It is possible to integrate the Emscripten compiler directly to Visual -Studio. This allows existing VS .sln files to be directly built using -emcc. The Microsoft compiler property pages are replaced by Clang and -emcc -specific options. +It is possible to integrate the Emscripten compiler directly to Visual Studio. This allows existing VS .sln files to be directly built using *emcc*. The Microsoft compiler property pages are replaced by *Clang* and emcc -specific options. 1. Install Visual Studio 2010 -- Note: Express version has not been tested, but should be ok. Please - drop a line on emscripten IRC channel or mailing list to report your - experience with VS2010 Express! + .. note:: Express version has not been tested, but should be ok. Please drop a line on Emscripten IRC channel or mailing list to report your experience with VS2010 Express! 2. Clone the juj/vs-tool repository from github: -- git clone https://github.com/juj/vs-tool -- The vs-tool repository contains a plugin to Visual Studio 2010 (or - rather, to MSBuild) that instructs Visual Studio how to use the - llvm-clang and emscripten toolchain. + - git clone https://github.com/juj/vs-tool + - The vs-tool repository contains a plugin to Visual Studio 2010 (or rather, to MSBuild) that instructs Visual Studio how to use the llvm-clang and emscripten toolchain. 3. Install vs-tool itself. 4. Navigate to folder vs-tool 5. Copy the folders Clang and Emscripten to C:Files (x86).Cpp.0\\. 6. Set up the required environment variables for vs-tool. -7. Windows 7: Open Control Panel -- System -- Advanced System Settings - -- Environment Variables. -8. Create a new environment variable 'CLANG\_BIN' and set it to point - to the folder where you built clang to (path to clang.exe) E.g. +7. Windows 7: Open Control Panel -- System -- Advanced System Settings -- Environment Variables. +8. Create a new environment variable 'CLANG\_BIN' and set it to point to the folder where you built clang to (path to clang.exe) E.g. - SETX CLANG\_BIN C:-build - - This is how vs-tool locates the folder to your llvm-clang - compiler. Alternatively, this path can be set per-project in - Visual Studio project property pages. + - This is how vs-tool locates the folder to your llvm-clang compiler. Alternatively, this path can be set per-project in Visual Studio project property pages. -9. Create a new environment variable 'EMSCRIPTEN' and set it to point - to the emscripten git repository root folder (the path where you - copied emcc.exe and other exes to). E.g. +9. Create a new environment variable 'EMSCRIPTEN' and set it to point to the Emscripten git repository root folder (the path where you copied emcc.exe and other exes to). E.g. - SETX EMSCRIPTEN C: - - This is how vs-tool locates the emscripten compiler. This path + - This is how vs-tool locates the Emscripten compiler. This path can also be overridden per-project in VS property pages. -10. Create a new environment variable 'EMCC\_WEBBROWSER\_EXE' and set it - to point to an executable you want to use to browse - emscripten-generated web pages from Visual Studio. This process is - spawned when you tap Start (Ctrl-F5) in Visual Studio for a - emscripten-targeted project. +10. Create a new environment variable 'EMCC\_WEBBROWSER\_EXE' and set it to point to an executable you want to use to browse Emscripten-generated web pages from Visual Studio. This process is spawned when you tap Start (Ctrl-F5) in Visual Studio for an Emscripten-targeted project. - SETX EMCC\_WEBBROWSER\_EXE C:Files (x86)Firefox.exe -11. Now you are all set to start developing Emscripten-based projects - from Visual Studio. To test the installation, open the Visual Studio - solution file 10\_msvc10.sln. +11. Now you are all set to start developing Emscripten-based projects from Visual Studio. To test the installation, open the Visual Studio solution file 10\_msvc10.sln. + Tips for using Emscripten from the Visual Studio 2010 IDE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To build a Visual Studio solution using the Emscripten toolchain, select -the "Emscripten" configuration from the Configuration Manager dropdown -as the active configuration, and choose Build Solution (F7). - -To launch a project directly to a web browser from Visual Studio, -right-click on the project to run, choose "Set as Startup Project", and -select Start without Debugging (Ctrl+F5). This should launch the -generated .html file to the browser you specified in -EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable -for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. -This can be ignored by clicking Yes, then No, or simply by hitting Esc -and then tapping Ctrl+F5 again. - -llvm-clang and emscripten compiler settings can be edited for the -project in the "usual" Visual Studio fashion: First make sure that the -Emscripten platform configuration is active, then right-click on a -project, and choose Properties. In the Project properties dialog, two -tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to -specify the desired compilation options. - -If you have an existing solution file you want to build using -Emscripten, open the Configuration Manager.. dialog for the solution, -and in the Active Solution Platform dropdown, choose New.... In the new -dialog, choose Emscripten as the platform name, and Copy settings from -Empty. After this, you can switch between building the solution for -Win32 and Emscripten from the Configuration Manager dropdown list. - -When you want to create a new Visual Studio project for Emscripten, we -recommend you start with a Visual C++ Empty Project. This will create a -new project for the Win32 platform. Then convert that project for -Emscripten as outlined in the previous paragraph. +To build a Visual Studio solution using the Emscripten toolchain, select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7). + +To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again. + +llvm-clang and Emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two +tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options. + +If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from +Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list. + +When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph. Building LLVM/Clang from Source ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In case the above-referenced prebuilt binaries do not work for you, you -can build LLVM and Clang from source. +In case the above-referenced prebuilt binaries do not work for you, you can build LLVM and Clang from source. -To install and set up ``llvm-clang 3.2``, open a Visual Studio 2010 -command prompt and type: +To install and set up ``llvm-clang 3.2``, open a Visual Studio 2010 command prompt and type: 1. ``svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_32/final llvm`` 2. ``cd llvm\tools`` @@ -221,9 +136,6 @@ command prompt and type: 7. ``cmake -G "Visual Studio 10" ..\llvm`` 8. ``msbuild LLVM.sln /p:Configuration=Release`` -If you have problems with the above, see more help here: -http://clang.llvm.org/get\_started.html +If you have problems with the above, see more help here: http://clang.llvm.org/get\_started.html -**NOTE**: Instead of checking out the trunk as the guide suggests, check -out the latest tagged release of Clang (3.2 at the time of writing). An -older version will not most likely work with Emscripten. +.. note:: Instead of checking out the trunk as the guide suggests, check out the latest tagged release of Clang (3.2 at the time of writing). An older version will not most likely work with Emscripten. diff --git a/site/source/docs/contributing/contributing.rst b/site/source/docs/contributing/contributing.rst index 0844cd99c2166..6a18452c52aa8 100644 --- a/site/source/docs/contributing/contributing.rst +++ b/site/source/docs/contributing/contributing.rst @@ -1,10 +1,10 @@ +.. _contributing: + ================================================ Contributing (ready-for-review) ================================================ -Anyone can contribute to Emscripten. Feel free to :doc:`join the discussion ` and share your suggestions, ideas, and `bug reports `_! - -If you find Emscripten useful and want to contribute, check out the information and suggestions below. +Anyone can contribute to Emscripten — if you find it useful and want to help improve the project, follow the suggestions below. Feel free to file :ref:`bug reports `, :ref:`join the discussion ` and share your own ideas with the community! Getting started @@ -12,7 +12,9 @@ Getting started A good starting point is to work on the `open issues on Github `_. Many issues can be resolved without an in-depth knowledge of compiler internals, and this is a great way to learn more about the project. -.. tip:: We really appreciate your help. Every closed issue means more time for experienced developers to work on compiler internals. +.. tip:: We really appreciate your help. Every existing issue closed means more time for the core contributors to work on new features, optimizations and other enhancements. + +As a new contributor you should read the :ref:`Developer's-Guide`, and you may also need to :ref:`install Emscripten from source `. Branches of interest @@ -20,7 +22,6 @@ Branches of interest - **master** - The "master" branch. This is always safe to pull from and the test suite always passes. - **incoming** - Branch for new code. Code in **incoming** is merged with the **master** only after it is code-reviewed and has passed all the automated tests. -- **llvmsvn** - Branch for work to support a new version of LLVM. Activity typically begins near the end of an LLVM 6-month dev cycle. When LLVM launches the new version, we merge this branch to master and incoming, at which point our support officially moves to that new LLVM version. Only one version of LVVM is supported at a time. Submitting patches @@ -28,13 +29,13 @@ Submitting patches Patches should be submitted as *pull requests* to the **incoming** branch. -.. note:: Before submitting your first patch, add yourself to the `AUTHORS `_ file. By doing so, you agree to license your code under the project's `open source licenses (MIT/LLVM) `_. +.. note:: Before submitting your first patch, add yourself to the `AUTHORS `_ file. By doing so, you agree to license your code under the project's :ref:`open source licenses (MIT/LLVM) `. When submitting patches, please: - Make pull requests to **incoming**, not master. - Do not include merge commits in pull requests; include only commits with the new relevant code. -- Run all the automatic tests and make sure they pass **tests/runner.py**. Some tests might not be required for very simple patches (for example, when just adding tests for new library functions). +- :ref:`Run all the automatic tests ` and make sure they pass **tests/runner.py**. Some tests might not be required for very simple patches (for example, when just adding tests for new library functions). - If you add any new functionality or fix a bug, add an automatic test to **tests/runner.py**. - Record the tests that were run in the pull request or issue. @@ -44,7 +45,7 @@ Code reviews `@kripken `_ reviews all pull requests before merging. -Exceptions are sub-projects that are 'owned' by other people. These developer/owners can push to incoming directly: +Exceptions are sub-projects that are 'owned' by other people. These owners can push to incoming directly: - OpenAL and audio in general: `@ehsan `_ - embind: `@imvu `_ @@ -55,6 +56,7 @@ Exceptions are sub-projects that are 'owned' by other people. These developer/ow Next steps ========== -After you've fixed some bugs and have a better understanding of the project, you may wish to contribute more "deeply". Please share your development ideas with the :doc:`community ` so that they can be evolved and planned. +Community members make a huge difference to this project. Please :ref:`get in touch with the community ` to share your ideas and work out where you can make the most difference. + + -Emscripten internal developers should also read the :doc:`PLACEHOLDER Developer's-Guide`. \ No newline at end of file diff --git a/site/source/docs/getting_started/Tutorial.rst b/site/source/docs/getting_started/Tutorial.rst index 5f70e13d481f0..754408b87459f 100644 --- a/site/source/docs/getting_started/Tutorial.rst +++ b/site/source/docs/getting_started/Tutorial.rst @@ -195,6 +195,9 @@ Further optimizations are done in ``-O2``, If you inspect the generated code now, you will see it looks very different. + +.. _running-emscripten-tests: + Running the Emscripten Test Suite and Benchmarks ------------------------------------------------ diff --git a/site/source/docs/introducing_emscripten/bug_reports.rst b/site/source/docs/introducing_emscripten/bug_reports.rst index 7cc8f712ad07a..32828a943b1b0 100644 --- a/site/source/docs/introducing_emscripten/bug_reports.rst +++ b/site/source/docs/introducing_emscripten/bug_reports.rst @@ -1,3 +1,5 @@ +.. _bug-reports: + ========================================= Bug Reporting (ready-for-review) ========================================= @@ -6,13 +8,13 @@ All bugs should be filed in the GitHub `main `_ link on the bottom-right of every page opens the Issue Tracker pre-seeded with the current page URL and title. diff --git a/site/source/docs/introducing_emscripten/community.rst b/site/source/docs/introducing_emscripten/community.rst new file mode 100644 index 0000000000000..e52b9165f7e8e --- /dev/null +++ b/site/source/docs/introducing_emscripten/community.rst @@ -0,0 +1,48 @@ +=========================================== +Community (ready-for-review) +=========================================== + +Welcome to the Emscripten community! + + +.. _contact: + +Get in touch +=========================================== + +The best way to contact us is to use either the *mailing list* or *IRC*. + +- Mailing list: `emscripten-discuss `_ +- IRC: **#emscripten** on `irc.mozilla.org `_ + + +Emscripten also has an *unofficial* presence on social media: + +- `Google+ page `_ +- `#emscripten `_ (Emscripten Hashtag on Twitter) +- `@kripken `_ (Emscripten Developer Account on Twitter) + + +Report a bug +============= + +:ref:`Bug reports ` can be posted in the GitHub `Issue Tracker `_. + + +.. _blogs: + + +Blogs +========================= + +Get the latest official Emscripten news on the blogs: `Developer blog (azakai) `_ and `Mozilla blog `_. + +In addition, other interesting blogs and demos are regularly shared on Twitter by the development team `(@kripken) `_ and the broader community `(#emscripten) `_. + +.. todo :: **HamishW** At some point in future would be nice to actually display RSS feeds from above links here. Perhaps including @kripen in feed. In this case would need a dedicated blogs link as well. + + +Contribute +============ + +Anyone can contribute to Emscripten. We've got some ideas to get you started on our :ref:`contributing` page. diff --git a/site/source/docs/introducing_emscripten/contact.rst b/site/source/docs/introducing_emscripten/contact.rst deleted file mode 100644 index 2c2d96802bf43..0000000000000 --- a/site/source/docs/introducing_emscripten/contact.rst +++ /dev/null @@ -1,17 +0,0 @@ -=========================================== -Get in touch (ready-for-review) -=========================================== - -The best channels to contact the development team (and the community) are the *mailing list* and *IRC*. Bug reports should be posted in the GitHub *Issue Tracker*: - -- Mailing list: `emscripten-discuss `_ -- IRC: **#emscripten** on `irc.mozilla.org `_ -- `Issue Tracker `_ (see :doc:`bug_reports`) - -Emscripten also has an *unofficial* presence on social media: - -- `Google+ page `_ -- `#emscripten `_ (Emscripten Hashtag on Twitter) -- `@kripken `_ (Emscripten Developer Account on Twitter) - - diff --git a/site/source/docs/introducing_emscripten/emscripten_license.rst b/site/source/docs/introducing_emscripten/emscripten_license.rst index df01939e3e8a2..e75b2196b0fce 100644 --- a/site/source/docs/introducing_emscripten/emscripten_license.rst +++ b/site/source/docs/introducing_emscripten/emscripten_license.rst @@ -1,3 +1,5 @@ +.. _emscripten-license: + =================== Open Source License =================== diff --git a/site/source/docs/introducing_emscripten/index.rst b/site/source/docs/introducing_emscripten/index.rst index aa64e65834b36..3a624dad3b325 100644 --- a/site/source/docs/introducing_emscripten/index.rst +++ b/site/source/docs/introducing_emscripten/index.rst @@ -7,7 +7,7 @@ Introducing Emscripten (under-construction) :maxdepth: 1 FAQ - contact + community emscripten_license bug_reports release_notes diff --git a/site/source/docs/site/blogs.rst b/site/source/docs/site/blogs.rst deleted file mode 100644 index 79bb5a31bb067..0000000000000 --- a/site/source/docs/site/blogs.rst +++ /dev/null @@ -1,14 +0,0 @@ -==================================== -Blogs (ready-for-review) -==================================== - -There are two main Emscripten blogs: - -- `Developer blog (azakai) `_. -- `Mozilla blog `_ (for sharing important "commercial" announcements and user stories). - -In addition, other interesting blogs and demos are regularly shared on Twitter by the development team `(@kripken) `_ and the broader community `(#emscripten) `_. - - -.. COMMENT BACKUP STUFF - Suggestion was to actually display RSS feeds from above links here. Perhaps including @kripen in feed. Not planning to do this at this time. diff --git a/site/source/docs/site/index.rst b/site/source/docs/site/index.rst index 186a14a74e240..baabba6baa2d9 100644 --- a/site/source/docs/site/index.rst +++ b/site/source/docs/site/index.rst @@ -5,9 +5,6 @@ Site Links (under-construction) .. toctree:: :maxdepth: 1 - blogs about - - diff --git a/site/source/index.rst b/site/source/index.rst index ad3200f41144b..39b91857e92d8 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -14,8 +14,8 @@ News ==== -- `Unity `_ blogs about WebGL support and launches `two public demos `_ (April 29, 2014). There is `more information `_ on the Mozilla blog. -- The new :doc:`fastcomp/LLVM backend ` has been merged to master and is present in the latest SDK release. +- `Unity `_ blogs about WebGL support and launches `two public demos `_ (April 29, 2014). See the `Mozilla Blog `_ for more information. +- The new :doc:`fastcomp/LLVM backend ` has been merged to master and is present in the latest SDK release. - `Unreal Engine 4 `_ ported to the web using Emscripten (Mar 19, 2014 ). There is `more information `_ on the Mozilla blog. @@ -27,18 +27,16 @@ News docs/introducing_emscripten/index docs/getting_started/index docs/coding/index + docs/optimizing/index docs/compiling/index docs/packaging/index docs/contributing/index docs/api_reference/index wiki_static/index - deleteme_scratchpad - deleteme_sitechanges docs/site/about - - + .. COMMENTS Scratchpad diff --git a/src/library_browser.js b/src/library_browser.js index a326a0de5c43e..41ccf8fac693a 100644 --- a/src/library_browser.js +++ b/src/library_browser.js @@ -256,146 +256,41 @@ mergeInto(LibraryManager.library, { }, createContext: function(canvas, useWebGL, setInModule, webGLContextAttributes) { -#if !USE_TYPED_ARRAYS - if (useWebGL) { - Module.print('(USE_TYPED_ARRAYS needs to be enabled for WebGL)'); - return null; - } -#endif - if (useWebGL && Module.ctx) return Module.ctx; // no need to recreate singleton GL context + if (useWebGL && Module.ctx && canvas == Module.canvas) return Module.ctx; // no need to recreate GL context if it's already been created for this canvas. var ctx; - var errorInfo = '?'; - function onContextCreationError(event) { - errorInfo = event.statusMessage || errorInfo; - } - try { - if (useWebGL) { - var contextAttributes = { - antialias: false, - alpha: false - }; - - if (webGLContextAttributes) { - for (var attribute in webGLContextAttributes) { - contextAttributes[attribute] = webGLContextAttributes[attribute]; - } - } - -#if GL_TESTING - contextAttributes.preserveDrawingBuffer = true; -#endif - - canvas.addEventListener('webglcontextcreationerror', onContextCreationError, false); - try { - ['experimental-webgl', 'webgl'].some(function(webglId) { - return ctx = canvas.getContext(webglId, contextAttributes); - }); - } finally { - canvas.removeEventListener('webglcontextcreationerror', onContextCreationError, false); - } - } else { - ctx = canvas.getContext('2d'); - } - if (!ctx) throw ':('; - } catch (e) { - Module.print('Could not create canvas: ' + [errorInfo, e]); - return null; - } + var contextHandle; if (useWebGL) { -#if GL_DEBUG - function wrapDebugGL(ctx) { - - var printObjectList = []; - - function prettyPrint(arg) { - if (typeof arg == 'undefined') return '!UNDEFINED!'; - if (typeof arg == 'boolean') arg = arg + 0; - if (!arg) return arg; - var index = printObjectList.indexOf(arg); - if (index >= 0) return '<' + arg + '|'; // + index + '>'; - if (arg.toString() == '[object HTMLImageElement]') { - return arg + '\n\n'; - } - if (arg.byteLength) { - return '{' + Array.prototype.slice.call(arg, 0, Math.min(arg.length, 400)) + '}'; // Useful for correct arrays, less so for compiled arrays, see the code below for that - var buf = new ArrayBuffer(32); - var i8buf = new Int8Array(buf); - var i16buf = new Int16Array(buf); - var f32buf = new Float32Array(buf); - switch(arg.toString()) { - case '[object Uint8Array]': - i8buf.set(arg.subarray(0, 32)); - break; - case '[object Float32Array]': - f32buf.set(arg.subarray(0, 5)); - break; - case '[object Uint16Array]': - i16buf.set(arg.subarray(0, 16)); - break; - default: - alert('unknown array for debugging: ' + arg); - throw 'see alert'; - } - var ret = '{' + arg.byteLength + ':\n'; - var arr = Array.prototype.slice.call(i8buf); - ret += 'i8:' + arr.toString().replace(/,/g, ',') + '\n'; - arr = Array.prototype.slice.call(f32buf, 0, 8); - ret += 'f32:' + arr.toString().replace(/,/g, ',') + '}'; - return ret; - } - if (typeof arg == 'object') { - printObjectList.push(arg); - return '<' + arg + '|'; // + (printObjectList.length-1) + '>'; - } - if (typeof arg == 'number') { - if (arg > 0) return '0x' + arg.toString(16) + ' (' + arg + ')'; - } - return arg; - } + // For GLES2/desktop GL compatibility, adjust a few defaults to be different to WebGL defaults, so that they align better with the desktop defaults. + var contextAttributes = { + antialias: false, + alpha: false + }; - var wrapper = {}; - for (var prop in ctx) { - (function(prop) { - switch (typeof ctx[prop]) { - case 'function': { - wrapper[prop] = function gl_wrapper() { - var printArgs = Array.prototype.slice.call(arguments).map(prettyPrint); - dump('[gl_f:' + prop + ':' + printArgs + ']\n'); - var ret = ctx[prop].apply(ctx, arguments); - if (typeof ret != 'undefined') { - dump('[ gl:' + prop + ':return:' + prettyPrint(ret) + ']\n'); - } - return ret; - } - break; - } - case 'number': case 'string': { - wrapper.__defineGetter__(prop, function() { - //dump('[gl_g:' + prop + ':' + ctx[prop] + ']\n'); - return ctx[prop]; - }); - wrapper.__defineSetter__(prop, function(value) { - dump('[gl_s:' + prop + ':' + value + ']\n'); - ctx[prop] = value; - }); - break; - } - } - })(prop); + if (webGLContextAttributes) { + for (var attribute in webGLContextAttributes) { + contextAttributes[attribute] = webGLContextAttributes[attribute]; } - return wrapper; } +#if GL_TESTING + contextAttributes.preserveDrawingBuffer = true; #endif - // possible GL_DEBUG entry point: ctx = wrapDebugGL(ctx); + contextHandle = GL.createContext(canvas, contextAttributes); + ctx = GL.getContext(contextHandle).GLctx; // Set the background of the WebGL canvas to black canvas.style.backgroundColor = "black"; + } else { + ctx = canvas.getContext('2d'); } + + if (!ctx) return null; + if (setInModule) { if (!useWebGL) assert(typeof GLctx === 'undefined', 'cannot set in module if GLctx is used, but we are a non-GL context that would replace it'); + Module.ctx = ctx; - if (useWebGL) GLctx = ctx; + if (useWebGL) GL.makeContextCurrent(contextHandle); Module.useWebGL = useWebGL; Browser.moduleContextCreatedCallbacks.forEach(function(callback) { callback() }); Browser.init(); diff --git a/src/library_gl.js b/src/library_gl.js index a4d560e74c997..79425b9f75369 100644 --- a/src/library_gl.js +++ b/src/library_gl.js @@ -20,9 +20,9 @@ var LibraryGL = { uniforms: [], shaders: [], vaos: [], + contexts: [], #if FULL_ES2 - clientBuffers: [], currArrayBuffer: 0, currElementArrayBuffer: 0, #endif @@ -59,7 +59,10 @@ var LibraryGL = { init: function() { GL.createLog2ceilLookup(GL.MAX_TEMP_BUFFER_SIZE); - Browser.moduleContextCreatedCallbacks.push(GL.initExtensions); + GL.miniTempBuffer = new Float32Array(GL.MINI_TEMP_BUFFER_SIZE); + for (var i = 0; i < GL.MINI_TEMP_BUFFER_SIZE; i++) { + GL.miniTempBufferViews[i] = GL.miniTempBuffer.subarray(0, i+1); + } }, // Records a GL error condition that occurred, stored until user calls glGetError() to fetch it. As per GLES2 spec, only the first error @@ -90,15 +93,9 @@ var LibraryGL = { // could cause a GPU-CPU pipeline stall. // Note that index buffers are not double-buffered (at the moment) in this manner. MAX_TEMP_BUFFER_SIZE: {{{ GL_MAX_TEMP_BUFFER_SIZE }}}, - tempVertexBuffers1: [], - tempVertexBufferCounters1: [], - tempVertexBuffers2: [], - tempVertexBufferCounters2: [], // Maximum number of temp VBOs of one size to maintain, after that we start reusing old ones, which is safe but can give // a performance impact. If CPU-GPU stalls are a problem, increasing this might help. numTempVertexBuffersPerSize: 64, // (const) - tempIndexBuffers: [], - tempQuadIndexBuffer: null, // Precompute a lookup table for the function ceil(log2(x)), i.e. how many bits are needed to represent x, or, // if x was rounded up to next pow2, which index is the single '1' bit at? @@ -118,19 +115,24 @@ var LibraryGL = { } }, - generateTempBuffers: function(quads) { + generateTempBuffers: function(quads, context) { var largestIndex = GL.log2ceilLookup[GL.MAX_TEMP_BUFFER_SIZE]; - GL.tempVertexBufferCounters1.length = GL.tempVertexBufferCounters2.length = largestIndex+1; - GL.tempVertexBuffers1.length = GL.tempVertexBuffers2.length = largestIndex+1; - GL.tempIndexBuffers.length = largestIndex+1; + context.tempVertexBufferCounters1 = []; + context.tempVertexBufferCounters2 = []; + context.tempVertexBufferCounters1.length = context.tempVertexBufferCounters2.length = largestIndex+1; + context.tempVertexBuffers1 = []; + context.tempVertexBuffers2 = []; + context.tempVertexBuffers1.length = context.tempVertexBuffers2.length = largestIndex+1; + context.tempIndexBuffers = []; + context.tempIndexBuffers.length = largestIndex+1; for(var i = 0; i <= largestIndex; ++i) { - GL.tempIndexBuffers[i] = null; // Created on-demand - GL.tempVertexBufferCounters1[i] = GL.tempVertexBufferCounters2[i] = 0; + context.tempIndexBuffers[i] = null; // Created on-demand + context.tempVertexBufferCounters1[i] = context.tempVertexBufferCounters2[i] = 0; var ringbufferLength = GL.numTempVertexBuffersPerSize; - GL.tempVertexBuffers1[i] = []; - GL.tempVertexBuffers2[i] = []; - var ringbuffer1 = GL.tempVertexBuffers1[i]; - var ringbuffer2 = GL.tempVertexBuffers2[i]; + context.tempVertexBuffers1[i] = []; + context.tempVertexBuffers2[i] = []; + var ringbuffer1 = context.tempVertexBuffers1[i]; + var ringbuffer2 = context.tempVertexBuffers2[i]; ringbuffer1.length = ringbuffer2.length = ringbufferLength; for(var j = 0; j < ringbufferLength; ++j) { ringbuffer1[j] = ringbuffer2[j] = null; // Created on-demand @@ -139,8 +141,8 @@ var LibraryGL = { if (quads) { // GL_QUAD indexes can be precalculated - GL.tempQuadIndexBuffer = GLctx.createBuffer(); - GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, GL.tempQuadIndexBuffer); + context.tempQuadIndexBuffer = GLctx.createBuffer(); + context.GLctx.bindBuffer(context.GLctx.ELEMENT_ARRAY_BUFFER, context.tempQuadIndexBuffer); var numIndexes = GL.MAX_TEMP_BUFFER_SIZE >> 1; var quadIndexes = new Uint16Array(numIndexes); var i = 0, v = 0; @@ -159,16 +161,16 @@ var LibraryGL = { if (i >= numIndexes) break; v += 4; } - GLctx.bufferData(GLctx.ELEMENT_ARRAY_BUFFER, quadIndexes, GLctx.STATIC_DRAW); - GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, null); + context.GLctx.bufferData(context.GLctx.ELEMENT_ARRAY_BUFFER, quadIndexes, context.GLctx.STATIC_DRAW); + context.GLctx.bindBuffer(context.GLctx.ELEMENT_ARRAY_BUFFER, null); } }, getTempVertexBuffer: function getTempVertexBuffer(sizeBytes) { var idx = GL.log2ceilLookup[sizeBytes]; - var ringbuffer = GL.tempVertexBuffers1[idx]; - var nextFreeBufferIndex = GL.tempVertexBufferCounters1[idx]; - GL.tempVertexBufferCounters1[idx] = (GL.tempVertexBufferCounters1[idx]+1) & (GL.numTempVertexBuffersPerSize-1); + var ringbuffer = GL.currentContext.tempVertexBuffers1[idx]; + var nextFreeBufferIndex = GL.currentContext.tempVertexBufferCounters1[idx]; + GL.currentContext.tempVertexBufferCounters1[idx] = (GL.currentContext.tempVertexBufferCounters1[idx]+1) & (GL.numTempVertexBuffersPerSize-1); var vbo = ringbuffer[nextFreeBufferIndex]; if (vbo) { return vbo; @@ -183,31 +185,31 @@ var LibraryGL = { getTempIndexBuffer: function getTempIndexBuffer(sizeBytes) { var idx = GL.log2ceilLookup[sizeBytes]; - var ibo = GL.tempIndexBuffers[idx]; + var ibo = GL.currentContext.tempIndexBuffers[idx]; if (ibo) { return ibo; } var prevIBO = GLctx.getParameter(GLctx.ELEMENT_ARRAY_BUFFER_BINDING); - GL.tempIndexBuffers[idx] = GLctx.createBuffer(); - GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, GL.tempIndexBuffers[idx]); + GL.currentContext.tempIndexBuffers[idx] = GLctx.createBuffer(); + GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, GL.currentContext.tempIndexBuffers[idx]); GLctx.bufferData(GLctx.ELEMENT_ARRAY_BUFFER, 1 << idx, GLctx.DYNAMIC_DRAW); GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, prevIBO); - return GL.tempIndexBuffers[idx]; + return GL.currentContext.tempIndexBuffers[idx]; }, // Called at start of each new WebGL rendering frame. This swaps the doublebuffered temp VB memory pointers, // so that every second frame utilizes different set of temp buffers. The aim is to keep the set of buffers // being rendered, and the set of buffers being updated disjoint. newRenderingFrameStarted: function newRenderingFrameStarted() { - var vb = GL.tempVertexBuffers1; - GL.tempVertexBuffers1 = GL.tempVertexBuffers2; - GL.tempVertexBuffers2 = vb; - vb = GL.tempVertexBufferCounters1; - GL.tempVertexBufferCounters1 = GL.tempVertexBufferCounters2; - GL.tempVertexBufferCounters2 = vb; + var vb = GL.currentContext.tempVertexBuffers1; + GL.currentContext.tempVertexBuffers1 = GL.currentContext.tempVertexBuffers2; + GL.currentContext.tempVertexBuffers2 = vb; + vb = GL.currentContext.tempVertexBufferCounters1; + GL.currentContext.tempVertexBufferCounters1 = GL.currentContext.tempVertexBufferCounters2; + GL.currentContext.tempVertexBufferCounters2 = vb; var largestIndex = GL.log2ceilLookup[GL.MAX_TEMP_BUFFER_SIZE]; for(var i = 0; i <= largestIndex; ++i) { - GL.tempVertexBufferCounters1[i] = 0; + GL.currentContext.tempVertexBufferCounters1[i] = 0; } }, @@ -479,7 +481,7 @@ var LibraryGL = { break; case 0x1406 /* GL_FLOAT */: #if GL_ASSERTIONS - if (!GL.floatExt) Module.printErr('Must have OES_texture_float to use float textures'); + if (!GL.currentContext.floatExt) Module.printErr('Must have OES_texture_float to use float textures'); #endif switch (format) { case 0x1907 /* GL_RGB */: @@ -582,8 +584,8 @@ var LibraryGL = { GL.resetBufferBinding = false; // TODO: initial pass to detect ranges we need to upload, might not need an upload per attrib - for (var i = 0; i < GL.maxVertexAttribs; ++i) { - var cb = GL.clientBuffers[i]; + for (var i = 0; i < GL.currentContext.maxVertexAttribs; ++i) { + var cb = GL.currentContext.clientBuffers[i]; if (!cb.clientside || !cb.enabled) continue; GL.resetBufferBinding = true; @@ -657,48 +659,194 @@ var LibraryGL = { } }, #endif + + // Returns the context handle to the new context. + createContext: function(canvas, webGLContextAttributes) { +#if !USE_TYPED_ARRAYS + Module.print('(USE_TYPED_ARRAYS needs to be enabled for WebGL)'); + return null; +#endif + // Default to creating a WebGL 1.0 context if nothing else is specified. + if (typeof webGLContextAttributes.majorVersion === 'undefined' && typeof webGLContextAttributes.minorVersion === 'undefined') { + webGLContextAttributes.majorVersion = 1; + webGLContextAttributes.minorVersion = 0; + } + var ctx; + var errorInfo = '?'; + function onContextCreationError(event) { + errorInfo = event.statusMessage || errorInfo; + } + try { + canvas.addEventListener('webglcontextcreationerror', onContextCreationError, false); + try { + if (webGLContextAttributes.majorVersion == 1 && webGLContextAttributes.minorVersion == 0) { + ctx = canvas.getContext("webgl", webGLContextAttributes) || canvas.getContext("experimental-webgl", webGLContextAttributes); + } else { + throw 'Unsupported WebGL context version ' + majorVersion + '.' + minorVersion + '!' + } + } finally { + canvas.removeEventListener('webglcontextcreationerror', onContextCreationError, false); + } + if (!ctx) throw ':('; + } catch (e) { + Module.print('Could not create canvas: ' + [errorInfo, e]); + return 0; + } +#if GL_DEBUG + function wrapDebugGL(ctx) { + + var printObjectList = []; + + function prettyPrint(arg) { + if (typeof arg == 'undefined') return '!UNDEFINED!'; + if (typeof arg == 'boolean') arg = arg + 0; + if (!arg) return arg; + var index = printObjectList.indexOf(arg); + if (index >= 0) return '<' + arg + '|'; // + index + '>'; + if (arg.toString() == '[object HTMLImageElement]') { + return arg + '\n\n'; + } + if (arg.byteLength) { + return '{' + Array.prototype.slice.call(arg, 0, Math.min(arg.length, 400)) + '}'; // Useful for correct arrays, less so for compiled arrays, see the code below for that + var buf = new ArrayBuffer(32); + var i8buf = new Int8Array(buf); + var i16buf = new Int16Array(buf); + var f32buf = new Float32Array(buf); + switch(arg.toString()) { + case '[object Uint8Array]': + i8buf.set(arg.subarray(0, 32)); + break; + case '[object Float32Array]': + f32buf.set(arg.subarray(0, 5)); + break; + case '[object Uint16Array]': + i16buf.set(arg.subarray(0, 16)); + break; + default: + alert('unknown array for debugging: ' + arg); + throw 'see alert'; + } + var ret = '{' + arg.byteLength + ':\n'; + var arr = Array.prototype.slice.call(i8buf); + ret += 'i8:' + arr.toString().replace(/,/g, ',') + '\n'; + arr = Array.prototype.slice.call(f32buf, 0, 8); + ret += 'f32:' + arr.toString().replace(/,/g, ',') + '}'; + return ret; + } + if (typeof arg == 'object') { + printObjectList.push(arg); + return '<' + arg + '|'; // + (printObjectList.length-1) + '>'; + } + if (typeof arg == 'number') { + if (arg > 0) return '0x' + arg.toString(16) + ' (' + arg + ')'; + } + return arg; + } + + var wrapper = {}; + for (var prop in ctx) { + (function(prop) { + switch (typeof ctx[prop]) { + case 'function': { + wrapper[prop] = function gl_wrapper() { + var printArgs = Array.prototype.slice.call(arguments).map(prettyPrint); + dump('[gl_f:' + prop + ':' + printArgs + ']\n'); + var ret = ctx[prop].apply(ctx, arguments); + if (typeof ret != 'undefined') { + dump('[ gl:' + prop + ':return:' + prettyPrint(ret) + ']\n'); + } + return ret; + } + break; + } + case 'number': case 'string': { + wrapper.__defineGetter__(prop, function() { + //dump('[gl_g:' + prop + ':' + ctx[prop] + ']\n'); + return ctx[prop]; + }); + wrapper.__defineSetter__(prop, function(value) { + dump('[gl_s:' + prop + ':' + value + ']\n'); + ctx[prop] = value; + }); + break; + } + } + })(prop); + } + return wrapper; + } +#endif + // possible GL_DEBUG entry point: ctx = wrapDebugGL(ctx); + + if (!ctx) return 0; + var handle = GL.getNewId(GL.contexts); + var context = { handle: handle }; + context.GLctx = ctx; + GL.contexts[handle] = context; + if (typeof webGLContextAttributes['webGLContextAttributes'] === 'undefined' || webGLContextAttributes.enableExtensionsByDefault) { + GL.initExtensions(context); + } + return handle; + }, + + makeContextCurrent: function(contextHandle) { + var context = GL.contexts[contextHandle]; + if (!context) return false; + GLctx = Module.ctx = context.GLctx; // Active WebGL context object. + GL.currentContext = context; // Active Emscripten GL layer context object. + return true; + }, + + getContext: function(contextHandle) { + return GL.contexts[contextHandle]; + }, + + deleteContext: function(contextHandle) { + if (GL.currentContext === GL.contexts[contextHandle]) GL.currentContext = 0; + GL.contexts[contextHandle] = null; + }, // In WebGL, extensions must be explicitly enabled to be active, see http://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.14 // In GLES2, all extensions are enabled by default without additional operations. Init all extensions we need to give to GLES2 user // code here, so that GLES2 code can operate without changing behavior. - initExtensions: function() { - if (GL.initExtensions.done) return; - GL.initExtensions.done = true; + initExtensions: function(context) { - if (!Module.useWebGL) return; // an app might link both gl and 2d backends + // If this function is called without a specific context object, init the extensions of the currently active context. + if (!context) context = GL.currentContext; - GL.miniTempBuffer = new Float32Array(GL.MINI_TEMP_BUFFER_SIZE); - for (var i = 0; i < GL.MINI_TEMP_BUFFER_SIZE; i++) { - GL.miniTempBufferViews[i] = GL.miniTempBuffer.subarray(0, i+1); - } + if (context.initExtensionsDone) return; + context.initExtensionsDone = true; + + var GLctx = context.GLctx; - GL.maxVertexAttribs = GLctx.getParameter(GLctx.MAX_VERTEX_ATTRIBS); + context.maxVertexAttribs = GLctx.getParameter(GLctx.MAX_VERTEX_ATTRIBS); #if FULL_ES2 - for (var i = 0; i < GL.maxVertexAttribs; i++) { - GL.clientBuffers[i] = { enabled: false, clientside: false, size: 0, type: 0, normalized: 0, stride: 0, ptr: 0 }; + context.clientBuffers = []; + for (var i = 0; i < context.maxVertexAttribs; i++) { + context.clientBuffers[i] = { enabled: false, clientside: false, size: 0, type: 0, normalized: 0, stride: 0, ptr: 0 }; } - GL.generateTempBuffers(); + GL.generateTempBuffers(false, context); #endif // Detect the presence of a few extensions manually, this GL interop layer itself will need to know if they exist. - GL.compressionExt = GLctx.getExtension('WEBGL_compressed_texture_s3tc') || + context.compressionExt = GLctx.getExtension('WEBGL_compressed_texture_s3tc') || GLctx.getExtension('MOZ_WEBGL_compressed_texture_s3tc') || GLctx.getExtension('WEBKIT_WEBGL_compressed_texture_s3tc'); - GL.anisotropicExt = GLctx.getExtension('EXT_texture_filter_anisotropic') || + context.anisotropicExt = GLctx.getExtension('EXT_texture_filter_anisotropic') || GLctx.getExtension('MOZ_EXT_texture_filter_anisotropic') || GLctx.getExtension('WEBKIT_EXT_texture_filter_anisotropic'); - GL.floatExt = GLctx.getExtension('OES_texture_float'); + context.floatExt = GLctx.getExtension('OES_texture_float'); // Extension available from Firefox 26 and Google Chrome 30 - GL.instancedArraysExt = GLctx.getExtension('ANGLE_instanced_arrays'); + context.instancedArraysExt = GLctx.getExtension('ANGLE_instanced_arrays'); // Extension available from Firefox 25 and WebKit - GL.vaoExt = Module.ctx.getExtension('OES_vertex_array_object'); + context.vaoExt = GLctx.getExtension('OES_vertex_array_object'); - GL.drawBuffersExt = Module.ctx.getExtension('WEBGL_draw_buffers'); + context.drawBuffersExt = GLctx.getExtension('WEBGL_draw_buffers'); // These are the 'safe' feature-enabling extensions that don't add any performance impact related to e.g. debugging, and // should be enabled by default so that client GLES2/GL code will not need to go through extra hoops to get its stuff working. @@ -870,7 +1018,7 @@ var LibraryGL = { glCompressedTexImage2D__sig: 'viiiiiiii', glCompressedTexImage2D: function(target, level, internalFormat, width, height, border, imageSize, data) { #if ASSERTIONS - assert(GL.compressionExt); + assert(GL.currentContext.compressionExt); #endif if (data) { data = {{{ makeHEAPView('U8', 'data', 'data+imageSize') }}}; @@ -884,7 +1032,7 @@ var LibraryGL = { glCompressedTexSubImage2D__sig: 'viiiiiiiii', glCompressedTexSubImage2D: function(target, level, xoffset, yoffset, width, height, format, imageSize, data) { #if ASSERTIONS - assert(GL.compressionExt); + assert(GL.currentContext.compressionExt); #endif if (data) { data = {{{ makeHEAPView('U8', 'data', 'data+imageSize') }}}; @@ -1159,7 +1307,7 @@ var LibraryGL = { glGetVertexAttribfv__sig: 'viii', glGetVertexAttribfv: function(index, pname, params) { #if FULL_ES2 - if (GL.clientBuffers[index].enabled) { + if (GL.currentContext.clientBuffers[index].enabled) { Module.printErr("glGetVertexAttribfv on client-side array: not supported, bad data returned"); } #endif @@ -1176,7 +1324,7 @@ var LibraryGL = { glGetVertexAttribiv__sig: 'viii', glGetVertexAttribiv: function(index, pname, params) { #if FULL_ES2 - if (GL.clientBuffers[index].enabled) { + if (GL.currentContext.clientBuffers[index].enabled) { Module.printErr("glGetVertexAttribiv on client-side array: not supported, bad data returned"); } #endif @@ -1193,7 +1341,7 @@ var LibraryGL = { glGetVertexAttribPointerv__sig: 'viii', glGetVertexAttribPointerv: function(index, pname, pointer) { #if FULL_ES2 - if (GL.clientBuffers[index].enabled) { + if (GL.currentContext.clientBuffers[index].enabled) { Module.printErr("glGetVertexAttribPointer on client-side array: not supported, bad data returned"); } #endif @@ -1873,12 +2021,12 @@ var LibraryGL = { _emulGlGenVertexArrays(n, arrays); #else #if GL_ASSERTIONS - assert(GL.vaoExt, 'Must have OES_vertex_array_object to use vao'); + assert(GL.currentContext.vaoExt, 'Must have OES_vertex_array_object to use vao'); #endif for(var i = 0; i < n; i++) { var id = GL.getNewId(GL.vaos); - var vao = GL.vaoExt.createVertexArrayOES(); + var vao = GL.currentContext.vaoExt.createVertexArrayOES(); vao.name = id; GL.vaos[id] = vao; {{{ makeSetValue('arrays', 'i*4', 'id', 'i32') }}}; @@ -1895,11 +2043,11 @@ var LibraryGL = { _emulGlDeleteVertexArrays(n, vaos); #else #if GL_ASSERTIONS - assert(GL.vaoExt, 'Must have OES_vertex_array_object to use vao'); + assert(GL.currentContext.vaoExt, 'Must have OES_vertex_array_object to use vao'); #endif for(var i = 0; i < n; i++) { var id = {{{ makeGetValue('vaos', 'i*4', 'i32') }}}; - GL.vaoExt.deleteVertexArrayOES(GL.vaos[id]); + GL.currentContext.vaoExt.deleteVertexArrayOES(GL.vaos[id]); GL.vaos[id] = null; } #endif @@ -1914,10 +2062,10 @@ var LibraryGL = { _emulGlBindVertexArray(vao); #else #if GL_ASSERTIONS - assert(GL.vaoExt, 'Must have OES_vertex_array_object to use vao'); + assert(GL.currentContext.vaoExt, 'Must have OES_vertex_array_object to use vao'); #endif - GL.vaoExt.bindVertexArrayOES(GL.vaos[vao]); + GL.currentContext.vaoExt.bindVertexArrayOES(GL.vaos[vao]); #endif }, @@ -1930,12 +2078,12 @@ var LibraryGL = { return _emulGlIsVertexArray(array); #else #if GL_ASSERTIONS - assert(GL.vaoExt, 'Must have OES_vertex_array_object to use vao'); + assert(GL.currentContext.vaoExt, 'Must have OES_vertex_array_object to use vao'); #endif var vao = GL.vaos[array]; if (!vao) return 0; - return GL.vaoExt.isVertexArrayOES(vao); + return GL.currentContext.vaoExt.isVertexArrayOES(vao); #endif }, @@ -2139,8 +2287,8 @@ var LibraryGL = { case 0x1F03 /* GL_EXTENSIONS */: // Add various extensions that we can support var ret = allocate(intArrayFromString(GLctx.getSupportedExtensions().join(' ') + ' GL_EXT_texture_env_combine GL_ARB_texture_env_crossbar GL_ATI_texture_env_combine3 GL_NV_texture_env_combine4 GL_EXT_texture_env_dot3 GL_ARB_multitexture GL_ARB_vertex_buffer_object GL_EXT_framebuffer_object GL_ARB_vertex_program GL_ARB_fragment_program GL_ARB_shading_language_100 GL_ARB_shader_objects GL_ARB_vertex_shader GL_ARB_fragment_shader GL_ARB_texture_cube_map GL_EXT_draw_range_elements' + - (GL.compressionExt ? ' GL_ARB_texture_compression GL_EXT_texture_compression_s3tc' : '') + - (GL.anisotropicExt ? ' GL_EXT_texture_filter_anisotropic' : '') + (GL.currentContext.compressionExt ? ' GL_ARB_texture_compression GL_EXT_texture_compression_s3tc' : '') + + (GL.currentContext.anisotropicExt ? ' GL_EXT_texture_filter_anisotropic' : '') ), 'i8', ALLOC_NORMAL); GL.stringCache[name_] = ret; return ret; @@ -4424,7 +4572,7 @@ var LibraryGL = { GLImmediate.vertexDataU8 = new Uint8Array(GLImmediate.tempData.buffer); - GL.generateTempBuffers(true); + GL.generateTempBuffers(true, GL.currentContext); GLImmediate.clientColor = new Float32Array([1, 1, 1, 1]); }, @@ -4602,7 +4750,7 @@ var LibraryGL = { #if ASSERTIONS assert(ptr + (numIndexes << 1) <= GL.MAX_TEMP_BUFFER_SIZE, 'too many immediate mode indexes (b)'); #endif - GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, GL.tempQuadIndexBuffer); + GLctx.bindBuffer(GLctx.ELEMENT_ARRAY_BUFFER, GL.currentContext.tempQuadIndexBuffer); emulatedElementArrayBuffer = true; } @@ -5274,7 +5422,7 @@ var LibraryGL = { glVertexAttribPointer__sig: 'viiiiii', glVertexAttribPointer: function(index, size, type, normalized, stride, ptr) { #if FULL_ES2 - var cb = GL.clientBuffers[index]; + var cb = GL.currentContext.clientBuffers[index]; #if ASSERTIONS assert(cb, index); #endif @@ -5298,7 +5446,7 @@ var LibraryGL = { glEnableVertexAttribArray__sig: 'vi', glEnableVertexAttribArray: function(index) { #if FULL_ES2 - var cb = GL.clientBuffers[index]; + var cb = GL.currentContext.clientBuffers[index]; #if ASSERTIONS assert(cb, index); #endif @@ -5310,7 +5458,7 @@ var LibraryGL = { glDisableVertexAttribArray__sig: 'vi', glDisableVertexAttribArray: function(index) { #if FULL_ES2 - var cb = GL.clientBuffers[index]; + var cb = GL.currentContext.clientBuffers[index]; #if ASSERTIONS assert(cb, index); #endif @@ -5393,25 +5541,25 @@ var LibraryGL = { glVertexAttribDivisor__sig: 'vii', glVertexAttribDivisor: function(index, divisor) { #if GL_ASSERTIONS - assert(GL.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); + assert(GL.currentContext.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); #endif - GL.instancedArraysExt.vertexAttribDivisorANGLE(index, divisor); + GL.currentContext.instancedArraysExt.vertexAttribDivisorANGLE(index, divisor); }, glDrawArraysInstanced__sig: 'viiii', glDrawArraysInstanced: function(mode, first, count, primcount) { #if GL_ASSERTIONS - assert(GL.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); + assert(GL.currentContext.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); #endif - GL.instancedArraysExt.drawArraysInstancedANGLE(mode, first, count, primcount); + GL.currentContext.instancedArraysExt.drawArraysInstancedANGLE(mode, first, count, primcount); }, glDrawElementsInstanced__sig: 'viiiii', glDrawElementsInstanced: function(mode, count, type, indices, primcount) { #if GL_ASSERTIONS - assert(GL.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); + assert(GL.currentContext.instancedArraysExt, 'Must have ANGLE_instanced_arrays extension to use WebGL instancing'); #endif - GL.instancedArraysExt.drawElementsInstancedANGLE(mode, count, type, indices, primcount); + GL.currentContext.instancedArraysExt.drawElementsInstancedANGLE(mode, count, type, indices, primcount); }, // OpenGL Desktop/ES 2.0 instancing extensions compatibility @@ -5430,13 +5578,13 @@ var LibraryGL = { glDrawBuffers__sig: 'vii', glDrawBuffers: function(n, bufs) { #if GL_ASSERTIONS - assert(GL.drawBuffersExt, 'Must have WEBGL_draw_buffers extension to use drawBuffers'); + assert(GL.currentContext.drawBuffersExt, 'Must have WEBGL_draw_buffers extension to use drawBuffers'); #endif var bufArray = []; for (var i = 0; i < n; i++) bufArray.push({{{ makeGetValue('bufs', 'i*4', 'i32') }}}); - GL.drawBuffersExt.drawBuffersWEBGL(bufArray); + GL.currentContext.drawBuffersExt.drawBuffersWEBGL(bufArray); }, // signatures of simple pass-through functions, see later diff --git a/src/library_html5.js b/src/library_html5.js index 238575de574bb..7e995cdd988f1 100644 --- a/src/library_html5.js +++ b/src/library_html5.js @@ -1304,6 +1304,64 @@ var LibraryJSEvents = { return {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}}; }, + emscripten_webgl_init_context_attributes: function(attributes) { + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.alpha, 1, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.depth, 1, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.stencil, 0, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.antialias, 1, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.premultipliedAlpha, 1, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.preserveDrawingBuffer, 0, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.preferLowPowerToHighPerformance, 0, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.failIfMajorPerformanceCaveat, 0, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.majorVersion, 1, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.minorVersion, 0, 'i32') }}}; + {{{ makeSetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.enableExtensionsByDefault, 1, 'i32') }}}; + }, + + emscripten_webgl_create_context: function(target, attributes) { + var contextAttributes = {}; + contextAttributes.alpha = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.alpha, 'i32') }}}; + contextAttributes.depth = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.depth, 'i32') }}}; + contextAttributes.stencil = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.stencil, 'i32') }}}; + contextAttributes.antialias = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.antialias, 'i32') }}}; + contextAttributes.premultipliedAlpha = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.premultipliedAlpha, 'i32') }}}; + contextAttributes.preserveDrawingBuffer = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.preserveDrawingBuffer, 'i32') }}}; + contextAttributes.preferLowPowerToHighPerformance = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.preferLowPowerToHighPerformance, 'i32') }}}; + contextAttributes.failIfMajorPerformanceCaveat = !!{{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.failIfMajorPerformanceCaveat, 'i32') }}}; + var majorVersion = {{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.majorVersion, 'i32') }}}; + var minorVersion = {{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.minorVersion, 'i32') }}}; + var enableExtensionsByDefault = {{{ makeGetValue('attributes', C_STRUCTS.EmscriptenWebGLContextAttributes.enableExtensionsByDefault, 'i32') }}}; + + if (!target) { + target = Module['canvas']; + } else { + target = JSEvents.findEventTarget(target); + } + var contextHandle = GL.createContext(target, contextAttributes); + return contextHandle; + }, + + emscripten_webgl_make_context_current: function(contextHandle) { + var success = GL.makeContextCurrent(contextHandle); + return success ? {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}} : {{{ cDefine('EMSCRIPTEN_RESULT_INVALID_PARAM') }}}; + }, + + emscripten_webgl_get_current_context: function() { + return GL.currentContext ? GL.currentContext.handle : 0; + }, + + emscripten_webgl_destroy_context: function(contextHandle) { + GL.deleteContext(contextHandle); + }, + + emscripten_webgl_enable_extension: function(contextHandle, extension) { + var context = GL.getContext(contextHandle); + var extString = Pointer_stringify(extension); + if (extString.indexOf('GL_') == 0) extString = extString.substr(3); // Allow enabling extensions both with "GL_" prefix and without. + var ext = context.GLctx.getExtension(extString); + return ext ? 1 : 0; + }, + emscripten_set_webglcontextlost_callback: function(target, userData, useCapture, callbackfunc) { JSEvents.registerWebGlEventCallback(target, userData, useCapture, callbackfunc, {{{ cDefine('EMSCRIPTEN_EVENT_WEBGLCONTEXTLOST') }}}, "webglcontextlost"); return {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}}; diff --git a/src/library_sdl.js b/src/library_sdl.js index c00c0d6c7925b..7025c4078aa46 100644 --- a/src/library_sdl.js +++ b/src/library_sdl.js @@ -1325,6 +1325,7 @@ var LibrarySDL = { return buf; }, + SDL_SetVideoMode__deps: ['$GL'], SDL_SetVideoMode: function(width, height, depth, flags) { ['touchstart', 'touchend', 'touchmove', 'mousedown', 'mouseup', 'mousemove', 'DOMMouseScroll', 'mousewheel', 'wheel', 'mouseout'].forEach(function(event) { Module['canvas'].addEventListener(event, SDL.receiveEvent, true); diff --git a/src/postamble.js b/src/postamble.js index cbf6450f5c376..7fd4eb1951505 100644 --- a/src/postamble.js +++ b/src/postamble.js @@ -179,10 +179,15 @@ function exit(status) { // Instead of process.exit() directly, wait for stdout flush event. // See https://github.com/joyent/node/issues/1669 and https://github.com/kripken/emscripten/issues/2582 // Workaround is based on https://github.com/RReverser/acorn/commit/50ab143cecc9ed71a2d66f78b4aec3bb2e9844f6 - process.stdout.once('drain', function () { + process['stdout']['once']('drain', function () { process['exit'](status); }); console.log(' '); // Make sure to print something to force the drain event to occur, in case the stdout buffer was empty. + // Work around another node bug where sometimes 'drain' is never fired - make another effort + // to emit the exit status, after a significant delay (if node hasn't fired drain by then, give up) + setTimeout(function() { + process['exit'](status); + }, 500); } else if (ENVIRONMENT_IS_SHELL && typeof quit === 'function') { quit(status); } else { diff --git a/src/shell.js b/src/shell.js index 7748ae72c704d..7f556fb9fde39 100644 --- a/src/shell.js +++ b/src/shell.js @@ -73,7 +73,9 @@ if (ENVIRONMENT_IS_NODE) { Module['thisProgram'] = process['argv'][1]; Module['arguments'] = process['argv'].slice(2); - module['exports'] = Module; + if (typeof module !== 'undefined') { + module['exports'] = Module; + } } else if (ENVIRONMENT_IS_SHELL) { if (!Module['print']) Module['print'] = print; diff --git a/src/struct_info.json b/src/struct_info.json index 94a64845cd5f3..17545c3da0fa1 100644 --- a/src/struct_info.json +++ b/src/struct_info.json @@ -1297,6 +1297,19 @@ "dischargingTime", "level", "charging" + ], + "EmscriptenWebGLContextAttributes": [ + "alpha", + "depth", + "stencil", + "antialias", + "premultipliedAlpha", + "preserveDrawingBuffer", + "preferLowPowerToHighPerformance", + "failIfMajorPerformanceCaveat", + "majorVersion", + "minorVersion", + "enableExtensionsByDefault" ] } } diff --git a/system/include/emscripten/html5.h b/system/include/emscripten/html5.h index 9ffb4ece9e098..98192e289e543 100644 --- a/system/include/emscripten/html5.h +++ b/system/include/emscripten/html5.h @@ -648,6 +648,92 @@ extern EMSCRIPTEN_RESULT emscripten_vibrate_pattern(int *msecsArray, int numEntr typedef const char *(*em_beforeunload_callback)(int eventType, const void *reserved, void *userData); extern EMSCRIPTEN_RESULT emscripten_set_beforeunload_callback(void *userData, em_beforeunload_callback callback); +// Represents a handle to an Emscripten WebGL context object. The value 0 denotes an invalid/no context. +typedef int EMSCRIPTEN_WEBGL_CONTEXT_HANDLE; + +/* + * Specifies WebGL context creation parameters, as documented at http://www.khronos.org/registry/webgl/specs/latest/1.0/#5.2 + */ +typedef struct EmscriptenWebGLContextAttributes { + // If true, request an alpha channel for the context. If you create an alpha channel, you can blend the canvas rendering with the + // underlying web page contents. Default value: true. + EM_BOOL alpha; + // If true, request a depth buffer of at least 16 bits. If false, no depth buffer will be initialized. Default value: true. + EM_BOOL depth; + // If true, request a stencil buffer of at least 8 bits. If false, no stencil buffer will be initialized. Default value: false. + EM_BOOL stencil; + // If true, antialiasing will be initialized with a browser-specified algorithm and quality level. If false, antialiasing is disabled. Default value: true. + EM_BOOL antialias; + // If true, the alpha channel of the rendering context will be treated as representing premultiplied alpha values. If false, the alpha + // channel represents non-premultiplied alpha. Default value: true. + EM_BOOL premultipliedAlpha; + // If true, the contents of the drawing buffer are preserved between consecutive requestAnimationFrame() calls. If false, color, depth + // and stencil are cleared at the beginning of each requestAnimationFrame(). Generally setting this to false gives better performance. Default value: false. + EM_BOOL preserveDrawingBuffer; + // If true, hints the browser to initialize a low-power GPU rendering context. If false, prefers to initialize a high-performance + // rendering context. Default value: false. + EM_BOOL preferLowPowerToHighPerformance; + // If true, requests context creation to abort if the browser is only able to create a context that does not give good + // hardware-accelerated performance. Default value: false. + EM_BOOL failIfMajorPerformanceCaveat; + + // Emscripten-specific extensions: + // majorVersion x minorVersion: Specifies the WebGL context version to initialize. + // For example, pass in majorVersion=1, minorVersion=0 to request a WebGL 1.0 context, and + // majorVersion=2, minorVersion=0 to request a WebGL 2.0 context. + // Default value: majorVersion=1, minorVersion=0 + int majorVersion; + int minorVersion; + + // If true, all GLES2-compatible non-performance-impacting WebGL extensions will automatically be enabled for you after the context + // has been created. If false, no extensions are enabled by default, and you need to manually call emscripten_webgl_enable_extension() + // to enable each extension that you want to use. Default value: true. + EM_BOOL enableExtensionsByDefault; +} EmscriptenWebGLContextAttributes; + +/* + * Populates all fields of the given EmscriptenWebGLContextAttributes structure to their default values for use with WebGL 1.0. + * Call this function as a forward-compatible way to ensure that if there are new fields added to the EmscriptenWebGLContextAttributes + * structure in the future, that they also will get default-initialized without having to change any code. + */ +extern void emscripten_webgl_init_context_attributes(EmscriptenWebGLContextAttributes *attributes); + +/* + * Creates a new WebGL context. See http://www.khronos.org/registry/webgl/specs/latest/1.0/#2.1 + * The parameter 'target' specifies the DOM canvas element in which to initialize the WebGL context. If 0 is passed for the target, + * the element specified by Module.canvas will be used. + * On success, this function returns a strictly positive value that represents a handle to the created context. + * On failure, this function returns a negative number that can be casted to a EMSCRIPTEN_RESULT field to get an error reason + * why the context creation failed. + * NOTE: A successful call to emscripten_webgl_create_context() will not immediately make that rendering context active. Call + * emscripten_webgl_make_context_current() after creating a context to activate it. + * NOTE: This function will try to initialize the context version that was *exactly* requested. It will not e.g. initialize a newer + * backwards-compatible version or similar. + */ +extern EMSCRIPTEN_WEBGL_CONTEXT_HANDLE emscripten_webgl_create_context(const char *target, const EmscriptenWebGLContextAttributes *attributes); + +/* + * Activates the given WebGL context for rendering. After calling this function, all gl***() functions apply to the given GL context. + */ +extern EMSCRIPTEN_RESULT emscripten_webgl_make_context_current(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context); + +/* + * Returns the currently active WebGL rendering context, or 0 if no such context is active. Calling any WebGL functions when there is no active + * rendering context is undefined and may throw a JavaScript exception. + */ +extern EMSCRIPTEN_WEBGL_CONTEXT_HANDLE emscripten_webgl_get_current_context(); + +/* + * Deletes the given WebGL context. If that context was active, then the no context is set to active. + */ +extern EMSCRIPTEN_RESULT emscripten_webgl_destroy_context(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context); + +/* + * Enables the given extension on the given context. + * Returns EM_TRUE if the given extension is supported by the context, and EM_FALSE if the extension was not available. + */ +extern EM_BOOL emscripten_webgl_enable_extension(EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context, const char *extension); + /* * Registers a callback function for the canvas webgl context webglcontextlost and webglcontextrestored events. * See http://www.khronos.org/registry/webgl/specs/latest/1.0/#5.15.2 diff --git a/tests/runner.py b/tests/runner.py index 7c5548180e49a..629047dfe5ea6 100755 --- a/tests/runner.py +++ b/tests/runner.py @@ -26,6 +26,7 @@ def path_from_root(*pathelems): sys.path += [path_from_root(''), path_from_root('third_party/websockify')] import tools.shared from tools.shared import * +from tools.line_endings import check_line_endings # Utils @@ -268,6 +269,7 @@ def run_generated_code(self, engine, filename, args=[], check_timeout=True, outp except: cwd = None os.chdir(self.get_dir()) + assert(check_line_endings(filename) == 0) # Make sure that we produced proper line endings to the .js file we are about to run. run_js(filename, engine, args, check_timeout, stdout=open(stdout, 'w'), stderr=open(stderr, 'w'), assert_returncode=assert_returncode) if cwd is not None: os.chdir(cwd) diff --git a/tests/test_browser.py b/tests/test_browser.py index 0ff0ea8167049..281e5852fe991 100644 --- a/tests/test_browser.py +++ b/tests/test_browser.py @@ -1900,6 +1900,11 @@ def test_html5(self): print opts self.btest(path_from_root('tests', 'test_html5.c'), args=opts, expected='0') + def test_html5_webgl_create_context(self): + for opts in [[], ['-O2', '-g1', '--closure', '1']]: + print opts + self.btest(path_from_root('tests', 'webgl_create_context.cpp'), args=opts, expected='0') + def test_sdl_touch(self): for opts in [[], ['-O2', '-g1', '--closure', '1']]: print opts diff --git a/tests/test_core.py b/tests/test_core.py index 19bfb8680a7d4..bf33b8ef1b5db 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -3,6 +3,7 @@ import glob, hashlib, os, re, shutil, subprocess, sys import tools.shared from tools.shared import * +from tools.line_endings import check_line_endings from runner import RunnerCore, path_from_root, checked_sanity, test_modes, get_bullet_library class T(RunnerCore): # Short name, to make it more fun to use manually on the commandline @@ -478,6 +479,9 @@ def test_negative_zero(self): self.do_run_from_file(src, output) + def test_line_endings(self): + self.build(open(path_from_root('tests', 'hello_world.cpp')).read(), self.get_dir(), self.in_dir('hello_world.cpp')) + def test_literal_negative_zero(self): if self.emcc_args == None: return self.skip('needs emcc') @@ -1501,6 +1505,7 @@ def test_exceptions_alias(self): def test_bad_typeid(self): if self.emcc_args is None: return self.skip('requires emcc') + if os.environ.get('EMCC_FAST_COMPILER') == '0': return self.skip('needs fastcomp') Settings.ERROR_ON_UNDEFINED_SYMBOLS = 1 Settings.DISABLE_EXCEPTION_CATCHING = 0 diff --git a/tests/test_other.py b/tests/test_other.py index 999ca92b8e11b..b3f6954b77fc3 100644 --- a/tests/test_other.py +++ b/tests/test_other.py @@ -1517,7 +1517,7 @@ def test_exclude_file(self): Popen([PYTHON, EMCC, os.path.join(self.get_dir(), 'main.cpp'), '--embed-file', 'tst', '--exclude-file', '*.exe']).communicate() output = run_js(os.path.join(self.get_dir(), 'a.out.js')) - assert output == '' + assert output == '' or output == ' \n' def test_multidynamic_link(self): # Linking the same dynamic library in statically will error, normally, since we statically link it, causing dupe symbols diff --git a/tests/webgl_create_context.cpp b/tests/webgl_create_context.cpp new file mode 100644 index 0000000000000..f116e2ece8927 --- /dev/null +++ b/tests/webgl_create_context.cpp @@ -0,0 +1,116 @@ +#include +#include + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +std::vector &split(const std::string &s, char delim, std::vector &elems) { + std::stringstream ss(s); + std::string item; + while (std::getline(ss, item, delim)) { + elems.push_back(item); + } + return elems; +} +std::vector split(const std::string &s, char delim) { + std::vector elems; + split(s, delim, elems); + return elems; +} + +GLint GetInt(GLenum param) +{ + GLint value; + glGetIntegerv(param, &value); + return value; +} + +int main() +{ + bool first = true; + EmscriptenWebGLContextAttributes attrs; + for(int depth = 0; depth <= 1; ++depth) + for(int stencil = 0; stencil <= 1; ++stencil) + for(int antialias = 0; antialias <= 1; ++antialias) + { + emscripten_webgl_init_context_attributes(&attrs); + attrs.depth = depth; + attrs.stencil = stencil; + attrs.antialias = antialias; + printf("Requesting depth: %d, stencil: %d, antialias: %d\n", depth, stencil, antialias); + + if (!first) + { + EM_ASM(var canvas2 = Module.canvas.cloneNode(); + Module.canvas.parentElement.appendChild(canvas2); + // Module.canvas.parentElement.removeChild(canvas); + Module.canvas = canvas2; + ); + } + first = false; + + assert(emscripten_webgl_get_current_context() == 0); + EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context = emscripten_webgl_create_context(0, &attrs); + assert(context > 0); // Must have received a valid context. + EMSCRIPTEN_RESULT res = emscripten_webgl_make_context_current(context); + assert(res == EMSCRIPTEN_RESULT_SUCCESS); + assert(emscripten_webgl_get_current_context() == context); + + // Let's try enabling all extensions. + const char *extensions = (const char*)glGetString(GL_EXTENSIONS); + std::vector exts = split(extensions, ' '); + for(size_t i = 0; i < exts.size(); ++i) + { + EM_BOOL supported = emscripten_webgl_enable_extension(context, exts[i].c_str()); + assert(supported); + } + + // Try with a simple glClear() that we got a context. + glClearColor(1.f, 0.f, 0.f, 1.f); + glClear(GL_COLOR_BUFFER_BIT); + unsigned char pixels[4]; + glReadPixels(0, 0, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, pixels); + assert(pixels[0] == 0xFF); + assert(pixels[1] == 0); + assert(pixels[2] == 0); + assert(pixels[3] == 0xFF); + + int numDepthBits = GetInt(GL_DEPTH_BITS); + int numStencilBits = GetInt(GL_STENCIL_BITS); + int numSamples = GetInt(GL_SAMPLES); + printf("RGBA: %d%d%d%d, Depth: %d, Stencil: %d, Samples: %d\n", + GetInt(GL_RED_BITS), GetInt(GL_GREEN_BITS), GetInt(GL_BLUE_BITS), GetInt(GL_ALPHA_BITS), + numDepthBits, numStencilBits, numSamples); + + if (!depth && stencil && numDepthBits && numStencilBits && EM_ASM_INT_V(navigator.userAgent.toLowerCase().indexOf('firefox')) > -1) + { + numDepthBits = 0; + printf("Applying workaround to ignore Firefox bug https://bugzilla.mozilla.org/show_bug.cgi?id=982477\n"); + } + assert(!!numDepthBits == !!depth); + assert(!!numStencilBits == !!stencil); + assert(!!numSamples == !!antialias); + printf("\n"); + + // Test that deleting the context works. + res = emscripten_webgl_destroy_context(context); + assert(res == 0); + assert(emscripten_webgl_get_current_context() == 0); + } + +#ifdef REPORT_RESULT + int result = 0; + REPORT_RESULT(); +#endif + return 0; +} diff --git a/tools/line_endings.py b/tools/line_endings.py new file mode 100644 index 0000000000000..e1c8797e39009 --- /dev/null +++ b/tools/line_endings.py @@ -0,0 +1,40 @@ +import sys + +# This function checks and prints out the detected line endings in the given file. +# If the file only contains either Windows \r\n line endings or Unix \n line endings, it returns 0. +# Otherwise, in the presence of old OSX or mixed/malformed line endings, a non-zero error code is returned. +def check_line_endings(filename, print_errors=True): + try: + data = open(filename, 'rb').read() + except Exception, e: + if print_errors: print >> sys.stderr, "Unable to read file '" + filename + "'! " + str(e) + return 1 + if len(data) == 0: + if print_errors: print >> sys.stderr, "Unable to read file '" + filename + "', or file was empty!" + return 1 + + if "\r\r\n" in data: + if print_errors: print >> sys.stderr, "File '" + filename + "' contains BAD line endings of form \\r\\r\\n!" + return 1 # Bad line endings in file, return a non-zero process exit code. + + has_dos_line_endings = False + has_unix_line_endings = False + if '\r\n' in data: + has_dos_line_endings = True + data = data.replace('\r\n', 'A') # Replace all DOS line endings with some other character, and continue testing what's left. + if '\n' in data: + has_unix_line_endings = True + if '\r' in data: + if print_errors: print >> sys.stderr, 'File \'' + filename + '\' contains OLD OSX line endings "\\r"' + return 1 # Return a non-zero process exit code since we don't want to use the old OSX (9.x) line endings anywhere. + if has_dos_line_endings and has_unix_line_endings: + if print_errors: print >> sys.stderr, 'File \'' + filename + '\' contains both DOS "\\r\\n" and UNIX "\\n" line endings!' + return 1 # Mixed line endings + else: return 0 + +if __name__ == '__main__': + if len(sys.argv) != 2: + print >> sys.stderr, 'Unknown command line ' + str(sys.argv) + '!' + print >> sys.stderr, 'Usage: ' + sys.argv[0] + ' ' + sys.exit(1) + sys.exit(check_line_endings(sys.argv[1]))