13 #if defined(ALURE_BUILD_STATIC) || defined(ALURE_STATIC_LIB)
15 #elif defined(ALURE_BUILD_DLL)
16 #define ALURE_API __declspec(dllexport)
18 #define ALURE_API __declspec(dllimport)
26 #ifndef EFXEAXREVERBPROPERTIES_DEFINED
27 #define EFXEAXREVERBPROPERTIES_DEFINED
37 float flReflectionsGain
;
38 float flReflectionsDelay
;
39 float flReflectionsPan
[3];
40 float flLateReverbGain
;
41 float flLateReverbDelay
;
42 float flLateReverbPan
[3];
45 float flModulationTime
;
46 float flModulationDepth
;
47 float flAirAbsorptionGainHF
;
50 float flRoomRolloffFactor
;
52 } EFXEAXREVERBPROPERTIES
, *LPEFXEAXREVERBPROPERTIES
;
64 class AuxiliaryEffectSlot
;
71 // A SharedPtr implementation, defaults to C++11's std::shared_ptr. If this is
72 // changed, you must recompile the library.
74 using SharedPtr
= std::shared_ptr
<T
>;
75 template<typename T
, typename
... Args
>
76 constexpr inline SharedPtr
<T
> MakeShared(Args
&&... args
)
78 return std::make_shared
<T
>(std::forward
<Args
>(args
)...);
81 // A UniquePtr implementation, defaults to C++11's std::unique_ptr. If this is
82 // changed, you must recompile the library.
84 using UniquePtr
= std::unique_ptr
<T
>;
85 template<typename T
, typename
... Args
>
86 constexpr inline UniquePtr
<T
> MakeUnique(Args
&&... args
)
88 #if __cplusplus >= 201402L
89 return std::make_unique
<T
>(std::forward
<Args
>(args
)...);
91 return std::unique_ptr
<T
>(new T(std::forward
<Args
>(args
)...));
95 // A Vector implementation, defaults to C++'s std::vector. If this is changed,
96 // you must recompile the library.
98 using Vector
= std::vector
<T
>;
100 // A String implementation, default's to C++'s std::string. If this is changed,
101 // you must recompile the library.
102 using String
= std::string
;
105 struct FilterParams
{
107 ALfloat mGainHF
; // For low-pass and band-pass filters
108 ALfloat mGainLF
; // For high-pass and band-pass filters
112 class ALURE_API Vector3
{
113 std::array
<ALfloat
,3> mValue
;
116 constexpr Vector3() noexcept
117 : mValue
{{0.0f
, 0.0f
, 0.0f
}}
119 constexpr Vector3(const Vector3
&rhs
) noexcept
120 : mValue
{{rhs
.mValue
[0], rhs
.mValue
[1], rhs
.mValue
[2]}}
122 constexpr Vector3(ALfloat val
) noexcept
123 : mValue
{{val
, val
, val
}}
125 constexpr Vector3(ALfloat x
, ALfloat y
, ALfloat z
) noexcept
128 Vector3(const ALfloat
*vec
) noexcept
129 : mValue
{{vec
[0], vec
[1], vec
[2]}}
132 const ALfloat
*getPtr() const noexcept
133 { return mValue
.data(); }
135 ALfloat
& operator[](size_t i
) noexcept
136 { return mValue
[i
]; }
137 constexpr const ALfloat
& operator[](size_t i
) const noexcept
138 { return mValue
[i
]; }
140 #define ALURE_DECL_OP(op) \
141 constexpr Vector3 operator op(const Vector3 &rhs) const noexcept \
143 return Vector3(mValue[0] op rhs.mValue[0], \
144 mValue[1] op rhs.mValue[1], \
145 mValue[2] op rhs.mValue[2]); \
152 #define ALURE_DECL_OP(op) \
153 Vector3& operator op(const Vector3 &rhs) noexcept \
155 mValue[0] op rhs.mValue[0]; \
156 mValue[1] op rhs.mValue[1]; \
157 mValue[2] op rhs.mValue[2]; \
166 #define ALURE_DECL_OP(op) \
167 constexpr Vector3 operator op(ALfloat scale) const noexcept \
169 return Vector3(mValue[0] op scale, \
170 mValue[1] op scale, \
171 mValue[2] op scale); \
176 #define ALURE_DECL_OP(op) \
177 Vector3& operator op(ALfloat scale) noexcept \
179 mValue[0] op scale; \
180 mValue[1] op scale; \
181 mValue[2] op scale; \
188 constexpr ALfloat
getLengthSquared() const noexcept
189 { return mValue
[0]*mValue
[0] + mValue
[1]*mValue
[1] + mValue
[2]*mValue
[2]; }
190 constexpr ALfloat
getLength() const noexcept
191 { return std::sqrt(getLengthSquared()); }
193 constexpr ALfloat
getDistanceSquared(const Vector3
&pos
) const noexcept
194 { return (pos
- *this).getLengthSquared(); }
195 constexpr ALfloat
getDistance(const Vector3
&pos
) const noexcept
196 { return (pos
- *this).getLength(); }
198 static_assert(sizeof(Vector3
) == sizeof(ALfloat
[3]), "Bad Vector3 size");
202 * Creates a version number value using the specified \param major and
203 * \param minor values.
205 constexpr inline ALCuint
MakeVersion(ALCushort major
, ALCushort minor
)
206 { return (major
<<16) | minor
; }
209 * Retrieves the major version of a version number value created by
212 constexpr inline ALCuint
MajorVersion(ALCuint version
)
213 { return version
>>16; }
215 * Retrieves the minor version of a version number value created by
218 constexpr inline ALCuint
MinorVersion(ALCuint version
)
219 { return version
&0xffff; }
222 enum class DeviceEnumeration
{
223 Basic
= ALC_DEVICE_SPECIFIER
,
224 Complete
= ALC_ALL_DEVICES_SPECIFIER
,
225 Capture
= ALC_CAPTURE_DEVICE_SPECIFIER
228 enum class DefaultDeviceType
{
229 Basic
= ALC_DEFAULT_DEVICE_SPECIFIER
,
230 Complete
= ALC_DEFAULT_ALL_DEVICES_SPECIFIER
,
231 Capture
= ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER
235 * A class managing \ref Device objects and other related functionality. This
236 * class is a singleton, only one instance will exist in a process.
238 class ALURE_API DeviceManager
{
240 /** Retrieves the DeviceManager instance. */
241 static DeviceManager
&get();
243 /** Queries the existence of a non-device-specific ALC extension. */
244 virtual bool queryExtension(const char *extname
) const = 0;
246 /** Enumerates available device names of the given \param type. */
247 virtual Vector
<String
> enumerate(DeviceEnumeration type
) const = 0;
248 /** Retrieves the default device of the given \param type. */
249 virtual String
defaultDeviceName(DefaultDeviceType type
) const = 0;
251 /** Opens the playback device given by \param name, or the default if empty. */
252 virtual Device
*openPlayback(const String
&name
=String()) = 0;
256 enum class PlaybackDeviceName
{
257 Basic
= ALC_DEVICE_SPECIFIER
,
258 Complete
= ALC_ALL_DEVICES_SPECIFIER
261 class ALURE_API Device
{
263 /** Retrieves the device name as given by \param type. */
264 virtual String
getName(PlaybackDeviceName type
=PlaybackDeviceName::Basic
) const = 0;
265 /** Queries the existence of an ALC extension on this device. */
266 virtual bool queryExtension(const char *extname
) const = 0;
269 * Retrieves the ALC version supported by this device, as constructed by
272 virtual ALCuint
getALCVersion() const = 0;
275 * Retrieves the EFX version supported by this device, as constructed by
276 * \ref MakeVersion. If the ALC_EXT_EFX extension is unsupported, this
279 virtual ALCuint
getEFXVersion() const = 0;
281 /** Retrieves the device's playback frequency, in hz. */
282 virtual ALCuint
getFrequency() const = 0;
285 * Retrieves the maximum number of auxiliary source sends. If ALC_EXT_EFX
286 * is unsupported, this will be 0.
288 virtual ALCuint
getMaxAuxiliarySends() const = 0;
291 * Enumerates available HRTF names. The names are sorted as OpenAL gives
292 * them, such that the index of a given name is the ID to use with
295 * Requires the ALC_SOFT_HRTF extension.
297 virtual Vector
<String
> enumerateHRTFNames() const = 0;
300 * Retrieves whether HRTF is enabled on the device or not.
302 * Requires the ALC_SOFT_HRTF extension.
304 virtual bool isHRTFEnabled() const = 0;
307 * Retrieves the name of the HRTF currently being used by this device.
309 * Requires the ALC_SOFT_HRTF extension.
311 virtual String
getCurrentHRTF() const = 0;
314 * Resets the device, using the specified \param attributes.
316 * Requires the ALC_SOFT_HRTF extension.
318 virtual void reset(const ALCint
*attributes
) = 0;
321 * Creates a new \ref Context on this device, using the specified
324 virtual Context
*createContext(const ALCint
*attributes
=0) = 0;
327 * Pauses device processing, stopping updates for its contexts. Multiple
328 * calls are allowed but it is not reference counted, so the device will
329 * resume after one \ref resumeDSP call.
331 * Requires the ALC_SOFT_pause_device extension.
333 virtual void pauseDSP() = 0;
336 * Resumes device processing, restarting updates for its contexts. Multiple
337 * calls are allowed and will no-op.
339 virtual void resumeDSP() = 0;
342 * Closes and frees the device. All previously-created contexts must first
345 virtual void close() = 0;
349 enum class DistanceModel
{
350 InverseClamped
= AL_INVERSE_DISTANCE_CLAMPED
,
351 LinearClamped
= AL_LINEAR_DISTANCE_CLAMPED
,
352 ExponentClamped
= AL_EXPONENT_DISTANCE_CLAMPED
,
353 Inverse
= AL_INVERSE_DISTANCE
,
354 Linear
= AL_LINEAR_DISTANCE
,
355 Exponent
= AL_EXPONENT_DISTANCE
,
359 class ALURE_API Context
{
361 /** Makes the specified \param context current for OpenAL operations. */
362 static void MakeCurrent(Context
*context
);
363 /** Retrieves the current context used for OpenAL operations. */
364 static Context
*GetCurrent();
367 * Makes the specified \param context current for OpenAL operations on the
368 * calling thread only. Requires the ALC_EXT_thread_local_context extension
369 * on both the context's device and the \ref DeviceManager.
371 static void MakeThreadCurrent(Context
*context
);
372 /** Retrieves the thread-specific context used for OpenAL operations. */
373 static Context
*GetThreadCurrent();
376 * Destroys the context. The context must not be current when this is
379 virtual void destroy() = 0;
381 /** Retrieves the \ref Device this context was created from. */
382 virtual Device
*getDevice() = 0;
384 virtual void startBatch() = 0;
385 virtual void endBatch() = 0;
388 * Retrieves a \ref Listener instance for this context. Each context will
389 * only have one listener.
391 virtual Listener
*getListener() = 0;
394 * Sets a MessageHandler instance which will be used to provide certain
395 * messages back to the application. Only one handler may be set for a
396 * context at a time. The previously set handler will be returned.
398 virtual SharedPtr
<MessageHandler
> setMessageHandler(SharedPtr
<MessageHandler
> handler
) = 0;
400 /** Gets the currently-set message handler. */
401 virtual SharedPtr
<MessageHandler
> getMessageHandler() const = 0;
404 * Specifies the desired interval (in milliseconds) that the background
405 * thread will be woken up to process tasks, e.g. keeping streaming sources
406 * filled. An interval of 0 means the background thread will only be woken
407 * up manually, for instance with calls to \ref update. The default is 0.
409 virtual void setAsyncWakeInterval(ALuint msec
) = 0;
412 * Retrieves the current interval used for waking up the background thread.
414 virtual ALuint
getAsyncWakeInterval() const = 0;
417 * Creates a \ref Decoder instance for the given audio file or resource
420 virtual SharedPtr
<Decoder
> createDecoder(const String
&name
) = 0;
422 // Functions below require the context to be current
425 * Creates and caches a \ref Buffer for the given audio file or resource
426 * \param name. Multiple calls with the same name will return the same
427 * \ref Buffer object.
429 virtual Buffer
*getBuffer(const String
&name
) = 0;
432 * Creates and caches a \ref Buffer for the given audio file or resource
433 * \param name. Multiple calls with the same name will return the same
434 * \ref Buffer object.
436 * The returned \ref Buffer object will be scheduled for loading
437 * asynchronously, and must be checked with a call to
438 * \ref Buffer::getLoadStatus prior to being played.
440 virtual Buffer
*getBufferAsync(const String
&name
) = 0;
443 * Deletes the cached \ref Buffer object for the given audio file or
444 * resource \param name. The buffer must not be in use by a \ref Source.
446 virtual void removeBuffer(const String
&name
) = 0;
448 * Deletes the given cached \param buffer instance. The buffer must not be
449 * in use by a \ref Source.
451 virtual void removeBuffer(Buffer
*buffer
) = 0;
454 * Gets a new \ref Source. There is no practical limit to the number of
455 * sources you may get.
457 virtual Source
*getSource() = 0;
459 virtual AuxiliaryEffectSlot
*createAuxiliaryEffectSlot() = 0;
461 virtual Effect
*createEffect() = 0;
463 virtual SourceGroup
*createSourceGroup() = 0;
465 virtual void setDopplerFactor(ALfloat factor
) = 0;
467 virtual void setSpeedOfSound(ALfloat speed
) = 0;
469 virtual void setDistanceModel(DistanceModel model
) = 0;
472 * Updates the context and all sources belonging to this context (you do
473 * not need to call the individual sources' update method if you call this
476 virtual void update() = 0;
480 enum class SampleType
{
486 ALURE_API
const char *GetSampleTypeName(SampleType type
);
488 enum class ChannelConfig
{
489 /** 1-channel mono sound. */
491 /** 2-channel stereo sound. */
493 /** 2-channel rear sound (back-left and back-right). */
495 /** 4-channel surround sound. */
497 /** 5.1 surround sound. */
499 /** 6.1 surround sound. */
501 /** 7.1 surround sound. */
503 /** 3-channel B-Format, using FuMa channel ordering and scaling. */
505 /** 4-channel B-Format, using FuMa channel ordering and scaling. */
508 ALURE_API
const char *GetChannelConfigName(ChannelConfig cfg
);
510 enum class BufferLoadStatus
{
515 class ALURE_API Listener
{
517 virtual void setGain(ALfloat gain
) = 0;
519 virtual void setPosition(ALfloat x
, ALfloat y
, ALfloat z
) = 0;
520 virtual void setPosition(const ALfloat
*pos
) = 0;
522 virtual void setVelocity(ALfloat x
, ALfloat y
, ALfloat z
) = 0;
523 virtual void setVelocity(const ALfloat
*vel
) = 0;
525 virtual void setOrientation(ALfloat x1
, ALfloat y1
, ALfloat z1
, ALfloat x2
, ALfloat y2
, ALfloat z2
) = 0;
526 virtual void setOrientation(const ALfloat
*at
, const ALfloat
*up
) = 0;
527 virtual void setOrientation(const ALfloat
*ori
) = 0;
529 virtual void setMetersPerUnit(ALfloat m_u
) = 0;
533 class ALURE_API Buffer
{
536 * Retrieves the length of the buffer in sample frames. The buffer must be
537 * fully loaded before this method is called.
539 virtual ALuint
getLength() const = 0;
541 /** Retrieves the buffer's frequency in hz. */
542 virtual ALuint
getFrequency() const = 0;
544 /** Retrieves the buffer's sample configuration. */
545 virtual ChannelConfig
getChannelConfig() const = 0;
547 /** Retrieves the buffer's sample type. */
548 virtual SampleType
getSampleType() const = 0;
551 * Retrieves the storage size used by the buffer, in bytes. The buffer must
552 * be fully loaded before this method is called.
554 virtual ALuint
getSize() const = 0;
557 * Sets the buffer's loop points, used for looping sources. If the current
558 * context does not support the AL_SOFT_loop_points extension, \param start
559 * and \param end must be 0 and \ref getLength() respectively. Otherwise,
560 * \param start must be less than \param end, and \param end must be less
561 * than or equal to \ref getLength().
563 * The buffer must not be in use when this method is called, and the buffer
564 * must be fully loaded.
566 * \param start The starting point, in sample frames (inclusive).
567 * \param end The ending point, in sample frames (exclusive).
569 virtual void setLoopPoints(ALuint start
, ALuint end
) = 0;
572 * Retrieves the current loop points as a [start,end) pair. The buffer must
573 * be fully loaded before this method is called.
575 virtual std::pair
<ALuint
,ALuint
> getLoopPoints() const = 0;
578 * Retrieves the \ref Source objects currently playing the buffer. Stopping
579 * the returned sources will allow the buffer to be removed from the
582 virtual Vector
<Source
*> getSources() const = 0;
585 * Queries the buffer's load status. A return of \ref BufferLoad_Pending
586 * indicates the buffer is not finished loading and can't be used with a
587 * call to \ref Source::play. Buffers created with \ref Context::getBuffer
588 * will always return \ref BufferLoad_Ready.
590 virtual BufferLoadStatus
getLoadStatus() = 0;
592 /** Retrieves the name the buffer was created with. */
593 virtual const String
&getName() const = 0;
595 /** Queries if the buffer is in use and can't be removed. */
596 virtual bool isInUse() const = 0;
600 class ALURE_API Source
{
603 * Plays the source using \param buffer. The same buffer may be played from
604 * multiple sources simultaneously.
606 virtual void play(Buffer
*buffer
) = 0;
608 * Plays the source by streaming audio from \param decoder. This will use
609 * \param queuelen buffers, each with \param updatelen sample frames. The
610 * given decoder must *NOT* have its read or seek methods called from
611 * elsewhere while in use.
613 virtual void play(SharedPtr
<Decoder
> decoder
, ALuint updatelen
, ALuint queuesize
) = 0;
615 * Stops playback, releasing the buffer or decoder reference.
617 virtual void stop() = 0;
619 /** Pauses the source if it is playing. */
620 virtual void pause() = 0;
622 /** Resumes the source if it is paused. */
623 virtual void resume() = 0;
625 /** Specifies if the source is currently playing. */
626 virtual bool isPlaying() const = 0;
628 /** Specifies if the source is currently paused. */
629 virtual bool isPaused() const = 0;
632 * Specifies the source's playback priority. Lowest priority sources will
633 * be evicted first when higher priority sources are played.
635 virtual void setPriority(ALuint priority
) = 0;
636 /** Retrieves the source's priority. */
637 virtual ALuint
getPriority() const = 0;
640 * Sets the source's offset, in sample frames. If the source is playing or
641 * paused, it will go to that offset immediately, otherwise the source will
642 * start at the specified offset the next time it's played.
644 virtual void setOffset(uint64_t offset
) = 0;
646 * Retrieves the source offset in sample frames. For streaming sources,
647 * this will be the offset from the beginning of the stream based on the
648 * decoder's reported position.
650 * \param latency If non-NULL and the device supports it, the source's
651 * latency, in nanoseconds, will be written to that location.
653 virtual uint64_t getOffset(uint64_t *latency
=0) const = 0;
656 * Specifies if the source should loop on the \ref Buffer or \ref Decoder
657 * object's loop points.
659 virtual void setLooping(bool looping
) = 0;
660 virtual bool getLooping() const = 0;
663 * Specifies a linear pitch shift base. A value of 1.0 is the default
666 virtual void setPitch(ALfloat pitch
) = 0;
667 virtual ALfloat
getPitch() const = 0;
670 * Specifies the base linear gain. A value of 1.0 is the default normal
673 virtual void setGain(ALfloat gain
) = 0;
674 virtual ALfloat
getGain() const = 0;
677 * Specifies the minimum and maximum gain. The source's gain is clamped to
678 * this range after distance attenuation and cone attenuation are applied
679 * to the gain base, although before the filter gain adjustements.
681 virtual void setGainRange(ALfloat mingain
, ALfloat maxgain
) = 0;
682 virtual ALfloat
getMinGain() const = 0;
683 virtual ALfloat
getMaxGain() const = 0;
686 * Specifies the reference distance and maximum distance the source will
687 * use for the current distance model. For Clamped distance models, the
688 * source's calculated distance is clamped to the specified range before
689 * applying distance-related attenuation.
691 * For all distance models, the reference distance is the distance at which
692 * the source's volume will not have any extra attenuation (an effective
693 * gain multiplier of 1).
695 virtual void setDistanceRange(ALfloat refdist
, ALfloat maxdist
) = 0;
696 virtual ALfloat
getReferenceDistance() const = 0;
697 virtual ALfloat
getMaxDistance() const = 0;
699 /** Specifies the source's 3D position. */
700 virtual void setPosition(ALfloat x
, ALfloat y
, ALfloat z
) = 0;
701 virtual void setPosition(const ALfloat
*pos
) = 0;
702 virtual Vector3
getPosition() const = 0;
705 * Specifies the source's 3D velocity, in units per second. As with OpenAL,
706 * this does not actually alter the source's position, and instead just
707 * alters the pitch as determined by the doppler effect.
709 virtual void setVelocity(ALfloat x
, ALfloat y
, ALfloat z
) = 0;
710 virtual void setVelocity(const ALfloat
*vel
) = 0;
711 virtual Vector3
getVelocity() const = 0;
714 * Specifies the source's 3D facing direction. Deprecated in favor of
715 * \ref setOrientation.
717 virtual void setDirection(ALfloat x
, ALfloat y
, ALfloat z
) = 0;
718 virtual void setDirection(const ALfloat
*dir
) = 0;
719 virtual Vector3
getDirection() const = 0;
722 * Specifies the source's 3D orientation. Note: unlike the AL_EXT_BFORMAT
723 * extension this property comes from, this also affects the facing
724 * direction, superceding \ref setDirection.
726 virtual void setOrientation(ALfloat x1
, ALfloat y1
, ALfloat z1
, ALfloat x2
, ALfloat y2
, ALfloat z2
) = 0;
727 virtual void setOrientation(const ALfloat
*at
, const ALfloat
*up
) = 0;
728 virtual void setOrientation(const ALfloat
*ori
) = 0;
731 * Specifies the source's cone angles, in degrees. The inner angle is the
732 * area within which the listener will hear the source with no extra
733 * attenuation, while the listener being outside of the outer angle will
734 * hear the source attenuated according to the outer cone gains.
736 virtual void setConeAngles(ALfloat inner
, ALfloat outer
) = 0;
737 virtual ALfloat
getInnerConeAngle() const = 0;
738 virtual ALfloat
getOuterConeAngle() const = 0;
741 * Specifies the linear gain multiplier when the listener is outside of the
742 * source's outer cone area. The specified \param gain applies to all
743 * frequencies, while \param gainhf applies extra attenuation to high
746 * \param gainhf has no effect without the ALC_EXT_EFX extension.
748 virtual void setOuterConeGains(ALfloat gain
, ALfloat gainhf
=1.0f
) = 0;
749 virtual ALfloat
getOuterConeGain() const = 0;
750 virtual ALfloat
getOuterConeGainHF() const = 0;
753 * Specifies the rolloff factors for the direct and send paths. This is
754 * effectively a distance scaling relative to the reference distance. Note:
755 * the room rolloff factor is 0 by default, disabling distance attenuation
756 * for send paths. This is because the reverb engine will, by default,
757 * apply a more realistic room attenuation based on the reverb decay time
758 * and direct path attenuation.
760 virtual void setRolloffFactors(ALfloat factor
, ALfloat roomfactor
=0.0f
) = 0;
761 virtual ALfloat
getRolloffFactor() const = 0;
762 virtual ALfloat
getRoomRolloffFactor() const = 0;
765 * Specifies the doppler factor for the doppler effect's pitch shift. This
766 * effectively scales the source and listener velocities for the doppler
769 virtual void setDopplerFactor(ALfloat factor
) = 0;
770 virtual ALfloat
getDopplerFactor() const = 0;
772 /** Specifies if the source properties are relative to the listener. */
773 virtual void setRelative(bool relative
) = 0;
774 virtual bool getRelative() const = 0;
777 * Specifies the source's radius. This causes the source to behave as if
778 * every point within the spherical area emits sound.
780 * Has no effect without the AL_EXT_SOURCE_RADIUS extension.
782 virtual void setRadius(ALfloat radius
) = 0;
783 virtual ALfloat
getRadius() const = 0;
786 * Specifies the left and right channel angles, in radians, when playing a
787 * stereo buffer or stream. The angles go counter-clockwise, with 0 being
788 * in front and positive values going left.
790 * Has no effect without the AL_EXT_STEREO_ANGLES extension.
792 virtual void setStereoAngles(ALfloat leftAngle
, ALfloat rightAngle
) = 0;
793 virtual std::pair
<ALfloat
,ALfloat
> getStereoAngles() const = 0;
795 virtual void setAirAbsorptionFactor(ALfloat factor
) = 0;
796 virtual ALfloat
getAirAbsorptionFactor() const = 0;
798 virtual void setGainAuto(bool directhf
, bool send
, bool sendhf
) = 0;
799 virtual bool getDirectGainHFAuto() const = 0;
800 virtual bool getSendGainAuto() const = 0;
801 virtual bool getSendGainHFAuto() const = 0;
803 /** Sets the \param filter properties on the direct path signal. */
804 virtual void setDirectFilter(const FilterParams
&filter
) = 0;
806 * Sets the \param filter properties on the given \param send path signal.
807 * Any auxiliary effect slot on the send path remains in place.
809 virtual void setSendFilter(ALuint send
, const FilterParams
&filter
) = 0;
811 * Connects the effect slot \param slot to the given \param send path. Any
812 * filter properties on the send path remain as they were.
814 virtual void setAuxiliarySend(AuxiliaryEffectSlot
*slot
, ALuint send
) = 0;
816 * Connects the effect slot \param slot to the given \param send path,
817 * using the \param filter properties.
819 virtual void setAuxiliarySendFilter(AuxiliaryEffectSlot
*slot
, ALuint send
, const FilterParams
&filter
) = 0;
822 * Updates the source, ensuring that resources are released when playback
825 virtual void update() = 0;
828 * Releases the source, stopping playback, releasing resources, and
829 * returning it to the system.
831 virtual void release() = 0;
835 class ALURE_API SourceGroup
{
838 * Adds \param source to the source group. A source may only be part of one
839 * group at a time, and will automatically be removed from its current
842 virtual void addSource(Source
*source
) = 0;
843 /** Removes \param source from the source group. */
844 virtual void removeSource(Source
*source
) = 0;
846 /** Adds a list of sources to the group at once. */
847 virtual void addSources(const Vector
<Source
*> &sources
) = 0;
848 /** Removes a list of sources from the source group. */
849 virtual void removeSources(const Vector
<Source
*> &sources
) = 0;
852 * Adds \param group as a subgroup of the source group. This method will
853 * throw an exception if \param group is being added to a group it has as a
854 * sub-group (i.e. it would create a circular sub-group chain).
856 virtual void addSubGroup(SourceGroup
*group
) = 0;
857 /** Removes \param group from the source group. */
858 virtual void removeSubGroup(SourceGroup
*group
) = 0;
860 /** Returns the list of sources currently in the group. */
861 virtual Vector
<Source
*> getSources() = 0;
863 /** Returns the list of subgroups currently in the group. */
864 virtual Vector
<SourceGroup
*> getSubGroups() = 0;
866 /** Sets the source group gain, which accumulates with its sources. */
867 virtual void setGain(ALfloat gain
) = 0;
868 /** Gets the source group gain. */
869 virtual ALfloat
getGain() const = 0;
871 /** Sets the source group pitch, which accumulates with its sources. */
872 virtual void setPitch(ALfloat pitch
) = 0;
873 /** Gets the source group pitch. */
874 virtual ALfloat
getPitch() const = 0;
877 * Pauses all currently-playing sources that are under this group,
878 * including sub-groups.
880 virtual void pauseAll() const = 0;
882 * Resumes all paused sources that are under this group, including
885 virtual void resumeAll() const = 0;
887 /** Stops all sources that are under this group, including sub-groups. */
888 virtual void stopAll() const = 0;
891 * Releases the source group, removing all sources from it before being
894 virtual void release() = 0;
903 class ALURE_API AuxiliaryEffectSlot
{
905 virtual void setGain(ALfloat gain
) = 0;
907 * If set to true, the reverb effect will automatically apply adjustments
908 * to the source's send slot based on the effect properties.
910 * Has no effect when using non-reverb effects. Default is true.
912 virtual void setSendAuto(bool sendauto
) = 0;
915 * Updates the effect slot with a new \param effect. The given effect
916 * object may be altered or destroyed without affecting the effect slot.
918 virtual void applyEffect(const Effect
*effect
) = 0;
921 * Releases the effect slot, returning it to the system. It must not be in
924 virtual void release() = 0;
927 * Retrieves each \ref Source object and its pairing send this effect slot
928 * is set on. Setting a different (or null) effect slot on each source's
929 * given send will allow the effect slot to be released.
931 virtual Vector
<SourceSend
> getSourceSends() const = 0;
933 /** Determines if the effect slot is in use by a source. */
934 virtual bool isInUse() const = 0;
938 class ALURE_API Effect
{
941 * Updates the effect with the specified reverb properties \param props. If
942 * the EAXReverb effect is not supported, it will automatically attempt to
943 * downgrade to the Standard Reverb effect.
945 virtual void setReverbProperties(const EFXEAXREVERBPROPERTIES
&props
) = 0;
947 virtual void destroy() = 0;
952 * Audio decoder interface. Applications may derive from this, implementing the
953 * necessary methods, and use it in places the API wants a Decoder object.
955 class ALURE_API Decoder
{
957 virtual ~Decoder() { }
959 /** Retrieves the sample frequency, in hz, of the audio being decoded. */
960 virtual ALuint
getFrequency() const = 0;
961 /** Retrieves the channel configuration of the audio being decoded. */
962 virtual ChannelConfig
getChannelConfig() const = 0;
963 /** Retrieves the sample type of the audio being decoded. */
964 virtual SampleType
getSampleType() const = 0;
967 * Retrieves the total length of the audio, in sample frames. If unknown,
968 * returns 0. Note that if the returned length is 0, the decoder may not be
969 * used to load a \ref Buffer.
971 virtual uint64_t getLength() = 0;
973 * Retrieves the current sample frame position (i.e. the number of sample
974 * frames from the beginning).
976 virtual uint64_t getPosition() = 0;
978 * Seek to \param pos, specified in sample frames. Returns true if the seek
981 virtual bool seek(uint64_t pos
) = 0;
984 * Retrieves the loop points, in sample frames, as a [start,end) pair. If
985 * start >= end, use all available data.
987 virtual std::pair
<uint64_t,uint64_t> getLoopPoints() const = 0;
990 * Decodes \param count sample frames, writing them to \param ptr, and
991 * returns the number of sample frames written. Returning less than the
992 * requested count indicates the end of the audio.
994 virtual ALuint
read(ALvoid
*ptr
, ALuint count
) = 0;
998 * Audio decoder factory interface. Applications may derive from this,
999 * implementing the necessary methods, and use it in places the API wants a
1000 * DecoderFactory object.
1002 class ALURE_API DecoderFactory
{
1004 virtual ~DecoderFactory() { }
1007 * Creates and returns a \ref Decoder instance for the given resource
1008 * \param file. Returns NULL if a decoder can't be created from the file.
1010 virtual SharedPtr
<Decoder
> createDecoder(SharedPtr
<std::istream
> file
) = 0;
1014 * Registers a decoder factory for decoding audio. Registered factories are
1015 * used in lexicographical order, e.g. if Factory1 is registered with name1 and
1016 * Factory2 is registered with name2, Factory1 will be used before Factory2 if
1017 * name1 < name2. Internal decoder factories are always used after registered
1020 * Alure retains a reference to the DecoderFactory instance and will release it
1021 * (potentially destroying the object) when the library unloads.
1023 * \param name A unique name identifying this decoder factory.
1024 * \param factory A DecoderFactory instance used to create Decoder instances.
1026 ALURE_API
void RegisterDecoder(const String
&name
, UniquePtr
<DecoderFactory
> factory
);
1029 * Unregisters a decoder factory by name. Alure returns the instance back to
1032 * \param name The unique name identifying a previously-registered decoder
1035 * \return The unregistered decoder factory instance, or 0 (nullptr) if a
1036 * decoder factory with the given name doesn't exist.
1038 ALURE_API UniquePtr
<DecoderFactory
> UnregisterDecoder(const String
&name
);
1042 * A file I/O factory interface. Applications may derive from this and set an
1043 * instance to be used by the audio decoders. By default, the library uses
1046 class ALURE_API FileIOFactory
{
1049 * Sets the \param factory instance to be used by the audio decoders. If a
1050 * previous factory was set, it's returned to the application. Passing in a
1051 * NULL factory reverts to the default.
1053 static UniquePtr
<FileIOFactory
> set(UniquePtr
<FileIOFactory
> factory
);
1056 * Gets the current FileIOFactory instance being used by the audio
1059 static FileIOFactory
&get();
1061 virtual ~FileIOFactory() { }
1063 /** Opens a read-only binary file for the given \param name. */
1064 virtual SharedPtr
<std::istream
> openFile(const String
&name
) = 0;
1069 * A message handler interface. Applications may derive from this and set an
1070 * instance on a context to receive messages. The base methods are no-ops, so
1071 * derived classes only need to implement methods for relevant messages.
1073 * It's recommended that applications mark their handler methods using the
1074 * override keyword, to ensure they're properly overriding the base methods in
1077 class ALURE_API MessageHandler
{
1079 virtual ~MessageHandler();
1082 * Called when the given \param device has been disconnected and is no
1083 * longer usable for output. As per the ALC_EXT_disconnect specification,
1084 * disconnected devices remain valid, however all playing sources are
1085 * automatically stopped, any sources that are attempted to play will
1086 * immediately stop, and new contexts may not be created on the device.
1088 * Note that connection status is checked during \ref Context::update
1089 * calls, so that method must be called regularly to be notified when a
1090 * device is disconnected. This method may not be called if the device
1091 * lacks support for the ALC_EXT_disconnect extension.
1093 * WARNING: Do not attempt to clean up resources within this callback
1094 * method, as Alure is in the middle of doing updates. Instead, flag the
1095 * device as having been lost and do cleanup later.
1097 virtual void deviceDisconnected(Device
*device
);
1100 * Called when the given \param source stops playback. If \param forced is
1101 * true, the source was stopped because either there were no more system
1102 * sources and a higher-priority source needs to play, or it's part of a
1103 * \ref SourceGroup (or sub-group thereof) that had its
1104 * \ref SourceGroup::stopAll method called.
1106 * Sources that stopped automatically will be detected upon a call to
1107 * \ref Context::update or \ref Source::update, and will have \param forced
1110 virtual void sourceStopped(Source
*source
, bool forced
);
1113 * Called when a new buffer is about to be created and loaded. May be
1114 * called asynchronously for buffers being loaded asynchronously.
1116 * \param name The resource name, as passed to \ref Context::getBuffer.
1117 * \param channels Channel configuration of the given audio data.
1118 * \param type Sample type of the given audio data.
1119 * \param samplerate Sample rate of the given audio data.
1120 * \param data The audio data that is about to be fed to the OpenAL buffer.
1122 virtual void bufferLoading(const String
&name
, ChannelConfig channels
, SampleType type
, ALuint samplerate
, const Vector
<ALbyte
> &data
);
1125 * Called when a resource isn't found, allowing the app to substitute in a
1126 * different resource. For buffers created with \ref Context::getBuffer or
1127 * \ref Context::getBufferAsync, the original name will still be used for
1128 * the cache map so the app doesn't have to keep track of substituted
1131 * This will be called again if the new name isn't found.
1133 * \param name The resource name that was not found.
1134 * \return The resplacement resource name to use instead. Returning an
1135 * empty string means to stop trying.
1137 virtual String
resourceNotFound(const String
&name
);
1140 } // namespace alure
1142 #endif /* AL_ALURE2_H */