1d6f8ca6efb3780cc77c7b15bfad086cc2ea8bd4
[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_Reference.h"
35 #include "AUD_IFactory.h"
36 #include "AUD_IReader.h"
37 #include "AUD_IHandle.h"
38
39 /**
40  * This class represents an output device for sound sources.
41  * Output devices may be several backends such as plattform independand like
42  * SDL or OpenAL or plattform specific like DirectSound, but they may also be
43  * files, RAM buffers or other types of streams.
44  * \warning Thread safety must be insured so that no reader is beeing called
45  *          twice at the same time.
46  */
47 class AUD_IDevice
48 {
49 public:
50         /**
51          * Destroys the device.
52          */
53         virtual ~AUD_IDevice() {}
54
55         /**
56          * Returns the specification of the device.
57          */
58         virtual AUD_DeviceSpecs getSpecs() const=0;
59
60         /**
61          * Plays a sound source.
62          * \param reader The reader to play.
63          * \param keep When keep is true the sound source will not be deleted but
64          *             set to paused when its end has been reached.
65          * \return Returns a handle with which the playback can be controlled.
66          *         This is NULL if the sound couldn't be played back.
67          * \exception AUD_Exception Thrown if there's an unexpected (from the
68          *            device side) error during creation of the reader.
69          */
70         virtual AUD_Reference<AUD_IHandle> play(AUD_Reference<AUD_IReader> reader, bool keep = false)=0;
71
72         /**
73          * Plays a sound source.
74          * \param factory The factory to create the reader for the sound source.
75          * \param keep When keep is true the sound source will not be deleted but
76          *             set to paused when its end has been reached.
77          * \return Returns a handle with which the playback can be controlled.
78          *         This is NULL if the sound couldn't be played back.
79          * \exception AUD_Exception Thrown if there's an unexpected (from the
80          *            device side) error during creation of the reader.
81          */
82         virtual AUD_Reference<AUD_IHandle> play(AUD_Reference<AUD_IFactory> factory, bool keep = false)=0;
83
84         /**
85          * Stops all playing sounds.
86          */
87         virtual void stopAll()=0;
88
89         /**
90          * Locks the device.
91          * Used to make sure that between lock and unlock, no buffers are read, so
92          * that it is possible to start, resume, pause, stop or seek several
93          * playback handles simultaneously.
94          * \warning Make sure the locking time is as small as possible to avoid
95          *          playback delays that result in unexpected noise and cracks.
96          */
97         virtual void lock()=0;
98
99         /**
100          * Unlocks the previously locked device.
101          */
102         virtual void unlock()=0;
103
104         /**
105          * Retrieves the overall device volume.
106          * \return The overall device volume.
107          */
108         virtual float getVolume() const=0;
109
110         /**
111          * Sets the overall device volume.
112          * \param handle The sound handle.
113          * \param volume The overall device volume.
114          */
115         virtual void setVolume(float volume)=0;
116 };
117
118 #endif //AUD_IDevice