obsproject
docs: Clarify obs_source_update can accept NULL for settings argument
Description
This PR adds the parameter description of the API obs_source_update.
Also fixed a gramatical error; will be not be called --> will not be called.
Motivation and Context
In the implementation, settings can be NULL and it will be just ignored if it is NULL.
https://github.com/obsproject/obs-studio/blob/15e9242acb8cbbd5ccdcdc9e80fa1e96a22bd1b8/libobs/obs-source.c#L990-L992
Passing NULL as the settings argument is useful to trigger update callback.
I realized AJA source calls obs_source_update with the existing settings. This is redundant, we can just pass NULL.
https://github.com/obsproject/obs-studio/blob/master/plugins/aja/aja-source.cpp#L327
How Has This Been Tested?
OS: Fedora 39
Called obs_source_update with the NULL argument and confirmed the settings was not changed.
Types of changes
- Documentation (a change to documentation pages)
Checklist:
- [x] My code has been run through clang-format.
- [x] I have read the contributing document.
- [x] My code is not on the master branch.
- [x] The code has been tested.
- [x] All commit messages are properly formatted and commits squashed where appropriate.
- [x] I have included updates to all appropriate documentation.
Sidenote:
When passing a valid obs_data_t object, elements that exists in the current settings but does not exist in the passed object are not removed.
This is because obs_source_update traverse each element in the given obs_data_t object and apply it to the current settings.
It would be good for the document to describe this behavior. However, I don't have a good idea to phrase this in concise sentence.
I would argue that if you’re calling this with NULL, you’re probably doing something in unintended ways. Personally I hate that it’s even possible to update source settings without calling obs_source_update (e.g. by directly changing the settings returned via obs_source_settings).
We have already had a usage in the image slideshow, which is recently added by Lain.
https://github.com/obsproject/obs-studio/blob/15e9242acb8cbbd5ccdcdc9e80fa1e96a22bd1b8/plugins/image-source/obs-slideshow-mk2.c#L843