From e03768ddc5cf0975e3c363a7e2d937ba11fb962f Mon Sep 17 00:00:00 2001 From: Dale Glass Date: Sun, 12 Nov 2023 13:39:37 +0100 Subject: [PATCH] Document PluginManager --- libraries/plugins/src/plugins/PluginManager.h | 173 +++++++++++++++++- 1 file changed, 171 insertions(+), 2 deletions(-) diff --git a/libraries/plugins/src/plugins/PluginManager.h b/libraries/plugins/src/plugins/PluginManager.h index 26c98ce5db..c5ff80774c 100644 --- a/libraries/plugins/src/plugins/PluginManager.h +++ b/libraries/plugins/src/plugins/PluginManager.h @@ -18,6 +18,22 @@ class QPluginLoader; using PluginManagerPointer = QSharedPointer; +/** + * @brief Manages loadable plugins + * + * The current implementation does initialization only once, as soon as it's needed. + * Once things are initialized the configuration is made permanent. + * + * Both loadable and statically modules are supported. Static modules have to be provided + * with setDisplayPluginProvider, setInputPluginProvider and setCodecPluginProvider. + * + * @warning Users of the PluginManager must take care to do any configuration very early + * on, because changes become impossible once initialization is done. Plugins can't be + * added or removed once that happens. + * + * Initialization is performed in the getDisplayPlugins, getInputPlugins and getCodecPlugins + * functions. + */ class PluginManager : public QObject, public Dependency { SINGLETON_DEPENDENCY Q_OBJECT @@ -25,33 +41,186 @@ class PluginManager : public QObject, public Dependency { public: static PluginManagerPointer getInstance(); + /** + * @brief Get the list of display plugins + * + * @note Calling this function will perform initialization and + * connects events to all the known the plugins on the first call. + * + * @return const DisplayPluginList& + */ const DisplayPluginList& getDisplayPlugins(); + + /** + * @brief Get the list of input plugins + * + * @note Calling this function will perform initialization and + * connects events to all the known the plugins on the first call. + * + * @return const InputPluginList& + */ const InputPluginList& getInputPlugins(); + + /** + * @brief Get the list of audio codec plugins + * + * @note Calling this function will perform initialization and + * connects events to all the known the plugins on the first call. + * + * @return const CodecPluginList& + */ const CodecPluginList& getCodecPlugins(); + + /** + * @brief Get the pointer to the Steam client plugin + * + * This may return a null pointer if Steam support isn't built in. + * + * @return const SteamClientPluginPointer + */ const SteamClientPluginPointer getSteamClientPlugin(); + + /** + * @brief Get the pointer to the Oculus Platform Plugin + * + * This may return a null pointer if Oculus support isn't built in. + * + * @return const OculusPlatformPluginPointer + */ const OculusPlatformPluginPointer getOculusPlatformPlugin(); + /** + * @brief Returns the list of preferred display plugins + * + * The preferred display plugins are set by setPreferredDisplayPlugins. + * + * @return DisplayPluginList + */ DisplayPluginList getPreferredDisplayPlugins(); + + /** + * @brief Sets the list of preferred display plugins + * + * @note This must be called early, before any call to getPreferredDisplayPlugins. + * + * @param displays + */ void setPreferredDisplayPlugins(const QStringList& displays); + /** + * @brief Disable a display plugin. + * + * This removes the plugin from the plugins list. + * The plugin is not deinitialized, and events are not disconnected. + * @param name + */ void disableDisplayPlugin(const QString& name); + + /** + * @brief Disable a list of displays + * + * This adds the display to a list of displays not to be used. + * + * @param displays + */ void disableDisplays(const QStringList& displays); + + /** + * @brief Disable a list of inputs + * + * This adds the input to a list of inputs not to be used. + * @param inputs + */ void disableInputs(const QStringList& inputs); + + /** + * @brief Save the settings + * + */ void saveSettings(); + + /** + * @brief Set the container for plugins + * + * This will be passed to all active plugins on initialization. + * + * @param container + */ void setContainer(PluginContainer* container) { _container = container; } int instantiate(); void shutdown(); - // Application that have statically linked plugins can expose them to the plugin manager with these function + + /** + * @brief Provide a list of statically linked plugins. + * + * This is used to provide a list of statically linked plugins to the plugin manager. + * + * @note This must be called very early on, and only works once. Once the plugin manager + * builds its internal list of plugins, the final list becomes set in stone. + * + * @param provider A std::function that returns a list of display plugins + */ void setDisplayPluginProvider(const DisplayPluginProvider& provider); + + /** + * @brief Provide a list of statically linked plugins. + * + * This is used to provide a list of statically linked plugins to the plugin manager. + * + * @note This must be called very early on, and only works once. Once the plugin manager + * builds its internal list of plugins, the final list becomes set in stone. + * + * @param provider A std::function that returns a list of input plugins + */ void setInputPluginProvider(const InputPluginProvider& provider); + + /** + * @brief Provide a list of statically linked plugins. + * + * This is used to provide a list of statically linked plugins to the plugin manager. + * + * @note This must be called very early on, and only works once. Once the plugin manager + * builds its internal list of plugins, the final list becomes set in stone. + * + * @param provider A std::function that returns a list of codec plugins + */ void setCodecPluginProvider(const CodecPluginProvider& provider); + + /** + * @brief Set the input plugin persister + * + * @param persister A std::function that saves input plugin settings + */ void setInputPluginSettingsPersister(const InputPluginSettingsPersister& persister); + + /** + * @brief Get the list of running input devices + * + * @return QStringList List of input devices in running state + */ QStringList getRunningInputDeviceNames() const; using PluginFilter = std::function; + + /** + * @brief Set the plugin filter that determines whether a plugin will be used or not + * + * @note This must be called very early on. Once the plugin manager + * builds its internal list of plugins, the final list becomes set in stone. + * + * As of writing, this is used in the audio mixer. + * + * @param pluginFilter + */ void setPluginFilter(PluginFilter pluginFilter) { _pluginFilter = pluginFilter; } + + /** + * @brief Get a list of all the display plugins + * + * @return DisplayPluginList List of display plugins + */ Q_INVOKABLE DisplayPluginList getAllDisplayPlugins(); bool getEnableOculusPluginSetting() { return _enableOculusPluginSetting.get(); } @@ -59,7 +228,7 @@ public: signals: void inputDeviceRunningChanged(const QString& pluginName, bool isRunning, const QStringList& runningDevices); - + private: PluginManager() = default;