001package jmri.jmrit.audio; 002 003/** 004 * An AudioFactory is responsible for the initialisation of specific audio 005 * system implementations, creation of audio system specific Audio objects and 006 * any necessary clean-up operations required by a specific audio system 007 * implementation. 008 * <p> 009 * Each factory varies in its capabilities with regard the faithfulness of the 010 * audio rendering model (such as spatial positioning approximation), number of 011 * concurrent sounds (polyphony), hardware required, etc. 012 * <p> 013 * Current implemented audio systems include: 014 * <ul> 015 * <li>JOAL 016 * <li>JavaSound 017 * <li>Null (a catch-all which doesn't actually play any sounds) 018 * </ul> 019 * <hr> 020 * This file is part of JMRI. 021 * <p> 022 * JMRI is free software; you can redistribute it and/or modify it under the 023 * terms of version 2 of the GNU General Public License as published by the Free 024 * Software Foundation. See the "COPYING" file for a copy of this license. 025 * <p> 026 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 027 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 028 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 029 * 030 * @author Matthew Harris copyright (c) 2009 031 */ 032public interface AudioFactory { 033 034 /** 035 * Perform any implementation specific initialisation routines. 036 * 037 * @return true, if initialisation successful 038 */ 039 boolean init(); 040 041 /** 042 * Perform any implementation specific clean-up operations. 043 */ 044 void cleanup(); 045 046 /** 047 * Determine if this AudioFactory is initialised 048 * @return true if initialised 049 */ 050 boolean isInitialised(); 051 052 /** 053 * Provide a specific new AudioBuffer object. 054 * 055 * @param systemName for this object instance 056 * @param userName for this object instance 057 * @return a new specific AudioBuffer 058 */ 059 AudioBuffer createNewBuffer(String systemName, String userName); 060 061 /** 062 * Provide a specific new AudioListener object. 063 * 064 * @param systemName for this object instance 065 * @param userName for this object instance 066 * @return a new specific AudioListener 067 */ 068 AudioListener createNewListener(String systemName, String userName); 069 070 /** 071 * Get the currently active Listener object. 072 * 073 * @return active AudioListener 074 */ 075 AudioListener getActiveAudioListener(); 076 077 /** 078 * Provide a specific new AudioSource object. 079 * 080 * @param systemName for this object instance 081 * @param userName for this object instance 082 * @return a new specific AudioSource 083 */ 084 AudioSource createNewSource(String systemName, String userName); 085 086 /** 087 * Queues a new AudioCommand for subsequent execution. 088 * <p> 089 * If newAudioCommand is null the current queue is executed and cleaned. 090 * 091 * @param newAudioCommand AudioCommand to queue or null to execute queue 092 * @return true, if further commands exist; false, if empty 093 */ 094 boolean audioCommandQueue(AudioCommand newAudioCommand); 095 096 /** 097 * Get the currently active Command thread. 098 * 099 * @return active CommandThread 100 */ 101 Thread getCommandThread(); 102 103 /** 104 * Set if this AudioFactory should attenuate sources based on their 105 * distance from the listener. 106 * <p> 107 * Default = true 108 * 109 * @param attenuated true if distance attenuation to be used 110 */ 111 void setDistanceAttenuated(boolean attenuated); 112 113 /** 114 * Determine if this AudioFactory attenuates sources based on their 115 * distance from the Listener. 116 * 117 * @return true if distance attenuation used 118 */ 119 boolean isDistanceAttenuated(); 120 121}