From 9cd4cfe1a58ab71602451adb0df947a540caec4a Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Fri, 19 Jul 2019 23:48:37 +0200 Subject: [PATCH] Document locking alternatives. --- theme.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/theme.rst b/theme.rst index 7667a60..6fa95fd 100644 --- a/theme.rst +++ b/theme.rst @@ -343,6 +343,51 @@ This allows you to e.g. have simple message overlays that you can change 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 -- 2.39.2