001package jmri.jmrit.audio;
002
003import java.util.Queue;
004import javax.vecmath.Vector3f;
005import jmri.Audio;
006
007/**
008 * Represent an AudioSource, a place to store or control sound information.
009 * <p>
010 * The AbstractAudio class contains a basic implementation of the state and
011 * messaging code, and forms a useful start for a system-specific
012 * implementation. Specific implementations in the jmrix package, e.g. for
013 * LocoNet and NCE, will convert to and from the layout commands.
014 * <p>
015 * The states and names are Java Bean parameters, so that listeners can be
016 * registered to be notified of any changes.
017 * <p>
018 * Each AudioSource object has a two names. The "user" name is entirely free
019 * form, and can be used for any purpose. The "system" name is provided by the
020 * system-specific implementations, and provides a unique mapping to the layout
021 * control system (for example LocoNet or NCE) and address within that system.
022 * <hr>
023 * This file is part of JMRI.
024 * <p>
025 * JMRI is free software; you can redistribute it and/or modify it under the
026 * terms of version 2 of the GNU General Public License as published by the Free
027 * Software Foundation. See the "COPYING" file for a copy of this license.
028 * <p>
029 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
030 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
031 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
032 *
033 * @author Matthew Harris copyright (c) 2009
034 */
035public interface AudioSource extends Audio {
036
037    /**
038     * Constant to define that this source should loop continously when played
039     */
040    public static final int LOOP_CONTINUOUS = -1;
041
042    /**
043     * Constant to define that this source should not loop when played
044     */
045    public static final int LOOP_NONE = 0;
046
047    /**
048     * Sets the position of this AudioSource object
049     * <p>
050     * Applies only to sub-types:
051     * <ul>
052     * <li>Listener
053     * <li>Source
054     * </ul>
055     *
056     * @param pos 3d position vector
057     */
058    public void setPosition(Vector3f pos);
059
060    /**
061     * Sets the position of this AudioSource object in x, y and z planes
062     * <p>
063     * Applies only to sub-types:
064     * <ul>
065     * <li>Listener
066     * <li>Source
067     * </ul>
068     *
069     * @param x x-coordinate
070     * @param y y-coordinate
071     * @param z z-coordinate
072     */
073    public void setPosition(float x, float y, float z);
074
075    /**
076     * Sets the position of this AudioSource object in x and y planes with z
077     * plane position fixed at zero
078     * <p>
079     * Equivalent to setPosition(x, y, 0.0f)
080     * <p>
081     * Applies only to sub-types:
082     * <ul>
083     * <li>Listener
084     * <li>Source
085     * </ul>
086     *
087     * @param x x-coordinate
088     * @param y y-coordinate
089     */
090    public void setPosition(float x, float y);
091
092    /**
093     * Returns the position of this AudioSource object as a 3-dimensional
094     * vector.
095     * <p>
096     * Applies only to sub-types:
097     * <ul>
098     * <li>Listener
099     * <li>Source
100     * </ul>
101     *
102     * @return 3d position vector
103     */
104    public Vector3f getPosition();
105
106    /**
107     * Returns the current position of this AudioSource object as a
108     * 3-dimensional vector.
109     * <p>
110     * Applies only to sub-types:
111     * <ul>
112     * <li>Listener
113     * <li>Source
114     * </ul>
115     *
116     * @return 3d position vector
117     */
118    public Vector3f getCurrentPosition();
119
120    /**
121     * Method to reset the current position of this AudioSource object to the
122     * initial position as defined by setPosition.
123     * <p>
124     * Applies only to sub-types:
125     * <ul>
126     * <li>Listener
127     * <li>Source
128     * </ul>
129     */
130    public void resetCurrentPosition();
131
132    /**
133     * Sets the position of this AudioSource object to be relative to the
134     * position of the AudioListener object or absolute.
135     * <p>
136     * Applies only to sub-types:
137     * <ul>
138     * <li>Source
139     * </ul>
140     *
141     * @param relative position relative or absolute
142     */
143    public void setPositionRelative(boolean relative);
144
145    /**
146     * Returns a boolean value that determines if the position of this
147     * AudioSource object is relative to the position of the AudioListener
148     * object or absolute.
149     * <p>
150     * Applies only to sub-types:
151     * <ul>
152     * <li>Source
153     * </ul>
154     *
155     * @return boolean position relative
156     */
157    public boolean isPositionRelative();
158
159    /**
160     * Sets the velocity of this AudioSource object
161     * <p>
162     * Applies only to sub-types:
163     * <ul>
164     * <li>Listener
165     * <li>Source
166     * </ul>
167     *
168     * @param vel 3d velocity vector
169     */
170    public void setVelocity(Vector3f vel);
171
172    /**
173     * Returns the velocity of this AudioSource object
174     * <p>
175     * Applies only to sub-types:
176     * <ul>
177     * <li>Listener
178     * <li>Source
179     * </ul>
180     *
181     * @return 3d velocity vector
182     */
183    public Vector3f getVelocity();
184
185    /**
186     * Returns linked AudioBuffer object
187     * <p>
188     * Applies only to sub-types:
189     * <ul>
190     * <li>Source
191     * </ul>
192     *
193     * @return AudioBuffer the AudioBuffer object bound to this AudioSource
194     */
195    public AudioBuffer getAssignedBuffer();
196
197    /**
198     * Return system name of linked AudioBuffer object
199     * <p>
200     * Applies only to sub-types:
201     * <ul>
202     * <li>Source
203     * </ul>
204     *
205     * @return sysName the SystemName of the AudioBuffer bound to this
206     *         AudioSource
207     */
208    public String getAssignedBufferName();
209
210    /**
211     * Sets the linked AudioBuffer object
212     * <p>
213     * Applies only to sub-types:
214     * <ul>
215     * <li>Source
216     * </ul>
217     *
218     * @param audioBuffer the AudioBuffer object to bind to this AudioSource
219     */
220    public void setAssignedBuffer(AudioBuffer audioBuffer);
221
222    /**
223     * Sets the system name of the linked AudioBuffer object
224     * <p>
225     * Applies only to sub-types:
226     * <ul>
227     * <li>Source
228     * </ul>
229     *
230     * @param sysName the SystemName of the AudioBuffer (i.e. IAB1) to bind to
231     *                this AudioSource
232     */
233    public void setAssignedBuffer(String sysName);
234
235    /**
236     * Queues the linked AudioBuffer object to this Source's buffer queue
237     * <p>
238     * Applies only to sub-types:
239     * <ul>
240     * <li>Source
241     * </ul>
242     *
243     * @param audioBuffers the AudioBuffer object to enqueue to this AudioSource
244     * @return true if successfully queued audioBuffers; false otherwise
245     */
246    public boolean queueBuffers(Queue<AudioBuffer> audioBuffers);
247
248    public boolean queueBuffer(AudioBuffer audioBuffer);
249
250    public boolean unqueueBuffers();
251
252    public int numQueuedBuffers();
253
254    public int numProcessedBuffers();
255
256    /**
257     * Method to return if this AudioSource has been bound to an AudioBuffer
258     * <p>
259     * Applies only to sub-types:
260     * <ul>
261     * <li>Source
262     * </ul>
263     *
264     * @return True if bound to an AudioBuffer
265     */
266    public boolean isBound();
267
268    /**
269     * Method to return if this AudioSource has AudioBuffers queued to it
270     * <p>
271     * Applies only to sub-types:
272     * <ul>
273     * <li>Source
274     * </ul>
275     *
276     * @return True if AudioBuffers are queued.
277     */
278    public boolean isQueued();
279
280    /**
281     * Return the currently stored gain setting
282     * <p>
283     * Default value = 1.0f
284     * <p>
285     * Applies only to sub-types:
286     * <ul>
287     * <li>Listener
288     * <li>Source
289     * </ul>
290     *
291     * @return gain setting of this AudioSource
292     */
293    public float getGain();
294
295    /**
296     * Set the gain of this AudioSource object
297     * <p>
298     * Default value = 1.0f
299     * <p>
300     * Applies only to sub-types:
301     * <ul>
302     * <li>Listener
303     * <li>Source
304     * </ul>
305     *
306     * @param gain the gain of this AudioSource
307     */
308    public void setGain(float gain);
309
310    /**
311     * Return the current pitch setting
312     * <p>
313     * Values are restricted from 0.5f to 2.0f, i.e. half to double
314     * <p>
315     * Default value = 1.0f
316     * <p>
317     * Applies only to sub-types:
318     * <ul>
319     * <li>Source
320     * </ul>
321     *
322     * @return pitch of this AudioSource
323     */
324    public float getPitch();
325
326    /**
327     * Set the pitch of this AudioSource object
328     * <p>
329     * Values are restricted from 0.5f to 2.0f, i.e. half to double
330     * <p>
331     * Default value = 1.0f
332     * <p>
333     * Applies only to sub-types:
334     * <ul>
335     * <li>Source
336     * </ul>
337     *
338     * @param pitch the pitch of this AudioSource
339     */
340    public void setPitch(float pitch);
341
342    /**
343     * Return the current reference distance setting
344     * <p>
345     * Default value = 1.0f
346     * <p>
347     * Applies only to sub-types:
348     * <ul>
349     * <li>Source
350     * </ul>
351     *
352     * @return Reference Distance of this AudioSource
353     */
354    public float getReferenceDistance();
355
356    /**
357     * Set the reference distance of this AudioSource object.
358     * <p>
359     * Default value = 1.0f
360     * <p>
361     * The Reference Distance is one of the main parameters you have for
362     * controlling the way that sounds attenuate with distance. A Source with
363     * Reference Distance set to 5 (meters) will be at maximum volume while it
364     * is within 5 metere of the listener, and start to fade out as it moves
365     * further away. At 10 meters it will be at half volume, and at 20 meters at
366     * a quarter volume, etc ...
367     * <p>
368     * Applies only to sub-types:
369     * <ul>
370     * <li>Source
371     * </ul>
372     *
373     * @param referenceDistance the Reference Distance for this AudioSource
374     */
375    public void setReferenceDistance(float referenceDistance);
376
377    /**
378     * Set the offset in which to start playback of this AudioSource.
379     * <p>
380     * Default value = 0
381     * <p>
382     * Value is clamped between 0 and length of attached AudioBuffer
383     * <p>
384     * Applies only to sub-types:
385     * <ul>
386     * <li>Source
387     * </ul>
388     *
389     * @param offset the offset in samples marking the point to commence
390     *               playback
391     */
392    public void setOffset(long offset);
393
394    /**
395     * Return the offset in which to start playback of this AudioSource.
396     * <p>
397     * Default value = 0
398     * <p>
399     * Applies only to sub-types:
400     * <ul>
401     * <li>Source
402     * </ul>
403     *
404     * @return the offset in samples marking the point to commence playback
405     */
406    public long getOffset();
407
408    /**
409     * Return the current maximum distance setting.
410     * <p>
411     * Default value = Audio.MAX_DISTANCE
412     * <p>
413     * The maximum distance is that where the volume of the sound would normally
414     * be zero.
415     * <p>
416     * Applies only to sub-types:
417     * <ul>
418     * <li>Source
419     * </ul>
420     * @return the maximum distance
421     */
422    public float getMaximumDistance();
423
424    /**
425     * Set the current maximum distance setting.
426     * <p>
427     * Default value = Audio.MAX_DISTANCE
428     * <p>
429     * The maximum distance is that where the volume of the sound would normally
430     * be zero.
431     * <p>
432     * Applies only to sub-types:
433     * <ul>
434     * <li>Source
435     * </ul>
436     *
437     * @param maximumDistance maximum distance of this source
438     */
439    public void setMaximumDistance(float maximumDistance);
440
441    /**
442     * Set the roll-off factor of this AudioSource object.
443     * <p>
444     * Default value = 1.0f
445     * <p>
446     * Applies only to sub-types:
447     * <ul>
448     * <li>Source
449     * </ul>
450     *
451     * @param rollOffFactor roll-off factor
452     */
453    public void setRollOffFactor(float rollOffFactor);
454
455    /**
456     * Get the roll-off factor of this AudioSource object.
457     * <p>
458     * Default value = 1.0f
459     * <p>
460     * Applies only to sub-types:
461     * <ul>
462     * <li>Source
463     * </ul>
464     * @return the roll-off factor
465     */
466    public float getRollOffFactor();
467
468    /**
469     * Check if this AudioSource object will loop or not.
470     * <p>
471     * Applies only to sub-types:
472     * <ul>
473     * <li>Source
474     * </ul>
475     *
476     * @return boolean loop
477     */
478    public boolean isLooped();
479
480    /**
481     * Sets this AudioSource object to loop infinitely or not.
482     * <p>
483     * When loop == false, sets the min and max number of loops to zero.
484     * <p>
485     * Applies only to sub-types:
486     * <ul>
487     * <li>Source
488     * </ul>
489     *
490     * @param loop infinite loop setting
491     */
492    public void setLooped(boolean loop);
493
494    /**
495     * Returns the minimum number of times that this AudioSource will loop, or
496     * LOOP_CONTINUOUS for infinite looping.
497     * <p>
498     * Default value = 0
499     * <p>
500     * Applies only to sub-types:
501     * <ul>
502     * <li>Source
503     * </ul>
504     *
505     * @return number of loops
506     */
507    public int getMinLoops();
508
509    /**
510     * The minimum number of times that this AudioSource should loop.
511     * <p>
512     * When set to 1, the sound will loop once (i.e. play through twice).
513     * <p>
514     * When set to LOOP_CONTINUOUS, determines that this AudioSource object
515     * should loop indefinitely until explicitly stopped.
516     * <p>
517     * Default value = 0
518     * <p>
519     * Applies only to sub-types:
520     * <ul>
521     * <li>Source
522     * </ul>
523     *
524     * @param loops minimum number of loops
525     */
526    public void setMinLoops(int loops);
527
528    /**
529     * Returns the maximum number of times that this AudioSource will loop, or
530     * LOOP_CONTINUOUS for infinite looping.
531     * <p>
532     * Default value = 0
533     * <p>
534     * Applies only to sub-types:
535     * <ul>
536     * <li>Source
537     * </ul>
538     *
539     * @return maximum number of loops
540     */
541    public int getMaxLoops();
542
543    /**
544     * The maximum number of times that this AudioSource should loop.
545     * <p>
546     * When set to 1, the sound will loop once (i.e. play through twice).
547     * <p>
548     * When set to LOOP_CONTINUOUS, determines that this AudioSource object
549     * should loop indefinitely until explicitly stopped.
550     * <p>
551     * Default value = 0
552     * <p>
553     * Applies only to sub-types:
554     * <ul>
555     * <li>Source
556     * </ul>
557     *
558     * @param loops maximum number of loops
559     */
560    public void setMaxLoops(int loops);
561
562    /**
563     * The number of times that this AudioSource should loop, or LOOP_CONTINUOUS
564     * for infinite looping.
565     * <p>
566     * When the minimum and maximum number of loops are different, each call to
567     * this method will return a different random number that lies between the
568     * two settings:
569     * <pre>
570     * minimum {@literal <=} number of loops {@literal <=} maximum
571     * </pre> Default value = 0
572     * <p>
573     * Applies only to sub-types:
574     * <ul>
575     * <li>Source
576     * </ul>
577     *
578     * @return number of loops
579     */
580    public int getNumLoops();
581
582//    /**
583//     * Set the minimum length of time in milliseconds to wait before
584//     * playing a subsequent loop of this source.
585//     * <p>
586//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
587//     * <p>
588//     * Default value = 0
589//     * <p>
590//     * Applies only to sub-types:
591//     * <ul>
592//     * <li>Source
593//     * </ul>
594//     * @param loopDelay minimum time in milliseconds to wait
595//     */
596//    public void setMinLoopDelay(int loopDelay);
597//
598//    /**
599//     * Retrieve the minimum length of time in milliseconds to wait before
600//     * playing a subsequent loop of this source.
601//     * <p>
602//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
603//     * <p>
604//     * Default value = 0
605//     * <p>
606//     * Applies only to sub-types:
607//     * <ul>
608//     * <li>Source
609//     * </ul>
610//     * @return minimum time in milliseconds to wait
611//     */
612//    public int getMinLoopDelay();
613//
614//    /**
615//     * Set the maximum length of time in milliseconds to wait before
616//     * playing a subsequent loop of this source.
617//     * <p>
618//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
619//     * <p>
620//     * Default value = 0
621//     * <p>
622//     * Applies only to sub-types:
623//     * <ul>
624//     * <li>Source
625//     * </ul>
626//     * @param loopDelay maximum time in milliseconds to wait
627//     */
628//    public void setMaxLoopDelay(int loopDelay);
629//
630//    /**
631//     * Set the maximum length of time in milliseconds to wait before
632//     * playing a subsequent loop of this source.
633//     * <p>
634//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
635//     * <p>
636//     * Default value = 0
637//     * <p>
638//     * Applies only to sub-types:
639//     * <ul>
640//     * <li>Source
641//     * </ul>
642//     * @return maximum time in milliseconds to wait
643//     */
644//    public int getMaxLoopDelay();
645//
646//    /**
647//     * The length of time in milliseconds that this source should wait
648//     * before playing a subsequent loop.
649//     * <p>
650//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
651//     * <p>
652//     * When the minimum and maximum delay times are different, each call
653//     * to this method will return a different random number that lies between
654//     * the two settings:
655//     * <pre>
656//     * minimum &lt= delay time &lt= maximum
657//     * </pre>
658//     * Default value = 0
659//     * <p>
660//     * Applies only to sub-types:
661//     * <ul>
662//     * <li>Source
663//     * </ul>
664//     * @return time in milliseconds to wait
665//     */
666//    public int getLoopDelay();
667    /**
668     * Set the length of time in milliseconds to fade this source in
669     * <p>
670     * Default value = 1000
671     * <p>
672     * Applies only to sub-types:
673     * <ul>
674     * <li>Source
675     * </ul>
676     *
677     * @param fadeInTime fade-in time in milliseconds
678     */
679    public void setFadeIn(int fadeInTime);
680
681    /**
682     * Retrieve the length of time in milliseconds to fade this source in
683     * <p>
684     * Default value = 1000
685     * <p>
686     * Applies only to sub-types:
687     * <ul>
688     * <li>Source
689     * </ul>
690     *
691     * @return fade-in time in milliseconds
692     */
693    public int getFadeIn();
694
695    /**
696     * Set the length of time in milliseconds to fade this source in
697     * <p>
698     * Default value = 1000
699     * <p>
700     * Applies only to sub-types:
701     * <ul>
702     * <li>Source
703     * </ul>
704     *
705     * @param fadeOutTime fade-out time in milliseconds
706     */
707    public void setFadeOut(int fadeOutTime);
708
709    /**
710     * Retrieve the length of time in milliseconds to fade this source in
711     * <p>
712     * Default value = 1000
713     * <p>
714     * Applies only to sub-types:
715     * <ul>
716     * <li>Source
717     * </ul>
718     *
719     * @return fade-in time in milliseconds
720     */
721    public int getFadeOut();
722
723    /**
724     * Set the doppler factor of this source
725     * <p>
726     * Default value = 1.0f
727     * <p>
728     * Only calculated for JoalAudioSources
729     * <p>
730     * Applies only to sub-types:
731     * <ul>
732     * <li>Source
733     * </ul>
734     *
735     * @param dopplerFactor factor to apply in doppler calculations
736     */
737    @Deprecated
738    default public void setDopplerFactor(float dopplerFactor) {}
739
740    /**
741     * Retrieve the doppler factor of this source
742     * <p>
743     * Default value = 1.0f
744     * <p>
745     * Only calculated for JoalAudioSources
746     * <p>
747     * Applies only to sub-types:
748     * <ul>
749     * <li>Source
750     * </ul>
751     *
752     * @return factor to apply in doppler calculations
753     */
754    @Deprecated
755    default public float getDopplerFactor() { return 1.0f; }
756
757    /**
758     * Method to start playing this AudioSource Object
759     * <p>
760     * If this AudioSource is already playing, this command is ignored.
761     * <p>
762     * Applies only to sub-types:
763     * <ul>
764     * <li>Source
765     * </ul>
766     */
767    public void play();
768
769    /**
770     * Method to stop playing this AudioSource Object
771     * <p>
772     * Applies only to sub-types:
773     * <ul>
774     * <li>Source
775     * </ul>
776     */
777    public void stop();
778
779    /**
780     * Method to toggle playback of this AudioSource Object reseting position
781     * <p>
782     * Applies only to sub-types:
783     * <ul>
784     * <li>Source
785     * </ul>
786     */
787    public void togglePlay();
788
789    /**
790     * Method to pause playing this AudioSource Object
791     * <p>
792     * Applies only to sub-types:
793     * <ul>
794     * <li>Source
795     * </ul>
796     */
797    public void pause();
798
799    /**
800     * Method to resume playing this AudioSource Object
801     * <p>
802     * Applies only to sub-types:
803     * <ul>
804     * <li>Source
805     * </ul>
806     */
807    public void resume();
808
809    /**
810     * Method to toggle playback of this AudioSource Object retaining postition
811     * <p>
812     * Applies only to sub-types:
813     * <ul>
814     * <li>Source
815     * </ul>
816     */
817    public void togglePause();
818
819    /**
820     * Method to rewind this AudioSource Object
821     * <p>
822     * Applies only to sub-types:
823     * <ul>
824     * <li>Source
825     * </ul>
826     */
827    public void rewind();
828
829    /**
830     * Method to fade in and then play this AudioSource Object
831     * <p>
832     * Applies only to sub-types:
833     * <ul>
834     * <li>Source
835     * </ul>
836     */
837    public void fadeIn();
838
839    /**
840     * Method to fade out and then stop this AudioSource Object only when it is
841     * already playing.
842     * <p>
843     * If not playing, command is ignored.
844     * <p>
845     * Applies only to sub-types:
846     * <ul>
847     * <li>Source
848     * </ul>
849     */
850    public void fadeOut();
851
852    /**
853     * Get debug info about this audio source.
854     * AbstractAudioSource overrides this to get more debug info. It was
855     * previously the method toString().
856     * @return a string with debug info or the result of the method toString()
857     */
858    default public String getDebugString() {
859        return toString();
860    }
861    
862}