unify include guard defines, __$FILENAME__
[blender-staging.git] / intern / audaspace / intern / AUD_IHandle.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_IHandle.h
26  *  \ingroup audaspaceintern
27  */
28
29 #ifndef __AUD_IHANDLE_H__
30 #define __AUD_IHANDLE_H__
31
32 //#include "AUD_Space.h"
33 //#include "AUD_Reference.h"
34
35 typedef void (*stopCallback)(void*);
36
37 /**
38  * This class represents a playback handles for specific devices.
39  */
40 class AUD_IHandle
41 {
42 public:
43         /**
44          * Destroys the handle.
45          */
46         virtual ~AUD_IHandle() {}
47
48         /**
49          * Pauses a played back sound.
50          * \return
51          *        - true if the sound has been paused.
52          *        - false if the sound isn't playing back or the handle is invalid.
53          */
54         virtual bool pause()=0;
55
56         /**
57          * Resumes a paused sound.
58          * \return
59          *        - true if the sound has been resumed.
60          *        - false if the sound isn't paused or the handle is invalid.
61          */
62         virtual bool resume()=0;
63
64         /**
65          * Stops a played back or paused sound. The handle is definitely invalid
66          * afterwards.
67          * \return
68          *        - true if the sound has been stopped.
69          *        - false if the handle is invalid.
70          */
71         virtual bool stop()=0;
72
73         /**
74          * Gets the behaviour of the device for a played back sound when the sound
75          * doesn't return any more samples.
76          * \return
77          *        - true if the source will be paused when it's end is reached
78          *        - false if the handle won't kept or is invalid.
79          */
80         virtual bool getKeep()=0;
81
82         /**
83          * Sets the behaviour of the device for a played back sound when the sound
84          * doesn't return any more samples.
85          * \param keep True when the source should be paused and not deleted.
86          * \return
87          *        - true if the behaviour has been changed.
88          *        - false if the handle is invalid.
89          */
90         virtual bool setKeep(bool keep)=0;
91
92         /**
93          * Seeks in a played back sound.
94          * \param position The new position from where to play back, in seconds.
95          * \return
96          *        - true if the handle is valid.
97          *        - false if the handle is invalid.
98          * \warning Whether the seek works or not depends on the sound source.
99          */
100         virtual bool seek(float position)=0;
101
102         /**
103          * Retrieves the current playback position of a sound.
104          * \return The playback position in seconds, or 0.0 if the handle is
105          *         invalid.
106          */
107         virtual float getPosition()=0;
108
109         /**
110          * Returns the status of a played back sound.
111          * \return
112          *        - AUD_STATUS_INVALID if the sound has stopped or the handle is
113          *.         invalid
114          *        - AUD_STATUS_PLAYING if the sound is currently played back.
115          *        - AUD_STATUS_PAUSED if the sound is currently paused.
116          * \see AUD_Status
117          */
118         virtual AUD_Status getStatus()=0;
119
120         /**
121          * Retrieves the volume of a playing sound.
122          * \return The volume.
123          */
124         virtual float getVolume()=0;
125
126         /**
127          * Sets the volume of a playing sound.
128          * \param volume The volume.
129          * \return
130          *        - true if the handle is valid.
131          *        - false if the handle is invalid.
132          */
133         virtual bool setVolume(float volume)=0;
134
135         /**
136          * Retrieves the pitch of a playing sound.
137          * \return The pitch.
138          */
139         virtual float getPitch()=0;
140
141         /**
142          * Sets the pitch of a playing sound.
143          * \param pitch The pitch.
144          * \return
145          *        - true if the handle is valid.
146          *        - false if the handle is invalid.
147          */
148         virtual bool setPitch(float pitch)=0;
149
150         /**
151          * Retrieves the loop count of a playing sound.
152          * A negative value indicates infinity.
153          * \return The remaining loop count.
154          */
155         virtual int getLoopCount()=0;
156
157         /**
158          * Sets the loop count of a playing sound.
159          * A negative value indicates infinity.
160          * \param count The new loop count.
161          * \return
162          *        - true if the handle is valid.
163          *        - false if the handle is invalid.
164          */
165         virtual bool setLoopCount(int count)=0;
166
167         /**
168          * Sets the callback function that's called when the end of a playing sound
169          * is reached.
170          * \param callback The callback function.
171          * \param data The data that should be passed to the callback function.
172          * \return
173          *        - true if the handle is valid.
174          *        - false if the handle is invalid.
175          */
176         virtual bool setStopCallback(stopCallback callback = 0, void* data = 0)=0;
177 };
178
179 #endif //AUD_IHandle