gfxdev
/
caudio
1
0
Fork 0
Code Issues 1 Pull Requests Projects Releases Activity

More commenting.

This commit is contained in:
Joshua Jones 2010-02-17 05:57:55 +00:00
parent ffb0a8bdf9
commit b05550fe69
10 changed files with 260 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
include/IAudioSource.h
View File

@ -15,78 +15,123 @@
namespace cAudio
{
//! Interface for a single audio source, which allow you to manipulate sound sources (speakers) in 2D or 3D space.
class IAudioSource : public IRefCounted
{
public:
IAudioSource() {}
virtual ~IAudioSource() {}
//! Plays the source with the default or last set values
//! Plays the source with the last set parameters.
/**
\return True if the source is playing, false if not. */
virtual bool play() = 0;
//! Plays the source in 2D mode
//! Plays the source in 2D mode.
/** No automatic attenuation or panning will take place in this mode, but using setPosition will allow you to manually pan mono audio streams.
\param toLoop: Whether to loop (restart) the audio when the end is reached.
\return True if the source is playing, false if not. */
virtual bool play2d(const bool& toLoop = false) = 0;
//! Plays the source in 3D mode
//! Plays the source in 3D mode.
/**
\param position: Position to start the sound off at.
\param soundstr: Affects how the source attenuates due to distance. Higher values cause the source to stand out more over distance.
\param toLoop: Whether to loop (restart) the audio when the end is reached.
\return True if the source is playing, false if not. */
virtual bool play3d(const cVector3& position, const float& soundstr = 1.0 , const bool& toLoop = false) = 0;
//! Pauses playback of the sound source
//! Pauses playback of the sound source.
virtual void pause() = 0;
//! Stops playback of the sound source
//! Stops playback of the sound source.
virtual void stop() = 0;
//! Controls whether the source should loop or not
//! Controls whether the source should loop or not.
/** \param toLoop: Whether to loop (restart) the audio when the end is reached. */
virtual void loop(const bool& toLoop) = 0;
//! Seeks through the audio stream to a specific spot
/** Note: May not be supported by all codecs
\param seconds: Number of seconds to seek
\param relative: Whether to seek from the current position or the start of the stream
//! Seeks through the audio stream to a specific spot.
/** Note: May not be supported by all codecs.
\param seconds: Number of seconds to seek.
\param relative: Whether to seek from the current position or the start of the stream.
\return True on success, False if the codec does not support seeking. */
virtual bool seek(const float& seconds, bool relative = false) = 0;
//! Returns the total amount of time in the audio stream. See IAudioDecoder for details.
virtual float getTotalAudioTime() = 0;
//! Returns the total decoded size of the audio stream. See IAudioDecoder for details.
virtual int getTotalAudioSize() = 0;
//! Returns the original size of the audio stream. See IAudioDecoder for details.
virtual int getCompressedAudioSize() = 0;
//! Returns the current position in the audio stream in seconds. See IAudioDecoder for details.
virtual float getCurrentAudioTime() = 0;
//! Returns the current position in the decoded audio stream in bytes. See IAudioDecoder for details.
virtual int getCurrentAudioPosition() = 0;
//! Returns the current position in the original audio stream in bytes. See IAudioDecoder for details.
virtual int getCurrentCompressedAudioPosition() = 0;
//! Normally called every frame by the audio manager to update the internal buffers
//! Note: For internal use only.
//! Normally called every frame by the audio manager to update the internal buffers. Note: For internal use only.
virtual bool update() = 0;
//! Releases all resources used by the audio source, normally used to clean up before deletion
//! Note: For internal use only.
//! Releases all resources used by the audio source, normally used to clean up before deletion. Note: For internal use only.
virtual void release() = 0;
//! Returns if the source is ready to be used
//! Returns if the source is ready to be used.
virtual const bool isValid() const = 0;
//! Returns if the source is playing
//! Returns if the source is playing.
virtual const bool isPlaying() const = 0;
//! Returns if the source is paused
//! Returns if the source is paused.
virtual const bool isPaused() const = 0;
//! Returns if the source is stopped
//! Returns if the source is stopped.
virtual const bool isStopped() const = 0;
//! Returns if the source is looping
//! Returns if the source is looping.
virtual const bool isLooping() const = 0;
//! Sets the position of the source in 3D space
//! Sets the position of the source in 3D space.
/**
\param position: A 3D vector giving the new location to put this source. */
virtual void setPosition(const cVector3& position) = 0;
//! Sets the current velocity of the source for doppler effects
//! Sets the current velocity of the source for doppler effects.
/**
\param velocity: A 3D vector giving the speed and direction that the source is moving. */
virtual void setVelocity(const cVector3& velocity) = 0;
//! Sets the direction the source is facing
//! Sets the direction the source is facing.
/**
\param direction: A 3D vector giving the direction that the source is aiming. */
virtual void setDirection(const cVector3& direction) = 0;
//! Sets the factor used in attenuating the source over distance
//! Larger values make it attenuate faster, smaller values make the source carry better
//! Range: 0.0f to +inf (Default: 1.0f)
//! Sets the factor used in attenuating the source over distance.
/** Larger values make it attenuate faster, smaller values make the source carry better.
Range: 0.0f to +inf (Default: 1.0f).
\param rolloff: The rolloff factor to apply to the attenuation calculation. */
virtual void setRolloffFactor(const float& rolloff) = 0;
//! Sets how well the source carries over distance
//! Same as setRolloffFactor(1.0f/soundstrength)
//! Range: 0.0f to +inf (Default: 1.0f)
//! Sets how well the source carries over distance.
/** Same as setRolloffFactor(1.0f/soundstrength).
Range: 0.0f to +inf (Default: 1.0f).
\param soundstrength: How well the sound carries over distance. */
virtual void setStrength(const float& soundstrength) = 0;
//! Sets the distance from the source where attenuation will begin
//! Range: 0.0f to +inf
//! Sets the distance from the source where attenuation will begin.
/** Range: 0.0f to +inf
\param minDistance: Distance from the source where attenuation begins. */
virtual void setMinDistance(const float& minDistance) = 0;
//! Sets the distance from the source where attenuation will stop
//! Range: 0.0f to +inf
/** Range: 0.0f to +inf
\param maxDistance: Distance where attenuation will cease. Normally the farthest range you can heard the source. */
virtual void setMaxDistance(const float& maxDistance) = 0;
//! Sets the pitch of the source
@ -177,7 +222,7 @@ namespace cAudio
//! Range (slot): 0 to getNumEffectSlotsAvailable()
virtual void removeEffect(unsigned int slot) = 0;
//! Attaches an audio filter to this sound source that will operate on the direct feed, seperate from any effects
//! Attaches an audio filter to this sound source that will operate on the direct feed, separate from any effects
virtual bool attachFilter(IFilter* filter) = 0;
//! Removes the previously attached filter
virtual void removeFilter() = 0;

2
include/IEffect.h
View File

@ -160,7 +160,7 @@ namespace cAudio
//! Sets the master volume for this effect.
/** This volume scales the amount of effect audible from all attached sources.
\param volume: Volume to set the master volume to. 1.0f equal no volume change. Range: 0.0f to inf.*/
\param volume: Volume to set the master volume to. 1.0f equal no volume change. Range: 0.0f to 1.0.*/
virtual void setMasterVolume(const float& volume) = 0;
//! Returns if the effect for each attached source is attenuated by distance.

24
include/IFilter.h
View File

@ -22,25 +22,49 @@ namespace cAudio
EFT_COUNT
};
//! Interface for a filter in cAudio.
class IFilter : public IRefCounted
{
public:
IFilter() { }
virtual ~IFilter() { }
//! Returns the type of the filter.
virtual const FilterTypes& getType() const = 0;
//! Sets the type of this filter.
/**
\param type: Type of filter to set this filter up as. */
virtual void setType(const FilterTypes& type) = 0;
//! Returns the master volume of this filter.
virtual float getVolume() const = 0;
//! Sets the master volume of this filter.
/** This volume scales all audio that goes through it by this amount.
\param volume: New volume amount. Range: 0.0f to 1.0. */
virtual void setVolume(const float& volume) = 0;
//! Returns the volume for low frequencies.
virtual float getLowFrequencyVolume() const = 0;
//! Sets the volume for low frequencies.
/** This volume scales lower frequency audio that goes through it by this amount.
\param volume: New volume amount. Range: 0.0f to 1.0. */
virtual void setLowFrequencyVolume(const float& volumeLF) = 0;
//! Returns the volume for high frequencies.
virtual float getHighFrequencyVolume() const = 0;
//! Sets the volume for high frequencies.
/** This volume scales higher frequency audio that goes through it by this amount.
\param volume: New volume amount. Range: 0.0f to 1.0. */
virtual void setHighFrequencyVolume(const float& volumeHF) = 0;
//! Returns a timestamp indicating the last time settings on this filter were changed. Used internally by the engine to update attached sources or effects.
virtual unsigned int getLastUpdated() const = 0;
//! Returns if this filter is ready to be used or if it has encountered a fatal error.
virtual bool isValid() const = 0;
};
};

