Let play return SoundFile&

Author: jhasse

src/jngl/SoundFile.cpp

@@ -94,9 +94,7 @@ SoundFile::SoundFile(const std::string& filename, std::launch)
 		           // fclose() the FILE * pointer itself.
 		throw std::runtime_error("Could not open OGG file (" + filename + ").");
 	}
-	Finally cleanup(
-	    [&oggFile]()
-	    {
+	Finally cleanup([&oggFile]() {
 		ov_clear(&oggFile); /* calls fclose */
 	});
 
@@ -262,8 +260,10 @@ std::shared_ptr<SoundFile> Audio::getSoundFile(std::string_view filename, std::l
 	    .first->second;
 }
 
-void play(const std::string& filename) {
-	Audio::handle().getSoundFile(filename, std::launch::deferred)->play();
+SoundFile& play(const std::string& filename) {
+	auto soundFile = Audio::handle().getSoundFile(filename, std::launch::deferred);
+	soundFile->play();
+	return *soundFile;
 }
 
 void stop(const std::string& filename) {

src/jngl/sound.hpp

@@ -18,7 +18,12 @@ float getVolume();
 /// Play an OGG audio file once
 ///
 /// Might block if the file hasn't been played before. To avoid that use jngl::load before.
-void play(const std::string& filename);
+///
+/// Example:
+/// \code
+/// jngl::play("sfx/foo.ogg").setVolume(0.2);
+/// \endcode
+SoundFile& play(const std::string& filename);
 
 /// Stop an OGG audio file if it's currently playing
 void stop(const std::string& filename);