Wwise SDK 2021.1.14
_plugin_info_generator_8h_source
Version
menu_open
link
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:1697
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
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell us about your project. We're here to help.
Register your project and we'll help you get started with no strings attached!
Get started with Wwise