diff --git a/Scripting.md b/Scripting.md index 464b1a4..910dad7 100644 --- a/Scripting.md +++ b/Scripting.md @@ -101,6 +101,54 @@ The advanced scene switcher offers the following [procedure handlers](https://do ### name The `name` field of calldata object associated with this procedure should specify the id of the action type you want to register. +It will also be the user facing name in the action type selection. + +### default_settings (optional) + +The `name` field of calldata object associated with this procedure should specify the a pointer to an [obs_data_t](https://docs.obsproject.com/reference-settings#data-settings-api-reference-obs-data-t) object. +It should contain the [default values](https://docs.obsproject.com/reference-settings#default-value-functions) for the settings for your custom action type. +The ownership and thus responsibility to free this obs_data_t* pointer will be that of the advanced scene switcher. +Thus you must not free / release this pointer yourself or you risk a crash of OBS. + +This value can be null, if you do not which to provide any default settings. + +### properties_signal_name (optional) + +The `properties_signal_name` field of calldata object associated with this procedure will specify the name of the signal, which will be called by the advanced scene switcher, when it requests a new [obs_properties_t](https://docs.obsproject.com/reference-properties#properties-api-reference-obs-properties-t) object. +These objects are used to determine which settings UI elements should be shown to the user when creating an instance of your custom action type. + +The signal will be registered by the advanced scene switcher. +You only have to connect to it. + +When the signal is called by the advanced scene switcher you will have to pass the pointer to the [obs_properties_t](https://docs.obsproject.com/reference-properties#properties-api-reference-obs-properties-t) object you created via [calldata_set_ptr](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_ptr) in the field named `properties`. + +You can ignore this field, if you do not wish to provide any controls to the user to modify the settings of this action type. + +### trigger_signal_name + +The `trigger_signal_name` field of calldata object associated with this procedure will specify the name of the signal, which will be called by the advanced scene switcher, when your custom action type needs to be executed. + +The signal will be registered by the advanced scene switcher. +You only have to connect to it. + +#### Handling the trigger signal + +In the following section `trigger_signal_name` is just a placeholder for the actual signal name. + +When `trigger_signal_name` is called by the advanced scene switcher, the settings for the instance of this action type will be passed as a pointer to an [obs_data_t](https://docs.obsproject.com/reference-settings#data-settings-api-reference-obs-data-t) object. +You can access it via [calldata_ptr](https://docs.obsproject.com/reference-libobs-callback#c.calldata_ptr) in the `settings` field of calldata object associated with this procedure. + +When `trigger_signal_name` is called by the advanced scene switcher you will have to pass the result of your operation via [calldata_set_bool](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_bool) in the field named `result`. +In case of a macro action this should always be `true` unless a catastrophic error occurred which should abort the whole macro's execution. + +When `trigger_signal_name` is called by the advanced scene switcher it will pass `completion_id` field, which is a unique id for each instance of your custom action being triggered. + +When `trigger_signal_name` is called by the advanced scene switcher it will also pass the name of the signal you will to emit when your action type's operation is done in the `completion_signal_name` field. + +When you emit this completion signal you will also have to pass the `completion_id` value you have received via `trigger_signal_name` using [calldata_set_int](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_int). + +The signal will be registered by the advanced scene switcher. +You only have to emit it. ### Return value @@ -111,7 +159,59 @@ Returns `true`, if the operation was successful, and `false` otherwise. ### name + The `name` field of calldata object associated with this procedure should specify the id of the condition type you want to register. +It will also be the user facing name in the condition type selection. + +### default_settings (optional) + +The `name` field of calldata object associated with this procedure should specify the a pointer to an [obs_data_t](https://docs.obsproject.com/reference-settings#data-settings-api-reference-obs-data-t) object. +It should contain the [default values](https://docs.obsproject.com/reference-settings#default-value-functions) for the settings for your custom condition type. +The ownership and thus responsibility to free this obs_data_t* pointer will be that of the advanced scene switcher. +Thus you must not free / release this pointer yourself or you risk a crash of OBS. + +This value can be null, if you do not which to provide any default settings. + +### properties_signal_name (optional) + +The `properties_signal_name` field of calldata object associated with this procedure will specify the name of the signal, which will be called by the advanced scene switcher, when it requests a new [obs_properties_t](https://docs.obsproject.com/reference-properties#properties-api-reference-obs-properties-t) object. +These objects are used to determine which settings UI elements should be shown to the user when creating an instance of your custom condition type. + +The signal will be registered by the advanced scene switcher. +You only have to connect to it. + +When the signal is called by the advanced scene switcher you will have to pass the pointer to the [obs_properties_t](https://docs.obsproject.com/reference-properties#properties-api-reference-obs-properties-t) object you created via [calldata_set_ptr](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_ptr) in the field named `properties`. + +You can ignore this field, if you do not wish to provide any controls to the user to modify the settings of this condition type. + +### trigger_signal_name + +The `trigger_signal_name` field of calldata object associated with this procedure will specify the name of the signal, which will be called by the advanced scene switcher, when your custom condition check needs to be executed. + +The signal will be registered by the advanced scene switcher. +You only have to connect to it. + +#### Handling the trigger signal + +In the following section `trigger_signal_name` is just a placeholder for the actual signal name. + +When `trigger_signal_name` is called by the advanced scene switcher, the settings for the instance of this condition type will be passed as a pointer to an [obs_data_t](https://docs.obsproject.com/reference-settings#data-settings-api-reference-obs-data-t) object. +You can access it via [calldata_ptr](https://docs.obsproject.com/reference-libobs-callback#c.calldata_ptr) in the `settings` field of calldata object associated with this procedure. + +When `trigger_signal_name` is called by the advanced scene switcher you will have to pass the result of your condition check via [calldata_set_bool](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_bool) in the field named `result`. + +When `trigger_signal_name` is called by the advanced scene switcher it will pass `completion_id` field, which is a unique id for each instance of your custom condition being triggered. + +When `trigger_signal_name` is called by the advanced scene switcher it will also pass the name of the signal you will to emit when your condition type's operation is done in the `completion_signal_name` field. + +When you emit this completion signal you will also have to pass the `completion_id` value you have received via `trigger_signal_name` using [calldata_set_int](https://docs.obsproject.com/reference-libobs-callback#c.calldata_set_int). + +The signal will be registered by the advanced scene switcher. +You only have to emit it. + +### Example +``` +``` ### Return value @@ -123,6 +223,7 @@ Returns `true`, if the operation was successful, and `false` otherwise. ### name The `name` field of calldata object associated with this procedure should specify the id of the action type you want to deregister. +It will also be the user facing name in the condition type selection. ### Return value @@ -141,7 +242,6 @@ def advss_deregister_action(name): success = obs.calldata_bool(data, "success") if success == False: - segment_type = "action" if is_action else "condition" obs.script_log(obs.LOG_WARNING, f'failed to deregister custom action"{name}"') obs.calldata_destroy(data) @@ -170,7 +270,6 @@ def advss_deregister_condition(name): success = obs.calldata_bool(data, "success") if success == False: - segment_type = "action" if is_action else "condition" obs.script_log(obs.LOG_WARNING, f'failed to deregister custom condition "{name}"') obs.calldata_destroy(data)