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 add this HTMLInput to a chain (or multiple chains if you'd like),
  35 using code like::
  36
  37   local image = chain:add_html_input(html_input)
  38
  39 Like video inputs, you can call *get_signal_num()* on the HTML input to get
  40 its signal number, for getting its resolution etc. (see below for changing
  41 it). Also like video inputs, there is no audio support (although you may find audio
  42 played by the web page coming out your regular speakers, not controlled by
  43 Nageru!). This may change in the future.
  44
  45
  46 Controlling HTML inputs
  47 -----------------------
  48
  49 Generally, HTML inputs run in a background thread and deliver frames
  50 asynchronously to Nageru. Due to the way CEF works, there is unfortunately no
  51 obvious way of getting frame-perfect sync between graphics and overlay
  52 (there can always be a frame or two of lag between the two);
  53 however, this is normal even in a hardware chain, and most overlay graphics
  54 does not need to be timed to the input more than through a few frames.
  55
  56 This, and the fact that the theme can not present a very detailed UI
  57 (short of :ref:`simple menus <menus>`), means that it can be hard to
  58 exert detailed control over the graphics using Nageru alone—you will
  59 probably want to have the theme contact some non-Nageru backend (possibly over
  60 WebSockets) from where it can take detailed instructions.
  61
  62 However, the theme *can* ask the HTML input to run arbitrary JavaScript,
  63 by calling *html_input:execute_javascript_async("your code here")*, which allows
  64 you to bring at least some loose coupling between the two. (The “async”
  65 part is to emphasize that you cannot necessarily expect the effects of
  66 the code to be visible on the same frame as you start them. The JavaScript
  67 still runs on the regular UI thread, so if you want to run longer jobs,
  68 you should use a web worker or similar.) There is currently no way to run
  69 Lua code from JavaScript, though.
  70
  71 Finally, you can change the URL by using *html_input:set_url("new_url")*,
  72 or reload the current one using *html_input:reload()*. It can be especially
  73 useful to bind the latter to a menu entry, in case you want to modify your
  74 HTML code without restarting Nageru.
  75
  76
  77 Changing the resolution and frame rate
  78 --------------------------------------
  79
  80 By default, HTML inputs try to run at the CEF maximum of 60 frames per second
  81 (CEF does not support non-integer frame rates), but if you wish to conserve
  82 CPU, or if you run at PAL rates, you can ask for a lower maximum frame rate using
  83 e.g. *html_input:set_max_fps(15)*. Also, you can change the resolution from
  84 the default (which is to match your output stream's resolution), using
  85 *html_input:resize(width, height)*.