diff --git a/docs/latest/Functions-(Sound-Instances).md b/docs/latest/Functions-(Sound-Instances).md index 1e2f1e1..7d6a9d1 100644 --- a/docs/latest/Functions-(Sound-Instances).md +++ b/docs/latest/Functions-(Sound-Instances).md @@ -3,9 +3,11 @@ **Returns:** N/A (`undefined`) |Argument |Datatype|Description | -|-----------------|--------|------------------------------------------------------| -|`soundInstanceID`|number | | -|`loop` |boolean | | +|-----------------|--------|--------------------------------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | +|`loop` |boolean |Whether the sound instance should replay from the start when it finishes playing| + +Plays the given sound instance. If the sound instance is set to *not* loop (`loop` is `false`) then `FAudio_SoundInstance_DestroyWhenFinished()` will be called automatically for the sound instance.   @@ -15,7 +17,21 @@ |Argument |Datatype|Description | |-----------------|--------|------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | + +Pauses playback of a sound instance. It can later be resumed by calling `FAudio_SoundInstance_Resume(soundInstanceID)`. + +  + +## `~_SoundInstance_Resume(soundInstanceID)` + +**Returns:** N/A (`undefined`) + +|Argument |Datatype|Description | +|-----------------|--------|------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | + +Resumes playback of a sound instance that has been paused by `FAudio_SoundInstance_Pause()`. If the sound instance in question hasn't been paused then this function does nothing.   @@ -25,7 +41,9 @@ |Argument |Datatype|Description | |-----------------|--------|------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | + +Stops playback of the given sound instance completely. To restart playback, `FAudio_SoundInstance_Play()` should be called.   @@ -35,7 +53,9 @@ |Argument |Datatype|Description | |-----------------|--------|------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | + +Destroys a sound instance, freeing memory associated with it.   @@ -45,7 +65,9 @@ |Argument |Datatype|Description | |-----------------|--------|------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | + +Sets a sound instance to self-destruct when it finishes playing. This is useful for one-off audio clips that you don't want to keep track of.   @@ -55,9 +77,11 @@ |Argument |Datatype|Description | |-----------------|--------|---------------------------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | |`pan` |number |Should be from `-1` (100% left) to `+1` (100% right) with `0` being central| +Sets the stereo (left/right) panning of the sound instance. This is useful to fake positional audio in 2D, amongst other mixing techniques. +   ## `~_SoundInstance_SetPitch(soundInstanceID, pitch)` @@ -66,9 +90,11 @@ |Argument |Datatype|Description | |-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target | |`pitch` |number |Frequency multiplier. A value of `2` will double the frequency and make the pitch higher, a value of `0.5` will halve the frequency and make the pitch lower| +Changes the pitch of the audio by time-stretching or time-condensing playback. This also changes the playback time accordingly (a higher-pitched sound will take less time to fully play). +   ## `~_SoundInstance_SetVolume(soundInstanceID, volume)` @@ -77,8 +103,10 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`volume` |number | | +|`soundInstanceID`|number |Sound instance to target | +|`volume` |number |Volume of the sound instance. `1` is 100% volume | + +Sets the volume for the sound instance. To change volume smoothly over time, please use `FAudio_SoundInstance_SetVolumeOverTime()`.   @@ -88,10 +116,12 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`x` |number | | -|`y` |number | | -|`z` |number | | +|`soundInstanceID`|number |Sound instance to target | +|`x` |number |x-position of the sound instance | +|`y` |number |y-position of the sound instance | +|`z` |number |z-position of the sound instance | + +Places the sound instance in 3D space. In combination with `FAudio_SetListenerPosition()`, this sets the relative panning and volume for the sound instance to give the illusion of the player being in a 3D environment.   @@ -101,10 +131,12 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`xVelocity` |number | | -|`yVelocity` |number | | -|`zVelocity` |number | | +|`soundInstanceID`|number |Sound instance to target | +|`xVelocity` |number |x-component of the velocity of the sound instance | +|`yVelocity` |number |y-component of the velocity of the sound instance | +|`zVelocity` |number |z-component of the velocity of the sound instance | + +Sets the velocity of the sound instance, allowing for pitch shifting to emulate the [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect).   @@ -114,8 +146,10 @@ |Argument |Datatype|Description | |------------------------|--------|--------------------------------------------------------| -|`soundInstanceID` |number | | -|`trackPositionInSeconds`|number | | +|`soundInstanceID` |number |Sound instance to target | +|`trackPositionInSeconds`|number |Track position to jump to, in seconds | + +Jumps to a fixed position in the sound instance's audio asset. This is useful for audio assets that are comprised of a few different sections.   @@ -125,9 +159,11 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`volume` |number | | -|`milliseconds` |number | | +|`soundInstanceID`|number |Sound instance to target | +|`volume` |number |Target velocity to interpolate towards | +|`milliseconds` |number |Duration of the interpolation, in milliseconds | + +Smoothly interpolates the volume of a sound instance over time. This time can be very short or very long, as you see fit.   @@ -135,11 +171,13 @@ **Returns:** N/A (`undefined`) -|Argument |Datatype|Description | -|-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`lowPassFilter` |number | | -|`Q` |number | | +|Argument |Datatype|Description | +|-----------------|--------|-------------------------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | +|`lowPassFilter` |number |Frequency of the low-pass. This is a value from `0` (20hz) to `1` (20khz)| +|`Q` |number |Unitless - the steepness of the cutoff knee. A recommended value is `1` | + +Sets a low-pass filter on a sound instance, cutting out high frequencies. This has the effect of making the sound seem muffled.   @@ -147,23 +185,13 @@ **Returns:** N/A (`undefined`) -|Argument |Datatype|Description | -|-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`lowPassFilter` |number | | -|`Q` |number | | +|Argument |Datatype|Description | +|-----------------|--------|--------------------------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | +|`highPassFilter` |number |Frequency of the high-pass. This is a value from `0` (20hz) to `1` (20khz)| +|`Q` |number |Unitless - the steepness of the cutoff knee. A recommended value is `1` | -  - -## `~_SoundInstance_SetHighPassFilter(soundInstanceID, highPassFilter, Q)` - -**Returns:** N/A (`undefined`) - -|Argument |Datatype|Description | -|-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`highPassFilter` |number | | -|`Q` |number | | +Sets a high-pass filter on a sound instance, cutting out low frequencies. This has the effect of making the sound seem tinny and thin.   @@ -171,11 +199,13 @@ **Returns:** N/A (`undefined`) -|Argument |Datatype|Description | -|-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | -|`bandPassFilter` |number | | -|`Q` |number | | +|Argument |Datatype|Description | +|-----------------|--------|--------------------------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | +|`bandPassFilter` |number |Frequency of the band-pass. This is a value from `0` (20hz) to `1` (20khz)| +|`Q` |number |Unitless - the steepness of the cutoff knee. A recommended value is `1` | + +Sets a band-pass filter on a sound instance, cutting out frequencies above and below the center of the band. What this sounds like depends on what frequency you choose, but it has a habit of making sounds seem nasal and boxy.   @@ -185,7 +215,7 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target |   @@ -195,7 +225,7 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target |   @@ -205,7 +235,7 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | +|`soundInstanceID`|number |Sound instance to target |   @@ -215,4 +245,4 @@ |Argument |Datatype|Description | |-----------------|--------|--------------------------------------------------------| -|`soundInstanceID`|number | | \ No newline at end of file +|`soundInstanceID`|number |Sound instance to target | \ No newline at end of file