Document overriding the status line, from Nageru 1.9.1.

[nageru-docs] / theme.rst

diff --git a/theme.rst b/theme.rst
index 7ce42f07dd9e2b54bfb30fc466baca1156c99ae1..2e8b6663b0ccddd05fe1314502ff9c5d2cf040f5 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()
 
@@ -146,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()
@@ -174,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)
@@ -183,15 +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. 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
 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.
@@ -482,3 +496,22 @@ or frame rate:
 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.
+
+
+Overriding the status line
+--------------------------
+
+Some users may wish to override the status line, e.g. with recording time.
+If so, it is possible (since Nageru 1.9.1) to declare a function **format_status_line**::
+
+  function format_status_line(disk_space_text, file_length_seconds)
+    if file_length_seconds > 86400.0 then
+      return "Time to make a new segment"
+    else
+      return "Disk space left: " .. disk_space_text
+    end
+  end
+
+As demonstrated, it is given the disk space text (that would normally
+be there), and the length of the current recording file in seconds.
+HTML is supported.