[examples] Review audio examples audio_raw_stream(split) and audio_sound_loading to add more clarity

[meisei4]

Review audio examples to provide more clarity

I was encountering many time-consuming audio specification issues in my own tests and so I thought things could be improved documentation-wise in this area. My idea is simply updating the following examples to be a little more clear/expressive with how raudio.c works, especially in relation to the Update related functions.

NOTE: the main diff for this reviewing this PR is:b3c2518 because it allows you to see how the original audio_raw_stream was updated after it was COPIED/SPLIT for both manual and callbacks variations.

audio_raw_stream: (manual) diff with original

1. fix the commented out code styling of this example -> split the manual and the callback into two separate examples
2. fix the wavelength discrepancy between callback and manual (manual resulted in an octave pitch higher than callback version):
   waveLength = (int)(22050/frequency); to waveLength = (int)(stream.sampleRate/frequency); <- this will use 44100 via sampleRate

audio_raw_stream_callback: diff with original

1. add more clarity with coverage/new callback options (ESPECIALLY TO ALLOW FOR TESTING PROBLEMATIC BEHAVIOR)
2. add simple toggle between callbacks specifications

---

audio_sound_loading

1. there was no usage of UpdateSound anywhere in the raylib codebase, so I added a simple reversal effect using that function in the existing audio_load_sound example. If this is inappropriate then perhaps UpdateSound as a function should be removed from raudio? as it is never used and just calls StopAudioBuffer and memcpy (which is very different behavior than something like UpdateAudioStream, and AudioProcessors take care of all the sort of effects you can do on sounds anyways i believe)
2. There may be some need for documentation improvements with Sound always setting stream specifications 'sampleSizeto32`, and channels as stereo, so I also thought it would be helpful to have this example for showing that updating sound you need to also always match those specs between any scratch data you want to work with

• ^^Sounds always have 32-bit sampleSize (code refs)
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L961 — LoadSoundFromWave 32 sampleSize
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L289 — raudio.c AUDIO_DEVICE_FORMAT 32
  • https://github.com/raysan5/raylib/blob/master/src/config.h#L277 — config.h AUDIO_DEVICE_FORMAT 32
• Sounds always have stereo channels (code refs)
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L962 — LoadSoundFromWave return channels as stereo
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L292 — raudio.c AUDIO_DEVICE_CHANNELS 2
  • https://github.com/raysan5/raylib/blob/master/src/config.h#L278 — config.h AUDIO_DEVICE_CHANNELS 2

Also since it provides really simple opportunity to demonstrate how strict the Sound streams are, I believe it is appropriate to add to this bare mininum load sound example, rather than try to add it somewhere else.

[raysan5]

@meisei4 I prefer to avoid changing audio_load_sound and keep it simple as it was.

[meisei4]

@raysan5 I have reverted the changes for that example. But i wanted to confirm that Sounds are intentionally always sampleSize of 32 and channeled to stereo?

The issue i encountered here was from trying to figure out how to use the UpdateSound function. Where now i am confused as to why the function exists actually, being that its just a memcpy that can result in issues if you are not careful with the exact specification of the audio data you are working with (must be exactly same formatting and size as the sound you are updating). I think it is something that is not very clear in comparison to the flexibility of what being an AudioStream wrapper could allow (and what Music and raw audio streams do allow)

[raysan5]

But i wanted to confirm that Sounds are intentionally always sampleSize of 32 and channeled to stereo?

No, afair, it is dependand on the loaded sound. About UpdateSound(), it is like UpdateTexture(), it's up to the user to provide data in the correct format.

[meisei4]

it is dependent on the loaded sound. About UpdateSound(), it is like UpdateTexture(), it's up to the user to provide data in the correct format.

I see, so then i think there might be an issue here in expected behavior. Because UpdateSound, and Sound in general (loading and then any processing) is enforcing (implicitly) 32 bit and stereo specifications according to my understanding from this investigation:

• Sounds always have 32-bit sampleSize (code refs)
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L961 — LoadSoundFromWave 32 sampleSize
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L289 — raudio.c AUDIO_DEVICE_FORMAT 32
  • https://github.com/raysan5/raylib/blob/master/src/config.h#L277 — config.h AUDIO_DEVICE_FORMAT 32
• Sounds always have stereo channels (code refs)
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L962 — LoadSoundFromWave return channels as stereo
  • https://github.com/raysan5/raylib/blob/master/src/raudio.c#L292 — raudio.c AUDIO_DEVICE_CHANNELS 2
  • https://github.com/raysan5/raylib/blob/master/src/config.h#L278 — config.h AUDIO_DEVICE_CHANNELS 2

So far in this area there has only been an addition in the form of commented warnings (thanks to @AmityWilder for helping me discover this behavior: #5031). It was being encountered over in the rust bindings initially: raylib-rs/raylib-rs#212

@raysan5 I am wondering if you would like for this to be updated such that Sound can be configured to behave as flexibly as raw AudioStream and Music? (allowing for both Mono and Stereo channeling and then 8, 16, and 32 bit depths etc?)