From ea3774de4cc24d80d6f4111338ba6a4fd85ac181 Mon Sep 17 00:00:00 2001 From: Nikita Krapivin Date: Thu, 27 Jan 2022 00:20:47 +0500 Subject: [PATCH] Update the docs a little bit --- docs/latest/Function-Index.md | 5 +-- docs/latest/Functions-(Essentials).md | 6 ++-- .../Functions-(Loading-Sound-Assets).md | 15 +++++---- docs/latest/Functions-(Sound-Instances).md | 31 +++++++++++++++++++ 4 files changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/latest/Function-Index.md b/docs/latest/Function-Index.md index 05d2742..9c0d471 100644 --- a/docs/latest/Function-Index.md +++ b/docs/latest/Function-Index.md @@ -13,7 +13,7 @@ - [`FAudioGMS_StaticSound_LoadWAV(filePath)`](Functions-(Loading-Sound-Assets)?id=_staticsound_loadwavfilepath) - [`FAudioGMS_StaticSound_CreateSoundInstance(staticSoundID)`](Functions-(Loading-Sound-Assets)?id=_staticsound_createsoundinstance) - [`FAudioGMS_StaticSound_Destroy(staticSoundID)`](Functions-(Loading-Sound-Assets)?id=_staticsound_destroystaticsoundid) -- [`FAudioGMS_StreamingSound_LoadOGG(filePath)`](Functions-(Loading-Sound-Assets)?id=_streamingsound_loadoggfilepath) +- [`FAudioGMS_StreamingSound_LoadOGG(filePath, bufferSizeInBytes)`](Functions-(Loading-Sound-Assets)?id=_streamingsound_loadoggfilepath-buffersizeinbytes)   @@ -29,6 +29,7 @@ - [`FAudioGMS_SoundInstance_SetVolume(soundInstanceID, volume)`](Functions-(Sound-Instances)?id=_soundinstance_setvolumesoundinstanceid-volume) - [`FAudioGMS_SoundInstance_Set3DPosition(soundInstanceID, x, y, z)`](Functions-(Sound-Instances)?id=_soundinstance_set3dpositionsoundinstanceid-x-y-z) - [`FAudioGMS_SoundInstance_Set3DVelocity(soundInstanceID, xVelocity, yVelocity, zVelocity)`](Functions-(Sound-Instances)?id=_soundinstance_set3dvelocitysoundinstanceid-xvelocity-yvelocity-zvelocity) +- [`FAudioGMS_SoundInstance_Set3DOrientation(soundInstanceID, xFront, yFront, zFront, xTop, yTop, zTop)`](Functions-(Sound-Instances)?id=_soundinstance_set3dorientationsoundinstanceid-xfront-yfront-zfront-xtop-ytop-ztop) - [`FAudioGMS_SoundInstance_SetTrackPositionInSeconds(soundInstanceID, trackPositionInSeconds)`](Functions-(Sound-Instances)?id=_soundinstance_settrackpositioninsecondssoundinstanceid-trackpositioninseconds) - [`FAudioGMS_SoundInstance_SetLoopPoints(soundInstanceID, loopStartInMilliseconds, loopEndInMilliseconds)`](http://moonside.games/docs/FAudioGMS/#/latest/Functions-(Sound-Instances)?id=_soundinstance_setlooppointssoundinstanceid-loopstartinmilliseconds-loopendinmilliseconds)? - [`FAudioGMS_SoundInstance_SetVolumeOverTime(soundInstanceID, volume, milliseconds)`](Functions-(Sound-Instances)?id=_soundinstance_setvolumeovertimesoundinstanceid-volume-milliseconds) @@ -61,4 +62,4 @@ - [`FAudioGMS_SetListenerVelocity(xVelocity, yVelocity, zVelocity)`](Functions-(Global-Behaviours)?id=_setlistenervelocityxvelocity-yvelocity-zvelocity) - [`FAudioGMS_PauseAll()`](Functions-(Global-Behaviours)?id=_pauseall) - [`FAudioGMS_ResumeAll()`](Functions-(Global-Behaviours)?id=_resumeall) -- [`FAudioGMS_StopAll`](Functions-(Global-Behaviours)?id=_stopall) \ No newline at end of file +- [`FAudioGMS_StopAll()`](Functions-(Global-Behaviours)?id=_stopall) \ No newline at end of file diff --git a/docs/latest/Functions-(Essentials).md b/docs/latest/Functions-(Essentials).md index f851734..f4e8bf0 100644 --- a/docs/latest/Functions-(Essentials).md +++ b/docs/latest/Functions-(Essentials).md @@ -4,10 +4,10 @@ **Returns:** N/A (`undefined`) -|Argument |Datatype|Description | -|----------------------|--------|------------------------------------------------------------------------------------------------------------| +|Argument |Datatype|Description | +|----------------------|--------|---------------------------------------------------------------------------------------------------------------| |`spatialDistanceScale`|number |3D Volume scaling factor. Higher numbers make sounds that are further away quieter. A recommended value is `50`| -|`timestep` |number |Number of seconds expected to pass for each call to `FAudio_Update()`. This is usually `1/fps` | +|`timestep` |number |Number of seconds expected to pass for each call to `FAudio_Update()`. This is usually `1/fps` | !> `FAudioGMS_Init()` must be called once at the very start of your game. If in doubt, place the `AUDIO` object in the first room in your game. diff --git a/docs/latest/Functions-(Loading-Sound-Assets).md b/docs/latest/Functions-(Loading-Sound-Assets).md index fd265da..ced9751 100644 --- a/docs/latest/Functions-(Loading-Sound-Assets).md +++ b/docs/latest/Functions-(Loading-Sound-Assets).md @@ -14,13 +14,13 @@ Loads an audio file from disk into memory, ready to be instantiated as a sound i   -## `~_StaticSound_CreateSoundInstance()` +## `~_StaticSound_CreateSoundInstance(staticSoundID)` **Returns:** Number, a **sound instance ID** |Argument |Datatype|Description | |---------------|--------|-------------------------------------------------------------------------| -|`staticSoundID`|number |Static sound to instantiate, as created by `FAudio_StaticSound_LoadWav()`| +|`staticSoundID`|number |Static sound to instantiate, as created by `FAudio_StaticSound_LoadWAV()`| Creates a sound instance that can be manipulated individually. Please see the [Sound Instances](Functions-(Sound-Instances)) page for commands specific to sound instances. @@ -40,16 +40,19 @@ Frees memory associated with the given static sound.   -## `~_StreamingSound_LoadOGG(filePath)` +## `~_StreamingSound_LoadOGG(filePath, bufferSizeInBytes)` **Returns:** Number, a **sound instance ID** -|Argument |Datatype|Description | -|----------|--------|------------------------------------------------------| -|`filePath`|string |Path to the audio file to stream | +|Argument |Datatype|Description | +|-------------------|--------|-----------------------------------------------------------| +|`filePath` |string |Path to the audio file to stream | +|`bufferSizeInBytes`|number |Stream buffer size, passing 0 will pick a sensible default.| Sets up an audio file on disk to be streamed. This is immediately converted into a sound instance ID that you can manipulate and play using the [Sound Instance](Functions-(Sound-Instances)) functions. +To prevent stutters the sound stream will be buffered, the size of the buffer is determined by the `bufferSizeInBytes` argument, passing 0 will pick a sensible default size. + ?> Audio loaded by this function must be an [.ogg file](https://en.wikipedia.org/wiki/Ogg). Please note that this function returns a sound instance ID (rather than a static sound ID). !> It is not recommended to try to stream the same .ogg file twice at the same time. \ No newline at end of file diff --git a/docs/latest/Functions-(Sound-Instances).md b/docs/latest/Functions-(Sound-Instances).md index 07b5d9a..d76bee8 100644 --- a/docs/latest/Functions-(Sound-Instances).md +++ b/docs/latest/Functions-(Sound-Instances).md @@ -132,6 +132,24 @@ Sets the velocity of the sound instance, allowing for pitch shifting to emulate   +## `~_SoundInstance_Set3DOrientation(soundInstanceID, xFront, yFront, zFront, xTop, yTop, zTop)` + +**Returns:** N/A (`undefined`) + +|Argument |Datatype|Description | +|-----------------|--------|-----------------------------------------------------------------| +|`soundInstanceID`|number |Sound instance to target | +|`xFront` |number |x-component of the front orientation vector of the sound instance| +|`yFront` |number |y-component of the front orientation vector of the sound instance| +|`zFront` |number |z-component of the front orientation vector of the sound instance| +|`xTop` |number |x-component of the top orientation vector of the sound instance | +|`yTop` |number |y-component of the top orientation vector of the sound instance | +|`zTop` |number |z-component of the top orientation vector of the sound instance | + +Sets the 3D orientation of the sound instance expressed as front and top vectors. + +  + ## `~_SoundInstance_SetTrackPositionInSeconds(soundInstanceID, trackPositionInSeconds)` **Returns:** N/A (`undefined`) @@ -217,6 +235,19 @@ Sets a band-pass filter on a sound instance, cutting out frequencies above and b   +## `~_SoundInstance_QueueSoundInstance(soundInstanceID, queueSoundInstanceID)` + +**Returns:** N/A (`undefined`) + +|Argument |Datatype|Description | +|----------------------|--------|--------------------------------------------------------------------------| +|`soundInstanceID` |number |Sound instance to target | +|`queueSoundInstanceID`|number |Sound instance to queue | + +Queues a `queueSoundInstanceID` sound instance to play after the `soundInstanceID`. + +  + ## `~_SoundInstance_GetPitch(soundInstanceID)` **Returns:** Number, the pitch of the sound instance, with `1` being no pitch shift