|
|
◆ SeekOnEvent() [3/4]
Seeks inside all playing objects that are referenced in Play Actions of the specified Event. Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
Notes:
- This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
- There is a restriction with sounds that play within a continuous sequence. Seeking is ignored if one of their ancestors is a continuous (random or sequence) container with crossfade or trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless the sound that is currently playing is the first sound of the sequence.
- Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
- If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker. With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor. Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored: seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
- This method posts a command in the sound engine queue, thus seeking will not occur before the audio thread consumes it (after a call to RenderAudio()).
Notes specific to Music Segments:
- With Music Segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or post-exit of a segment using this method. Use absolute values instead.
- Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification in order to restart them if required.
- In order to restart at the correct location, with all their tracks synchronized, Music Segments take the "look-ahead time" property of their streamed tracks into account for seeking. Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the value that was passed to the method. Use
AK::MusicEngine::GetPlayingSegmentInfo() to query the exact position of a segment. Also, the segment will be silent during the time that period (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() also informs you about the remaining look-ahead time.
Notes specific to Music Switch Containers:
- Seeking triggers a music transition towards the current (or target) segment. This transition is subject to the container's transition rule that matches the current and defined in the container, so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
- If the specified time is greater than the destination segment's length, the modulo is taken.
- See also
-
- Parameters
-
| in_pszEventName | Name of the event |
| in_gameObjectID | Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects |
| in_fPercent | Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds) |
| in_bSeekToNearestMarker | If true, the final seeking position will be made equal to the nearest marker (see notes above). |
| in_PlayingID | Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID. |
|