55
include/IListener.h
View File

@ -10,44 +10,67 @@
namespace cAudio
{
//! Interface for the listener in cAudio. This class provides abilities to move and orient where your camera or user is in the audio world.
class IListener
{
public:
IListener() {}
virtual ~IListener() {}
//!Sets the position of the listener
//!Note that you will still have to set velocity after this call for proper doppler effects
//!Use move() if you'd like to have cAudio automatically handle velocity for you
//! Sets the position of the listener.
/** Note that you will still have to set velocity after this call for proper doppler effects.
Use move() if you'd like to have cAudio automatically handle velocity for you. */
/**
\param pos: New position for the listener. */
virtual void setPosition(const cVector3 pos) = 0;
//!Sets the direction the listener is facing
//! Sets the direction the listener is facing
/**
\param dir: New direction vector for the listener. */
virtual void setDirection(const cVector3 dir) = 0;
//!Sets the up vector to use for the listener
//! Sets the up vector to use for the listener
/** Default up vector is Y+, same as OpenGL.
\param up: New up vector for the listener. */
virtual void setUpVector(const cVector3 up) = 0;
//!Sets the current velocity of the listener for doppler effects
//! Sets the current velocity of the listener for doppler effects
/**
\param vel: New velocity for the listener. */
virtual void setVelocity(const cVector3 vel) = 0;
//!Sets the global volume modifier (will effect all sources)
//! Sets the global volume modifier (will effect all sources)
/**
\param volume: Volume to scale all sources by. Range: 0.0 to +inf. */
virtual void setMasterVolume(const float volume) = 0;
//!Convenience function to automatically set the velocity and position for you in a single call
//!Velocity will be set to new position - last position
//! Convenience function to automatically set the velocity and position for you in a single call
/** Velocity will be set to new position - last position
\param pos: New position to move the listener to. */
virtual void move(const cVector3 pos) = 0;
//!Returns the current position of the listener
//! Returns the current position of the listener
virtual cVector3 getPosition(void) const = 0;
//!Returns the current direction of the listener
//! Returns the current direction of the listener
virtual cVector3 getDirection(void) const = 0;
//!Returns the current up vector of the listener
//! Returns the current up vector of the listener
virtual cVector3 getUpVector(void) const = 0;
//!Returns the current velocity of the listener
//! Returns the current velocity of the listener
virtual cVector3 getVelocity(void) const = 0;
//!Returns the global volume modifier for all sources
//! Returns the global volume modifier for all sources
virtual float getMasterVolume(void) const = 0;
#ifdef CAUDIO_EFX_ENABLED
//!Sets the meters per user world unit for use with sound effects
//! Sets the meters per user world unit for use with sound effects
/**
\param meters: Number of meters per world unit in your simulation. */
virtual void setMetersPerUnit(const float& meters) = 0;
//!Returns the meters per user world unit for use with sound effects
//! Returns the meters per user world unit for use with sound effects
virtual float getMetersPerUnit(void) const = 0;
#endif

9
include/ILogReceiver.h
View File

@ -7,6 +7,7 @@
namespace cAudio
{
//! Enum of all supported log levels in cAudio.
enum LogLevel
{
ELL_DEBUG,
@ -17,6 +18,7 @@ namespace cAudio
ELL_COUNT
};
//! Contains strings for each log level to make them easier to print to a stream.
const char* const LogLevelStrings[] =
{
"Debug",
@ -27,12 +29,19 @@ namespace cAudio
0
};
//! Interface for receiving log messages and relaying them to some kind of output device or stream.
class ILogReceiver
{
public:
ILogReceiver() { }
~ILogReceiver() { }
//! Called on every logged message that is greater than or equal to the minimum log level.
/**
\param sender: The class/component sending the message.
\param message: The log message itself.
\param level: Log level of the message.
\param time: Time in seconds that the message was sent. This time has millisecond accuracy. */
virtual bool OnLogMessage(const char* sender, const char* message, LogLevel level, float time) = 0;
};
};

60
include/ILogger.h
View File

@ -10,40 +10,82 @@
namespace cAudio
{
//! Interface for all logging operations in cAudio.
class ILogger
{
public:
ILogger() { }
virtual ~ILogger() { }
//! Used to log a critical error message to the logging system.
/**
\param sender: Name of the class/component sending the message.
\param msg: The message to send. */
virtual void logCritical( const char* sender, const char *msg, ... ) = 0;
//! Used to log an error message to the logging system.
/**
\param sender: Name of the class/component sending the message.
\param msg: The message to send. */
virtual void logError( const char* sender, const char *msg, ... ) = 0;
//! Used to log a warning to the logging system.
/**
\param sender: Name of the class/component sending the message.
\param msg: The message to send. */
virtual void logWarning( const char* sender, const char *msg, ... ) = 0;
//! Used to log an informational message to the logging system.
/**
\param sender: Name of the class/component sending the message.
\param msg: The message to send. */
virtual void logInfo( const char* sender, const char *msg, ... ) = 0;
//! Used to log a debug message to the logging system.
/**
\param sender: Name of the class/component sending the message.
\param msg: The message to send. */
virtual void logDebug( const char* sender, const char *msg, ... ) = 0;
//! Returns the minimum log level that will be sent to the log receivers.
virtual const LogLevel& getLogLevel() const = 0;
//! Sets the minimum log level that the engine will send to log receivers.
/** Primarily used to prevent too much verbose information from being sent to disk/console.
\param logLevel: LogLevel to set as the new minimum. Anything equal to or greater than this level will be logged. */
virtual void setLogLevel( const LogLevel& logLevel ) = 0;
//! Register Log Receiver
//! Note: Any class registered will become owned by the internal thread.
//! If threading is enabled, you MUST make the receiver threadsafe if you plan to access it in your application while it is registered
//! Register Log Receiver.
/** Note: Any class registered will become owned by the internal thread.
If threading is enabled, you MUST make the receiver threadsafe if you plan to access it in your application while it is registered.
\param receiver: Pointer to your implementation of ILogReceiver.
\param name: Name of the log receiver.
\return True on success, False on failure. */
virtual bool registerLogReceiver(ILogReceiver* receiver, const char* name) = 0;
//!Unregister a Log Receiver
//!Will NOT delete any user added receiver, you must do that yourself
//! Unregister a Log Receiver.
/** Will NOT delete any user added receiver, you must do that yourself.
\param name: Name of the log receiver to remove. */
virtual void unRegisterLogReceiver(const char* name) = 0;
//!Returns whether an log receiver is currently registered
//! Returns whether an log receiver is currently registered.
/**
\param name: Name of the log receiver to check for. */
virtual bool isLogReceiverRegistered(const char* name) = 0;
//!Returns a registered log receiver
//! Returns a registered log receiver.
/**
\param name: Name of the log receiver to return.
\return Pointer to the found log receiver or NULL if it could not be found. */
virtual ILogReceiver* getLogReceiver(const char* name) = 0;
protected:
private:
};
//! Gets the interface to the logger
//! Gets the interface to the logger.
/** Note: This is the only way to get access to the logging capabilities of cAudio.
\return A pointer to the object
\return A pointer to the logger interface.
*/
CAUDIO_API ILogger* getLogger();
};

25
include/IManagerEventHandler.h
View File

@ -5,27 +5,30 @@
#ifndef IMANAGEREVENTHANDLER_H
#define IMANAGEREVENTHANDLER_H
namespace cAudio{
namespace cAudio
{
//! Interface for event handlers for playback manager events.
class IManagerEventHandler
{
public:
//! This function is called on manager initialization
//! This function is called on manager initialization.
virtual void onInit() = 0;
//! This function is called on manager update
//! This function is called on every manager update.
virtual void onUpdate() = 0;
//! This function is called on manager release
//! This function is called on manager shutdown.
virtual void onRelease() = 0;
//! This function is called on source creation
//! This function is called on when an audio source is created.
virtual void onSourceCreate() = 0;
//! This function is called on decoder registration
//! This function is called when an audio decoder is registered.
virtual void onDecoderRegister() = 0;
//! This function is called on data source registration
//! This function is called when a data source is registered.
virtual void onDataSourceRegister() = 0;
};
};
#endif //! IMANAGEREVENTHANDLER_H

33
include/IPluginManager.h
View File

@ -5,26 +5,55 @@
namespace cAudio
{
//! Interface for the plugin capabilities of cAudio.
class IPluginManager
{
public:
IPluginManager() { }
~IPluginManager() { }
//! Installs a plugin using a statically linked plugin implementation.
/**
\param plugin: Pointer to a plugin implementation to install.
\param name: Optional name for the plugin. Pass NULL to have the plugin use its default name.
\return True if plugin was installed successfully. */
virtual bool installPlugin(IAudioPlugin* plugin, const char* name = NULL) = 0;
//! Installs a plugin from a dynamically linked library on your hard drive.
/**
\param filename: Path to the dll/so/dynlib on your hard drive.
\param name: Optional name for the plugin. Pass NULL to have the plugin use its default name.
\return True if plugin was installed successfully. */
virtual bool installPlugin(const char* filename, const char* name = NULL) = 0;
//! Checks for the existance of a plugin with the supplied name.
/**
\param name: Name of the plugin to check for. */
virtual bool checkForPlugin(const char* name) = 0;
//! Returns a plugin interface for a plugin with the supplied name.
/**
\param name: Name of the plugin to check return.
\return A pointer to the plugin interface or NULL if it could not be found. */
virtual IAudioPlugin* getPlugin(const char* name) = 0;
//! Returns the total number of installed plugins.
virtual unsigned int getPluginCount() = 0;
//! Removes a plugin installed via statically linked reference.
/**
\param plugin: Pointer to the plugin implementation to uninstall. */
virtual void uninstallPlugin(IAudioPlugin* plugin) = 0;
//! Removes a plugin with the specified name.
/**
\param name: Name of the plugin to uninstall. */
virtual void uninstallPlugin(const char* name) = 0;
};
//! Gets the interface to the plugin manager
//! Gets the interface to the plugin manager.
/** Note: This is the only way to get access to the plugin capabilities of cAudio.
\return A pointer to the manager
\return A pointer to the manager.
*/
CAUDIO_API IPluginManager* getPluginManager();
};

4
include/IRefCounted.h
View File

@ -7,17 +7,20 @@
namespace cAudio
{
//! Applies reference counting to certain cAudio objects.
class IRefCounted
{
public:
IRefCounted() : RefCount(1) { }
virtual ~IRefCounted() { }
//! Increments the reference count by one.
void grab()
{
++RefCount;
}
//! Decrements the reference count by one. If it hits zero, this object is deleted.
bool drop()
{
--RefCount;
@ -29,6 +32,7 @@ namespace cAudio
return false;
}
//! Returns the current reference count of this object.
int getReferenceCount() const
{
return RefCount;

15
include/ISourceEventHandler.h
View File

@ -7,18 +7,23 @@
namespace cAudio
{
//! Interface for event handlers on Audio Sources.
class ISourceEventHandler
{
public:
//! This function calls on source update
//! This function is called when a source updates its buffers.
virtual void onUpdate() = 0;
//! This function calls on source release
//! This function is called when a source is released and soon to be deleted.
virtual void onRelease() = 0;
//! This function calls on source play
//! This function is called when a source starts playing.
virtual void onPlay() = 0;
//! This function calls on source stop
//! This function is called when a source stopped playback.
virtual void onStop() = 0;
//! This function calls on source pause
//! This function is called when a source is paused.
virtual void onPause() = 0;
};
};