001package com.fs.starfarer.api;
002
003import org.lwjgl.util.vector.Vector2f;
004
005/**
006 * @author Alex Mosolov
007 *
008 * Copyright 2013 Fractal Softworks, LLC
009 */
010public interface SoundPlayerAPI {
011        /**
012         * UI sound files should be stereo.
013         * @param id
014         * @param pitch
015         * @param volume
016         */
017        SoundAPI playUISound(String id, float pitch, float volume);
018        
019        /**
020         * Sound file must be *mono* for it to be properly played within the engine.
021         * @param id
022         * @param pitch
023         * @param volume
024         * @param loc
025         * @param vel
026         * @return
027         */
028        SoundAPI playSound(String id, float pitch, float volume, Vector2f loc, Vector2f vel);
029        
030        /**
031         * Loop a sound. Must be called every frame or the loop will fade out. Should be mono.
032         * 
033         * @param id
034         * @param playingEntity Required. Used to help uniquely identify playing loops. Also used to figure out which loops to not play (i.e., same entity playing multiples of the same loop would only play the one.)
035         * @param pitch
036         * @param volume
037         * @param loc
038         * @param vel
039         */
040        void playLoop(String id, Object playingEntity, float pitch, float volume, Vector2f loc, Vector2f vel);
041        
042        
043        /**
044         * Thread-safe - can be called from threads other than the main loop thread.
045         */
046        void restartCurrentMusic();
047        
048        /**
049         * Thread-safe - can be called from threads other than the main loop thread.
050         * The music id is the name of the file, including its path. It is NOT the
051         * name of the music set that gets passed in to playMusic, which may consist
052         * of multiple files, one of which will get picked randomly.
053         * 
054         * Returns the string "nothing" when nothing is playing.
055         * 
056         * @return
057         */
058        String getCurrentMusicId();
059        
060        
061        /**
062         * Thread-safe - can be called from threads other than the main loop thread.
063         * 
064         * Fade in/out are in seconds and have to be whole numbers.
065         * Can pass in null for musicSetId to stop the current track without starting a new one.
066         * @param fadeOutIfAny
067         * @param fadeIn
068         * @param musicSetId
069         */
070        void playCustomMusic(int fadeOutIfAny, int fadeIn, String musicSetId);
071        
072        /**
073         * Use playCustomMusic instead; has same effect. Deprecation is for naming consistency only.
074         * @param fadeOutIfAny
075         * @param fadeIn
076         * @param musicSetId
077         */
078        @Deprecated void playMusic(int fadeOutIfAny, int fadeIn, String musicSetId);
079        
080        /**
081         * Thread-safe - can be called from threads other than the main loop thread.
082         * 
083         * Won't stop any currently-playing music, but will prevent new tracks from starting playback
084         * automatically when the current one is over. Meant to be used in conjunction with
085         * playMusic() for customized music playback.
086         * 
087         * See also: SettingsAPI.getCurrentGameState()
088         * 
089         * Stops
090         * @param suspendMusicPlayback
091         */
092        void setSuspendDefaultMusicPlayback(boolean suspendMusicPlayback);
093        
094        Vector2f getListenerPos();
095
096        void pauseCustomMusic();
097        void resumeCustomMusic();
098        void playCustomMusic(int fadeOutIfAny, int fadeIn, String musicSetId, boolean looping);
099
100        void playUILoop(String id, float pitch, float volume);
101
102        void playLoop(String id, Object playingEntity, float pitch, float volume, Vector2f loc, Vector2f vel, float fadeIn, float fadeOut);
103
104        void applyLowPassFilter(float gain, float gainHF);
105
106        void setListenerPosOverrideOneFrame(Vector2f listenerPosOverrideOneFrame);
107
108        void pauseMusic();
109
110        void setNextLoopFadeInAndOut(float nextLoopFadeIn, float nextLoopFadeOut);
111}
112
113
114
115