1//************************************ bs::framework - Copyright 2018 Marko Pintera **************************************//
2//*********** Licensed under the MIT license. See LICENSE.md for full terms. This notice is not to be removed. ***********//
3#pragma once
4
5#include "BsCorePrerequisites.h"
6#include "Resources/BsIResourceListener.h"
7#include "Scene/BsSceneActor.h"
8#include "Math/BsVector3.h"
9
10namespace bs
11{
12 /** @addtogroup Audio
13 * @{
14 */
15
16 /** Valid states in which AudioSource can be in. */
17 enum class BS_SCRIPT_EXPORT(m:Audio) AudioSourceState
18 {
19 Playing, /**< Source is currently playing. */
20 Paused, /**< Source is currently paused (play will resume from paused point). */
21 Stopped /**< Source is currently stopped (play will resume from start). */
22 };
23
24 /**
25 * Represents a source for emitting audio. Audio can be played spatially (gun shot), or normally (music). Each audio
26 * source must have an AudioClip to play-back, and it can also have a position in the case of spatial (3D) audio.
27 *
28 * Whether or not an audio source is spatial is controlled by the assigned AudioClip. The volume and the pitch of a
29 * spatial audio source is controlled by its position and the AudioListener's position/direction/velocity.
30 */
31 class BS_CORE_EXPORT AudioSource : public IReflectable, public SceneActor, public IResourceListener
32 {
33 public:
34 virtual ~AudioSource() = default;
35
36 /** Audio clip to play. */
37 virtual void setClip(const HAudioClip& clip);
38
39 /** @copydoc setClip() */
40 HAudioClip getClip() const { return mAudioClip; }
41
42 /**
43 * Velocity of the source. Determines pitch in relation to AudioListener's position. Only relevant for spatial
44 * (3D) sources.
45 */
46 virtual void setVelocity(const Vector3& velocity);
47
48 /** @copydoc setVelocity() */
49 Vector3 getVelocity() const { return mVelocity; }
50
51 /** Volume of the audio played from this source, in [0, 1] range. */
52 virtual void setVolume(float volume);
53
54 /** @copydoc setVolume() */
55 float getVolume() const { return mVolume; }
56
57 /** Determines the pitch of the played audio. 1 is the default. */
58 virtual void setPitch(float pitch);
59
60 /** @copydoc setPitch() */
61 float getPitch() const { return mPitch; }
62
63 /** Determines whether the audio clip should loop when it finishes playing. */
64 virtual void setIsLooping(bool loop);
65
66 /** @copydoc setIsLooping() */
67 bool getIsLooping() const { return mLoop; }
68
69 /**
70 * Determines the priority of the audio source. If more audio sources are playing than supported by the hardware,
71 * some might get disabled. By setting a higher priority the audio source is guaranteed to be disabled after sources
72 * with lower priority.
73 */
74 virtual void setPriority(INT32 priority);
75
76 /** @copydoc setPriority() */
77 UINT32 getPriority() const { return mPriority; }
78
79 /**
80 * Minimum distance at which audio attenuation starts. When the listener is closer to the source
81 * than this value, audio is heard at full volume. Once farther away the audio starts attenuating.
82 */
83 virtual void setMinDistance(float distance);
84
85 /** @copydoc setMinDistance() */
86 float getMinDistance() const { return mMinDistance; }
87
88 /**
89 * Attenuation that controls how quickly does audio volume drop off as the listener moves further from the source.
90 */
91 virtual void setAttenuation(float attenuation);
92
93 /** @copydoc setAttenuation() */
94 float getAttenuation() const { return mAttenuation; }
95
96 /** Starts playing the currently assigned audio clip. */
97 virtual void play() = 0;
98
99 /** Pauses the audio playback. */
100 virtual void pause() = 0;
101
102 /** Stops audio playback, rewinding it to the start. */
103 virtual void stop() = 0;
104
105 /**
106 * Determines the current time of playback. If playback hasn't yet started, it specifies the time at which playback
107 * will start at. The time is in seconds, in range [0, clipLength].
108 */
109 virtual void setTime(float time) = 0;
110
111 /** @copydoc setTime() */
112 virtual float getTime() const = 0;
113
114 /** Returns the current state of the audio playback (playing/paused/stopped). */
115 virtual AudioSourceState getState() const = 0;
116
117 /** Creates a new audio source. */
118 static SPtr<AudioSource> create();
119
120 protected:
121 AudioSource() = default;
122
123 /** @copydoc IResourceListener::getListenerResources */
124 void getListenerResources(Vector<HResource>& resources) override;
125
126 /** @copydoc IResourceListener::notifyResourceChanged */
127 void notifyResourceChanged(const HResource& resource) override;
128
129 /** Triggered by the resources system whenever the attached audio clip changed (e.g. was reimported.) */
130 virtual void onClipChanged() { }
131
132 HAudioClip mAudioClip;
133 Vector3 mVelocity = BsZero;
134 float mVolume = 1.0f;
135 float mPitch = 1.0f;
136 bool mLoop = false;
137 INT32 mPriority = 0;
138 float mMinDistance = 1.0f;
139 float mAttenuation = 1.0f;
140
141 /************************************************************************/
142 /* RTTI */
143 /************************************************************************/
144 public:
145 friend class AudioSourceRTTI;
146 static RTTITypeBase* getRTTIStatic();
147 RTTITypeBase* getRTTI() const override;
148 };
149
150 /** @} */
151}
152