Audaspace:
[blender.git] / intern / audaspace / intern / AUD_IDevice.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * Copyright 2009-2011 Jörg Hermann Müller
5  *
6  * This file is part of AudaSpace.
7  *
8  * Audaspace is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * AudaSpace is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with Audaspace; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24
25 /** \file audaspace/intern/AUD_IDevice.h
26  *  \ingroup audaspaceintern
27  */
28
29
30 #ifndef __AUD_IDEVICE_H__
31 #define __AUD_IDEVICE_H__
32
33 #include "AUD_Space.h"
34 #include "AUD_IFactory.h"
35 #include "AUD_IReader.h"
36 #include "AUD_IHandle.h"
37 #include "AUD_ILockable.h"
38
39 #include <boost/shared_ptr.hpp>
40
41 /**
42  * This class represents an output device for sound sources.
43  * Output devices may be several backends such as plattform independand like
44  * SDL or OpenAL or plattform specific like DirectSound, but they may also be
45  * files, RAM buffers or other types of streams.
46  * \warning Thread safety must be insured so that no reader is beeing called
47  *          twice at the same time.
48  */
49 class AUD_IDevice : public AUD_ILockable
50 {
51 public:
52         /**
53          * Destroys the device.
54          */
55         virtual ~AUD_IDevice() {}
56
57         /**
58          * Returns the specification of the device.
59          */
60         virtual AUD_DeviceSpecs getSpecs() const=0;
61
62         /**
63          * Plays a sound source.
64          * \param reader The reader to play.
65          * \param keep When keep is true the sound source will not be deleted but
66          *             set to paused when its end has been reached.
67          * \return Returns a handle with which the playback can be controlled.
68          *         This is NULL if the sound couldn't be played back.
69          * \exception AUD_Exception Thrown if there's an unexpected (from the
70          *            device side) error during creation of the reader.
71          */
72         virtual boost::shared_ptr<AUD_IHandle> play(boost::shared_ptr<AUD_IReader> reader, bool keep = false)=0;
73
74         /**
75          * Plays a sound source.
76          * \param factory The factory to create the reader for the sound source.
77          * \param keep When keep is true the sound source will not be deleted but
78          *             set to paused when its end has been reached.
79          * \return Returns a handle with which the playback can be controlled.
80          *         This is NULL if the sound couldn't be played back.
81          * \exception AUD_Exception Thrown if there's an unexpected (from the
82          *            device side) error during creation of the reader.
83          */
84         virtual boost::shared_ptr<AUD_IHandle> play(boost::shared_ptr<AUD_IFactory> factory, bool keep = false)=0;
85
86         /**
87          * Stops all playing sounds.
88          */
89         virtual void stopAll()=0;
90
91         /**
92          * Locks the device.
93          * Used to make sure that between lock and unlock, no buffers are read, so
94          * that it is possible to start, resume, pause, stop or seek several
95          * playback handles simultaneously.
96          * \warning Make sure the locking time is as small as possible to avoid
97          *          playback delays that result in unexpected noise and cracks.
98          */
99         virtual void lock()=0;
100
101         /**
102          * Unlocks the previously locked device.
103          */
104         virtual void unlock()=0;
105
106         /**
107          * Retrieves the overall device volume.
108          * \return The overall device volume.
109          */
110         virtual float getVolume() const=0;
111
112         /**
113          * Sets the overall device volume.
114          * \param handle The sound handle.
115          * \param volume The overall device volume.
116          */
117         virtual void setVolume(float volume)=0;
118 };
119
120 #endif //AUD_IDevice