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}