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,
-- 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
The number of channels is determined by calling this function
once at the start of the program::
- function num_channels()
+ Nageru.set_num_channels(2)
-It should simply return the number of channels (0 is allowed,
-but doesn't make a lot of sense). Live and preview comes in addition to this.
+0 is allowed, but doesn't make a lot of sense. Live and preview comes in
+addition to this.
-Each channel will have a label on it; Nageru asks the theme
-by calling this function::
+Each channel will have a label on it; you set it by calling::
- function channel_name(channel)
+ Nageru.set_channel_name(2, "Side-by-side")
-Here, channel is 2, 3, 4, etc.—0 is always called “Live” and
-1 is always called “Preview”.
+Here, channel is 2, 3, 4, etc.—by default, 0 is called “Live” and
+1 is called “Preview”, and you probably don't need to change this.
Each channel has its own scene, starting from number 2 for the first one
(since 0 is live and 1 is preview). The simplest form is simply a direct copy
(Below, we will see that there are more types of channels, however.)
Since the mapping between the channel UI element and inputs is so typical,
Nageru allows the theme to simply declare that a channel corresponds to
-a given signal, by asking it::
-
- function channel_signal(channel)
- if channel == 2 then
- return 0
- elseif channel == 3 then
- return 1
- else
- return -1
- end
- end
+a given signal::
+
+ Nageru.set_channel_signal(2, 0)
+ Nageru.set_channel_signal(3, 1)
Here, channels 2 and 3 (the two first ones) correspond directly to inputs
0 and 1, respectively. The others don't, and return -1. The effect on the
UI is that the user can right-click on the channel and configure the input
that way; in fact, this is currently the only way to configure them.
-Furthermore, channels can have a color::
+Furthermore, channels can have a color, which is governed by Nageru calling
+a function your theme::
function channel_color(channel)
And finally, there are two entry points related to white balance::
- function supports_set_wb(channel)
+ Nageru.set_supports_wb(2, true)
function set_wb(channel, red, green, blue)
-If the first function returns true (called once, at the start of the program),
+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
function will be called (with the RGB values in linear light—not sRGB!),
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)
+
+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
projects / nageru-docs / blobdiff