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}