Document signal information queries in get_scene().

[nageru-docs] / theme.rst

diff --git a/theme.rst b/theme.rst
index 6fa95fdd1b23a926c11833119b1131bebe9a79bd..7ce42f07dd9e2b54bfb30fc466baca1156c99ae1 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -94,9 +94,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**
@@ -155,6 +154,8 @@ scaler before mixing; *ResampleEffect* provides one::
   input1:display(1)
   local input1_scaled = ... -- Similarly here and the rest.
 
+  input1_scaled:enable_if(some_variable)  -- Convenience form for enable() or disable() depending on some_variable.
+
   -- The rest is unchanged.
 
 Clearly, there are four options here; both inputs could be unscaled,
@@ -182,7 +183,10 @@ 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.
+Note that add_effect returns its input for convenience. 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).
 
 Actually, add_optional_effect() is just a wrapper around add_effect() with
 IdentityEffect as the other alternative, and disable() is a convenience version of
@@ -446,3 +450,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.