Merge pull request #54 from hexaheximal/unstable

Implement an audio portability API

docs/en/audio.md

@@ -15,11 +15,15 @@
 
 * <a name="playsound"></a>**`playSound( sound, loops )`**
 
-  Plays a sound that repeats as many times as defined by `loops`. If `-1` is used, the sound will loop until stopped. Returns the channel number of the sound being played. If looping, the return value should be stored in order to stop it later.
+  Plays a sound that repeats as many times as defined by `loops`.  
+
+  If `-1` is used, the sound will loop until stopped. Returns the channel number of the sound being played. If looping, the return value should be stored in order to stop it later.
 
 * <a name="playmusic"></a>**`playMusic( music, loops )`**
 
-  Plays a music track and repeats as many times as `loops` says. Unlike with sound, it does not return a channel since only one music track can play at once.
+  Plays a music track and repeats as many times as `loops` says.  
+
+  Unlike with sound, it does not return a channel since only one music track can play at once.
 
 * <a name="deletesound"></a>**`deleteSound( sound )`**
 
@@ -83,4 +87,18 @@
 
 * <a name="getSoundVolume"></a>**`getSoundVolume()`**
 
-  Returns the current sound volume with an integer between 0 and 128.
+  Returns the current sound volume with an integer between 0 and 128.
+
+* <a name="getAudioDriver"></a>**`getAudioDriver()`**
+
+  Returns the name of the currently active audio driver.  
+
+  If no audio driver is present, this will return the string `None`.  
+
+  Note that `None` actually is an audio driver (see `src/audio/audio_none.cpp`), but it does not actually handle audio and is only used as a fallback.
+
+* <a name="isAudioAvailable"></a>**`isAudioAvailable()`**
+
+  Checks if audio playback is currently available.  
+
+  Note that this function's implementation currently does not check that the audio stack is working, it only checks that a real audio driver (not the fallback `None` driver, which doesn't actually handle audio) is present.

docs/en/fileio.md

@@ -76,10 +76,6 @@
   The intended usage of this function is by providing the result of `getPrefDir()` as a parameter. This usage allows setting a proper writing directory for the game.
   By default, Brux uses the `brux` (or `brux/brux`) user-and-app specific directory for writing.
 
-* <a name="chdir"></a>**`chdir( string )`**
-
-  Attempts to change the current working directory.
-
 * <a name="lsdir"></a>**`lsdir( string )`**
 
   Returns a list of the directory `string`'s contents as an array.

rte/CMakeLists.txt

@@ -4,13 +4,46 @@ project(brux)
 set(CMAKE_CXX_STANDARD 17)
 
 # Set initial variables
+
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 set(INSTALL_SUBDIR_BIN "/")
 
 # Define options
+
 option(BUILD_STATIC_LIBS "Link libraries statically whenever possible" OFF)
 
+find_package(SDL2_mixer QUIET)
+
+# Enable USE_SDL2_MIXER by default if SDL2_mixer is found
+
+if (SDL2_mixer_FOUND)
+  option(USE_SDL2_MIXER "Use SDL2 to provide audio support" ON)
+else()
+  option(USE_SDL2_MIXER "Use SDL2 to provide audio support" OFF)
+  message(STATUS "Could NOT find SDL2 Mixer, disabling audio support")
+endif()
+
+# Please don't disable this unless you have a specific reason to.
+# fastfill is significantly faster than the original algorithm, as it's O(1) instead of O(n).
+
+if (USE_SDL2_MIXER)
+  option(USE_FASTFILL "Use an O(1) algorithm for replacing unloaded sounds with new sounds instead of the original O(n) algorithm" ON)
+endif()
+
+if (USE_SDL2_MIXER)
+  set(AUDIO_SOURCE src/audio/audio_sdl2.cpp)
+else()
+  set(AUDIO_SOURCE src/audio/audio_none.cpp)
+endif()
+
+# preprocess config.hpp, used for optional libraries
+
+configure_file(src/config.hpp.in config.hpp)
+
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+
 # Set runtime output directory for Visual Studio and others.
+
 if(MSVC)
   set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG "Debug")
   set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE "Release")
@@ -20,27 +53,32 @@ if(MSVC)
 else()
   set(RUNTIME_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_RUNTIME_OUTPUT_DIRECTORY}")
 endif()
+
 set(CMAKE_INSTALL_PREFIX "${RUNTIME_OUTPUT_DIR}")
 
 # Prefer static linking, whenever possible
+
 if(BUILD_STATIC_LIBS)
   set(CMAKE_FIND_LIBRARY_SUFFIXES .lib .a ${CMAKE_FIND_LIBRARY_SUFFIXES})
 endif()
 
 # Required includes
+
 include(ExternalProject)
 include(CheckSymbolExists)
 
 # Find/provide packages
