/// <summary>
/// Request for playing a certain Theme at the desired intensity
/// </summary>
/// <remarks>
/// Please note that there is a hierarchy among the different types of Themes, which will e.g. prevent a Base Mood from interrupting a Theme of type Action Event.
/// Likewise, a Theme of type Shock Event will interrupt any other Theme that may be currently playing. Please refer to the psai Manual included in the psai SDK for
/// a description of all the Theme Types and their playback priorities. The general interruption behaviour is as follows:
/// If a Theme of a lower priority is currently playing when a new Theme is triggered, the psai soundtrack will play the newly triggered Theme immediately and quickly
/// fade out
/// the previous Theme. This way it is possible to build up a stack of interrupted Themes: A Base Mood may be interrupted by an Action Event, which is then interrupted
/// by a Shock Event. When the intensity of the Shock Event has dropped to zero, psai will return to the Action Event, starting with the intensity level that was up at
/// the time of its interruption. Likewise, when the intensity of the Action Event has reached zero intensity, psai will continue with the Basic Mood.
/// If another Theme of the same priority is playing when a Theme has been triggered, psai will switch to the next Theme as soon as the Segment currently playing has
/// reached its end. This can only
/// work if there is at least one Segment in the newly triggered Theme, that has been marked within the psai® Editor as a compatible follower to the Segment currently playing.
/// Please refer to the psai® Editor documentation for more information about Segment compatibilites.
/// If the newly triggered Theme is the very same Theme that is currently playing, psai will set the internal Intensity level to the Intensity-argument of the new trigger-call.
/// Thus, triggering the same Theme over and over again will not result in an accumulation of the triggered intensity values. Please see the 'Intensity'-section of the psai Manual
/// for more information about psai's Intensity concept.
/// If a Theme of type Basic Mood is triggered while a Theme of higher priority is playing, psai will internally store the triggered Basic Mood as the one to switch to, when
/// the Intensity level of all stacked Themes has dropped to zero. All other trigger-calls to Themes of lower priority are ignored completely.
/// The Theme will be playing for a timespan as defined by the member "music duration" within the psai Editor. The intensity falloff rate will be automatically adjusted to reach
/// zero accordingly. To manually override this setting, call the overloaded version of TriggerMusicTheme() with the additional musicDuration parameter.
/// Troubleshooting: If the soundtrack does not react as expected, please check your 'psai.log' file in your '[current user]/Documents/psai' folder to see what happened, and check back
/// with your composer to make sure that the Types of the affected Themes have been assigned correctly within the psai Editor authoring software.
/// </remarks>
/// <param name="themeId">The id of the Theme to play</param>
/// <param name="intensity">The initial intensity value. The valid range is between 0.0f and 1.0f.</param>
/// <returns>
/// <list type="table">
/// <listheader>
/// <term>term</term>
/// <description>description</description>
/// </listheader>
/// <item>
/// <term>"PsaiResult.OK</term>
/// <description> if successful</description>
/// </item>
/// <item>
/// <term>"PsaiResult.initialization_error</term>
/// <description>psai has not been initialized correctly. See psai.log for more information.</description>
/// </item>
/// <item>
/// <term>"PsaiResult.unknown_theme</term>
/// <description>the requested Theme does not exist in the current soundtrack</description>
/// </item>
/// <item>
/// <term>"PsaiResult.commandIgnoredMenuModeActive</term>
/// <description>the command was ignored, call <see cref="MenuModeLeave">MenuModeLeave()</see> first.</description>
/// </item>
/// </list>
/// </returns>
public PsaiResult TriggerMusicTheme(int themeId, float intensity)
{
return(m_logik.TriggerMusicTheme(themeId, intensity));
}
