Struct NativeSource.PlayOptions

Used with Play(NativeAudioPointer, NativeSource.PlayOptions) to customize your play. Start creating it from defaultOptions.

Namespace: E7.Native

Assembly: E7.NativeAudio.dll

Syntax

public struct PlayOptions

Remarks

On some platforms like iOS, adjusting them after the play with NativeSource is already too late because you will already hear the audio. (Even in consecutive lines of code)

It has to be a struct since this will be sent to the native side, interop to a matching code in other language.

Fields

defaultOptions

Structs couldn't have custom default values and something like volume is better defaulted to 1 instead of 0.

This pre-allocated static variable contains sensible default values that you can copy from as a starting point.

Declaration

public static readonly NativeSource.PlayOptions defaultOptions

Field Value

Type	Description
NativeSource.PlayOptions

Remarks

Consists of :

• Volume 1 (no attenuation).
• Pan 0 (center).
• Offset seconds 0 (starts from the beginning).
• Source loop false.

offsetSeconds

Start playing from other point in the audio by offsetting the target native source's play head time SECONDS unit.

Will do nothing if the offset is over the length of audio.

Declaration

public float offsetSeconds

Field Value

Type	Description
System.Single

pan

Set the pan of target native source before play. -1 for full left, 0 for center, 1 for full right.

This pan is based on "balance effect" and not a "constant energy pan" that is at the center you hear each side fully. (Constant energy pan has 3dB attenuation to both on center.)

Declaration

public float pan

Field Value

Type	Description
System.Single

Remarks

[iOS] 2D panning in iOS will be emulated in OpenAL's 3D audio engine by splitting your stereo sound into a separated mono sounds, then position each one on left and right ear of the listener. When panning, instead of adjusting gain we will just move the source further from the listener and the distance attenuation will do the work. (Gain is reserved to the setting volume command, so we have 2 stage of gain adjustment this way.)

[Android] Maps to SLVolumeItf interface -> SetStereoPosition

sourceLoop

Apply a looping state on the native source.

Declaration

public bool sourceLoop

Field Value

Type	Description
System.Boolean

Remarks

The reason why it is "sourceLoop" instead of "loop" is to emphasize that if some newer sound decided to use that native source to play, that looping sound is immediately stopped since we do not mix and one native source can only handle one audio.

To "protect" the looping sound, you likely have to plan your native source index carefully when choosing which source to play via GetNativeSource(Int32)

Using the default round-robin GetNativeSourceAuto() sooner or later will stop your looping sound when it wraps back.

volume

Set the volume of target native source before play.

Declaration

public float volume

Field Value

Type	Description
System.Single

Remarks

[iOS] Maps to AL_GAIN. It is a scalar amplitude multiplier, so the value can go over 1.0 for increasing volume but can be clipped. If you put 0.5f, it is attenuated by 6 dB.

[Android] Maps to SLVolumeItf interface -> SetVolumeLevel. The floating volume parameter will be converted to millibel (20xlog10x100) so that putting 0.5f here results in 6dB attenuation.