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 <= delay time <= 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}