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 char SOURCE = 'S'; 039 040 /** 041 * Definition of AudioBuffer NamedBean sub-type code 042 */ 043 char BUFFER = 'B'; 044 045 /** 046 * Definition of AudioListener NamedBean sub-type code 047 */ 048 char LISTENER = 'L'; 049 050 // Define orientation constants 051 /** 052 * Definition of Audio object orientation at vector code 053 */ 054 int AT = 0x01; 055 056 /** 057 * Definition of Audio object orientation up vector code 058 */ 059 int UP = 0x02; 060 061 // Define state variables for Audio objects 062 /** 063 * Default state for any newly created Audio object 064 */ 065 int STATE_INITIAL = 0x00; 066 067 // Define applicable states for Source sub-types 068 /** 069 * State code for an AudioSource when stopped 070 */ 071 int STATE_STOPPED = 0x10; 072 073 /** 074 * State code for an AudioSource when playing 075 */ 076 int STATE_PLAYING = 0x11; 077 078 // Define applicable states for Buffer sub-types 079 /** 080 * State code for an AudioBuffer when empty 081 */ 082 int STATE_EMPTY = 0x20; 083 084 /** 085 * State code for an AudioBuffer when loaded 086 */ 087 int STATE_LOADED = 0x21; 088 089 // Define applicable states for Listener sub-types 090 /** 091 * State code for an AudioListener when positioned 092 */ 093 int STATE_POSITIONED = 0x30; 094 095 /** 096 * State code for an AudioListener when moving 097 */ 098 int STATE_MOVING = 0x31; 099 100 // Define Audio command constants 101 // Constants defining Factory related commands 102 /** 103 * Command to initialise AudioFactory 104 */ 105 int CMD_INIT_FACTORY = 0x01; 106 107 // Constants defining Buffer related commands 108 /** 109 * Command to load the sound 110 */ 111 int CMD_LOAD_SOUND = 0x20; 112 113 // Constants defining Source related commands 114 /** 115 * Command to bind Buffer to Source 116 */ 117 int CMD_BIND_BUFFER = 0x30; 118 119 /** 120 * Command to queue Buffer to Source 121 */ 122 int CMD_QUEUE_BUFFERS = 0x31; 123 124 /** 125 * Command to unqueue used Buffers from Source 126 */ 127 int CMD_UNQUEUE_BUFFERS = 0x32; 128 129 /** 130 * Command to play this Source from the beginning 131 */ 132 int CMD_PLAY = 0x40; 133 134 /** 135 * Command to stop playing this Source and rewind to the start 136 */ 137 int CMD_STOP = 0x41; 138 139 /** 140 * Command to start or stop this Source from the beginning 141 */ 142 int CMD_PLAY_TOGGLE = 0x42; 143 144 /** 145 * Command to pause playback of this Source and retain the position 146 */ 147 int CMD_PAUSE = 0x43; 148 149 /** 150 * Command to resume playback of this Source from the current position 151 */ 152 int CMD_RESUME = 0x44; 153 154 /** 155 * Command to pause or resume this Source from the current position 156 */ 157 int CMD_PAUSE_TOGGLE = 0x45; 158 159 /** 160 * Command to rewind this Source to the beginning 161 */ 162 int CMD_REWIND = 0x46; 163 164 /** 165 * Command to fade in and start playback of this Source 166 */ 167 int CMD_FADE_IN = 0x47; 168 169 /** 170 * Command to fade out and stop playback of this Source 171 */ 172 int CMD_FADE_OUT = 0x48; 173 174 /** 175 * Command to reset the position of this Source 176 */ 177 int CMD_RESET_POSITION = 0x49; 178 179 // Define state variables for fade states 180 /** 181 * Fade state of Source when not fading 182 */ 183 int FADE_NONE = 0x00; 184 185 /** 186 * Fade state of Source when fading out 187 */ 188 int FADE_OUT = 0x01; 189 190 /** 191 * Fade state of Source when fading in 192 */ 193 int FADE_IN = 0x02; 194 195 /** 196 * Maximum distance for Audio objects 197 */ 198 float MAX_DISTANCE = 9999.99f; 199 200 /** 201 * Number of decimal places for float values to be stored in 202 */ 203 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 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 void stateChanged(int oldState); 228 229}