Review multichannel PR addition

- Capital letters at beginning
- for loop spacing and brackets
- Functions naming for consistency
- Example following examples template
- Other tweaks

4 files changed, 112 insertions, 122 deletions

diff --git a/examples/audio/audio_multichannel_sound.c b/examples/audio/audio_multichannel_sound.c
index 42c71704..f3db341e 100644
--- a/examples/audio/audio_multichannel_sound.c
+++ b/examples/audio/audio_multichannel_sound.c
@@ -1,25 +1,17 @@
-
-/*
-* This example was coded to demonstrate multi channel audio changes added to raylib
+/*******************************************************************************************
+*
+*   raylib [audio] example - Multichannel sound playing
 *
-*   This example has been created using raylib (www.raylib.com)
+*   This example has been created using raylib 2.6 (www.raylib.com)
 *   raylib is licensed under an unmodified zlib/libpng license (View raylib.h for details)
 *
-*   This example Copyright (c) 2018 Chris Camacho (codifies) http://bedroomcoders.co.uk/captcha/
+*   Example contributed by Chris Camacho (@codifies) and reviewed by Ramon Santamaria (@raysan5)
 *
-* THIS EXAMPLE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-* OTHER DEALINGS IN THE SOFTWARE.
+*   Copyright (c) 2019 Chris Camacho (@codifies) and Ramon Santamaria (@raysan5)
 *
-* This example may be freely redistributed.
-*/
+********************************************************************************************/
 
 #include "raylib.h"
