Document the return value of choose() and how it is useful.

[nageru-docs] / theme.rst

diff --git a/theme.rst b/theme.rst
index 3fa5873587a0a665c8ea0061283983eb452fa3f5..7fbe735b1ce6f081947603c1f4c0386b217f1982 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -83,6 +83,7 @@ produces a mix of them; Movit's *MixEffect* is exactly what you want here::
   local input1 = scene:add_input()
   input1:display(1)
 
+  -- Note that add_effect returns its input for convenience.
   local mix_effect = scene:add_effect(MixEffect.new(), input0, input1)
   scene:finalize()
 
@@ -94,9 +95,8 @@ this signature:
 “width” and “height” are what you'd expect (the output resolution).
 t contains the current stream time in seconds. “num” contains 0
 for the live view, 1 for the preview view, and 2, 3, 4, … for each
-of the individual stream previews. “signals“ contains a bit of
-information about each input signal, like its current resolution
-or frame rate.
+of the individual stream previews. “signals” contains a bit of
+information about each input signal (see :ref:`signal-info`).
 
 get_scene in return should return a scene. However, before you do that,
 you can set the parameters **strength_first** and **strength_second**
@@ -147,8 +147,8 @@ scaler before mixing; *ResampleEffect* provides one::
   local input0 = scene:add_input()
   input0:display(0)
   local input0_scaled = scene:add_optional_effect(ResampleEffect.new())  -- Implicitly uses input0.
-  scene_or_input.resample_effect:set_int("width", 1280)  -- Could also be set in get_scene().
-  scene_or_input.resample_effect:set_int("height", 720)
+  input0_scaled:set_int("width", 1280)  -- Could also be set in get_scene().
+  input0_scaled:set_int("height", 720)
   input0_scaled:enable()  -- Enable or disable as needed.
 
   local input1 = scene:add_input()
@@ -175,8 +175,8 @@ directly by the GPU) that instead. The scaling is set up like this::
   local input0 = scene:add_input()
   input0:display(0)
   local input0_scaled = scene:add_effect({ResampleEffect.new(), ResizeEffect.new()})  -- Implicitly uses input0.
-  scene_or_input.resample_effect:set_int("width", 1280)  -- Just like before.
-  scene_or_input.resample_effect:set_int("height", 720)
+  input0_scaled:set_int("width", 1280)  -- Just like before.
+  input0_scaled:set_int("height", 720)
 
   -- Pick one in get_scene() like this:
   input0_scaled:choose(ResizeEffect)
@@ -184,12 +184,28 @@ directly by the GPU) that instead. The scaling is set up like this::
   -- Or by numerical index:
   input0_scaled:choose(1)  -- Chooses ResizeEffect
 
-Note that add_effect returns its input for convenience.
-
 Actually, add_optional_effect() is just a wrapper around add_effect() with
 IdentityEffect as the other alternative, and disable() is a convenience version of
 choose(IdentityEffect).
 
+All alternatives must
+have the same amount of inputs, with an exception for IdentityEffect, which can
+coexist with an effect requiring any amount of inputs (if selected, the IdentityEffect
+just passes its first input unchanged). Similarly, if you set a parameter with
+set_int() or similar, it must be valid for all alternatives (again excepting
+IdentityEffect); if there is one that can only be used on a certain alternative,
+you must set it directly on the effect::
+
+  local resample_effect = ResampleEffect.new()
+  resample_effect:set_float("zoom_x", 1.0001)  -- Not valid for ResizeEffect.
+   
+  local input0_scaled = scene:add_effect({resample_effect, ResizeEffect.new()})
+  input0_scaled:set_int("width", 1280)  -- Set on both alternatives.
+  input0_scaled:set_int("height", 720)
+
+  -- This is also possible, as choose() returns the chosen effect:
+  input0_scaled:choose(ResampleEffect):set_float("zoom_y", 1.0001)
+
 Actually, more versions are created than you'd immediately expect.
 In particular, the output format for the live output and all previews are
 different (Y'CbCr versus RGBA), which is also handled transparently for you.
@@ -448,3 +464,35 @@ 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.
+
+
+.. _signal-info:
+
+Signal information queries
+--------------------------
+
+As previously mentioned, get_scene() takes in a “signals” parameter
+that you can query for information about each signal (numbered from 0;
+live and preview are channels, not signals), like its current resolution
+or frame rate:
+
+  * get_frame_width(signal), get_frame_height(signal): Width and height of the last frame.
+  * get_width(signal), get_height(signal): Width and height of the last *field*
+    (the field height is half of the frame height for an interlaced signal).
+  * get_interlaced(signal): Whether the last frame was interlaced.
+  * get_has_signal(signal): Whether there is a valid input signal.
+  * get_is_connected(signal): Whether there is even a card connected
+    to this signal (USB cards can be swapped in or out); if not,
+    you will get a stream of single-colored frames.
+  * get_frame_rate_nom(signal), get_frame_rate_den(signal): The frame rate
+    of the last frame, as a rational (e.g. 60/1, or 60000/1001 for 59.94).
+  * get_last_subtitle(signal): See :ref:`subtitle-ingest`.
+  * get_human_readable_resolution(signal): The resolution and frame rate in
+    human-readable form (e.g. “1080i59.94”), suitable for e.g. stream titles.
+    Note that Nageru does not follow the EBU recommendation of using
+    frame rate even for interlaced signals (e.g. “1080i25” instead of “1080i50”),
+    since it is little-used and confusing to most users.
+
+You can use this either for display purposes, or for choosing the right
+effect alternatives. In particular, you may want to disable scaling if
+the frame is already of the correct resolution.