-
Notifications
You must be signed in to change notification settings - Fork 4
Basic Usage
#include <SfmlSoundSystem.hpp>
sss::Control sss;
Note that this object name (sss) will be used throughout this information but any normal name can be used.
The namespace "sss" is separate and is the namespace of the sound system. This is the shortcut namespace; the full namespace is sfmlSoundSystem and the full namespace can always be used. However, if you wish to stop the shortcut namespace from being created (e.g. to avoid a clash with another namespace), you can simply define "SFMLSOUNDSYSTEM_NO_NAMESPACE_SHORTCUT" before including the sound system (i.e.#define SFMLSOUNDSYSTEM_NO_NAMESPACE_SHORTCUT)
Here, we simply inform SSS where the music file is so that it can stream from it:
This does not load the music into memory; it simply opens/links to it so the music file (on file or in memory) needs to stay available as long as it is needed.
sss.openMusic("song 1", "music001.ogg");
sss.openMusic("song 2", "music002.ogg");
sss.openMusic("song 3", "music003.ogg");
sss.openMusic("song 4", "music004.ogg");
sss.openMusic("song 5", "music005.ogg");Of course, you may have loaded (copied) that file into memory. You can open/link that memory block instead of an actual file:
std::vector<char> memoryBlockMusic1;
std::vector<char> memoryBlockMusic2;
std::vector<char> memoryBlockMusic3;
std::vector<char> memoryBlockMusic4;
std::vector<char> memoryBlockMusic5;
/// .. copy files to memory blocks
sss.openMusic("song 1", memoryBlockMusic1);
sss.openMusic("song 2", memoryBlockMusic2);
sss.openMusic("song 3", memoryBlockMusic2);
sss.openMusic("song 4", memoryBlockMusic2);
sss.openMusic("song 5", memoryBlockMusic2);Note that the format of the file must still be completely intact within the memory block so that the memory block acts as a file; SSS simply streams directly from the memory block as if it was a file. To open/link to a memory block, we can pass a reference of a vector of chars. You must remember this; you may want to create the memory block as a vector of chars (simpler and safe) or reinterpret a different memory block.
With the sounds (for effects, for example), we do actually load the sounds into sound buffers within the sound system. This means that the sounds are all stored within SSS and do not link elsewhere.
You can load the from a file or a memory block (as with music above) but you can also load them from already existing sound buffers. This allows you to set up and process sound buffers separately and then copy them into SSS, ready to play.
sss.loadBuffer("sound 1", "sound001.wav");
sss.loadBuffer("sound 2", "sound002.wav");
sss.loadBuffer("sound 3", "sound003.wav");
sss.loadBuffer("sound 4", "sound004.wav");
sss.loadBuffer("sound 5", "sound005.wav");As above with the musics, you can load from a memory block in the same way by replacing the filename with a reference to a vector of chars.
To copy from existing sound buffers, simply replace the filename with a reference to an sf::SoundBuffer.
You can assign default maximum volumes to each sound and each music. This may not be necessary; they default to full volume.
sss.assignVolumeMusic("song 1", 0.2f);
sss.assignVolumeMusic("song 2", 0.5f);
sss.assignVolumeMusic("song 3", 0.3f);
sss.assignVolumeMusic("song 4", 1.f);
sss.assignVolumeMusic("song 5", 0.25f);
sss.assignVolumeSound("sound 1", 0.4f);
sss.assignVolumeSound("sound 2", 1.f);
sss.assignVolumeSound("sound 3", 0.7f);
sss.assignVolumeSound("sound 4", 1.f);
sss.assignVolumeSound("sound 5", 1.f);That's it for the set-up! Pretty simple, eh?! ;)
You simply play a sound by telling SSS to play the sound with the relavant ID (the string ID you assigned to the sound during the loading process):
sss.playSound("sound 1");
You can add additional information to the sound (each parameter has a default so you can specify however many you need). The volume provided here is multiplied with the previous global/default volume for that sound. The position (positionOffset3d) here is an sf::Vector3f:
sss.playSound("sound 1", sf::Vector2f(70.f, 20.f, 50.f), 0.7f); // ID, position, volume. You can also provide an sf::Vector2f for the position; the z becomes effectively zero (it's technically a very small positive value).
You can play any of the musics by giving SSS the ID of the music you'd like to play:
sss.playMusic("song 1");
Again, you can add additional information to the music (again, each parameter has a default). Again, the volume provided here is multiplied by the previous global/default volume for that music; the transition is an sf::Time (default is zero so there is no transition unless you provide a time):
ss.playMusic("song 1", sf::seconds(2.f), 0.6f);
You can stop everything in SSS by using:
sss.stopAll();
You can also stop all sounds (effect etc.) without affecting the music by using:
sss.stopFx();
To stop all music but do not affect the sounds that are currently playing, you can use:
sss.stopMusic();
You can pause music:
sss.pauseMusic();
You can resume previous paused music:
sss.resumeMusic();
Pause has no effect on already paused music and resume has no effect on music that is not paused.
sss.restartMusic();
Restarting music will start the current music playing from the beginning. This will occur whether the music is already playing, currently paused or has been stopped.
When playing sounds, they play in poly-phony - they play together, not stopping the others. There is, however, a maximum number of sounds that can be played at once and if that is exceeded, the new sound will not be played (and playSound returns a false value).
The default number of voices (sounds playing at once) is 64. You can set this maximum to any value you would like if you need very many sounds to play at once or just want to restrict the number:
sss.setMaxNumberOfVoices(128u);
The sound system should be updated on each cycle (basically, as often as possible) as this allows the music to perform its cross-fade.
You can ignore the update if you do not use the musics and only use the sounds. However, if you use the music, you must perform the updates otherwise the music will stay silent.
If you definitely don't use any fades in the music, you can perform the update immediately after playing the music without a need to perform the update every cycle; however, the update is a very 'light' piece of code so can be comfortably performed every cycle without any issues.
You can get information from SSS about certain things going on inside it.
To get the current playing position of the music currently playing:
sf::Time currentMusicTime{ sss.getCurrentMusicPosition() };
To get the currently set maximum number of voices:
std::size_t maxVoices{ sss.getMaxNumberOfVoices };
To get the ID of the currently playing music:
std::string musicId = sss.getCurrentMusic();
To get the current status of the current music:
sf::SoundSource::Status currentMusicStatus{ getCurrentMusicStatus() };
To get the current number of sounds playing:
std::size_t numberOfSoundsPlaying{ sss.getNumberOfSoundPlaying };
To find out whether or not the current music is currently paused:
bool isMusicCurrentlyPaused{ sss.getIsCurrentlyPaused() };
To get a direct reference to the sound buffer stored by SSS:
sf::SoundBuffer& soundBuffer{ sss.getBuffer("sound 1") };