Sample Stop Functions (#224)

Adds in bassh_stop_sample for source and audio_sample_stop for Lua. These functions immediately stop whatever audio the specified sample is playing.

If used in tandem with #223, this allows you to create custom character voice clips without them ever overlapping with each other.

autogen/lua_definitions/functions.lua

@@ -7391,6 +7391,12 @@ function audio_sample_play(audio, position, volume)
     -- ...
 end
 
+--- @param audio BassAudio
+--- @return nil
+function audio_sample_stop(audio)
+    -- ...
+end
+
 --- @param audio BassAudio
 --- @return nil
 function audio_stream_destroy(audio)

docs/lua/functions-4.md

@@ -5673,6 +5673,26 @@
 
 <br />
 
+## [audio_sample_stop](#audio_sample_stop)
+
+### Lua Example
+`audio_sample_stop(audio)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| audio | [BassAudio](structs.md#BassAudio) |
+
+### Returns
+- None
+
+### C Prototype
+`void audio_sample_stop(struct BassAudio* audio);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ## [audio_stream_destroy](#audio_stream_destroy)
 
 ### Lua Example

docs/lua/functions.md

@@ -1385,6 +1385,7 @@
    - [audio_sample_destroy](functions-4.md#audio_sample_destroy)
    - [audio_sample_load](functions-4.md#audio_sample_load)
    - [audio_sample_play](functions-4.md#audio_sample_play)
+   - [audio_sample_stop](functions-4.md#audio_sample_stop)
    - [audio_stream_destroy](functions-4.md#audio_stream_destroy)
    - [audio_stream_get_frequency](functions-4.md#audio_stream_get_frequency)
    - [audio_stream_get_looping](functions-4.md#audio_stream_get_looping)

src/bass_audio/bass_audio_helpers.c

@@ -24,6 +24,10 @@ void bassh_free_sample(HSAMPLE sample) {
     BASS_SampleFree(sample);
 }
 
+void bassh_stop_sample(HSAMPLE sample) {
+    BASS_SampleStop(sample);
+}
+
 void bassh_set_looping(HSTREAM stream, BOOL loop) {
     BASS_ChannelFlags(stream, loop == TRUE ? BASS_SAMPLE_LOOP : 0, BASS_SAMPLE_LOOP);
 }

src/bass_audio/bass_audio_helpers.h

@@ -7,6 +7,7 @@ HSAMPLE bassh_create_sample_from_file(char* data, QWORD length, QWORD offset);
 
 HSTREAM bassh_sample_get_stream(HSAMPLE sample);
 void bassh_free_sample(HSAMPLE sample);
+void bassh_stop_sample(HSAMPLE sample);
 void bassh_set_looping(HSTREAM stream, BOOL loop);
 
 void bassh_set_stream_volume(HSTREAM stream, float volume);

src/pc/lua/smlua_functions_autogen.c

@@ -16405,6 +16405,17 @@ int smlua_func_audio_sample_play(lua_State* L) {
     return 1;
 }
 
+int smlua_func_audio_sample_stop(lua_State* L) {
+    if(!smlua_functions_valid_param_count(L, 1)) { return 0; }
+
+    struct BassAudio* audio = (struct BassAudio*)smlua_to_cobject(L, 1, LOT_BASSAUDIO);
+    if (!gSmLuaConvertSuccess) { LOG_LUA("Failed to convert parameter 1 for function 'audio_sample_stop'"); return 0; }
+
+    audio_sample_stop(audio);
+
+    return 1;
+}
+
 int smlua_func_audio_stream_destroy(lua_State* L) {
     if(!smlua_functions_valid_param_count(L, 1)) { return 0; }
 
@@ -19635,6 +19646,7 @@ void smlua_bind_functions_autogen(void) {
     smlua_bind_function(L, "audio_sample_destroy", smlua_func_audio_sample_destroy);
     smlua_bind_function(L, "audio_sample_load", smlua_func_audio_sample_load);
     smlua_bind_function(L, "audio_sample_play", smlua_func_audio_sample_play);
+    smlua_bind_function(L, "audio_sample_stop", smlua_func_audio_sample_stop);
     smlua_bind_function(L, "audio_stream_destroy", smlua_func_audio_stream_destroy);
     smlua_bind_function(L, "audio_stream_get_frequency", smlua_func_audio_stream_get_frequency);
     smlua_bind_function(L, "audio_stream_get_looping", smlua_func_audio_stream_get_looping);

src/pc/lua/utils/smlua_audio_utils.c

@@ -407,6 +407,13 @@ void audio_sample_destroy(struct BassAudio* audio) {
     audio->rawData = NULL;
 }
 
+void audio_sample_stop(struct BassAudio* audio) {
+    if (!audio_sanity_check(audio, false, "stop")) {
+        return;
+    }
+    bassh_stop_sample(audio->handle);
+}  
+
 void audio_sample_play(struct BassAudio* audio, Vec3f position, f32 volume) {
     if (!audio_sanity_check(audio, false, "play")) {
         return;

src/pc/lua/utils/smlua_audio_utils.h

@@ -37,6 +37,7 @@ void audio_stream_set_speed(struct BassAudio* audio, f32 initial_freq, f32 speed
 
 struct BassAudio* audio_sample_load(const char* filename);
 void audio_sample_destroy(struct BassAudio* audio);
+void audio_sample_stop(struct BassAudio* audio);
 void audio_sample_play(struct BassAudio* audio, Vec3f position, f32 volume);
 
 void audio_custom_shutdown(void);