Document HTML inputs.

[nageru-docs] / html.rst

diff --git a/html.rst b/html.rst
new file mode 100644 (file)
index 0000000..644e924
--- /dev/null
+++ b/html.rst
@@ -0,0 +1,85 @@
+HTML inputs
+===========
+
+HTML inputs are used for on-the-fly generated graphics, ie. typically animated
+overlay graphics that cannot be simple still pictures. They allow you to write graphics
+in full HTML5 (including JavaScript) by way of `Chromium Embedded Framework
+<https://bitbucket.org/chromiumembedded/cef/>`_ (CEF for short), a library that
+basically embeds a full copy of the Chromium web browser into Nageru.
+
+HTML inputs are available from Nageru 1.7.0 onwards, but note that they are an
+optional component, since many distributions don't carry CEF. Thus, your copy
+of Nageru may not support them. See :ref:`compiling` for information on how to
+build Nageru with CEF.
+
+Due to CEF performance issues, Nageru does not currently run CEF with GPU
+rendering enabled, even though the rest of Nageru is very much centered around
+the GPU. In particular, this means you do not currently have WebGL support.
+
+
+Basic HTML inputs
+-----------------
+
+In many ways, HTML inputs are similar to :doc:`video inputs <video>`, so you should
+probably understand how they work first. An HTML input is created by way of instantiating
+the *HTMLInput* class::
+
+  local html_input = HTMLInput.new("file:///path/to/graphics/foo.html")
+
+Any regular URL is acceptable, and the sandbox is turned off for convenience,
+so that you can load remote resources from local files. (If you wish to locate
+your HTML path by way of the theme, the variable Nageru.THEME_PATH could prove
+useful, as it contains the absolute path to the theme in current use.)
+
+You can then add this HTMLInput to a chain (or multiple chains if you'd like),
+using code like::
+
+  local image = chain:add_html_input(html_input)
+
+Like video inputs, you can call *get_signal_num()* on the HTML input to get
+its signal number, for getting its resolution etc. (see below for changing
+it). Also like video inputs, there is no audio support (although you may find audio
+played by the web page coming out your regular speakers, not controlled by
+Nageru!). This may change in the future.
+
+
+Controlling HTML inputs
+-----------------------
+
+Generally, HTML inputs run in a background thread and deliver frames
+asynchronously to Nageru. Due to the way CEF works, there is unfortunately no
+obvious way of getting frame-perfect sync between graphics and overlay
+(there can always be a frame or two of lag between the two);
+however, this is normal even in a hardware chain, and most overlay graphics
+does not need to be timed to the input more than through a few frames.
+
+This, and the fact that the theme can not present a very detailed UI
+(short of :ref:`simple menus <menu>`), means that it can be hard to
+exert detailed control over the graphics using Nageru alone—you will
+probably want to have the theme contact some non-Nageru backend (possibly over
+WebSockets) from where it can take detailed instructions.
+
+However, the theme *can* ask the HTML input to run arbitrary JavaScript,
+by calling *html_input:execute_javascript_async("your code here")*, which allows
+you to bring at least some loose coupling between the two. (The “async”
+part is to emphasize that you cannot necessarily expect the effects of
+the code to be visible on the same frame as you start them. The JavaScript
+still runs on the regular UI thread, so if you want to run longer jobs,
+you should use a web worker or similar.) There is currently no way to run
+Lua code from JavaScript, though.
+
+Finally, you can change the URL by using *html_input:set_url("new_url")*,
+or reload the current one using *html_input:reload()*. It can be especially
+useful to bind the latter to a menu entry, in case you want to modify your
+HTML code without restarting Nageru.
+
+
+Changing the resolution and frame rate
+--------------------------------------
+
+By default, HTML inputs try to run at the CEF maximum of 60 frames per second
+(CEF does not support non-integer frame rates), but if you wish to conserve
+CPU, or if you run at PAL rates, you can ask for a lower maximum frame rate using
+e.g. *html_input:set_max_fps(15)*. Also, you can change the resolution from
+the default (which is to match your output stream's resolution), using
+*html_input:resize(width, height)*.