3D Audio GSoC:
[blender.git] / intern / audaspace / intern / AUD_IHandle.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * Copyright 2009-2011 Jörg Hermann Müller
7  *
8  * This file is part of AudaSpace.
9  *
10  * Audaspace is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version.
14  *
15  * AudaSpace is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with Audaspace; if not, write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file audaspace/intern/AUD_IHandle.h
28  *  \ingroup audaspaceintern
29  */
30
31 #ifndef AUD_IHANDLE
32 #define AUD_IHANDLE
33
34 //#include "AUD_Space.h"
35 //#include "AUD_Reference.h"
36
37 typedef void (*stopCallback)(void*);
38
39 /**
40  * This class represents a playback handles for specific devices.
41  */
42 class AUD_IHandle
43 {
44 public:
45         /**
46          * Destroys the handle.
47          */
48         virtual ~AUD_IHandle() {}
49
50         /**
51          * Pauses a played back sound.
52          * \return
53          *        - true if the sound has been paused.
54          *        - false if the sound isn't playing back or the handle is invalid.
55          */
56         virtual bool pause()=0;
57
58         /**
59          * Resumes a paused sound.
60          * \return
61          *        - true if the sound has been resumed.
62          *        - false if the sound isn't paused or the handle is invalid.
63          */
64         virtual bool resume()=0;
65
66         /**
67          * Stops a played back or paused sound. The handle is definitely invalid
68          * afterwards.
69          * \return
70          *        - true if the sound has been stopped.
71          *        - false if the handle is invalid.
72          */
73         virtual bool stop()=0;
74
75         /**
76          * Gets the behaviour of the device for a played back sound when the sound
77          * doesn't return any more samples.
78          * \return
79          *        - true if the source will be paused when it's end is reached
80          *        - false if the handle won't kept or is invalid.
81          */
82         virtual bool getKeep()=0;
83
84         /**
85          * Sets the behaviour of the device for a played back sound when the sound
86          * doesn't return any more samples.
87          * \param keep True when the source should be paused and not deleted.
88          * \return
89          *        - true if the behaviour has been changed.
90          *        - false if the handle is invalid.
91          */
92         virtual bool setKeep(bool keep)=0;
93
94         /**
95          * Seeks in a played back sound.
96          * \param position The new position from where to play back, in seconds.
97          * \return
98          *        - true if the handle is valid.
99          *        - false if the handle is invalid.
100          * \warning Whether the seek works or not depends on the sound source.
101          */
102         virtual bool seek(float position)=0;
103
104         /**
105          * Retrieves the current playback position of a sound.
106          * \return The playback position in seconds, or 0.0 if the handle is
107          *         invalid.
108          */
109         virtual float getPosition()=0;
110
111         /**
112          * Returns the status of a played back sound.
113          * \return
114          *        - AUD_STATUS_INVALID if the sound has stopped or the handle is
115          *.         invalid
116          *        - AUD_STATUS_PLAYING if the sound is currently played back.
117          *        - AUD_STATUS_PAUSED if the sound is currently paused.
118          * \see AUD_Status
119          */
120         virtual AUD_Status getStatus()=0;
121
122         /**
123          * Retrieves the volume of a playing sound.
124          * \return The volume.
125          */
126         virtual float getVolume()=0;
127
128         /**
129          * Sets the volume of a playing sound.
130          * \param volume The volume.
131          * \return
132          *        - true if the handle is valid.
133          *        - false if the handle is invalid.
134          */
135         virtual bool setVolume(float volume)=0;
136
137         /**
138          * Retrieves the pitch of a playing sound.
139          * \return The pitch.
140          */
141         virtual float getPitch()=0;
142
143         /**
144          * Sets the pitch of a playing sound.
145          * \param pitch The pitch.
146          * \return
147          *        - true if the handle is valid.
148          *        - false if the handle is invalid.
149          */
150         virtual bool setPitch(float pitch)=0;
151
152         /**
153          * Retrieves the loop count of a playing sound.
154          * A negative value indicates infinity.
155          * \return The remaining loop count.
156          */
157         virtual int getLoopCount()=0;
158
159         /**
160          * Sets the loop count of a playing sound.
161          * A negative value indicates infinity.
162          * \param count The new loop count.
163          * \return
164          *        - true if the handle is valid.
165          *        - false if the handle is invalid.
166          */
167         virtual bool setLoopCount(int count)=0;
168
169         /**
170          * Sets the callback function that's called when the end of a playing sound
171          * is reached.
172          * \param callback The callback function.
173          * \param data The data that should be passed to the callback function.
174          * \return
175          *        - true if the handle is valid.
176          *        - false if the handle is invalid.
177          */
178         virtual bool setStopCallback(stopCallback callback = 0, void* data = 0)=0;
179 };
180
181 #endif //AUD_IHandle