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 (CEF for short), a library that basically embeds a full copy of the Chromium web browser into Nageru.
Note that HTML inputs are an optional component, since many distributions don’t carry CEF. Thus, your copy of Nageru may not support them. See 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 video inputs, 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 display HTMLInput or any input in your scene (that you created earlier with scene:add_input()), using code like:
input:display(html_input)
or, as described in Locking alternatives, you can create an input that can only show HTML when you create it:
local scene = Scene.new(16, 9)
local input = scene:add_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 simple menus), 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).