git.sesse.net Git - nageru-docs/blob - html.rst

   1 HTML inputs
   2 ===========
   3
   4 HTML inputs are used for on-the-fly generated graphics, ie. typically animated
   5 overlay graphics that cannot be simple still pictures. They allow you to write graphics
   6 in full HTML5 (including JavaScript) by way of `Chromium Embedded Framework
   7 <https://bitbucket.org/chromiumembedded/cef/>`_ (CEF for short), a library that
   8 basically embeds a full copy of the Chromium web browser into Nageru.
   9
  10 HTML inputs are available from Nageru 1.7.0 onwards, but note that they are an
  11 optional component, since many distributions don't carry CEF. Thus, your copy
  12 of Nageru may not support them. See :ref:`compiling` for information on how to
  13 build Nageru with CEF.
  14
  15 Due to CEF performance issues, Nageru does not currently run CEF with GPU
  16 rendering enabled, even though the rest of Nageru is very much centered around
  17 the GPU. In particular, this means you do not currently have WebGL support.
  18
  19
  20 Basic HTML inputs
  21 -----------------
  22
  23 In many ways, HTML inputs are similar to :doc:`video inputs <video>`, so you should
  24 probably understand how they work first. An HTML input is created by way of instantiating
  25 the *HTMLInput* class::
  26
  27   local html_input = HTMLInput.new("file:///path/to/graphics/foo.html")
  28
  29 Any regular URL is acceptable, and the sandbox is turned off for convenience,
  30 so that you can load remote resources from local files. (If you wish to locate
  31 your HTML path by way of the theme, the variable Nageru.THEME_PATH could prove
  32 useful, as it contains the absolute path to the theme in current use.)
  33
  34 You can then display HTMLInput or any input in your scene (that you created
  35 earlier with scene:add_input()), using code like::
  36
  37   input:display(html_input)
  38
  39 or, as described in :ref:`locking`, you can create an input that can *only*
  40 show HTML when you create it::
  41
  42   local scene = Scene.new(16, 9)
  43   local input = scene:add_input(html_input)
  44
  45 Like video inputs, you can call *get_signal_num()* on the HTML input to get
  46 its signal number, for getting its resolution etc. (see below for changing
  47 it). Also like video inputs, there is no audio support (although you may find audio
  48 played by the web page coming out your regular speakers, not controlled by
  49 Nageru!). This may change in the future.
  50
  51
  52 Controlling HTML inputs
  53 -----------------------
  54
  55 Generally, HTML inputs run in a background thread and deliver frames
  56 asynchronously to Nageru. Due to the way CEF works, there is unfortunately no
  57 obvious way of getting frame-perfect sync between graphics and overlay
  58 (there can always be a frame or two of lag between the two);
  59 however, this is normal even in a hardware chain, and most overlay graphics
  60 does not need to be timed to the input more than through a few frames.
  61
  62 This, and the fact that the theme can not present a very detailed UI
  63 (short of :ref:`simple menus <menus>`), means that it can be hard to
  64 exert detailed control over the graphics using Nageru alone—you will
  65 probably want to have the theme contact some non-Nageru backend (possibly over
  66 WebSockets) from where it can take detailed instructions.
  67
  68 However, the theme *can* ask the HTML input to run arbitrary JavaScript,
  69 by calling *html_input:execute_javascript_async("your code here")*, which allows
  70 you to bring at least some loose coupling between the two. (The “async”
  71 part is to emphasize that you cannot necessarily expect the effects of
  72 the code to be visible on the same frame as you start them. The JavaScript
  73 still runs on the regular UI thread, so if you want to run longer jobs,
  74 you should use a web worker or similar.) There is currently no way to run
  75 Lua code from JavaScript, though.
  76
  77 Finally, you can change the URL by using *html_input:set_url("new_url")*,
  78 or reload the current one using *html_input:reload()*. It can be especially
  79 useful to bind the latter to a menu entry, in case you want to modify your
  80 HTML code without restarting Nageru.
  81
  82
  83 Changing the resolution and frame rate
  84 --------------------------------------
  85
  86 By default, HTML inputs try to run at the CEF maximum of 60 frames per second
  87 (CEF does not support non-integer frame rates), but if you wish to conserve
  88 CPU, or if you run at PAL rates, you can ask for a lower maximum frame rate using
  89 e.g. *html_input:set_max_fps(15)*. Also, you can change the resolution from
  90 the default (which is to match your output stream's resolution), using
  91 *html_input:resize(width, height)*.