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    static final int LOOP_CONTINUOUS = -1;
041
042    /**
043     * Constant to define that this source should not loop when played
044     */
045    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    boolean queueBuffers(Queue<AudioBuffer> audioBuffers);
247
248    boolean queueBuffer(AudioBuffer audioBuffer);
249
250    boolean unqueueBuffers();
251
252    int numQueuedBuffers();
253
254    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    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    int getNumLoops();
581
582    /**
583     * Get the last value returned by {@link #getNumLoops() }
584     * @return the number of loops
585     */
586    int getLastNumLoops();
587
588//    /**
589//     * Set the minimum length of time in milliseconds to wait before
590//     * playing a subsequent loop of this source.
591//     * <p>
592//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
593//     * <p>
594//     * Default value = 0
595//     * <p>
596//     * Applies only to sub-types:
597//     * <ul>
598//     * <li>Source
599//     * </ul>
600//     * @param loopDelay minimum time in milliseconds to wait
601//     */
602//    void setMinLoopDelay(int loopDelay);
603//
604//    /**
605//     * Retrieve the minimum length of time in milliseconds to wait before
606//     * playing a subsequent loop of this source.
607//     * <p>
608//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
609//     * <p>
610//     * Default value = 0
611//     * <p>
612//     * Applies only to sub-types:
613//     * <ul>
614//     * <li>Source
615//     * </ul>
616//     * @return minimum time in milliseconds to wait
617//     */
618//    int getMinLoopDelay();
619//
620//    /**
621//     * Set the maximum length of time in milliseconds to wait before
622//     * playing a subsequent loop of this source.
623//     * <p>
624//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
625//     * <p>
626//     * Default value = 0
627//     * <p>
628//     * Applies only to sub-types:
629//     * <ul>
630//     * <li>Source
631//     * </ul>
632//     * @param loopDelay maximum time in milliseconds to wait
633//     */
634//    void setMaxLoopDelay(int loopDelay);
635//
636//    /**
637//     * Set the maximum length of time in milliseconds to wait before
638//     * playing a subsequent loop of this source.
639//     * <p>
640//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
641//     * <p>
642//     * Default value = 0
643//     * <p>
644//     * Applies only to sub-types:
645//     * <ul>
646//     * <li>Source
647//     * </ul>
648//     * @return maximum time in milliseconds to wait
649//     */
650//    int getMaxLoopDelay();
651//
652//    /**
653//     * The length of time in milliseconds that this source should wait
654//     * before playing a subsequent loop.
655//     * <p>
656//     * Not applicable when number of loops is LOOP_NONE or LOOP_CONTINUOUS
657//     * <p>
658//     * When the minimum and maximum delay times are different, each call
659//     * to this method will return a different random number that lies between
660//     * the two settings:
661//     * <pre>
662//     * minimum &lt= delay time &lt= maximum
663//     * </pre>
664//     * Default value = 0
665//     * <p>
666//     * Applies only to sub-types:
667//     * <ul>
668//     * <li>Source
669//     * </ul>
670//     * @return time in milliseconds to wait
671//     */
672//    int getLoopDelay();
673    /**
674     * Set the length of time in milliseconds to fade this source in
675     * <p>
676     * Default value = 1000
677     * <p>
678     * Applies only to sub-types:
679     * <ul>
680     * <li>Source
681     * </ul>
682     *
683     * @param fadeInTime fade-in time in milliseconds
684     */
685    void setFadeIn(int fadeInTime);
686
687    /**
688     * Retrieve the length of time in milliseconds to fade this source in
689     * <p>
690     * Default value = 1000
691     * <p>
692     * Applies only to sub-types:
693     * <ul>
694     * <li>Source
695     * </ul>
696     *
697     * @return fade-in time in milliseconds
698     */
699    int getFadeIn();
700
701    /**
702     * Set the length of time in milliseconds to fade this source in
703     * <p>
704     * Default value = 1000
705     * <p>
706     * Applies only to sub-types:
707     * <ul>
708     * <li>Source
709     * </ul>
710     *
711     * @param fadeOutTime fade-out time in milliseconds
712     */
713    void setFadeOut(int fadeOutTime);
714
715    /**
716     * Retrieve the length of time in milliseconds to fade this source in
717     * <p>
718     * Default value = 1000
719     * <p>
720     * Applies only to sub-types:
721     * <ul>
722     * <li>Source
723     * </ul>
724     *
725     * @return fade-in time in milliseconds
726     */
727    int getFadeOut();
728
729    /**
730     * Method to start playing this AudioSource Object
731     * <p>
732     * If this AudioSource is already playing, this command is ignored.
733     * <p>
734     * Applies only to sub-types:
735     * <ul>
736     * <li>Source
737     * </ul>
738     */
739    void play();
740
741    /**
742     * Method to stop playing this AudioSource Object
743     * <p>
744     * Applies only to sub-types:
745     * <ul>
746     * <li>Source
747     * </ul>
748     */
749    void stop();
750
751    /**
752     * Method to toggle playback of this AudioSource Object reseting position
753     * <p>
754     * Applies only to sub-types:
755     * <ul>
756     * <li>Source
757     * </ul>
758     */
759    void togglePlay();
760
761    /**
762     * Method to pause playing this AudioSource Object
763     * <p>
764     * Applies only to sub-types:
765     * <ul>
766     * <li>Source
767     * </ul>
768     */
769    void pause();
770
771    /**
772     * Method to resume playing this AudioSource Object
773     * <p>
774     * Applies only to sub-types:
775     * <ul>
776     * <li>Source
777     * </ul>
778     */
779    void resume();
780
781    /**
782     * Method to toggle playback of this AudioSource Object retaining postition
783     * <p>
784     * Applies only to sub-types:
785     * <ul>
786     * <li>Source
787     * </ul>
788     */
789    void togglePause();
790
791    /**
792     * Method to rewind this AudioSource Object
793     * <p>
794     * Applies only to sub-types:
795     * <ul>
796     * <li>Source
797     * </ul>
798     */
799    void rewind();
800
801    /**
802     * Method to fade in and then play this AudioSource Object
803     * <p>
804     * Applies only to sub-types:
805     * <ul>
806     * <li>Source
807     * </ul>
808     */
809    void fadeIn();
810
811    /**
812     * Method to fade out and then stop this AudioSource Object only when it is
813     * already playing.
814     * <p>
815     * If not playing, command is ignored.
816     * <p>
817     * Applies only to sub-types:
818     * <ul>
819     * <li>Source
820     * </ul>
821     */
822    void fadeOut();
823
824    /**
825     * Get debug info about this audio source.
826     * AbstractAudioSource overrides this to get more debug info. It was
827     * previously the method toString().
828     * @return a string with debug info or the result of the method toString()
829     */
830    default String getDebugString() {
831        return toString();
832    }
833
834}