mod: Allow mods to start at specific "order".

Fixes #826.

(cherry picked from commit b004875)

Author: icculus

docs/README-migration.md

@@ -17,8 +17,8 @@ think that once you move to them, you'll be quite happy you did.
 There are a lot of things that don't have simple replacements that can be
 changed mechanically to migrate to SDL3_mixer. The new API is in many ways
 more powerful, but also much simpler. For example, there's no equivalent of
-Mix_ModMusicJumpToOrder(), because messing with the specifics
-of MOD files in the public API is both uncommon and generally pretty messy.
+Mix_GetNumTracks(), because messing with the specifics of MOD files in the
+public API is both uncommon and generally pretty messy.
 
 This migration guide will attempt to walk through the important details but
 it's possible that some things can't be done the same way. Feel free to open
@@ -34,10 +34,8 @@ function name and a brief explanation about what to do with it.
   and packaged it as a separate library that can be used alongside SDL3_mixer,
   or without SDL_mixer at all: https://github.com/libsdl-org/SDL_native_midi
 
-- Mix_GetNumTracks(), Mix_StartTrack(), and Mix_ModMusicJumpToOrder() have
-  been removed; these were decoder-specific APIs.
-
-- Mix_SetSoundFonts(), Mix_GetSoundFonts(), Mix_EachSoundFont(),
+- Mix_GetNumTracks(), Mix_StartTrack(), Mix_ModMusicJumpToOrder(),
+  Mix_SetSoundFonts(), Mix_GetSoundFonts(), Mix_EachSoundFont(),
   Mix_SetTimidityCfg(), Mix_GetTimidityCfg(): these have been removed, but
   decoder-specific settings can be passed on in a generic way in SDL3_mixer,
   using SDL properties.
@@ -392,7 +390,7 @@ can discuss it!
 - Mix_ResumeMusic => MIX_ResumeTrack
 - Mix_RewindMusic => MIX_SetTrackPlaybackPosition(track, 0)
 - Mix_PausedMusic => MIX_TrackPaused
-- Mix_ModMusicJumpToOrder => no equivalent in SDL3_mixer.
+- Mix_ModMusicJumpToOrder => MIX_PlayTrack with MIX_PROP_PLAY_START_ORDER_NUMBER property set.
 - Mix_StartTrack => no equivalent in SDL3_mixer.
 - Mix_GetNumTracks => no equivalent in SDL3_mixer.
 - Mix_SetMusicPosition => MIX_SetTrackPlaybackPosition

include/SDL3_mixer/SDL_mixer.h