+
 find_package(SDL2 REQUIRED)
 find_package(SDL2_image REQUIRED)
 find_package(SDL2_gfx REQUIRED)
-find_package(SDL2_mixer REQUIRED)
-find_package(SDL2_net REQUIRED)
+
 include(ProvidePhysFS)
 include(ProvideSquirrel)
 
 # If static linking is enabled, link additional libraries
+# Also, look at all of the dependencies it uses. This is one of the reasons why the portability API exists.
+
 if(BUILD_STATIC_LIBS)
   # SDL2::Image libraries
   find_package(JPEG REQUIRED)
@@ -54,13 +92,16 @@ if(BUILD_STATIC_LIBS)
   target_link_libraries(SDL2::Image INTERFACE ${JPEG_LIBRARIES} ${PNG_LIBRARIES} ${TIFF_LIBRARIES} ${LZMA_LIBRARIES} ${zstd_LIBRARIES} ${JBIG_LIBRARIES} ${Deflate_LIBRARIES} ${WebP_LIBRARIES})
 
   # SDL2::Mixer libraries
-  find_package(OGG REQUIRED)
-  find_package(FLAC REQUIRED)
-  find_package(Modplug REQUIRED)
-  find_package(MPG123 REQUIRED)
-  find_package(VORBIS REQUIRED)
-  find_package(OpusFile REQUIRED)
-  target_link_libraries(SDL2::Mixer INTERFACE ${FLAC_LIBRARY} fluidsynth ${MODPLUG_LIBRARIES} ${MPG123_LIBRARIES} ${VORBIS_LIBRARIES} ${OPUSFILE_LIBRARIES} ${OGG_LIBRARIES})
+
+  if (USE_SDL2_MIXER)
+    find_package(OGG REQUIRED)
+    find_package(FLAC REQUIRED)
+    find_package(Modplug REQUIRED)
+    find_package(MPG123 REQUIRED)
+    find_package(VORBIS REQUIRED)
+    find_package(OpusFile REQUIRED)
+    target_link_libraries(SDL2::Mixer INTERFACE ${FLAC_LIBRARY} fluidsynth ${MODPLUG_LIBRARIES} ${MPG123_LIBRARIES} ${VORBIS_LIBRARIES} ${OPUSFILE_LIBRARIES} ${OGG_LIBRARIES})
+  endif()
 endif()
 
 # Include additional scripts
