docs/sphinx: Add scripting documentation

docs/sphinx/index.rst

@@ -15,6 +15,7 @@ Welcome to OBS Studio's documentation!
    plugins
    frontends
    graphics
+   scripting
    reference-core
    reference-modules
    reference-core-objects

docs/sphinx/reference-settings.rst

@@ -140,6 +140,8 @@ Set Functions
 ---------------------
 
 
+.. _obs_data_get_funcs:
+
 Get Functions
 -------------
 
@@ -171,6 +173,9 @@ Get Functions
 
 ---------------------
 
+
+.. _obs_data_default_funcs:
+
 Default Value Functions
 -----------------------
 

docs/sphinx/scripting.rst

@@ -0,0 +1,320 @@
+Python/Lua Scripting
+====================
+
+Scripting (21.0+) adds support for Python 3 and Luajit 2 (which is
+roughly equivalent to Lua 5.2), allowing the ability to quickly extend,
+add features, or automate the program without needing to build a native
+plugin module.
+
+Scripting can be accessed in OBS Studio via the Tools menu -> Scripts
+option, which will bring up the scripting dialog.  Scripts can be added,
+removed, and reloaded in real time while the program is running.
+
+**NOTE:** On windows, currently only Python 3.6 is supported.  To use
+Python on windows, you must install Python 3.6 64bit for OBS 64bit
+(64bit is the default for OBS), or Python 3.6 32bit if using OBS 32bit.
+Then, in the scripting dialog, you can manually set the path to your
+Python 3.6 install in the "Python Settings" tab.
+
+All API bindings are provided through the **obspython** module in
+Python, and the **obslua** module in Lua.
+
+Certain functions have been changed/replaced in order to provide script
+callbacks, see :ref:`other_script_differences` for more information.
+
+**WARNING:** Because bindings to the entire API are provided, it is
+possible to leak memory or crash the program with an improperly-written
+script.  Please exercise caution when making scripts and check the
+memory leak counter in your log file to make sure scripts you write
+aren't leaking memory.  **Please treat the API bindings as though you
+were writing a C program:  read the documentation for functions you use,
+and release/destroy objects you reference or create via the API.**
+
+
+Script Function Exports
+-----------------------
+
+There are a number of global functions that scripts can optionally
+provide:
+
+.. py:function:: script_load(settings)
+
+   Called on script startup with specific settings associated with the
+   script.  The *settings* parameter provided is not typically used for
+   settings that are set by the user; instead the parameter is used for
+   any extra internal settings data that may be used in the script.
+
+   :param settings: Settings associated with the script.
+
+.. py:function:: script_unload()
+
+   Called when the script is being unloaded.
+
+.. py:function:: script_save(settings)
+
+   Called when the script is being saved.  This is not necessary for
+   settings that are set by the user; instead this is used for any
+   extra internal settings data that may be used in the script.
+
+   :param settings: Settings associated with the script.
+
+.. py:function:: script_defaults(settings)
+
+   Called to set default settings (if any) associated with the script.
+   You would typically call :ref:`obs_data_default_funcs` for the
+   on the settings in order to set its default values.
+
+   :param settings: Settings associated with the script.
+
+.. py:function:: script_update(settings)
+
+   Called when the script's settings (if any) have been changed by the
+   user.
+
+   :param settings: Settings associated with the script.
+
+.. py:function:: script_properties()
+
+   Called to define user properties associated with the script.  These
+   properties are used to define how to show settings properties to a
+   user.
+
+   :return: obs_properties_t object created via
+            :c:func:`obs_properties_create()`.
+
+.. py:function:: script_tick(seconds)
+
+   Called every frame in case per-frame processing is needed.  If a
+   timer is needed, please use :ref:`scripting_timers` instead, as
+   timers are more efficient if all that's needed is basic timer
+   functionality.  Using this function in Python is not recommended due
+   to the global interpreter lock of Python.
+
+   :param seconds: Seconds passed since previous frame.
+
+
+Getting the Current Script's Path
+---------------------------------
+
+There is a function you can use to get the current script's path.  This
+function is automatically implemented in to each script before the
+script is loaded, and is part of the script's namespace, not
+obslua/obspython:
+
+.. py:function:: script_path()
+
+   :return: The path to the script.
+
+
+.. _scripting_timers:
+
+Script Timers
+-------------
+
+Script timers provide an efficient means of providing timer callbacks
+without necessarily having to lock scripts/interpreters every frame.
+(These functions are part of the obspython/obslua modules/namespaces).
+
+.. py:function:: timer_add(callback, milliseconds)
+
+    Adds an timer callback which triggers every *millseconds*.
+
+.. py:function:: timer_remove(callback)
+
+    Removes a timer callback.  (Note: You can also use
+    :py:func:`remove_current_callback()` to terminate the timer from the
+    timer callback)
+
+
+Script Sources (Lua Only)
+-------------------------
+
+It is possible to register sources in Lua.  To do so, create a table,
+and define its keys the same way you would define an
+:c:type:`obs_source_info` structure:
+
+.. code:: lua
+
+    local info = {}
+    info.id = "my_source_id"
+    info.type = obslua.OBS_SOURCE_TYPE_INPUT
+    info.output_flags = obslua.OBS_SOURCE_VIDEO
+
+    info.get_name = function()
+            return "My Source"
+    end
+
+    info.create = function(source, settings)
+            -- typically source data would be stored as a table
+            local my_source_data = {}
+
+            [...]
+
+            return my_source_data
+    end
+
+    info.video_render = function(my_source_data, effect)
+            [...]
+    end
+
+    info.get_width = function(my_source_data)
+            [...]
+
+            -- assuming the source data contains a 'width' key
+            return my_source_data.width
+    end
+
+    info.get_height = function(my_source_data)
+            [...]
+
+            -- assuming the source data contains a 'height' key
+            return my_source_data.height
+    end
+
+    -- register the source
+    obs_register_source(info)
+
+
+.. _other_script_differences:
+
+Other Differences From the C API
+--------------------------------
+
+Certain functions are implemented differently from the C API due to how
+callbacks work.  (These functions are part of the obspython/obslua
+modules/namespaces).
+
+.. py:function:: obs_enum_sources()
+
+   Enumerates all sources.
+
+   :return: An array of reference-incremented sources.  Release with
+            :py:func:`source_list_release()`.
+
+.. py:function:: obs_scene_enum_items(scene)
+
+   Enumerates scene items within a scene.
+
+   :param scene: obs_scene_t object to enumerate items from.
+   :return:      List of scene items.  Release with
+                 :py:func:`sceneitem_list_release()`.
+
+.. py:function:: obs_add_main_render_callback(callback)
+
+   **Lua only:** Adds a primary output render callback.  This callback
+   has no parameters.
+
+   :param callback: Render callback.  Use
+                    :py:func:`obs_remove_main_render_callback()` or
+                    :py:func:`remove_current_callback()` to remove the
+                    callback.
+
+.. py:function:: obs_remove_main_render_callback(callback)
+
+   **Lua only:** Removes a primary output render callback.
+
+   :param callback: Render callback.
+
+.. py:function:: signal_handler_connect(handler, signal, callback)
+
+   Adds a callback to a specific signal on a signal handler.  This
+   callback has one parameter:  the calldata_t object.
+
+   :param handler:  A signal_handler_t object.
+   :param signal:   The signal on the signal handler (string)
+   :param callback: The callback to connect to the signal.  Use
+                    :py:func:`signal_handler_disconnect()` or
+                    :py:func:`remove_current_callback()` to remove the
+                    callback.
+
+.. py:function:: signal_handler_disconnect(handler, signal, callback)
+
+   Removes a callback from a specific signal of a signal handler.
+
+   :param handler:  A signal_handler_t object.
+   :param signal:   The signal on the signal handler (string)
+   :param callback: The callback to disconnect from the signal.
+
+.. py:function:: signal_handler_connect_global(handler, callback)
+
+   Adds a global callback to a signal handler.  This callback has two
+   parameters:  the first parameter is the signal string, and the second
+   parameter is the calldata_t object.
+
+   :param handler:  A signal_handler_t object.
+   :param callback: The callback to connect.  Use
+                    :py:func:`signal_handler_disconnect_global()` or
+                    :py:func:`remove_current_callback()` to remove the
+                    callback.
+
+.. py:function:: signal_handler_disconnect_global(handler, callback)
+
+   Removes a global callback from a signal handler.
+
+   :param handler:  A signal_handler_t object.
+   :param callback: The callback to disconnect.
+
+.. py:function:: obs_hotkey_register_frontend(name, description, callback)
+
+   Adds a frontend hotkey.  The callback takes one parameter: a boolean
+   'pressed' parameter.
+
+   :param name:        Unique name identifier string of the hotkey.
+   :param description: Hotkey description shown to the user.
+   :param callback:    Callback for the hotkey.  Use
+                       :py:func:`obs_hotkey_unregister()` or
+                       :py:func:`remove_current_callback()` to remove
+                       the callback.
+
+.. py:function:: obs_hotkey_unregister(callback)
+
+   Unregisters the hotkey associated with the specified callback.
+
+   :param callback: Callback of the hotkey to unregister.
+
+.. py:function:: obs_properties_add_button(properties, setting_name, text, callback)
+
+   Adds a button properties to an obs_properties_t object.  The callback
+   takes no parameters.
+
+   :param properties:   An obs_properties_t object.
+   :param setting_name: A setting identifier string.
+   :param text:         Button text.
+   :param callback:     Button callback.  This callback is automatically
+                        cleaned up.
+
+.. py:function:: remove_current_callback()
+
+   Removes the current callback being executed.  Does nothing if not
+   within a callback.
+
+.. py:function:: source_list_release(source_list)
+
+   Releases the references of a source list.
+
+   :param source_list: Array of sources to release.
+
+
+.. py:function:: sceneitem_list_release(item_list)
+
+   Releases the references of a scene item list.
+
+   :param item_list: Array of scene items to release.
+
+.. py:function:: calldata_source(calldata, name)
+
+   Casts a pointer parameter of a calldata_t object to an obs_source_t
+   object.
+
+   :param calldata: A calldata_t object.
+   :param name:     Name of the parameter.
+   :return:         A borrowed reference to an obs_source_t object.
+
+.. py:function:: calldata_sceneitem(calldata, name)
+
+   Casts a pointer parameter of a calldata_t object to an
+   obs_sceneitem_t object.
+
+   :param calldata: A calldata_t object.
+   :param name:     Name of the parameter.
+   :return:         A borrowed reference to an obs_sceneitem_t object.