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()
“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**
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()
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,
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)
-- 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.
channel when asked; it can vary from frame to frame. A typical use is to mark
the currently playing input as red, or the preview as green.
-And finally, there are two entry points related to white balance::
+
+.. _white-balance:
+
+White balance
+.............
+
+Finally, there are two entry points related to white balance. The first one
+is::
Nageru.set_supports_wb(2, true)
- function set_wb(channel, red, green, blue)
If the first function is called with a true value (at the start of the theme),
the channel will get a “Set WB” button next to it, which will activate a color
-picker. When the user picks a color (ostensibly with a gray point), the second
+picker, to select the gray point. To actually *apply* this white balance change,
+you have two options. If you're using Nageru 1.9.2 or newer, it's as simple
+as adding one element to the scene::
+
+ scene:add_white_balance()
+
+The white balance effect will automatically figure out which input it is
+connected to, and fetch its gray point if needed. (If it is connected to
+e.g. a mix of several inputs, such as a camera and an overlay, you will need to
+give the input to fetch white balance from as as a parameter.)
+
+If, on the other hand, you are using Nageru 1.9.1 or older (or just wish
+for more manual control), there's an entry point you will need to implement::
+
+ function set_wb(channel, red, green, blue)
+
+When the user picks a gray point, this function
function will be called (with the RGB values in linear light—not sRGB!),
and the theme can then use it to adjust the white balance for that channel.
The typical way to to this is to have a *WhiteBalanceEffect* on each input
without restarting Nageru.
+.. _locking:
+
+Locking alternatives
+--------------------
+
+In some cases, Nageru may be building in alternatives to a scene that you
+don't really need, resulting in combinatorial explosion. (If the number of
+instances is getting high, you will get a warning when finalizing the scene.)
+For instance, in some cases, you know that a given transition scene will never
+be used for previews, just live. In this case, you can replace the call to
+scene:finalize() with::
+
+ scene:finalize(false)
+
+In this case, you guarantee that the scene will never be returned when
+get_scene() is called with the number 0. (Similarly, you can use true
+to *only* use it for the live channel.)
+
+Similarly, inputs can hold four different input types, but in some scenes,
+you may always use them with a specific one, e.g. an image “bg_img”. In this case,
+you may add the input with a specific type right away::
+
+ scene:add_input(bg_img)
+
+Similarly, for a live input, you can do::
+
+ scene:add_input(0)
+
+You can still use scene:display() to change the input, but it needs to be of
+the same *type* as the one you gave to add_input().
+
+Finally, you can specify that some effects only make sense together, reducing
+the number of possibilities further. For instance, you may have an optional
+crop effect followed by a resample, where the resample is only enabled if the
+crop is. If so, you can do this::
+
+ resample_effect:always_disable_if_disabled(crop_effect)
+
+Also, since Nageru 1.9.1, you can disable an optional effect if a given other
+effect is *enabled*::
+
+ overlay1_effect:promise_to_disable_if_enabled(overlay2_effect)
+ overlay2_effect:promise_to_disable_if_enabled(overlay1_effect)
+
+Note that the latter is a promise from the user, not automatic disabling; since
+it is mostly useful for mutual exclusions, Nageru wouldn't know which of the
+two to disable. (If you violate the promise, you will get an error message at
+runtime.) It can still be useful for reducing the number of alternatives, though.
+
+For more advanced exclusions, you may choose to split up the scenes into several
+distinct ones that you manage yourself; indeed, before Nageru 1.9.0, that was
+the only option. At some point, however, you may choose to simply accept the
+added startup time and a bit of extra RAM cost; ease of use and flexibility often
+trumps such concerns.
+
+
.. _menus:
Theme menus
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
+Menus can contain submenus, by giving an array instead of a function::
+
+ ThemeMenu.set(
+ { "Overlay", {
+ { "Version A", select_overlay_a },
+ { "Version B", select_overlay_b }
+ },
+ { "&Reload overlay", reload_html }
+ )
+
+They can also be checkable, or have checkboxes, by adding a third
+array element containing flags for that::
+
+ ThemeMenu.set(
+ { "Enable overlay", enable_overlay, Nageru.CHECKED }, -- Currently checked.
+ { "Enable crashing", make_unstable, Nageru.CHECKABLE } -- Can be checked, but isn't currently.
+ )
+
+When such an option is selected, you probably want to rebuild the menu to
+reflect the new state.
+
+There currently is no support for input boxes, sliders,
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.
+
+
+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.
projects / nageru-docs / blobdiff