001package jmri;
002
003/**
004 * Represent an Audio, a place to store or control sound information.
005 * <p>
006 * The AbstractAudio class contains a basic implementation of the state and
007 * messaging code, and forms a useful start for a system-specific
008 * implementation. Specific implementations will convert
009 * to and from the hardware commands.
010 * <p>
011 * The states and names are Java Bean parameters, so that listeners can be
012 * registered to be notified of any changes.
013 * <p>
014 * Each Audio object has a two names. The "user" name is entirely free form, and
015 * can be used for any purpose. The "system" name is provided by the
016 * system-specific implementations, and provides a unique mapping to the layout
017 * control system and address within that system.
018 * <br>
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 Audio extends NamedBean {
033
034    // Define Object sub-type constants
035    /**
036     * Definition of AudioSource NamedBean sub-type code
037     */
038    public static final char SOURCE = 'S';
039
040    /**
041     * Definition of AudioBuffer NamedBean sub-type code
042     */
043    public static final char BUFFER = 'B';
044
045    /**
046     * Definition of AudioListener NamedBean sub-type code
047     */
048    public static final char LISTENER = 'L';
049
050    // Define orientation constants
051    /**
052     * Definition of Audio object orientation at vector code
053     */
054    public static final int AT = 0x01;
055
056    /**
057     * Definition of Audio object orientation up vector code
058     */
059    public static final int UP = 0x02;
060
061    // Define state variables for Audio objects
062    /**
063     * Default state for any newly created Audio object
064     */
065    public static final int STATE_INITIAL = 0x00;
066
067    // Define applicable states for Source sub-types
068    /**
069     * State code for an AudioSource when stopped
070     */
071    public static final int STATE_STOPPED = 0x10;
072
073    /**
074     * State code for an AudioSource when playing
075     */
076    public static final int STATE_PLAYING = 0x11;
077
078    // Define applicable states for Buffer sub-types
079    /**
080     * State code for an AudioBuffer when empty
081     */
082    public static final int STATE_EMPTY = 0x20;
083
084    /**
085     * State code for an AudioBuffer when loaded
086     */
087    public static final int STATE_LOADED = 0x21;
088
089    // Define applicable states for Listener sub-types
090    /**
091     * State code for an AudioListener when positioned
092     */
093    public static final int STATE_POSITIONED = 0x30;
094
095    /**
096     * State code for an AudioListener when moving
097     */
098    public static final int STATE_MOVING = 0x31;
099
100    // Define Audio command constants
101    // Constants defining Factory related commands
102    /**
103     * Command to initialise AudioFactory
104     */
105    public static final int CMD_INIT_FACTORY = 0x01;
106
107    // Constants defining Buffer related commands
108    /**
109     * Command to load the sound
110     */
111    public static final int CMD_LOAD_SOUND = 0x20;
112
113    // Constants defining Source related commands
114    /**
115     * Command to bind Buffer to Source
116     */
117    public static final int CMD_BIND_BUFFER = 0x30;
118
119    /**
120     * Command to queue Buffer to Source
121     */
122    public static final int CMD_QUEUE_BUFFERS = 0x31;
123
124    /**
125     * Command to unqueue used Buffers from Source
126     */
127    public static final int CMD_UNQUEUE_BUFFERS = 0x32;
128
129    /**
130     * Command to play this Source from the beginning
131     */
132    public static final int CMD_PLAY = 0x40;
133
134    /**
135     * Command to stop playing this Source and rewind to the start
136     */
137    public static final int CMD_STOP = 0x41;
138
139    /**
140     * Command to start or stop this Source from the beginning
141     */
142    public static final int CMD_PLAY_TOGGLE = 0x42;
143
144    /**
145     * Command to pause playback of this Source and retain the position
146     */
147    public static final int CMD_PAUSE = 0x43;
148
149    /**
150     * Command to resume playback of this Source from the current position
151     */
152    public static final int CMD_RESUME = 0x44;
153
154    /**
155     * Command to pause or resume this Source from the current position
156     */
157    public static final int CMD_PAUSE_TOGGLE = 0x45;
158
159    /**
160     * Command to rewind this Source to the beginning
161     */
162    public static final int CMD_REWIND = 0x46;
163
164    /**
165     * Command to fade in and start playback of this Source
166     */
167    public static final int CMD_FADE_IN = 0x47;
168
169    /**
170     * Command to fade out and stop playback of this Source
171     */
172    public static final int CMD_FADE_OUT = 0x48;
173
174    /**
175     * Command to reset the position of this Source
176     */
177    public static final int CMD_RESET_POSITION = 0x49;
178
179    // Define state variables for fade states
180    /**
181     * Fade state of Source when not fading
182     */
183    public static final int FADE_NONE = 0x00;
184
185    /**
186     * Fade state of Source when fading out
187     */
188    public static final int FADE_OUT = 0x01;
189
190    /**
191     * Fade state of Source when fading in
192     */
193    public static final int FADE_IN = 0x02;
194
195    /**
196     * Maximum distance for Audio objects
197     */
198    public static final float MAX_DISTANCE = 9999.99f;
199
200    /**
201     * Number of decimal places for float values to be stored in
202     */
203    public static final double DECIMAL_PLACES = 2;
204
205    /**
206     * An Audio object can represent one of a number of subtypes of object.
207     * <p>
208     * This method enables us to determine which of those subtypes this
209     * particular instance is and be able to process accordingly.
210     * <p>
211     * Current supported subtypes are:
212     * <ul>
213     * <li>B = Buffer
214     * <li>L = Listener
215     * <li>S = Source
216     * </ul>
217     *
218     * @return subType char
219     */
220    public char getSubType();
221
222    /**
223     * Method used to update the current state of the Audio object
224     *
225     * @param oldState the former state
226     */
227    public void stateChanged(int oldState);
228
229}