Bump version to 1.8.2.

[nageru-docs] / theme.rst
diff --git a/theme.rst b/theme.rst

index 162d86234dd29afbc9603461746cdece1162a94e..04146e8fce0003e701d66566419fb4ec869bf65d 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -30,7 +30,7 @@ is a library for high-quality, high-performance video filters,
  and Nageru's themes can use a simplified version of Movit's API where
  most of the low-level details are abstracted away.
  
  and Nageru's themes can use a simplified version of Movit's API where
  most of the low-level details are abstracted away.
  
-Every frame, the theme choses a chain and a set of parameters to it,
+Every frame, the theme chooses a chain and a set of parameters to it,
  based on what it thinks the picture should look like. Every chain
  consists of a set of *inputs* (which can be either live video streams
  or static pictures) and then a set of operators or *effects* to combine
  based on what it thinks the picture should look like. Every chain
  consists of a set of *inputs* (which can be either live video streams
  or static pictures) and then a set of operators or *effects* to combine
@@ -55,7 +55,7 @@ the screen, and in this case, that would be the input)::
  
  Note the “hq” parameter. Every chain needs to be able to run in two
  situations: Both for the stream output (the ”live” pane) and for the preview
  
  Note the “hq” parameter. Every chain needs to be able to run in two
  situations: Both for the stream output (the ”live” pane) and for the preview
-displays (the big “preview” pane and the smaller ones). The details have
+displays (the big “preview” pane and the :ref:`channels <channels>`). The details have
  to do with Nageru internals (high-quality chains need to have an additional
  Y'CbCr output), but the distinction is also useful for themes. In particular,
  some operations, like scaling, can be done in various quality levels,
  to do with Nageru internals (high-quality chains need to have an additional
  Y'CbCr output), but the distinction is also useful for themes. In particular,
  some operations, like scaling, can be done in various quality levels,
@@ -67,6 +67,7 @@ and then scaled down for the GUI. Preview chains are rendered in exactly
  the resolution required, although of course, intermediate steps could be
  bigger.
  
  the resolution required, although of course, intermediate steps could be
  bigger.
  
+
  Setting parameters, and the get_chain entry point
  -------------------------------------------------
  
  Setting parameters, and the get_chain entry point
  -------------------------------------------------
  
@@ -228,6 +229,8 @@ the transition is over and changes back to showing only one input
  (presumably the new one).
  
  
  (presumably the new one).
  
  
+.. _channels:
+
  Channels
  --------
  
  Channels
  --------
  
@@ -317,6 +320,8 @@ Transitions involving scenes tend to be the most complicated parts of the theme
  logic, but also make for the most distinct parts of your visual look.
  
  
  logic, but also make for the most distinct parts of your visual look.
  
  
+.. _images:
+
  Image inputs
  ------------
  
  Image inputs
  ------------
  
@@ -340,3 +345,42 @@ so if you update the file on-disk, it will be available in Nageru without
  a restart. (If the file contains an error, the update will be ignored.)
  This allows you to e.g. have simple message overlays that you can change
  without restarting Nageru.
  a restart. (If the file contains an error, the update will be ignored.)
  This allows you to e.g. have simple message overlays that you can change
  without restarting Nageru.
+
+
+.. _menus:
+
+Theme menus
+-----------
+
+Complicated themes, especially those dealing with :doc:`HTML inputs <html>`,
+may have needs for user control that go beyond those of transition buttons.
+(An obvious example may be “reload the HTML file”.) For this reason,
+themes can also set simple *theme menus*, which are always visible
+no matter what inputs are chosen.
+
+If a theme chooses to set a theme menu, it will be available on the
+main menu bar under “Theme”; if not, it will be hidden. You can set
+the menu at startup or at any other point, using a simple series of
+labels and function references::
+
+  function modify_aspect()
+    -- Your code goes here.
+  end
+
+  function reload_html()
+    html_input:reload()
+  end
+
+  ThemeMenu.set(
+    { "Change &aspect", modify_aspect },
+    { "&Reload overlay", reload_html }
+  )
+
+When the user chooses a menu entry, the given Lua function will
+automatically be called. There are no arguments nor return values.
+
+There currently is no support for checkboxes, submenus, input boxes
+or the likes. However, do note that since the theme is written in unrestricted
+Lua, so you can use e.g. `lua-http <https://github.com/daurnimator/lua-http>`_
+to listen for external connections and accept more complicated inputs
+from those.