1 /* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef API_CORE_PLUGIN_IPLUGIN_H 17 #define API_CORE_PLUGIN_IPLUGIN_H 18 19 #include <base/containers/array_view.h> 20 #include <base/namespace.h> 21 #include <base/util/uid.h> 22 #include <core/namespace.h> 23 24 CORE_BEGIN_NAMESPACE() 25 class IEngine; 26 class IComponentManager; 27 class ISystem; 28 class IEcs; 29 class IInterface; 30 class IClassFactory; 31 class IClassRegister; 32 class IPluginRegister; 33 34 /** \addtogroup group_plugin_iplugin 35 * @{ 36 */ 37 /** Plugin version */ 38 struct Version { 39 /** UID for identifying different versions of the plugin. */ 40 const BASE_NS::Uid uid; 41 /** Function returning a free form version string. */ 42 const char* (*GetVersionString)() { nullptr }; 43 }; 44 45 /** Type information. Base for different registrable information structures. */ 46 struct ITypeInfo { 47 BASE_NS::Uid typeUid; 48 }; 49 50 /** Information needed from the plugin for managing ComponentManagers. */ 51 struct ComponentManagerTypeInfo : public ITypeInfo { 52 /** TypeInfo UID for component manager. */ 53 static constexpr BASE_NS::Uid UID { "f812e951-c860-4208-99e0-66b45841bb58" }; 54 55 using CreateComponentManagerFn = IComponentManager* (*)(IEcs&); 56 using DestroyComponentManagerFn = void (*)(IComponentManager* instance); 57 58 /** Unique ID of the component manager. */ 59 const BASE_NS::Uid uid; 60 /** Name used during component manager creation to identify the type of the component manager. */ 61 const char* const typeName { "" }; 62 /** Pointer to function which is used to create component manager instances. */ 63 const CreateComponentManagerFn createManager; 64 /** Pointer to function which is used to destroy component manager instances. */ 65 const DestroyComponentManagerFn destroyManager; 66 }; 67 68 /** Information needed from the plugin for managing Systems. */ 69 struct SystemTypeInfo : public ITypeInfo { 70 /** TypeInfo UID for system. */ 71 static constexpr BASE_NS::Uid UID { "c476a794-9c77-4a3a-a5e4-eb2399899d37" }; 72 73 using CreateSystemFn = ISystem* (*)(IEcs&); 74 using DestroySystemFn = void (*)(ISystem* instance); 75 76 /** Unique ID of the system. */ 77 const BASE_NS::Uid uid; 78 /** Name used during system creation to identify the type of the system. */ 79 const char* const typeName { "" }; 80 /** Pointer to function which is used to create system instances. */ 81 const CreateSystemFn createSystem; 82 /** Pointer to function which is used to destroy system instances. */ 83 const DestroySystemFn destroySystem; 84 /** List of component managers the system might modify during ISystem::Update. Combined with 85 * readOnlyComponentDependencies they form a list of component managers to be created before creating this system. 86 * These can be also used to determine which systems can be executed in parallel. Default constructed UID can be 87 * used as wild card to indicate dependencies not known at compile time. */ 88 const BASE_NS::array_view<const BASE_NS::Uid> componentDependencies; 89 /** List of component managers the system would only read during ISystem::Update. Combined with 90 * componentDependencies they form a list of component managers to be created before creating this system. 91 * These can be also used to determine which systems can be executed in parallel. Default constructed UID can be 92 * used as wild card to indicate dependencies not known at compile time. */ 93 const BASE_NS::array_view<const BASE_NS::Uid> readOnlyComponentDependencies; 94 95 /** Optional UID of a system which should complete its ISystem::Update before this system starts ISystem::Update. */ 96 const BASE_NS::Uid afterSystem; 97 /** Optional UID of a system which should start its ISystem::Update only after this system has completed 98 * ISystem::Update. */ 99 const BASE_NS::Uid beforeSystem; 100 }; 101 102 // Plugin token is a plugin defined token to identify instance. 103 // Think of this as an instance to the factory that provides the get/create interface method. 104 using PluginToken = void*; 105 106 /** Information needed from the plugin for managing Interfaces. */ 107 struct InterfaceTypeInfo { 108 using CreateInstanceFn = IInterface* (*)(IClassFactory&, PluginToken); 109 using GetInstanceFn = IInterface* (*)(IClassRegister&, PluginToken); 110 111 /* Token created by the plugin. (plugin specific instance data for the interface factory) */ 112 const PluginToken token; 113 /** Unique ID of the interface implementation. */ 114 const BASE_NS::Uid uid; 115 /** Name used during system creation to identify the type of the interface. */ 116 const char* const typeName { "" }; 117 /** Pointer to function which is used to create interface instances bound to IClassFactory instance. 118 * It is acceptable to return same pointer, but with a added reference count. 119 */ 120 const CreateInstanceFn createInterface; 121 /** Pointer to function which is used to get singleton interface instances bound to IClassRegister instance. 122 * It is acceptable to return same pointer, but with a added reference count. 123 */ 124 const GetInstanceFn getInterface; 125 }; 126 127 /** Exported information from a plugin (.so/.dll). */ 128 struct IPlugin : public ITypeInfo { 129 /** TypeInfo UID for a plugin. */ 130 static constexpr BASE_NS::Uid UID { "5fc9b017-5b13-4612-81c2-5a6d6fc3d897" }; 131 132 /* 133 Plugin lifecycle. 134 1. registerInterfaces, once during IPluginRegister::LoadPlugins 135 (First call to plugin is here, initialize "global" resources/data/state here.) 136 2. IEnginePlugin::createPlugin, IEcsPlugin::createPlugin etc., multiple times. 137 (during e.g. engine and ESC initialization) 138 3. IEnginePlugin::destroyPlugin, IEcsPlugin::destroyPlugin etc., multiple times. 139 (during e.g. engine and ESC destruction) 140 4. unregisterInterfaces, once during IPluginRegister::UnloadPlugins 141 (Last call to plugin is here, uninitialize "global" resources/data/state here.) 142 */ 143 144 using RegisterInterfacesFn = PluginToken (*)(IPluginRegister&); 145 using UnregisterInterfacesFn = void (*)(PluginToken); 146 147 /** Name of this plugin. */ 148 const char* const name { "" }; 149 /** Version information of the plugin. */ 150 const Version version; 151 152 /** Called when attaching plugin to plugin registry. 153 * Is expected to register its own named interfaces (IInterface) which are globally available and also register to 154 * different plugin categories e.g. IEnginePlugin and IEcsPlugin when there's a dependency to a specific instance. 155 * Think of this as "CreateInterfaceFactory" 156 */ 157 const RegisterInterfacesFn registerInterfaces { nullptr }; 158 159 /** Called when detaching plugin from plugin registry. 160 * Is expected to unregister its own named interfaces (IInterface) from the global registry and also unregister 161 * different plugin categories e.g. IEnginePlugin and IEcsPlugin when there's a dependency to a specific instance. 162 */ 163 const UnregisterInterfacesFn unregisterInterfaces { nullptr }; 164 165 /** List of plugins this plugin requires. */ 166 const BASE_NS::array_view<const BASE_NS::Uid> pluginDependencies; 167 }; 168 169 /** A plugin which adds new interfaces to the engine. */ 170 struct IEnginePlugin : public ITypeInfo { 171 /** TypeInfo UID for engine plugin. */ 172 static constexpr BASE_NS::Uid UID { "a81c121b-160c-467e-8bd6-63902da85c6b" }; 173 174 /* 175 Plugin lifecycle. 176 1. createPlugin (*as many times as engines instantiated) (initialize IEngine specific state here.) 177 2. destroyPlugin (*as many times as engines instantiated) (deinitialize IEngine specific state here.) 178 */ 179 180 using CreatePluginFn = PluginToken (*)(IEngine&); 181 using DestroyPluginFn = void (*)(PluginToken); 182 IEnginePluginIEnginePlugin183 constexpr IEnginePlugin(CreatePluginFn create, DestroyPluginFn destroy) 184 : ITypeInfo { UID }, createPlugin { create }, destroyPlugin { destroy } 185 {} 186 187 /** Initialize function for engine plugin. 188 * Called when plugin is initially loaded by engine. Used to register paths etc. 189 * Is expected to register its own named interfaces (IInterface) which are tied to the engine instance. 190 * Called when attaching to engine. 191 */ 192 const CreatePluginFn createPlugin { nullptr }; 193 194 /** Deinitialize function for engine plugin. 195 * Called when plugin is about to be unloaded by engine. 196 * Called when detaching from engine. 197 */ 198 const DestroyPluginFn destroyPlugin { nullptr }; 199 }; 200 201 /** A plugin which adds new component managers and systems to the ECS. */ 202 struct IEcsPlugin : public ITypeInfo { 203 /** TypeInfo UID for ECS plugin. */ 204 static constexpr BASE_NS::Uid UID { "b4843032-e144-4757-a28c-03c119c3a10c" }; 205 206 using CreatePluginFn = PluginToken (*)(IEcs&); 207 using DestroyPluginFn = void (*)(PluginToken); 208 IEcsPluginIEcsPlugin209 constexpr IEcsPlugin(CreatePluginFn create, DestroyPluginFn destroy) 210 : ITypeInfo { UID }, createPlugin { create }, destroyPlugin { destroy } 211 {} 212 213 /** Initialize function for ECS plugin. 214 * Called when attaching to ECS. 215 */ 216 const CreatePluginFn createPlugin { nullptr }; 217 218 /** Deinitialize function for ECS plugin. 219 * Called when detaching from ECS. 220 */ 221 const DestroyPluginFn destroyPlugin { nullptr }; 222 }; 223 224 /** @} */ 225 CORE_END_NAMESPACE() 226 227 #endif // API_CORE_PLUGIN_IPLUGIN_H 228