Version
menu_open

Method 4: Preparing Action Events

This method will apply if:

  • A very small level of granularity is required for media to keep the memory usage low.

  • You do not want to worry about managing which media assets must be assigned which SoundBank.

What exactly is a prepared Action Event? When calling the PrepareEvent() function, the system analyses the Action Event and makes sure that all the structure and media related to this Event are loaded into memory. If they are not, the system will automatically stream from disk the missing information. An Event is prepared until it is explicitly unprepared.

[Note] Note

Only Action Events can be prepared in advance. The “PrepareEvent” method does not work with Dialogue Events.

This method requires that you create at least one SoundBank; however, the structure part can be in either the same SoundBank as the Events, or in a completely separate SoundBank.

When building SoundBanks that will use the PrepareEvent mechanism, the criteria is that every required Event and structure must be found in at least one SoundBank, and the loose media assets must be accessible by the file system. Remember though, that it is possible to manage your memory more efficiently by splitting structure into multiple SoundBanks.

Prior to preparing an action Event, the Event itself must have been loaded into memory from one SoundBank (using LoadBank()). This is required because the Event contains information about the dependencies required to prepare the Event.

[Note] Note

It is also possible to prepare Events in combination with AK::SoundEngine::PrepareBank. The main advantage of using the PrepareBank mechanism is that it removes the need to split the SoundBanks into "Event banks" and "Media banks". Under this method, all content is contained in the same SoundBank, but when AK::SoundEngine::PrepareBank is called, only the metadata content of the SoundBank is loaded into memory. When the media is required by your game, you can load it using PrepareEvent.

To set up your SoundBanks in Wwise when preparing Events:

  1. Create a SoundBank called “Events” and load it into the SoundBank Editor.

  2. Add some of the Action Events in your project to the “Event” SoundBank, or simply add the Event Work Units.

  3. Disable the Media check box, leaving only the Events and Structures check boxes enabled. When using PrepareEvent(), the media must not reside in a SoundBank, but be loaded directly off disk as a loose file.

    [Note] Note

    For the purposes of this example, all the Events and structures are contained in one SoundBank. Although this is acceptable for small projects, you will most likely want to split up your content into several SoundBanks. It is also possible to create a separate “Structures” SoundBank that does not need to be explicitly loaded nor prepared from the SDK command because each Event includes references to the other SoundBanks that need to be loaded.

  4. Generate the SoundBanks and copy the generated SoundBank folder to the game application.

    [Note] Note

    The structure data contained within a single SoundBank can't be split at runtime. Therefore, if you are using AK::SoundEngine::PrepareEvent(), and the structure data from a separate SoundBank is required, all the structures within that SoundBank will be loaded at once. For this reason, you may want to split the structure content in your project into multiple SoundBanks, to minimize the amount of unnecessary information that is loaded into memory.

To prepare Events in game:

  1. In the game, load the Events' SoundBank at the beginning of your game and then prepare the Events when they are required in game. The corresponding structures and media will be loaded automatically.

    The following code sample gives you an idea of how to prepare Events in game.

                  
                  // Initializing the sound engine. 
    
                  AkInitSettings initSettings;
                  AkPlatformInitSettings platformInitSettings;
                  AK::SoundEngine::GetDefaultInitSettings( initSettings ):
                  AK::SoundEngine::GetDefaultPlatformInitSettings( platformInitSettings ):
    
                  // Set the required settings. 
    
                  ...
    
                  // Set PrepareEvent related settings. 
                  initSettings.bEnableGameSyncPreparation = false; // Not used in the current sample. 
    
                  // (Optional) Allocate a memory pool into which prepared media will be loaded. 
                  // If this is not done, memory will be allocated directly in the default memory pool. 
                  {
                    initSettings.uPrepareEventMemoryPoolID = AK.MemoryMgr.CreatePool( NULL, 4*1024*1024, 1024, AkMalloc );
    
                    // (Optional) Give the memory pool a name. This can be very useful for profiling. 
                    AK::MemoryMgr::SetPoolName( initSettings.uPrepareEventMemoryPoolID, L"PrepareEventPool" );
                  }
    
                  AKRESULT eResult = AK.SoundEngine.Init( initSettings, platformInitSettings );
                  if( eResult != AK_Success )
                  {
                    // Handle error. 
                  }
    
                  // Load Init bank and the event/structure bank. 
                  AkBankID    bankID;  // Not used in the sample. 
                  AKRESULT eResult = AK::SoundEngine::LoadBank( L"Init.bnk", AK_DEFAULT_POOL_ID, bankID );
                  if( eResult == AK_Success )
                  {
                    eResult = AK::SoundEngine::LoadBank( L"Events.bnk", AK_DEFAULT_POOL_ID, bankID );
                  }
    
                  ...
    
                  // And then, at various points in the code:
    
                  AkLpCtstr pEventsNameArray[1] = { L"My_Event_Name" };
    
                  // Preparing an event:
                  eResult = AK::SoundEngine::PrepareEvent( Preparation_Load, pEventsNameArray, 1 ); // 1 is the array size. 
    
                  // Unpreparing an event:
                  eResult = AK::SoundEngine::PrepareEvent( Preparation_Unload, pEventsNameArray, 1 ); // 1 is the array size. 
                

Additional Notes on this Method

Keep in mind that calls to AK::SoundEngine::PrepareEvent() must be considered as I/O functions calls. In the previous example, we used blocking functions. You can use other overloads of the function AK::SoundEngine::PrepareEvent() to make them non-blocking calls, and then revive the completion notification through a separate callback.

The following table lists the pros and cons of preparing action events.

Pros

Cons

SoundBank generation process is simple.

Level of granularity for media is very small.

Overall low memory usage is maintained.

Automation of the process is easy.

Potentially increases the number of reads and seeks on the disk as the media assets will be loaded one by one.

Control over the total amount of memory used is reduced.

Working with Interactive Music becomes complicated.


Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell 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