001package jmri.jmrit.audio; 002 003import javax.vecmath.Vector3f; 004import jmri.Audio; 005 006/** 007 * Represent an AudioListener, a place to store or control sound information. 008 * <p> 009 * The AbstractAudio class contains a basic implementation of the state and 010 * messaging code, and forms a useful start for a system-specific 011 * implementation. Specific implementations in the jmrix package, e.g. for 012 * LocoNet and NCE, will convert to and from the layout commands. 013 * <p> 014 * The states and names are Java Bean parameters, so that listeners can be 015 * registered to be notified of any changes. 016 * <p> 017 * Each AudioListener object has a two names. The "user" name is entirely free 018 * form, and can be used for any purpose. The "system" name is provided by the 019 * system-specific implementations, and provides a unique mapping to the layout 020 * control system (for example LocoNet or NCE) and address within that system. 021 * <br> 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 AudioListener extends Audio { 036 037 /** 038 * Sets the position of this AudioListener object 039 * <p> 040 * Applies only to sub-types: 041 * <ul> 042 * <li>Listener 043 * <li>Source 044 * </ul> 045 * 046 * @param pos 3d position vector 047 */ 048 void setPosition(Vector3f pos); 049 050 /** 051 * Sets the position of this AudioListener object in x, y and z planes 052 * <p> 053 * Applies only to sub-types: 054 * <ul> 055 * <li>Listener 056 * <li>Source 057 * </ul> 058 * 059 * @param x x-coordinate 060 * @param y y-coordinate 061 * @param z z-coordinate 062 */ 063 void setPosition(float x, float y, float z); 064 065 /** 066 * Sets the position of this AudioListener object in x and y planes with z 067 * plane position fixed at zero 068 * <p> 069 * Equivalent to setPosition(x, y, 0.0f) 070 * <p> 071 * Applies only to sub-types: 072 * <ul> 073 * <li>Listener 074 * <li>Source 075 * </ul> 076 * 077 * @param x x-coordinate 078 * @param y y-coordinate 079 */ 080 void setPosition(float x, float y); 081 082 /** 083 * Returns the position of this AudioListener object as a 3-dimensional 084 * vector. 085 * <p> 086 * Applies only to sub-types: 087 * <ul> 088 * <li>Listener 089 * <li>Source 090 * </ul> 091 * 092 * @return 3d position vector 093 */ 094 Vector3f getPosition(); 095 096 /** 097 * Returns the current position of this AudioListener object as a 098 * 3-dimensional vector. 099 * <p> 100 * Applies only to sub-types: 101 * <ul> 102 * <li>Listener 103 * <li>Source 104 * </ul> 105 * 106 * @return 3d position vector 107 */ 108 Vector3f getCurrentPosition(); 109 110 /** 111 * Method to reset the current position of this AudioListener object to the 112 * initial position as defined by setPosition. 113 * <p> 114 * Applies only to sub-types: 115 * <ul> 116 * <li>Listener 117 * <li>Source 118 * </ul> 119 */ 120 void resetCurrentPosition(); 121 122 /** 123 * Sets the velocity of this AudioListener object 124 * <p> 125 * Applies only to sub-types: 126 * <ul> 127 * <li>Listener 128 * <li>Source 129 * </ul> 130 * 131 * @param vel 3d velocity vector 132 */ 133 void setVelocity(Vector3f vel); 134 135 /** 136 * Returns the velocity of this AudioListener object 137 * 138 * Applies only to sub-types: - Listener - Source 139 * 140 * @return 3d velocity vector 141 */ 142 Vector3f getVelocity(); 143 144 /** 145 * Set the orientation of this AudioListener object 146 * <p> 147 * Applies only to sub-types: 148 * <ul> 149 * <li>Listener 150 * </ul> 151 * 152 * @param at 3d vector representing the position 153 * @param up 3d vector representing the look-at point 154 */ 155 void setOrientation(Vector3f at, Vector3f up); 156 157 /** 158 * Return the orientation of this AudioListener object 159 * <p> 160 * Applies only to sub-types: 161 * <ul> 162 * <li>Listener 163 * </ul> 164 * 165 * @param which the orientation vector to return: == AT - position; == UP - 166 * look-at point 167 * @return vector representing the chosen orientation vector 168 */ 169 Vector3f getOrientation(int which); 170 171 /** 172 * Return the current orientation of this AudioListener object 173 * <p> 174 * Applies only to sub-types: 175 * <ul> 176 * <li>Listener 177 * </ul> 178 * 179 * @param which the orientation vector to return: == AT - position; == UP - 180 * look-at point 181 * @return vector representing the chosen orientation vector 182 */ 183 Vector3f getCurrentOrientation(int which); 184 185 /** 186 * Return the current gain setting 187 * <p> 188 * Applies only to sub-types: 189 * <ul> 190 * <li>Listener 191 * <li>Source 192 * </ul> 193 * 194 * @return float gain 195 */ 196 float getGain(); 197 198 /** 199 * Set the gain of this AudioListener object 200 * <p> 201 * Applicable values 0.0f to 1.0f 202 * <p> 203 * When applied to Listeners, has the effect of altering the master gain (or 204 * volume) 205 * <p> 206 * Applies only to sub-types: 207 * <ul> 208 * <li>Listener 209 * <li>Source 210 * </ul> 211 * 212 * @param gain new gain value - range 0.0f to 1.0f 213 */ 214 void setGain(float gain); 215 216 /** 217 * Method to set the Meters per unit ratio for all distance calculations. 218 * <p> 219 * Default value = 1.0f (i.e. 1 unit == 1 metre) 220 * <p> 221 * Typical alternative values: 222 * <ul> 223 * <li>0.3048f (i.e. 1 unit == 1 foot) 224 * <li>0.9144f (i.e. 1 unit == 1 yard) 225 * </ul> 226 * <p> 227 * Applies only to sub-types: 228 * <ul> 229 * <li>Listener 230 * </ul> 231 * 232 * @param metersPerUnit Meters per unit ratio 233 */ 234 void setMetersPerUnit(float metersPerUnit); 235 236 /** 237 * Retrieve the current Meters per unit ratio to use for all distance 238 * calculations. 239 * <p> 240 * Default value = 1.0f (i.e. 1 unit == 1 metre) 241 * <p> 242 * Typical alternative values: 243 * <ul> 244 * <li>0.3048f (i.e. 1 unit == 1 foot) 245 * <li>0.9144f (i.e. 1 unit == 1 yard) 246 * </ul> 247 * <p> 248 * Applies only to sub-types: 249 * <ul> 250 * <li>Listener 251 * </ul> 252 * 253 * @return Meters per unit ratio 254 */ 255 float getMetersPerUnit(); 256 257}