-#include <stdio.h> // sprintf
 
 int main(void)
 {
@@ -28,69 +20,65 @@ int main(void)
     const int screenWidth = 800;
     const int screenHeight = 450;
 
-    InitWindow(screenWidth, screenHeight, "raylib [audio] abuse!");
+    InitWindow(screenWidth, screenHeight, "raylib [audio] example - Multichannel sound playing");
 
     InitAudioDevice();      // Initialize audio device
 
     Sound fxWav = LoadSound("resources/sound.wav");         // Load WAV audio file
     Sound fxOgg = LoadSound("resources/tanatana.ogg");      // Load OGG audio file
-
-
-    //InitPlayBufferPool();
-
-
-
-    SetTargetFPS(60);               // Set our game to run at 60 frames-per-second
-    //--------------------------------------------------------------------------------------
+    
     int frame = 0;
-    // Main game loop
 
-    // old system still works alongside
-    SetSoundVolume(fxWav, 0.2); // effects all mutltiplay replay (really annoying sound!!!)
+    SetSoundVolume(fxWav, 0.2);
     PlaySound(fxOgg);
 
     bool inhibitWav = false;
     bool inhibitOgg = false;
     int maxFrame = 60;
-    int numberPlaying = 0;
+    
+    int soundsCounter = 0;
+
+    SetTargetFPS(60);       // Set our game to run at 60 frames-per-second
+    //--------------------------------------------------------------------------------------
 
+    // Main game loop
     while (!WindowShouldClose())    // Detect window close button or ESC key
     {
         // Update
         //----------------------------------------------------------------------------------
         frame++;
 
-        if (IsKeyDown(KEY_ENTER)) { inhibitWav=true; } else { inhibitWav=false; }
-        if (IsKeyDown(KEY_SPACE)) { inhibitOgg=true; } else { inhibitOgg=false; }
+        if (IsKeyDown(KEY_ENTER)) inhibitWav = !inhibitWav;
+        if (IsKeyDown(KEY_SPACE)) inhibitOgg = !inhibitOgg;
 
-        // deliberatly hammer the play pool to see what dropping old
-        // pool entries sounds like....
-        if (frame % 5==0) {
-           if (!inhibitWav) PlaySoundEx(fxWav);
+        // Deliberatly hammer the play pool to see what dropping old pool entries sounds like....
+        if ((frame%5) == 0) 
+        {
+           if (!inhibitWav) PlaySoundMulti(fxWav);
         }
-        if (frame==maxFrame) {
-            if (!inhibitOgg) PlaySoundEx(fxOgg);
-            frame=0;
+        
+        if (frame == maxFrame) 
+        {
+            if (!inhibitOgg) PlaySoundMulti(fxOgg);
+            
+            frame = 0;
             maxFrame = GetRandomValue(6,12);
         }
 
-        numberPlaying = ConcurrentPlayChannels();
-
+        soundsCounter = GetSoundsPlaying();
         //----------------------------------------------------------------------------------
 
-
         // Draw
         //----------------------------------------------------------------------------------
         BeginDrawing();
 
             ClearBackground(RAYWHITE);
-            char msg[1024];
-            DrawText("multichannel sound abuse!", 200, 180, 20, LIGHTGRAY);
+            
+            DrawText("Multichannel sound abuse!", 200, 180, 20, LIGHTGRAY);
             DrawText("Space to inhibit new ogg triggering", 200, 200, 20, LIGHTGRAY);
             DrawText("Enter to inhibit new wav triggering", 200, 220, 20, LIGHTGRAY);
 
-            sprintf(msg,"concurrently playing %i", numberPlaying);
-            DrawText(msg, 200, 280, 20, LIGHTGRAY);
+            DrawText(FormatText("Number of concurrentsounds: %i", soundsCounter), 200, 280, 20, LIGHTGRAY);
 
         EndDrawing();
         //----------------------------------------------------------------------------------
@@ -98,11 +86,7 @@ int main(void)
 
     // De-Initialization
     //--------------------------------------------------------------------------------------
-
-
-    // you MUST stop the buffer pool before unloading
-    // any Sounds it might have used...
-    StopPlayBufferPool();
+    StopSoundMulti();       // We must stop the buffer pool before unloading
 
     UnloadSound(fxWav);     // Unload sound data
     UnloadSound(fxOgg);     // Unload sound data
diff --git a/src/raudio.c b/src/raudio.c
index 2008c2bf..4d44978a 100644
--- a/src/raudio.c
+++ b/src/raudio.c
@@ -207,7 +207,7 @@ void TraceLog(int msgType, const char *text, ...);              // Show trace lo
 #endif
 
 //----------------------------------------------------------------------------------
-// miniaudio AudioBuffer Functionality
+// AudioBuffer Functionality
 //----------------------------------------------------------------------------------
 #define DEVICE_FORMAT       ma_format_f32
 #define DEVICE_CHANNELS     2
@@ -269,24 +269,21 @@ void SetAudioBufferPitch(AudioBuffer *audioBuffer, float pitch);
 void TrackAudioBuffer(AudioBuffer *audioBuffer);
 void UntrackAudioBuffer(AudioBuffer *audioBuffer);
 
-
 //----------------------------------------------------------------------------------
-// multi channel playback globals
+// Multi channel playback globals
 //----------------------------------------------------------------------------------
 
-// number of channels in the pool
-#define PLAY_POOL_SIZE 16
-
-// the buffer pool
-AudioBuffer* PlayBufferPool[PLAY_POOL_SIZE];
+// Number of channels in the audio pool
+#define MAX_AUDIO_BUFFER_POOL_CHANNELS 16
 
-// these are used to determine the oldest playing channel
-unsigned long PlayPoolAge = 0;
-unsigned long PlayPoolAges[PLAY_POOL_SIZE] = {0};
+// Audio buffer pool
+AudioBuffer *audioBufferPool[MAX_AUDIO_BUFFER_POOL_CHANNELS] = { 0 };
 
+// These are used to determine the oldest playing channel
+unsigned long audioBufferPoolCounter = 0;
+unsigned long audioBufferPoolChannels[MAX_AUDIO_BUFFER_POOL_CHANNELS] = { 0 };
 //----------------------------------------------------------------------------------
 
-
 // Log callback function
 static void OnLog(ma_context *pContext, ma_device *pDevice, ma_uint32 logLevel, const char *message)
 {
@@ -481,12 +478,13 @@ static void MixAudioFrames(float *framesOut, const float *framesIn, ma_uint32 fr
     }
 }
 
-// initialise the multichannel buffer pool
-static void InitPlayBufferPool()
+// Initialise the multichannel buffer pool
+static void InitAudioBufferPool()
 {
-    // dummy buffers
-    for (int i=0; i<PLAY_POOL_SIZE; i++) {
-        PlayBufferPool[i] = CreateAudioBuffer(DEVICE_FORMAT, DEVICE_CHANNELS, DEVICE_SAMPLE_RATE, 0, AUDIO_BUFFER_USAGE_STATIC);
+    // Dummy buffers
+    for (int i = 0; i < MAX_AUDIO_BUFFER_POOL_CHANNELS; i++) 
+    {
+        audioBufferPool[i] = CreateAudioBuffer(DEVICE_FORMAT, DEVICE_CHANNELS, DEVICE_SAMPLE_RATE, 0, AUDIO_BUFFER_USAGE_STATIC);
     }
 }
 
@@ -554,17 +552,17 @@ void InitAudioDevice(void)
     TraceLog(LOG_INFO, "Audio sample rate: %d -> %d", device.sampleRate, device.playback.internalSampleRate);
     TraceLog(LOG_INFO, "Audio buffer size: %d", device.playback.internalBufferSizeInFrames);
 
-    InitPlayBufferPool();
-    TraceLog(LOG_INFO, "Audio multichannel pool size: %i", PLAY_POOL_SIZE);
+    InitAudioBufferPool();
+    TraceLog(LOG_INFO, "Audio multichannel pool size: %i", MAX_AUDIO_BUFFER_POOL_CHANNELS);
 
     isAudioInitialized = MA_TRUE;
 }
 
 // internal
-static void FreePlayBufferPool() {
-    for (int i = 0; i < PLAY_POOL_SIZE; i++) {
+static void FreeaudioBufferPool() {
+    for (int i = 0; i < MAX_AUDIO_BUFFER_POOL_CHANNELS; i++) {
         // NB important free only the buffer struct not the attached data...!
-        RL_FREE(PlayBufferPool[i]);
+        RL_FREE(audioBufferPool[i]);
     }
 }
 
@@ -582,7 +580,7 @@ void CloseAudioDevice(void)
     ma_device_uninit(&device);
     ma_context_uninit(&context);
 
-    FreePlayBufferPool();
+    FreeaudioBufferPool();
 
     TraceLog(LOG_INFO, "Audio device closed successfully");
 }
@@ -1010,79 +1008,87 @@ void PlaySound(Sound sound)
     PlayAudioBuffer((AudioBuffer *)sound.audioBuffer);
 }
 
-// play a sound in the multichannel buffer pool
-void PlaySoundEx(Sound s)
+// Play a sound in the multichannel buffer pool
+void PlaySoundMulti(Sound sound)
 {
-    int found = -1;
+    int index = -1;
     unsigned long oldAge = 0;
     int oldIndex = -1;
 
     // find the first non playing pool entry
-    for (int i=0; i<PLAY_POOL_SIZE; i++) {
-        if (PlayPoolAges[i] > oldAge) {
-            oldAge = PlayPoolAges[i];
+    for (int i = 0; i < MAX_AUDIO_BUFFER_POOL_CHANNELS; i++)
+    {
+        if (audioBufferPoolChannels[i] > oldAge)
+        {
+            oldAge = audioBufferPoolChannels[i];
             oldIndex = i;
         }
-        if (!IsAudioBufferPlaying(PlayBufferPool[i])) {
-            found = i;
+        
+        if (!IsAudioBufferPlaying(audioBufferPool[i]))
+        {
+            index = i;
             break;
         }
     }
 
-    // if no none playing pool members can be found choose the oldest
-    if (found == -1) {
-        TraceLog(LOG_WARNING,"pool age %i ended a sound early no room in buffer pool",PlayPoolAge);
-        if (oldIndex == -1) {
-            // shouldn't be able to get here... but just in case something odd happens!
+    // If no none playing pool members can be index choose the oldest
+    if (index == -1)
+    {
+        TraceLog(LOG_WARNING,"pool age %i ended a sound early no room in buffer pool", audioBufferPoolCounter);
+        
+        if (oldIndex == -1)
+        {
+            // Shouldn't be able to get here... but just in case something odd happens!
             TraceLog(LOG_ERROR,"sound buffer pool couldn't determine oldest buffer not playing sound");
+            
             return;
         }
-        found = oldIndex;
-        // just in case...
-        StopAudioBuffer(PlayBufferPool[found]);
+        
+        index = oldIndex;
+        
+        // Just in case...
+        StopAudioBuffer(audioBufferPool[index]);
     }
 
-    // experimentally mutex lock doesn't seem to be needed this makes sense
-    // as PlayBufferPool[found] isn't playing and the only stuff we're copying
+    // Experimentally mutex lock doesn't seem to be needed this makes sense
+    // as audioBufferPool[index] isn't playing and the only stuff we're copying
     // shouldn't be changing...
 
-    PlayPoolAges[found] = PlayPoolAge;
-    PlayPoolAge++;
-    PlayBufferPool[found]->volume = ((AudioBuffer*)s.audioBuffer)->volume;
-    PlayBufferPool[found]->pitch = ((AudioBuffer*)s.audioBuffer)->pitch;
-    PlayBufferPool[found]->looping = ((AudioBuffer*)s.audioBuffer)->looping;
-    PlayBufferPool[found]->usage = ((AudioBuffer*)s.audioBuffer)->usage;
-    PlayBufferPool[found]->isSubBufferProcessed[0] = false;
-    PlayBufferPool[found]->isSubBufferProcessed[1] = false;
-    PlayBufferPool[found]->bufferSizeInFrames = ((AudioBuffer*)s.audioBuffer)->bufferSizeInFrames;
-    PlayBufferPool[found]->buffer = ((AudioBuffer*)s.audioBuffer)->buffer;
+    audioBufferPoolChannels[index] = audioBufferPoolCounter;
+    audioBufferPoolCounter++;
+    
+    audioBufferPool[index]->volume = ((AudioBuffer*)sound.audioBuffer)->volume;
+    audioBufferPool[index]->pitch = ((AudioBuffer*)sound.audioBuffer)->pitch;
+    audioBufferPool[index]->looping = ((AudioBuffer*)sound.audioBuffer)->looping;
+    audioBufferPool[index]->usage = ((AudioBuffer*)sound.audioBuffer)->usage;
+    audioBufferPool[index]->isSubBufferProcessed[0] = false;
+    audioBufferPool[index]->isSubBufferProcessed[1] = false;
+    audioBufferPool[index]->bufferSizeInFrames = ((AudioBuffer*)sound.audioBuffer)->bufferSizeInFrames;
+    audioBufferPool[index]->buffer = ((AudioBuffer*)sound.audioBuffer)->buffer;
 
-    PlayAudioBuffer(PlayBufferPool[found]);
+    PlayAudioBuffer(audioBufferPool[index]);
 
 }
 
-// MUST be called before UnLoadSound is used on any sound played with PlaySoundEx
-void StopPlayBufferPool()
+// Stop any sound played with PlaySoundMulti()
+void StopSoundMulti(void)
 {
-    for (int i = 0; i < PLAY_POOL_SIZE; i++) {
-        StopAudioBuffer(PlayBufferPool[i]);
-    }
+    for (int i = 0; i < MAX_AUDIO_BUFFER_POOL_CHANNELS; i++) StopAudioBuffer(audioBufferPool[i]);
 }
 
-// number of sounds playing in the multichannel buffer pool
-int ConcurrentPlayChannels()
+// Get number of sounds playing in the multichannel buffer pool
+int GetSoundsPlaying(void)
 {
-    int n = 0;
-    for (int i=0; i<PLAY_POOL_SIZE; i++) {
-        if (IsAudioBufferPlaying(PlayBufferPool[i])) {
-            n++;
-        }
+    int counter = 0;
+    
+    for (int i = 0; i < MAX_AUDIO_BUFFER_POOL_CHANNELS; i++)
+    {
+        if (IsAudioBufferPlaying(audioBufferPool[i])) counter++;
     }
-    return n;
+    
+    return counter;
 }
 
-
-
 // Pause a sound
 void PauseSound(Sound sound)
 {
diff --git a/src/raudio.h b/src/raudio.h
index 0077d8fa..e032d09b 100644
--- a/src/raudio.h
+++ b/src/raudio.h
@@ -139,12 +139,12 @@ void UpdateSound(Sound sound, const void *data, int samplesCount);// Update soun
 void UnloadWave(Wave wave);                                     // Unload wave data
 void UnloadSound(Sound sound);                                  // Unload sound
 void PlaySound(Sound sound);                                    // Play a sound
-void PlaySoundEx(Sound s);                                      // Play a sound using the multi channel buffer pool
-void StopPlayBufferPool();                                      // MUST be called before UnLoadSound is used on any sound played with PlaySoundEx
-int ConcurrentPlayChannels();                                   // Number of sounds playing in the multichannel buffer pool
+void PlaySoundMulti(Sound sound);                               // Play a sound using the multi channel buffer pool
+int GetSoundsPlaying(void);                                     // Get number of sounds playing in the multichannel buffer pool
 void PauseSound(Sound sound);                                   // Pause a sound
 void ResumeSound(Sound sound);                                  // Resume a paused sound
 void StopSound(Sound sound);                                    // Stop playing a sound
+void StopSoundMulti(void);                                      // Stop any sound played with PlaySoundMulti()
 bool IsSoundPlaying(Sound sound);                               // Check if a sound is currently playing
 void SetSoundVolume(Sound sound, float volume);                 // Set volume for a sound (1.0 is max level)
 void SetSoundPitch(Sound sound, float pitch);                   // Set pitch for a sound (1.0 is base level)
diff --git a/src/raylib.h b/src/raylib.h
index f40a30dc..c3be9d1e 100644
--- a/src/raylib.h
+++ b/src/raylib.h
@@ -1356,12 +1356,12 @@ RLAPI void ExportWaveAsCode(Wave wave, const char *fileName);         // Export
 
 // Wave/Sound management functions
 RLAPI void PlaySound(Sound sound);                                    // Play a sound
-RLAPI void PlaySoundEx(Sound s);                                      // Play a sound using the multi channel buffer pool
-RLAPI void StopPlayBufferPool();                                      // MUST be called before UnLoadSound is used on any sound played with PlaySoundEx
-RLAPI int ConcurrentPlayChannels();                                   // Number of sounds playing in the multichannel buffer pool
+RLAPI void PlaySoundMulti(Sound sound);                               // Play a sound using the multi channel buffer pool
+RLAPI int GetSoundsPlaying(void);                                     // Get number of sounds playing in the multichannel buffer pool
 RLAPI void PauseSound(Sound sound);                                   // Pause a sound
 RLAPI void ResumeSound(Sound sound);                                  // Resume a paused sound
 RLAPI void StopSound(Sound sound);                                    // Stop playing a sound
+RLAPI void StopSoundMulti(void);                                      // Stop any sound played with PlaySoundMulti()
 RLAPI bool IsSoundPlaying(Sound sound);                               // Check if a sound is currently playing
 RLAPI void SetSoundVolume(Sound sound, float volume);                 // Set volume for a sound (1.0 is max level)
 RLAPI void SetSoundPitch(Sound sound, float pitch);                   // Set pitch for a sound (1.0 is base level)