Version
Wwise SDK 2021.1.8
|
PluginInfoGenerator.h
Go to the documentation of this file.
29 * \brief Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in a class.
42 * \brief The specific version for native plug-in interfaces. Must be identical down to the build number.
43 * \warning Private API. Using this makes the plug-in compatible with this Authoring's build version only.
45 #define AK_WWISESDK_VERSION_NATIVE_COMBINED ((AK_WWISESDK_VERSION_MAJOR << 19) | (AK_WWISESDK_VERSION_MINOR << 16) | AK_WWISESDK_VERSION_SUBMINOR)
49 using InterfaceType = decltype(BaseInterface::m_interface); ///< PluginInfoGenerator: Type for the m_interface value in BaseInterface
50 using InterfaceTypeValue = std::underlying_type<InterfaceType>::type; ///< PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface
51 using InterfaceVersion = decltype(BaseInterface::m_version); ///< PluginInfoGenerator: Type for the m_version value in BaseInterface
56 * When the host calls the Instantiate of the plug-in, PluginInfoGenerator will automatically set this thread
57 * variable to the provided \c in_pluginInfo. This allows the interfaces to bind themselves without having
72 * \brief PluginInfoGenerator: For each plug-in interface type, provides a single static instance used throughout this plug-in container.
74 * This uses a C++ template principle where you can define a static variable inside a templated class, and you
77 * Also, having a class outer shell means the static member can reside in a header and be instantiated in that same
90 static GluedInterface* g_cinterface; ///< The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host once loaded.
92 template<typename CInterface> CInterface* CBaseInterfaceGlue<CInterface>::g_cinterface = nullptr;
95 * \brief PluginInfoGenerator: Associates an existing C Interface with a variable that can be used. Derives from the instance that uses it.
98 * \tparam CInstance The C Instance that will be instantiated. Automatically derived from the CInterface::Instance typedef.
111 * \brief PluginInfoGenerator: Base class for every C++ instance that retrieves a service from the Wwise Authoring host.
113 * Compared to C, where the interface contains all the functions and the instance is an opaque block, the C++
114 * version is the opposite; the instance is a class containing all the methods, and the interface is hidden as
117 * The HostInterfaceGlue helper class provides that distinction. Depending on the in_baseInstance parameter,
138 template<typename CPPInstance, bool in_baseInstance> typename CPPInstance::GluedInterface HostInterfaceGlue<CPPInstance, in_baseInstance>::g_cppinterface;
151 HostInterfaceGlue(CInstance* in_instance) : m_instance(static_cast<CPPInstance*>(in_instance)) {}
158 * \ref PluginInfoTLS<>::tls_pluginInfo is used to retrieve the plug-in we are trying to instantiate.
167 if (intf.m_interface->m_interface == static_cast<InterfaceType>(HostInterfaceGlue::k_interfaceType) &&
181 * Used so we can ask a KnownInterfaceClass<in_interface, in_version> and receive which class and interface it points to.
207 template<> struct KnownInterfaceClass<(AK::Wwise::Plugin::InterfaceType)in_name::k_interfaceType, in_name::k_interfaceVersion> \
215 * \brief PluginInfoGenerator: Requests a host-provided service, and optionally receives a variable containing the default instance.
226 * \brief PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name, and creates a variable instance named m_ followed by in_varname.
231 * \param in_varname Name of the variable to instantiate. Will be prefixed by m_. A second static variable is created with g_ prefix, containing the C++ interface.
251 * \brief PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name.
256 * \param in_varname Name of the static variable to be created with g_ prefix, containing the C++ interface.
275 * \brief PluginInfoGenerator: Defines a compile-time dictionary with the latest version known to the SDK for each interface.
289 * \brief PluginInfoGenerator: Creates a C++ link to the latest version known to the SDK for each interface.
318 * Retrieves the list of plug-in interfaces required by a plug-in through derivation, and automatically creates a
321 * Compared to a manually generated C version, the generated structure is done through a function that fills all
322 * the required data. Since it's a static global function called only once, and contains only value stores, the cost
344 };
355 * \brief Get the latest version stored in the container. Assumes the container is sorted in ascending order.
366 * \brief Recursively accumulate each version of the interface requested or provided by the plug-in (there should be one or none).
368 * \aknote Assumes the interface versions range from 1 to k_latestInterfaceVersion, except for native interfaces. \endaknote
370 * \return A pair containing a VersionPack of the requested versions and a VersionPack of the provided versions of the interface.
376 template <uint32_t in_interfaceVersion = k_latestInterfaceVersion, uint32_t... in_requestedVersions, uint32_t... in_providedVersions>
377 static constexpr auto GetUsedInterfaceVersions(VersionPack<in_requestedVersions...> = {}, VersionPack<in_providedVersions...> = {})
381 using InterfaceClass = typename KnownInterfaceClass<in_interfaceType, in_interfaceVersion>::Type;
402 * \brief Pair type containing a VersionPack of the requested versions and a VersionPack of the provided versions of the interface.
431 * \brief Is the interface requested (interface provided by host) by the generated plug-in class.
452 static_assert(RequestedInterfaceVersions::size() <= 1, "Plugin can't request more than one version of the same interface");
453 static_assert(ProvidedInterfaceVersions::size() <= 1, "Plugin can't provide more than one version of the same interface");
454 static_assert(!(k_requested && k_provides), "Requested interfaces can't be provided and provided interfaces can't be requested");
459 * \aknote If this interface hasn't been requested or provided at all by the plug-in, k_latestInterfaceVersion is returned. \endaknote
494 };
503 using InterfaceClass = typename KnownInterfaceClass<in_interfaceType, k_interfaceVersion>::Type;
527 * \return BaseInterface* An empty Base Interface pointing to the proper type and version. This is used
528 * when requesting an interface with the host, and the placeholder object pointer will get replaced.
572 };
588 return InterfaceArrayItem(InterfaceInfo<in_interfaceType>::ToInterfaceClass::Cast(nullptr)->GetInterfacePointer());
599 * \tparam in_interfaceType The current interface being processed. They are processed recursively from max to 0
602 static constexpr void GenerateInterfaceArray(InterfaceArrayItem out_interfaces[k_interfaceCount], int in_count, InterfaceArrayItem)
604 if constexpr (in_interfaceType != AK_WWISE_PLUGIN_INTERFACE_TYPE_UNKNOWN && in_interfaceType != AK_WWISE_PLUGIN_INTERFACE_TYPE_NUM)
609 InterfaceInfo<in_interfaceType>::k_has ? out_interfaces[in_count] = GenerateInterface<in_interfaceType>() : InterfaceArrayItem());
613 static constexpr InterfaceArrayItem* GenerateInterfaceArray(InterfaceArrayItem out_interfaces[k_interfaceCount])
632 using InterfaceToUpdate = typename KnownInterfaceClass<in_interfaceType, InterfaceInfo<in_interfaceType>::k_interfaceVersion>::Interface;
633 CBaseInterfaceGlue<InterfaceToUpdate>::g_cinterface = static_cast<InterfaceToUpdate*>(in_original.m_interface);
637 static inline void Constructor(InterfaceArrayItem& out_interface, const InterfaceArrayItem& in_original, PluginT* in_instance)
647 out_interface.m_instance = InterfaceInfo<in_interfaceType>::ToInterfaceClass::Cast(in_instance)->GetInstancePointer();
653 * \brief Recursively generates the constructors and interface pointer updater for all the Interfaces.
655 * \tparam in_interfaceType The current interface being processed. They are processed recursively from max to 0
657 template <InterfaceType in_interfaceType = (InterfaceType)(AK_WWISE_PLUGIN_INTERFACE_TYPE_UNKNOWN + 1)>
660 static inline void UpdateCInterface(const InterfaceArrayItem in_original[k_interfaceCount], int in_count = 0)
667 GenerateConstructorArray<(InterfaceType)(in_interfaceType + 1)>::UpdateCInterface(in_original, in_count + 1);
671 GenerateConstructorArray<(InterfaceType)(in_interfaceType + 1)>::UpdateCInterface(in_original, in_count);
676 static inline void Constructor(InterfaceArrayItem out_interfaces[k_interfaceCount], const InterfaceArrayItem in_original[k_interfaceCount], PluginT* in_instance, int in_count = 0)
682 GenerateConstructor<in_interfaceType>::Constructor(out_interfaces[in_count], in_original[in_count], in_instance);
683 GenerateConstructorArray<(InterfaceType)(in_interfaceType + 1)>::Constructor(out_interfaces, in_original, in_instance, in_count + 1);
687 GenerateConstructorArray<(InterfaceType)(in_interfaceType + 1)>::Constructor(out_interfaces, in_original, in_instance, in_count);
698 * It is known there is only one bridging interface between the C interface of the plug-in and the host, which
699 * means it's effectively limited to instantiating one instance at a time, where the host pre-fills its instance
703 * As such, this unique g_instance to do instantiation is not a new requirement, but merely an acknowledgement
711 * This array is writable and updated both by the host and the plug-in. Its data is then copied to the static
712 * instances of the plug-in (Interface) and copied to a new array, that is returned by the Instantiate method.
721 * It is currently assumed the in_pluginInfo parameter, as passed, is the same as the one provided in the
722 * ak_wwise_plugin_container structure. As such, in the current version of the SDK, this is not reentrant, as
725 * \warning This function is not reentrant. See \ref g_instance and \ref m_interfaceArray for more information.
728 * \return InterfaceArrayItem* The new instance: A copy of the structure, containing the instantiated pointers.
770 * \brief The unique m_pluginInfo used in the ak_wwise_plugin_container for that particular plug-in.
828 #define AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME1(prefix,suffix) AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME2(prefix, suffix)
835 #define AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME1(UserGeneratedPluginInfo, __COUNTER__)
837 #define AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME1(UserGeneratedPluginInfo, __LINE__)
839 #define AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME1(UserGeneratedPluginInfo, __LINE__)
841 #define AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME1(UserGeneratedPluginInfo, __COUNTER__)
849 * The container name must be the plug-in file/xml name. For example, it should be AkCompressor for AkCompressor.dll/.xml.
853 #define AK_DECLARE_PLUGIN_CONTAINER(ContainerName) extern AK::Wwise::Plugin::PluginContainer& GetPluginContainer ## ContainerName()
858 * The container name must be the plug-in file/xml name. For example, it should be AkCompressor for AkCompressor.dll/.xml.
872 * The export name is ak_wwise_plugin_container_export_ContainerName, where ContainerName must be the
875 * For non-Windows platforms, the export name is ak_wwise_plugin_container_export_libContainerName.
881 extern "C" __declspec(dllexport) AK::Wwise::Plugin::PluginContainer * ak_wwise_plugin_container_export_ ## ContainerName; \
882 AK::Wwise::Plugin::PluginContainer * ak_wwise_plugin_container_export_ ## ContainerName = &GetPluginContainer ## ContainerName()
885 extern "C" __attribute__ ((visibility ("default"))) AK::Wwise::Plugin::PluginContainer * ak_wwise_plugin_container_export_lib ## ContainerName; \
886 AK::Wwise::Plugin::PluginContainer * ak_wwise_plugin_container_export_lib ## ContainerName = &GetPluginContainer ## ContainerName()
890 * \brief (C++) Adds a Wwise Authoring plug-in and a Sound Engine plug-in to a plug-in container.
892 * Creates a custom namespace with custom plug-in info, that contains the generated plug-in info structure. Then,
895 * This uses the Sound Engine part to retrieve the plug-in information (Company id, Plug-in ID and Plug-in Type). It
896 * also adds up the Sound Engine's registration structure, so the host can initialize this part on first instantiation.
905 #define AK_ADD_PLUGIN_CLASS_TO_CONTAINER(ContainerName, WwiseClassName, AudioEngineRegisteredName) \
908 static struct UserGeneratedPluginInfo : private AK::Wwise::Plugin::PluginInfoGenerator<WwiseClassName> \
922 * Creates a custom namespace with custom plug-in info, that contains the generated plug-in info structure. Then,
934 #define AK_ADD_PLUGIN_CLASSID_TO_CONTAINER(ContainerName, WwiseClassName, CompanyID, PluginID, Type) \
936 static struct UserGeneratedPluginInfo : private AK::Wwise::Plugin::PluginInfoGenerator<WwiseClassName> \
951 #define AK_AUDIOPLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME AK_PLUGIN_USERGENERATEDPLUGININFO_NAMESPACE_NAME
966 #define ADD_AUDIOPLUGIN_CLASSID_TO_CONTAINER(x, y, a, b, c) AK_ADD_PLUGIN_CLASSID_TO_CONTAINER(x, y, a, b, c)
static PluginInfoGenerator * g_instance
The unique generator instance for this particular plug-in.
Definition: PluginInfoGenerator.h:706
static void UpdateCInterface(const InterfaceArrayItem in_original[k_interfaceCount], int in_count=0)
Definition: PluginInfoGenerator.h:660
PluginInfoGenerator: For each plug-in interface type, provides a single static instance used througho...
Definition: PluginInfoGenerator.h:87
static void Constructor(InterfaceArrayItem &out_interface, const InterfaceArrayItem &in_original, PluginT *in_instance)
Definition: PluginInfoGenerator.h:637
static void Constructor(InterfaceArrayItem out_interfaces[k_interfaceCount], const InterfaceArrayItem in_original[k_interfaceCount], PluginT *in_instance, int in_count=0)
Definition: PluginInfoGenerator.h:676
decltype(BaseInterface::m_interface) InterfaceType
PluginInfoGenerator: Type for the m_interface value in BaseInterface.
Definition: PluginInfoGenerator.h:49
Generic base for all plug-in instances. In C++, this is derived. In C, they are equivalent.
Definition: PluginDef.h:495
PluginInfoGenerator(const AkUInt32 *in_companyID, const AkUInt32 *in_pluginID, const AkPluginType *in_pluginType, uint32_t in_pluginFlags=0)
Definition: PluginInfoGenerator.h:791
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_PLUGIN_CONTAINER
2021.1 Plug-in container plug-in. Contains all the other plug-ins. ak_wwise_plugin_container
Definition: PluginBaseInterface.h:54
The interface information of the plug-in currently being instantiated.
Definition: PluginInfoGenerator.h:64
static constexpr InterfaceArrayItem GenerateInterface()
Generates the InterfaceArrayItem for our particular type.
Definition: PluginInfoGenerator.h:580
ak_wwise_plugin_interface_type m_interface
Interface type (see ak_wwise_plugin_interface_type)
Definition: PluginBaseInterface.h:118
typename UsedInterfaceVersions::first_type RequestedInterfaceVersions
VersionPack containing the requested versions of the interface by the plug-in.
Definition: PluginInfoGenerator.h:417
static constexpr InterfaceArrayItem * GenerateInterfaceArray(InterfaceArrayItem out_interfaces[k_interfaceCount])
Definition: PluginInfoGenerator.h:613
typename UsedInterfaceVersions::second_type ProvidedInterfaceVersions
VersionPack containing the provided versions of the interface by the plug-in.
Definition: PluginInfoGenerator.h:426
void Type
Definition: PluginInfoGenerator.h:307
static GluedInterface * g_cinterface
The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host onc...
Definition: PluginInfoGenerator.h:90
typename Super::CInstance CInstance
Definition: PluginInfoGenerator.h:145
typename CInterface::Instance Instance
Definition: PluginInfoGenerator.h:107
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:51
typename KnownInterfaceClass< in_interfaceType, k_interfaceVersion >::Type InterfaceClass
Interface class of the versioned interface type.
Definition: PluginInfoGenerator.h:503
static GluedInterface g_cppinterface
The unique interface for this plug-in interface.
Definition: PluginInfoGenerator.h:136
InterfaceArrayItem m_interfaceArray[k_interfaceCount]
Current array of interfaces, used in the bridge between host and plug-in.
Definition: PluginInfoGenerator.h:716
typename Super::Instance Instance
Definition: PluginInfoGenerator.h:146
CInterfaceArrayItem InterfaceArrayItem
A single instantiatable plug-in interface.
Definition: PluginDef.h:969
Casts the plug-in class to the requested interface class.
Definition: PluginInfoGenerator.h:512
PluginInfoGenerator: Compile-time dictionary of known interface-version.
Definition: PluginInfoGenerator.h:191
static void UpdateCInterface(const InterfaceArrayItem &in_original)
Definition: PluginInfoGenerator.h:627
#define AK_WWISESDK_VERSION_NATIVE_COMBINED
The specific version for native plug-in interfaces. Must be identical down to the build number.
Definition: PluginInfoGenerator.h:45
Generates the constructor for our particular type.
Definition: PluginInfoGenerator.h:626
PluginInfoGenerator: Requests a host-provided service, and optionally receives a variable containing ...
Definition: PluginInfoGenerator.h:223
@ k_latestInterfaceVersion
Most up-to-date version of the interface in the current SDK.
Definition: PluginInfoGenerator.h:343
Compile-time dictionary about a particular interface type.
Definition: PluginInfoGenerator.h:337
PluginInfoGenerator: Defines a compile-time dictionary with the latest version known to the SDK for e...
Definition: PluginInfoGenerator.h:284
Root interface allowing a logical unit (variable, library) to contain more than one interface.
Definition: PluginContainer.h:52
static InterfaceArrayItem * Instantiate(PluginInfo *in_pluginInfo)
Plug-in instance constructor, as shared with the host.
Definition: PluginInfoGenerator.h:730
@ k_interfaceType
Definition: PluginInfoGenerator.h:130
static constexpr void GenerateInterfaceArray(InterfaceArrayItem out_interfaces[k_interfaceCount], int in_count, InterfaceArrayItem)
Recursively generates an interface array of all the Interfaces pointers.
Definition: PluginInfoGenerator.h:602
static thread_local PluginInfo * tls_pluginInfo
Definition: PluginInfoGenerator.h:68
static void Disembody(InterfaceArrayItem *in_instance)
Plug-in instance destructor, as shared to the host.
Definition: PluginInfoGenerator.h:757
Generic base for all plug-in instances in C++.
Definition: PluginDef.h:512
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
Definition: PluginInfoGenerator.h:105
Definition: IAkPlugin.h:1699
CPluginContainer PluginContainer
Root interface allowing a logical unit (variable, library) to contain more than one interface.
Definition: PluginDef.h:971
HostInterfaceGlue(CInstance *in_instance)
Definition: PluginInfoGenerator.h:151
PluginInfo m_pluginInfo
The unique m_pluginInfo used in the ak_wwise_plugin_container for that particular plug-in.
Definition: PluginInfoGenerator.h:774
Compile-time container of version numbers.
Definition: PluginInfoGenerator.h:353
CInterface GluedInterface
Definition: PluginInfoGenerator.h:89
@ k_interfaceVersion
Definition: PluginInfoGenerator.h:131
void Interface
Definition: PluginInfoGenerator.h:193
PluginInfoGenerator(PluginRegistration *in_pluginRegistration, uint32_t in_pluginFlags=0)
Definition: PluginInfoGenerator.h:776
PluginInfoGenerator: Base class for every C++ instance that retrieves a service from the Wwise Author...
Definition: PluginInfoGenerator.h:128
decltype(GetUsedInterfaceVersions()) UsedInterfaceVersions
Pair type containing a VersionPack of the requested versions and a VersionPack of the provided versio...
Definition: PluginInfoGenerator.h:408
Recursively generates the constructors and interface pointer updater for all the Interfaces.
Definition: PluginInfoGenerator.h:659
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
Definition: PluginInfoGenerator.h:50
@ k_interfaceVersion
Version of the interface used by the plug-in or k_latestInterfaceVersion if unused.
Definition: PluginInfoGenerator.h:493
typename CPPInstance::GluedInterface GluedInterface
Definition: PluginInfoGenerator.h:132
@ k_interfaceVersion
Definition: PluginInfoGenerator.h:285
static constexpr uint32_t GetLatest()
Get the latest version stored in the container. Assumes the container is sorted in ascending order.
Definition: PluginInfoGenerator.h:359
static constexpr uint32_t GetInterfaceVersion()
Extract the version of the interface used by the plug-in.
Definition: PluginInfoGenerator.h:468
static constexpr auto GetUsedInterfaceVersions(VersionPack< in_requestedVersions... >={}, VersionPack< in_providedVersions... >={})
Recursively accumulate each version of the interface requested or provided by the plug-in (there shou...
Definition: PluginInfoGenerator.h:377
CPPInstance Instance
Definition: PluginInfoGenerator.h:133
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:117
static BaseInterface * GetPlaceholderPointer()
Get a Placeholder Pointer object.
Definition: PluginInfoGenerator.h:530
Host API to retrieve a link to the plug-in's backend instance.
Definition: PluginLinks.h:137
C++ PluginInfo Generator.
Definition: PluginInfoGenerator.h:329
Wwise Authoring Plug-ins - Root interface allowing a logical unit (variable, library) to contain more...
constexpr static InterfaceClass * Cast(PluginT *in_plugin)
Definition: PluginInfoGenerator.h:513
A single instantiatable plug-in interface.
Definition: PluginInterfaceArrayItem.h:45
Definition: PluginInfo.h:39
typename Super::GluedInterface GluedInterface
Definition: PluginInfoGenerator.h:147
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_UNKNOWN
2021.1 Unknown plug-in ID (0 - error, invalid, uninitialized)
Definition: PluginBaseInterface.h:53
CPPInstance * m_instance
The default instance for this plug-in interface.
Definition: PluginInfoGenerator.h:149
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_NUM
Definition: PluginBaseInterface.h:96
typename CPPInstance::Instance CInstance
Definition: PluginInfoGenerator.h:134
HostInterfaceGlue()
Definition: PluginInfoGenerator.h:152
ak_wwise_plugin_instance_ptr m_instance
That particular instance.
Definition: PluginInterfaceArrayItem.h:58
ak_wwise_plugin_interface_ptr m_interface
The interface. Should be identical for every instance of this DLL.
Definition: PluginInterfaceArrayItem.h:51
@ k_interfaceCount
Number of interfaces we are currently using.
Definition: PluginInfoGenerator.h:571
static constexpr size_t CountInterfaces()
Count the number of interfaces we are currently using.
Definition: PluginInfoGenerator.h:544
Definition: AudioPlugin.h:112
~PluginInfoGenerator()
Definition: PluginInfoGenerator.h:810