@@ -1885,6 +1885,14 @@ extern SDL_DECLSPEC Sint64 SDLCALL MIX_FramesToMS(int sample_rate, Sint64 frames
  *   possible. Note that a track is not consider exhausted until all its loops
  *   and appended silence have been mixed (and also, that loops don't mean
  *   anything when the input is an AudioStream). Default true.
+ * - `MIX_PROP_PLAY_START_ORDER_NUMBER`: This is a special-case property
+ *   that most apps can ignore. For mod file formats, start mixing from a
+ *   specific "order" index instead of the start of the file. A value < 0 will
+ *   cause this property to be ignored. If the decoder doesn't support this
+ *   property, it will also be ignored. If this property is _not_ ignored,
+ *   the MIX_PROP_PLAY_START_FRAME_NUMBER and
+ *   MIX_PROP_PLAY_START_MILLISECOND_NUMBER properties will be ignored instead.
+ *   Default -1. Since SDL_mixer 3.2.2.
  *
  * If this function fails, mixing of this track will not start (or restart, if
  * it was already started).
@@ -1910,6 +1918,7 @@ extern SDL_DECLSPEC bool SDLCALL MIX_PlayTrack(MIX_Track *track, SDL_PropertiesI
 #define MIX_PROP_PLAY_MAX_MILLISECONDS_NUMBER "SDL_mixer.play.max_milliseconds"
 #define MIX_PROP_PLAY_START_FRAME_NUMBER "SDL_mixer.play.start_frame"
 #define MIX_PROP_PLAY_START_MILLISECOND_NUMBER "SDL_mixer.play.start_millisecond"
+#define MIX_PROP_PLAY_START_ORDER_NUMBER "SDL_mixer.play.start_order"
 #define MIX_PROP_PLAY_LOOP_START_FRAME_NUMBER "SDL_mixer.play.loop_start_frame"
 #define MIX_PROP_PLAY_LOOP_START_MILLISECOND_NUMBER "SDL_mixer.play.loop_start_millisecond"
 #define MIX_PROP_PLAY_FADE_IN_FRAMES_NUMBER "SDL_mixer.play.fade_in_frames"

src/SDL_mixer.c

@@ -2242,6 +2242,7 @@ bool MIX_PlayTrack(MIX_Track *track, SDL_PropertiesID options)
     Sint64 loop_start = 0;
     Sint64 fade_in = 0;
     Sint64 append_silence_frames = 0;
+    int start_order = -1;
     float fade_start_gain = 0.0f;
     bool halt_when_exhausted = true;
 
@@ -2255,6 +2256,7 @@ bool MIX_PlayTrack(MIX_Track *track, SDL_PropertiesID options)
         fade_start_gain = SDL_GetFloatProperty(options, MIX_PROP_PLAY_FADE_IN_START_GAIN_FLOAT, fade_start_gain);
         append_silence_frames = GetTrackOptionFramesOrTicks(track, options, MIX_PROP_PLAY_APPEND_SILENCE_FRAMES_NUMBER, MIX_PROP_PLAY_APPEND_SILENCE_MILLISECONDS_NUMBER, append_silence_frames);
         halt_when_exhausted = SDL_GetBooleanProperty(options, MIX_PROP_PLAY_HALT_WHEN_EXHAUSTED_BOOLEAN, halt_when_exhausted);
+        start_order = (int) SDL_GetNumberProperty(options, MIX_PROP_PLAY_START_ORDER_NUMBER, start_order);
 
         if (start_pos < 0) {
             start_pos = 0;
@@ -2271,7 +2273,14 @@ bool MIX_PlayTrack(MIX_Track *track, SDL_PropertiesID options)
         fade_start_gain = SDL_clamp(fade_start_gain, 0.0f, 1.0f);
     }
 
-    if (track->input_audio && (!track->input_audio->decoder->seek(track->decoder_userdata, start_pos))) {
+    if ((start_order >= 0) && (!track->input_audio || !track->input_audio->decoder->jump_to_order)) {
+        start_order = -1;  // ignore this option, it doesn't mean anything on this decoder.
+    }
+
+    if ((start_order >= 0) && !track->input_audio->decoder->jump_to_order(track->decoder_userdata, start_order)) {
+        UnlockTrack(track);
+        return false;
+    } else if (track->input_audio && (!track->input_audio->decoder->seek(track->decoder_userdata, start_pos))) {
         UnlockTrack(track);
         return false;
     } else if (!track->input_audio && (start_pos != 0)) {

src/SDL_mixer_internal.h

@@ -105,6 +105,7 @@ typedef struct MIX_Decoder
     bool (SDLCALL *init_track)(void *audio_userdata, SDL_IOStream *io, const SDL_AudioSpec *spec, SDL_PropertiesID props, void **track_userdata);  // init decoder instance data for a single track.
     bool (SDLCALL *decode)(void *track_userdata, SDL_AudioStream *stream);
     bool (SDLCALL *seek)(void *track_userdata, Uint64 frame);
+    bool (SDLCALL *jump_to_order)(void *track_userdata, int order);
     void (SDLCALL *quit_track)(void *track_userdata);
     void (SDLCALL *quit_audio)(void *audio_userdata);
     void (SDLCALL *quit)(void);   // deinitialize the decoder (unload external libraries, etc).

src/decoder_aiff.c

@@ -581,6 +581,7 @@ const MIX_Decoder MIX_Decoder_AIFF = {
     AIFF_init_track,
     AIFF_decode,
     AIFF_seek,
+    NULL,  // jump_to_order
     AIFF_quit_track,
     AIFF_quit_audio,
     NULL  // quit

src/decoder_au.c

@@ -269,6 +269,7 @@ const MIX_Decoder MIX_Decoder_AU = {
     AU_init_track,
     AU_decode,
     AU_seek,
+    NULL,  // jump_to_order
     AU_quit_track,
     AU_quit_audio,
     NULL  // quit

src/decoder_drflac.c

@@ -331,6 +331,7 @@ const MIX_Decoder MIX_Decoder_DRFLAC = {
     DRFLAC_init_track,
     DRFLAC_decode,
     DRFLAC_seek,
+    NULL,  // jump_to_order
     DRFLAC_quit_track,
     DRFLAC_quit_audio,
     NULL  // quit

src/decoder_drmp3.c

@@ -195,6 +195,7 @@ const MIX_Decoder MIX_Decoder_DRMP3 = {
     DRMP3_init_track,
     DRMP3_decode,
     DRMP3_seek,
+    NULL,  // jump_to_order
     DRMP3_quit_track,
     DRMP3_quit_audio,
     NULL  // quit

src/decoder_flac.c

@@ -507,6 +507,7 @@ const MIX_Decoder MIX_Decoder_FLAC = {
     FLAC_init_track,
     FLAC_decode,
     FLAC_seek,
+    NULL,  // jump_to_order
     FLAC_quit_track,
     FLAC_quit_audio,
     FLAC_quit

src/decoder_fluidsynth.c

@@ -451,6 +451,7 @@ const MIX_Decoder MIX_Decoder_FLUIDSYNTH = {
     FLUIDSYNTH_init_track,
     FLUIDSYNTH_decode,
     FLUIDSYNTH_seek,
+    NULL,  // jump_to_order
     FLUIDSYNTH_quit_track,
     FLUIDSYNTH_quit_audio,
     FLUIDSYNTH_quit