Wwise SDK 2024.1.0
|
In Wwise 2021.1, we introduced a new API for the Authoring part of plug-ins that included several changes. This migration guide will cover those changes and provide information to help you update your plug-in code to use this new API.
참고: The new Authoring Plug-in API can be found under <Wwise>/SDK/include/AK/Wwise/Plugin . |
In 2021.1, the plug-in API has been rewritten with a few goals in mind. The main goals are to provide a better default design that separates concerns between the backend and frontend implementations, to offer better support for backward compatibility and to minimize the requirements when creating a plug-in. These goals have been accomplished in the following ways:
AK::Wwise::IAudioPlugin
class has been split into smaller interfaces that are all versioned. Plug-ins are now able to request and provide services to the Authoring application by requesting service instances and implementing specific interfaces. Because there are fewer dependencies for typical plug-ins and the Authoring application has knowledge of the interface versions used, adapters for previous versions can be implemented to support them in future Wwise versions. Also, when interfaces are no longer supported, users can be informed of unsupported plug-ins. A consequence of this design is that plug-in makers will need to update their plug-ins less often to support newer Wwise versions.VARIANT
. Plug-in dynamic libraries expose a simple C-defined structure that, for every plug-in, describes its components and provides pointers to implementations. For convenience, a C++ API reproducing the features of the original API produces these lower-level structures at compile time.In addition to the aforementioned new features, some functions have been reworked for clarity.
참고: The Sound Engine part of the plug-in does not adopt the same design, retaining the approach of previous versions. |
A few methods that were deemed obsolete were removed from the API in 2021.1. Some other methods were not removed, but reworked by renaming and/or changing their arguments to make them clearer or easier to use.
AK::Wwise::IAudioPlugin::SetPluginPropertySet()
: Removed (obsolete)AK::Wwise::IAudioPlugin::SetPluginObjectStore()
: Removed (obsolete)AK::Wwise::IAudioPlugin::SetPluginObjectMedia()
: Removed (obsolete)AK::Wwise::IAudioPlugin::Destroy()
: Removed (obsolete)AK::Wwise::IAudioPlugin::IsPlayable()
: Removed (unused)AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface()
: Removed. Replaced by a standalone AK::Wwise::Plugin::MediaConverter
interface.AK::Wwise::IAudioPlugin::CopyInto()
-> AK::Wwise::Plugin::CustomData::InitFromInstance()
: Renamed, argument changed. The logic has been reversed to resemble other Init
methods as they are mutually exclusive.AK::Wwise::IAudioPlugin::Load()
-> AK::Wwise::Plugin::CustomData::InitFromWorkunit()
: RenamedAK::Wwise::IAudioPlugin::Delete()
-> AK::Wwise::Plugin::CustomData::OnDelete()
: RenamedNot listed are methods that have had non-optional pointer arguments changed to references.
It is likely that your plug-in uses a subset of the features provided by the Authoring plug-in API. Each of the following sections covers the changes related to a specific feature: refer to the appropriate section based on your plug-in's usage of the API. For more advanced features of the Authoring plug-in API, refer to Common Use Cases for Requests.
참고: This section refers to pre-2021.1 as the "original" API, and to 2021.1 and up to the "new" API. |
In the original API, the AK::Wwise::IAudioPlugin
interface contained all the features of the Authoring plug-in API. You could simply subclass AK::Wwise::DefaultAudioPluginImplementation
to empty implementations for each method, but your class still had all of these unused methods defined.
In the new API, there is a similar AK::Wwise::Plugin::AudioPlugin
interface, but its only method is AK::Wwise::Plugin::AudioPlugin::GetBankParameters()
. For a simple plug-in that has typical properties being written to a SoundBank, implementing this single interface is all that is needed. Implementing this interface also serves as an indicator that the implementing class is a backend class (as opposed to a frontend class, which is covered in the Implementing a Frontend section).
Concretely, there are few differences between an original and a new API class:
Original API
New API
Notice that there is only a single method left to implement: GetBankParameters
. The AK::Wwise::IAudioPlugin::Destroy() function is also not necessary anymore, as instantiation and destruction is completely handled by the plug-in API. The standard C++ destructor can be use to release resources.
You may have noticed that the function AK::Wwise::IAudioPlugin::SetPluginPropertySet()
has been removed in the previous section's code example. Indeed, this function is not needed anymore thanks to the AK::Wwise::Plugin::AudioPlugin
interface that requests the property set component for you. By subclassing AK::Wwise::Plugin::RequestPropertySet
, the AK::Wwise::Plugin::AudioPlugin
interface adds a PropertySet
component requirement to the plug-in description, which will be fulfilled by the Authoring application when the plug-in is instantiated. It also adds a member variable m_propertySet
that will automatically be set to the PropertySet
component instance at instantiation. This removes the need to manually create this member variable and implement its corresponding setter.
Implementing a simple Authoring plug-in with only GetBankParameters
is therefore simplified:
Original API
New API
Some key differences:
DataWriter
argument is now a reference, as it is not optional (cannot be NULL)m_propertySet
AK::Wwise::Plugin::PropertySet::GetReal32()
is of type const char*
, instead of LPCWSTR
(const wchar_t*).AK::Wwise::Plugin::PropertySet
accessors for consistency with AK::Wwise::Plugin::DataWriter
.All of these changes make implementing this function simpler, safer and more portable.
Implementing AK::Wwise::Plugin::AudioPlugin
provides the minimum implementation for SoundBank generation. However, providing only this part of the plug-in means there is no custom GUI to display, and so the Authoring application will generate one that looks similar to the Multi-Editor view.
As previously hinted, the AudioPlugin
class represents the backend of the Authoring plug-in: it can be used in a command-line context (without a GUI) and implements any custom data or state management. To display a custom GUI, a new class needs to be created that will be attached to the same plug-in identifier. This class will be instantiated separately from the backend class.
The frontend class is implemented by subclassing a frontend interface. Due to the nature of GUIs, these are permitted to be platform specific. Hence, the AK::Wwise::Plugin::GUIWindows
interface, to which the original frontend-related methods were moved, can be subclass for providing a custom plug-in GUI on Windows.
참고: If you intend to use MFC, you should also subclass AK::Wwise::Plugin::PluginMFCWindows first. This will handle the initialization of a global CWinApp for your library. |
Notice that copies of eDialog
and PopulateTableItem
have been added to the AK::Wwise::Plugin
namespace. In the case of PopulateTableItem
, the related macros have also been updated to reflect their relation to the frontend interface:
AK_BEGIN_POPULATE_TABLE()
-> AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE()
AK_POP_ITEM()
-> AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM()
AK_END_POPULATE_TABLE()
-> AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()See 속성에 규칙 제어 연결하기 for more details.
In a frontend class, you must not subclass AK::Wwise::Plugin::AudioPlugin
or implement any backend related logic, such as property value adjustments or operations affecting the result of a SoundBank generation. The frontend should be solely responsible for displaying properties and monitoring data in a user-friendly way, and update the plug-in model based on user input.
If the backend does not need to make any adjustments to values supplied by the user, the frontend can simply request the PropertySet
component by subclassing AK::Wwise::Plugin::RequestPropertySet
. However, if the backend does any value adjustments on properties, for example to implement dynamic property ranges, this should be implemented in the backend.
If the backend offers some implementations that the frontend requires, it can request theLinkBackend
service by subclassing AK::Wwise::Plugin::RequestLinkBackend
. It will provide the frontend class with a m_backend
instance representing the backend instance to which it is bound.
The reverse is also possible, where a backend class can request LinkFrontend
by subclassing AK::Wwise::Plugin::RequestLinkFrontend
. One big difference for LinkFrontend
is that there can be multiple frontends for one backend: the m_frontend
instance inherited therefore represents an array of frontends. The size of the array can be obtained by the GetArray
method and a ForEach
function is offered for convenience.
While the PropertySet
component request is made implicitly by the AK::Wwise::Plugin::AudioPlugin
interface because it is typically needed in the context of AK::Wwise::Plugin::AudioPlugin::GetBankParameters()
, other components and services are optional and can be requested manually by subclassing any of the available AK::Wwise::Plugin::Request[...]
classes (refer to Request Components and Services). When the plug-in provides an implementation to the Authoring application, the interface is not prefixed by Request
. For example, this is the case for AK::Wwise::Plugin::Source
, AK::Wwise::Plugin::SinkDevices
and AK::Wwise::Plugin::PropertyDisplayName
.
The following is a list of common use cases in the original API and the corresponding services that need to be requested to obtain the same features in the new API.
Monitoring data sent by the Sound Engine counter-part of the plug-in is received through the NotifyMonitorData
method. This method has been moved to a notification interface. Subclass AK::Wwise::Plugin::Notifications::Monitor
to implement this method.
Refer to Monitoring in Authoring for details on implementing the AK::Wwise::Plugin::Notifications::Monitor
interface.
In the original API, to provide a custom handler for licensing you had to implement AK::Wwise::IAudioPlugin::GetLicenseStatus
. This function has been moved to a separate interface: subclass AK::Wwise::Plugin::License
to implement this method.
Refer to Managing Licenses for details on how to implement AK::Wwise::Plugin::License
.
Plug-in data meant to be handled as media, typically audio files that can be encoded during a source conversion process, could be supported by implementing AK::Wwise::IAudioPlugin::SetPluginObjectMedia()
and AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface()
. These, along with the management of media objects, have been centralized in the AK::Wwise::Plugin::ObjectMedia
. Object media methods are implemented directly inside the plug-in class. The media converter, which is still optional, is a separate interface to implement: AK::Wwise::Plugin::MediaConverter
.
Refer to 오디오 플러그인에 미디어 추가하기 for details on how to use these interfaces.
All plug-in data that are not managed through the PropertySet or ObjectMedia components have been centralized in a common interface AK::Wwise::Plugin::CustomData
. While most methods are the same, CopyInto
has been reworked to reverse its logic.
AK::Wwise::IAudioPlugin::GetPluginData()
-> AK::Wwise::Plugin::CustomData::GetPluginData()
AK::Wwise::IAudioPlugin::InitToDefault()
-> AK::Wwise::Plugin::CustomData::InitToDefault()
AK::Wwise::IAudioPlugin::CopyInto()
-> AK::Wwise::Plugin::CustomData::InitFromInstance()
AK::Wwise::IAudioPlugin::Load()
-> AK::Wwise::Plugin::CustomData::InitFromWorkunit()
AK::Wwise::IAudioPlugin::Save()
-> AK::Wwise::Plugin::CustomData::Save()
AK::Wwise::IAudioPlugin::Delete()
-> AK::Wwise::Plugin::CustomData::OnDelete()
The three Init
functions are mutually exclusive: one of them will be called when the plug-in is initialized depending on the context where it is loaded.
Subclass the AK::Wwise::Plugin::CustomData
interface to implement these methods. Refer to Providing Custom Data for details on how to implement the CustomData
interface.
참고: Make sure to apply this logic reversal when porting a plug-in using Custom Data to the 2021.1 Authoring Plug-in API. |
프로젝트를 등록하세요. 아무런 조건이나 의무 사항 없이 빠른 시작을 도와드리겠습니다.
Wwise를 시작해 보세요