@@ -73,26 +114,33 @@ include_directories("${CMAKE_CURRENT_SOURCE_DIR}/src")
 # Search for source files and copy the test suite to the output directory
 file(GLOB SRCFILES src/api/*.cpp
                    src/brux/*.cpp
+                   ${AUDIO_SOURCE}
                    src/external/*.c
                    src/squirrel/*.cpp
                    src/squirrel/wrapper.cpp)
 add_executable(brux ${SRCFILES})
 file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/test/" DESTINATION "${RUNTIME_OUTPUT_DIR}")
 
 # Link libraries
+
 if(WIN32) # FIXME: Proper way of having the SDL2 libraries copied over to binary on Windows?
   target_link_libraries(brux PUBLIC ${SDL2_LIBRARIES})
   target_link_libraries(brux PUBLIC ${SDL2_IMAGE_LIBRARIES})
   target_link_libraries(brux PUBLIC ${SDL2_GFX_LIBRARIES})
-  target_link_libraries(brux PUBLIC ${SDL2_MIXER_LIBRARIES})
-  target_link_libraries(brux PUBLIC ${SDL2_NET_LIBRARIES})
+
+  if (USE_SDL2_MIXER)
+    target_link_libraries(brux PUBLIC ${SDL2_MIXER_LIBRARIES})
+  endif()
 else()
   target_link_libraries(brux PUBLIC SDL2)
   target_link_libraries(brux PUBLIC SDL2::Image)
   target_link_libraries(brux PUBLIC SDL2::GFX)
-  target_link_libraries(brux PUBLIC SDL2::Mixer)
-  target_link_libraries(brux PUBLIC SDL2::Net)
+
+  if (USE_SDL2_MIXER)
+    target_link_libraries(brux PUBLIC SDL2::Mixer)
+  endif()
 endif()
+
 target_link_libraries(brux PUBLIC LibPhysfs)
 target_link_libraries(brux PUBLIC LibSquirrel)
 target_link_libraries(brux PUBLIC LibSqstdlib)

rte/src/api/audio.cpp

@@ -1,6 +1,7 @@
 //  Brux - Audio API
 //  Copyright (C) 2016 KelvinShadewing
-//                2023 Vankata453
+//  Copyright (C) 2023 Vankata453
+//  Copyright (C) 2023 hexaheximal
 //
 //  This program is free software: you can redistribute it and/or modify
 //  it under the terms of the GNU Affero General Public License as published by
@@ -19,7 +20,7 @@
 
 #include "brux/main.hpp"
 
-#include "brux/audio.hpp"
+#include "audio/audio.hpp"
 #include "brux/global.hpp"
 
 namespace BruxAPI {
@@ -37,30 +38,15 @@ int loadMusic(const std::string& m) {
 }
 
 int playSound(int s, int l) {
-	const int c = xyPlaySound(s, l);
-	if (c != -1)
-		Mix_Volume(c, gvVolumeSound);
-
-	return c;
+	return xyPlaySound(s, l);
 }
 
 int playSoundChannel(int s, int l, int c) {
-	const int i = Mix_PlayChannel(c, vcSounds[s], l);
-	if (i == -1) {
-		std::stringstream err;
-		err << "Error playing sound! SDL_Mixer Error: " << Mix_GetError() << std::endl;
-		throw std::runtime_error(err.str());
-	}
-	else {
-		Mix_Volume(i, gvVolumeSound);
-	}
-
-	return i;
+	return xyPlaySoundChannel(s, l, c);
 }
 
 void playMusic(int m, int l) {
 	xyPlayMusic(m, l);
-	Mix_VolumeMusic(gvVolumeMusic);
 }
 
 void deleteSound(int s) {
@@ -76,44 +62,44 @@ void stopSound(int s) {
 }
 
 void stopMusic() {
-	Mix_HaltMusic();
+	xyStopMusic();
 }
 
 void stopChannel(int c) {
-	Mix_HaltChannel(c);
+	xyStopChannel(c);
 }
 
 bool checkSound(int c) {
-	return Mix_Playing(c);
+	return xyCheckSound(c);
 }
 
 bool checkMusic() {
-	return Mix_PlayingMusic();
+	return xyCheckMusic();
 }
 
 void setMaxChannels(int c) {
-	Mix_AllocateChannels(c);
+	xyAllocateChannels(c);
 }
 
 void pauseMusic() {
-	Mix_PauseMusic();
+	xyPauseMusic();
 }
 
 void resumeMusic() {
-	Mix_ResumeMusic();
+	xyResumeMusic();
 }
 
 bool musicPaused() {
-	return Mix_PlayingMusic() && Mix_PausedMusic();
+	return xyIsMusicPaused();
 }
 
 void fadeMusic(int f) {
-	Mix_FadeOutMusic(f * 1000);
+	xyFadeMusic(f);
 }
 
 void setMusicVolume(int vol) {
 	gvVolumeMusic = vol;
-	Mix_VolumeMusic(vol);
+	xySetMusicVolume(vol);
 }
 
 void setSoundVolume(int vol) {
@@ -128,4 +114,12 @@ int getSoundVolume() {
 	return gvVolumeSound;
 }
 
+const std::string& getAudioDriver() {
+	return gvAudioDriver;
+}
+
+bool isAudioAvailable() {
+	return xyIsAudioAvailable();
+}
+
 } // namespace BruxAPI

rte/src/api/audio.hpp

@@ -1,6 +1,7 @@
 //  Brux - Audio API
 //  Copyright (C) 2016 KelvinShadewing
-//                2023 Vankata453
+//  Copyright (C) 2023 Vankata453
+//  Copyright (C) 2023 hexaheximal
 //
 //  This program is free software: you can redistribute it and/or modify
 //  it under the terms of the GNU Affero General Public License as published by
@@ -48,6 +49,8 @@ void setMusicVolume(int vol); // Doc'd
 void setSoundVolume(int vol); // Doc'd
 int getMusicVolume(); // Doc'd
 int getSoundVolume(); // Doc'd
+const std::string& getAudioDriver(); // Doc'd
+bool isAudioAvailable(); // Doc'd
 
 } // namespace BruxAPI
 

rte/src/api/graphics.cpp

@@ -63,7 +63,10 @@ int loadImage(const std::string& file) {
 	return xyLoadImage(file);
 }
 
-int loadImageKey(const std::string& file, int key) {
+// Originally this was named loadImageKey, although that seems to be a typo - the documentation says it's getImageKeyed.
+// I discovered that by running the test suite and noticing the missing function.
+
+int loadImageKeyed(const std::string& file, int key) {
 	return xyLoadImageKeyed(file, key);
 }
 

rte/src/api/graphics.hpp

@@ -36,7 +36,7 @@ void drawImagePart(int img, int x, int y, int ox, int oy, int w, int h);
 void drawImageEx(int img, int x, int y, float a, int f, int w, int h, int c);
 void setDrawColor(int color); // Doc'd
 int loadImage(const std::string& file); // Doc'd
-int loadImageKey(const std::string& file, int key); // Doc'd
+int loadImageKeyed(const std::string& file, int key); // Doc'd
 void setBackgroundColor(int color); // Doc'd
 void setScaling(float scale);
 void setScalingFilter(int hint); // Doc'd