From e71449e4cb2f9192867f410b948ab2d14a952c44 Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Sat, 20 Jul 2019 00:18:06 +0200 Subject: [PATCH] Document signal information queries in get_scene(). --- theme.rst | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/theme.rst b/theme.rst index d43687f..7ce42f0 100644 --- 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** @@ -451,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 `_ 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. -- 2.39.2