3D Audio GSoC:
authorJoerg Mueller <nexyon@gmail.com>
Tue, 16 Aug 2011 13:00:55 +0000 (13:00 +0000)
committerJoerg Mueller <nexyon@gmail.com>
Tue, 16 Aug 2011 13:00:55 +0000 (13:00 +0000)
Code documentation.

Also:
* Fix: rlint for MSVC.
* Minor other small fixes/changes.

56 files changed:
intern/audaspace/FX/AUD_AccumulatorFactory.h
intern/audaspace/FX/AUD_BaseIIRFilterReader.h
intern/audaspace/FX/AUD_ButterworthFactory.h
intern/audaspace/FX/AUD_DelayReader.h
intern/audaspace/FX/AUD_DoubleFactory.h
intern/audaspace/FX/AUD_DoubleReader.h
intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h
intern/audaspace/FX/AUD_DynamicIIRFilterReader.h
intern/audaspace/FX/AUD_HighpassFactory.h
intern/audaspace/FX/AUD_LimiterReader.h
intern/audaspace/FX/AUD_LowpassFactory.h
intern/audaspace/FX/AUD_PingPongFactory.h
intern/audaspace/FX/AUD_PitchReader.h
intern/audaspace/FX/AUD_ReverseFactory.h
intern/audaspace/FX/AUD_ReverseReader.h
intern/audaspace/FX/AUD_SuperposeFactory.h
intern/audaspace/FX/AUD_SuperposeReader.h
intern/audaspace/FX/AUD_VolumeFactory.h
intern/audaspace/OpenAL/AUD_OpenALDevice.h
intern/audaspace/SRC/AUD_SRCResampleFactory.h
intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp
intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h
intern/audaspace/ffmpeg/AUD_FFMPEGReader.h
intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h
intern/audaspace/intern/AUD_3DMath.h
intern/audaspace/intern/AUD_AnimateableProperty.cpp
intern/audaspace/intern/AUD_AnimateableProperty.h
intern/audaspace/intern/AUD_C-API.h
intern/audaspace/intern/AUD_ChannelMapperFactory.h
intern/audaspace/intern/AUD_ChannelMapperReader.h
intern/audaspace/intern/AUD_ConverterFactory.h
intern/audaspace/intern/AUD_FileWriter.h
intern/audaspace/intern/AUD_I3DHandle.h
intern/audaspace/intern/AUD_IDevice.h
intern/audaspace/intern/AUD_JOSResampleFactory.h
intern/audaspace/intern/AUD_JOSResampleReader.cpp
intern/audaspace/intern/AUD_JOSResampleReader.h
intern/audaspace/intern/AUD_LinearResampleFactory.h
intern/audaspace/intern/AUD_Mixer.h
intern/audaspace/intern/AUD_ReadDevice.h
intern/audaspace/intern/AUD_Reference.h
intern/audaspace/intern/AUD_ResampleReader.h
intern/audaspace/intern/AUD_SequencerEntry.h
intern/audaspace/intern/AUD_SequencerFactory.cpp
intern/audaspace/intern/AUD_SequencerFactory.h
intern/audaspace/intern/AUD_SequencerHandle.h
intern/audaspace/intern/AUD_SequencerReader.h
intern/audaspace/intern/AUD_SilenceFactory.h
intern/audaspace/intern/AUD_SilenceReader.h
intern/audaspace/intern/AUD_SinusReader.h
intern/audaspace/intern/AUD_SoftwareDevice.h
intern/audaspace/intern/AUD_Space.h
intern/audaspace/intern/AUD_StreamBufferFactory.h
intern/audaspace/jack/AUD_JackDevice.h
intern/audaspace/sndfile/AUD_SndFileWriter.h
source/blender/makesrna/intern/rna_scene.c

index 5838ccee7f081f98827302bafdf6ea7ad331916a..95246ef534110ae5009a86fb928cdac26b905615 100644 (file)
@@ -37,6 +37,10 @@ class AUD_CallbackIIRFilterReader;
 
 /**
  * This factory creates an accumulator reader.
+ *
+ * The accumulator adds the difference at the input to the last output in case
+ * it's positive. In additive mode it additionaly adds the difference always.
+ * So in case the difference is positive, it's added twice.
  */
 class AUD_AccumulatorFactory : public AUD_EffectFactory
 {
index 644bcffbfafff80b4463cf5c06c0b99d312f60bd..6bf877d66dadf7f09d930ce07c94959d6a86911f 100644 (file)
@@ -97,11 +97,21 @@ protected:
        void setLengths(int in, int out);
 
 public:
+       /**
+        * Retrieves the last input samples.
+        * \param pos The position, valid are 0 (current) or negative values.
+        * \return The sample value.
+        */
        inline sample_t x(int pos)
        {
                return m_x[(m_xpos + pos + m_xlen) % m_xlen * m_specs.channels + m_channel];
        }
 
+       /**
+        * Retrieves the last output samples.
+        * \param pos The position, valid are negative values.
+        * \return The sample value.
+        */
        inline sample_t y(int pos)
        {
                return m_y[(m_ypos + pos + m_ylen) % m_ylen * m_specs.channels + m_channel];
@@ -111,7 +121,16 @@ public:
 
        virtual void read(int& length, bool& eos, sample_t* buffer);
 
+       /**
+        * Runs the filtering function.
+        * \return The current output sample value.
+        */
        virtual sample_t filter()=0;
+
+       /**
+        * Notifies the filter about a sample rate change.
+        * \param rate The new sample rate.
+        */
        virtual void sampleRateChanged(AUD_SampleRate rate);
 };
 
index 16d0b3dbc23a0b4d0cec3a3d79c3dac24ac3170f..12d28eb40383740eafa3e75c4142b9581f11c137 100644 (file)
@@ -35,7 +35,7 @@
 #include "AUD_DynamicIIRFilterFactory.h"
 
 /**
- * This factory creates a butterworth filter reader.
+ * This factory creates a butterworth lowpass filter reader.
  */
 class AUD_ButterworthFactory : public AUD_DynamicIIRFilterFactory
 {
index a89afe73b372be8e9977a32b3e40c3aa97a1b6f1..128e589eede7171f28c0c1f8a8775dc4aa36fc05 100644 (file)
@@ -36,7 +36,7 @@
 #include "AUD_Buffer.h"
 
 /**
- * This class reads another reader and changes it's delay.
+ * This class reads another reader and delays it.
  */
 class AUD_DelayReader : public AUD_EffectReader
 {
index f2be71324427d8f6b7578876afa846a6aef64d34..2db2257244c7c4aaa70fcb5d416894067c93fe9c 100644 (file)
@@ -36,7 +36,6 @@
 
 /**
  * This factory plays two other factories behind each other.
- * \note Readers from the underlying factories must have the same sample rate and channel count.
  */
 class AUD_DoubleFactory : public AUD_IFactory
 {
index 86f636e2cb28fa18d760e5227c5fd4421cf78d32..750868a94007a7d2c0d3c7fadc8aa9e1046d61a0 100644 (file)
@@ -37,7 +37,7 @@
 #include "AUD_Reference.h"
 
 /**
- * This reader plays two readers with the same specs sequently.
+ * This reader plays two readers sequently.
  */
 class AUD_DoubleReader : public AUD_IReader
 {
@@ -57,21 +57,15 @@ private:
         */
        bool m_finished1;
 
-       /**
-        * The playback buffer for the intersecting part.
-        */
-       AUD_Buffer m_buffer;
-
        // hide copy constructor and operator=
        AUD_DoubleReader(const AUD_DoubleReader&);
        AUD_DoubleReader& operator=(const AUD_DoubleReader&);
 
 public:
        /**
-        * Creates a new ping pong reader.
+        * Creates a new double reader.
         * \param reader1 The first reader to read from.
         * \param reader2 The second reader to read from.
-        * \exception AUD_Exception Thrown if the specs from the readers differ.
         */
        AUD_DoubleReader(AUD_Reference<AUD_IReader> reader1, AUD_Reference<AUD_IReader> reader2);
 
index 19c1a0f0a54e4e201f43ff4170d0eae018895db9..56d56a977d49d1000cd36e3790f422d5e6c49c42 100644 (file)
 #include "AUD_EffectFactory.h"
 #include <vector>
 
+/**
+ * This factory creates a IIR filter reader.
+ *
+ * This means that on sample rate change the filter recalculates its
+ * coefficients.
+ */
 class AUD_DynamicIIRFilterFactory : public AUD_EffectFactory
 {
 public:
+       /**
+        * Creates a new Dynmic IIR filter factory.
+        * \param factory The input factory.
+        */
        AUD_DynamicIIRFilterFactory(AUD_Reference<AUD_IFactory> factory);
 
        virtual AUD_Reference<AUD_IReader> createReader();
 
+       /**
+        * Recalculates the filter coefficients.
+        * \param rate The sample rate of the audio data.
+        * \param[out] b The input filter coefficients.
+        * \param[out] a The output filter coefficients.
+        */
        virtual void recalculateCoefficients(AUD_SampleRate rate,
                                                                                 std::vector<float>& b,
                                                                                 std::vector<float>& a)=0;
index 92f491f04d47feceabffc96df452cafa8d7dd17e..427897267280f7550e90b1e90a1f6431c879d01d 100644 (file)
 #include "AUD_IIRFilterReader.h"
 #include "AUD_DynamicIIRFilterFactory.h"
 
+/**
+ * This class is for dynamic infinite impulse response filters with simple
+ * coefficients that change depending on the sample rate.
+ */
 class AUD_DynamicIIRFilterReader : public AUD_IIRFilterReader
 {
 private:
index 51d5f55cb36b775a69d2034e6e426ff1f0018861..c135be27d770f0ac3753aec243e79a872d6c76d9 100644 (file)
@@ -41,7 +41,7 @@ class AUD_HighpassFactory : public AUD_DynamicIIRFilterFactory
 {
 private:
        /**
-        * The attack value in seconds.
+        * The cutoff frequency.
         */
        const float m_frequency;
 
index d9bee6f6463b49df620e667d1fa4d6056ac007d2..9cddd4d57ec1476ea0c55da63e4eac05e240c5a1 100644 (file)
@@ -35,7 +35,7 @@
 #include "AUD_EffectReader.h"
 
 /**
- * This reader limits another reader in start and end sample.
+ * This reader limits another reader in start and end times.
  */
 class AUD_LimiterReader : public AUD_EffectReader
 {
@@ -58,9 +58,9 @@ public:
        /**
         * Creates a new limiter reader.
         * \param reader The reader to read from.
-        * \param start The desired start sample (inclusive).
-        * \param end The desired end sample (exklusive), a negative value signals
-        *            that it should play to the end.
+        * \param start The desired start time (inclusive).
+        * \param end The desired end time (sample exklusive), a negative value
+        *            signals that it should play to the end.
         */
        AUD_LimiterReader(AUD_Reference<AUD_IReader> reader, float start = 0, float end = -1);
 
index 6558663df4e874db8c796e867aeb15ddc1bb89ec..644d25ec73d12fc9e3cc91ec4eba275acb8eb3de 100644 (file)
@@ -41,7 +41,7 @@ class AUD_LowpassFactory : public AUD_DynamicIIRFilterFactory
 {
 private:
        /**
-        * The attack value in seconds.
+        * The cutoff frequency.
         */
        const float m_frequency;
 
index 908591a6ebec6dc8c95568c93e406b6778933205..b023501d45bde9810627fe3eb76efe107ccb1816 100644 (file)
@@ -36,7 +36,7 @@
 
 /**
  * This factory plays another factory first normal, then reversed.
- * \note Readers from the underlying factory must be from the buffer type.
+ * \note Readers from the underlying factory must be reversable with seeking.
  */
 class AUD_PingPongFactory : public AUD_EffectFactory
 {
index 7418531ca55a3f4c9326385bfb19bcdad674573d..ed6adbf02fb447f2fc6da8914638830a65475724 100644 (file)
@@ -53,13 +53,22 @@ public:
        /**
         * Creates a new pitch reader.
         * \param reader The reader to read from.
-        * \param pitch The size of the buffer.
+        * \param pitch The pitch value.
         */
        AUD_PitchReader(AUD_Reference<AUD_IReader> reader, float pitch);
 
        virtual AUD_Specs getSpecs() const;
 
+       /**
+        * Retrieves the pitch.
+        * \return The current pitch value.
+        */
        float getPitch() const;
+
+       /**
+        * Sets the pitch.
+        * \param pitch The new pitch value.
+        */
        void setPitch(float pitch);
 };
 
index b501b4e76c86b8c346e6791ecdee379bb1bf88aa..f43d37d8f465d6d2a6081c6dcf43fb6049d5d20f 100644 (file)
@@ -36,7 +36,7 @@
 
 /**
  * This factory reads another factory reverted.
- * \note Readers from the underlying factory must be from the buffer type.
+ * \note Readers from the underlying factory must be seekable.
  */
 class AUD_ReverseFactory : public AUD_EffectFactory
 {
index da0add9464e49b89c06dc4eb988e761115ebb16f..197d10dfe001fecebf10f1d62f3747e6bca38f43 100644 (file)
@@ -37,7 +37,7 @@
 
 /**
  * This class reads another reader from back to front.
- * \note The underlying reader must be a buffer.
+ * \note The underlying reader must be seekable.
  */
 class AUD_ReverseReader : public AUD_EffectReader
 {
index ac7ec0801343fc1948637bf0c4b6d47210080299..b12da62b49780c94b3cb9e1e529970479d61d921 100644 (file)
@@ -35,8 +35,9 @@
 #include "AUD_IFactory.h"
 
 /**
- * This factory plays two other factories behind each other.
- * \note Readers from the underlying factories must have the same sample rate and channel count.
+ * This factory mixes two other factories, playing them the same time.
+ * \note Readers from the underlying factories must have the same sample rate
+ *       and channel count.
  */
 class AUD_SuperposeFactory : public AUD_IFactory
 {
index a87f1fdb739e42b3c4c429491487302b2774faa6..07b4b105835854c312b3aebfe9f188a983842544 100644 (file)
@@ -37,7 +37,7 @@
 #include "AUD_Reference.h"
 
 /**
- * This reader plays two readers with the same specs sequently.
+ * This reader plays two readers with the same specs in parallel.
  */
 class AUD_SuperposeReader : public AUD_IReader
 {
@@ -53,7 +53,7 @@ private:
        AUD_Reference<AUD_IReader> m_reader2;
 
        /**
-        * The playback buffer for the intersecting part.
+        * Buffer used for mixing.
         */
        AUD_Buffer m_buffer;
 
index bcc08e7d04ad1f1b29f695fd53acdde85885e88b..0ca0102b7900bc019a38bf7fb5eb556923a9a270 100644 (file)
@@ -61,6 +61,7 @@ public:
 
        /**
         * Returns the volume.
+        * \return The current volume.
         */
        float getVolume() const;
 
index 3e8b05d79e252a26b6e7c17b748c3c238f7a7c97..a04b483132a17a480427d03bc1014c5b20edb543 100644 (file)
@@ -100,6 +100,13 @@ private:
 
        public:
 
+               /**
+                * Creates a new OpenAL handle.
+                * \param device The OpenAL device the handle belongs to.
+                * \param format The AL format.
+                * \param reader The reader this handle plays.
+                * \param keep Whether to keep the handle alive when the reader ends.
+                */
                AUD_OpenALHandle(AUD_OpenALDevice* device, ALenum format, AUD_Reference<AUD_IReader> reader, bool keep);
 
                virtual ~AUD_OpenALHandle() {}
@@ -214,6 +221,7 @@ private:
 
        /**
         * Starts the streaming thread.
+        * \param Whether the previous thread should be joined.
         */
        void start(bool join = true);
 
index 2f5fe30ac471283823dab75cd7af2ad21f80d800..685dbc0b176811f1dcdb77f1e81746c7335d579f 100644 (file)
@@ -46,6 +46,11 @@ private:
        AUD_SRCResampleFactory& operator=(const AUD_SRCResampleFactory&);
 
 public:
+       /**
+        * Creates a new factory.
+        * \param factory The input factory.
+        * \param specs The target specifications.
+        */
        AUD_SRCResampleFactory(AUD_Reference<AUD_IFactory> factory, AUD_DeviceSpecs specs);
 
        virtual AUD_Reference<AUD_IReader> createReader();
index 909f41302d7081caf2aef39dbd27cdc64c58dad1..e9d045bd3032bfb1a1e02670e3c510a840f37d30 100644 (file)
@@ -36,7 +36,6 @@
 
 #include "AUD_FFMPEGFactory.h"
 #include "AUD_FFMPEGReader.h"
-#include "AUD_Buffer.h"
 
 AUD_FFMPEGFactory::AUD_FFMPEGFactory(std::string filename) :
                m_filename(filename)
index af95e3a3b813d2aca31160345bae845805fd5fdc..18510d8db8b17e4ab28097d0d7636dbd27c4df7f 100644 (file)
@@ -34,7 +34,7 @@
 
 #include "AUD_IFactory.h"
 #include "AUD_Reference.h"
-class AUD_Buffer;
+#include "AUD_Buffer.h"
 
 #include <string>
 
index 222a3d8581aa0f537470850b96f75a9f21457c1e..a83477b50d682a61c7f283bb8488ddcb9f4d1f99 100644 (file)
@@ -49,8 +49,6 @@ extern "C" {
  * \warning Seeking may not be accurate! Moreover the position is updated after
  *          a buffer reading call. So calling getPosition right after seek
  *          normally results in a wrong value.
- * \warning Playback of an ogg with some outdated ffmpeg versions results in a
- *          segfault on windows.
  */
 class AUD_FFMPEGReader : public AUD_IReader
 {
index 618ec9402ce3bd0769ade69373f95f3d4729c258..92460eed7ca13db544e097cb0445a618fee37307 100644 (file)
@@ -69,16 +69,34 @@ private:
         */
        AVCodecContext* m_codecCtx;
 
+       /**
+        * The AVOutputFormat structure for using ffmpeg.
+        */
        AVOutputFormat* m_outputFmt;
 
+       /**
+        * The AVStream structure for using ffmpeg.
+        */
        AVStream* m_stream;
 
+       /**
+        * The input buffer for the format converted data before encoding.
+        */
        AUD_Buffer m_input_buffer;
 
+       /**
+        * The output buffer for the encoded audio data.
+        */
        AUD_Buffer m_output_buffer;
 
+       /**
+        * The count of input samples we have so far.
+        */
        unsigned int m_input_samples;
 
+       /**
+        * The count of input samples necessary to encode a packet.
+        */
        unsigned int m_input_size;
 
        /**
@@ -90,12 +108,20 @@ private:
        AUD_FFMPEGWriter(const AUD_FFMPEGWriter&);
        AUD_FFMPEGWriter& operator=(const AUD_FFMPEGWriter&);
 
+       /**
+        * Encodes to the output buffer.
+        * \param data Pointer to the data to encode.
+        */
        void encode(sample_t* data);
 
 public:
        /**
         * Creates a new writer.
         * \param filename The path to the file to be read.
+        * \param specs The file's audio specification.
+        * \param format The file's container format.
+        * \param codec The codec used for encoding the audio data.
+        * \param bitrate The bitrate for encoding.
         * \exception AUD_Exception Thrown if the file specified does not exist or
         *            cannot be read with ffmpeg.
         */
index 007682df2914dbe60d07100a907108e00e8f13dd..eb16dcf2d502bcd75842ab74cd190570281fbce8 100644 (file)
 #define AUD_3DMATH
 
 #include <cmath>
+#include <cstring>
 
+/**
+ * This class represents a 3 dimensional vector.
+ */
 class AUD_Vector3
 {
 private:
+       /**
+        * The vector components.
+        */
        union
        {
                float m_v[3];
@@ -93,9 +100,7 @@ public:
         */
        inline void get(float* destination) const
        {
-               destination[0] = m_x;
-               destination[1] = m_y;
-               destination[2] = m_z;
+               memcpy(destination, m_v, sizeof(m_v));
        }
 
        /**
@@ -125,6 +130,11 @@ public:
                return sqrt(m_x*m_x + m_y*m_y + m_z*m_z);
        }
 
+       /**
+        * Retrieves the cross product.
+        * \param op The second operand.
+        * \return The cross product of the two vectors.
+        */
        inline AUD_Vector3 cross(const AUD_Vector3& op) const
        {
                return AUD_Vector3(m_y * op.m_z - m_z * op.m_y,
@@ -142,26 +152,50 @@ public:
                return m_x * op.m_x + m_y * op.m_y + m_z * op.m_z;
        }
 
+       /**
+        * Retrieves the product with a scalar.
+        * \param op The second operand.
+        * \return The scaled vector.
+        */
        inline AUD_Vector3 operator*(const float& op) const
        {
                return AUD_Vector3(m_x * op, m_y * op, m_z * op);
        }
 
+       /**
+        * Adds two vectors.
+        * \param op The second operand.
+        * \return The sum vector.
+        */
        inline AUD_Vector3 operator+(const AUD_Vector3& op) const
        {
                return AUD_Vector3(m_x + op.m_x, m_y + op.m_y, m_z + op.m_z);
        }
 
+       /**
+        * Subtracts two vectors.
+        * \param op The second operand.
+        * \return The difference vector.
+        */
        inline AUD_Vector3 operator-(const AUD_Vector3& op) const
        {
                return AUD_Vector3(m_x - op.m_x, m_y - op.m_y, m_z - op.m_z);
        }
 
+       /**
+        * Negates the vector.
+        * \return The vector facing in the opposite direction.
+        */
        inline AUD_Vector3 operator-() const
        {
                return AUD_Vector3(-m_x, -m_y, -m_z);
        }
 
+       /**
+        * Subtracts the second vector.
+        * \param op The second operand.
+        * \return The difference vector.
+        */
        inline AUD_Vector3& operator-=(const AUD_Vector3& op)
        {
                m_x -= op.m_x;
@@ -171,9 +205,15 @@ public:
        }
 };
 
+/**
+ * This class represents a quaternion used for 3D rotations.
+ */
 class AUD_Quaternion
 {
 private:
+       /**
+        * The quaternion components.
+        */
        union
        {
                float m_v[4];
@@ -241,10 +281,7 @@ public:
         */
        inline void get(float* destination) const
        {
-               destination[0] = m_w;
-               destination[1] = m_x;
-               destination[2] = m_y;
-               destination[3] = m_z;
+               memcpy(destination, m_v, sizeof(m_v));
        }
 
        /**
@@ -265,6 +302,11 @@ public:
                return m_v;
        }
 
+       /**
+        * When the quaternion represents an orientation, this returns the negative
+        * z axis vector.
+        * \return The negative z axis vector.
+        */
        inline AUD_Vector3 getLookAt() const
        {
                return AUD_Vector3(-2 * (m_w * m_y + m_x * m_z),
@@ -272,6 +314,11 @@ public:
                                                        2 * (m_x * m_x + m_y * m_y) - 1);
        }
 
+       /**
+        * When the quaternion represents an orientation, this returns the y axis
+        * vector.
+        * \return The y axis vector.
+        */
        inline AUD_Vector3 getUp() const
        {
                return AUD_Vector3(2 * (m_x * m_y - m_w * m_z),
index adc71928efd2918d877417d2b17497803ae6eca5..98d5b4cb6e1a5a4a1c3e810804ec4527bb40b1b5 100644 (file)
@@ -35,7 +35,7 @@
 #include <cmath>
 
 AUD_AnimateableProperty::AUD_AnimateableProperty(int count) :
-       AUD_Buffer(count * sizeof(float)), m_count(count), m_isAnimated(false), m_changed(false)
+       AUD_Buffer(count * sizeof(float)), m_count(count), m_isAnimated(false)
 {
        memset(getBuffer(), 0, count * sizeof(float));
 
@@ -68,7 +68,6 @@ void AUD_AnimateableProperty::write(const float* data)
        lock();
 
        m_isAnimated = false;
-       m_changed = true;
        memcpy(getBuffer(), data, m_count * sizeof(float));
 
        unlock();
@@ -158,13 +157,3 @@ bool AUD_AnimateableProperty::isAnimated() const
 {
        return m_isAnimated;
 }
-
-bool AUD_AnimateableProperty::hasChanged()
-{
-       if(m_isAnimated)
-               return true;
-
-       bool result = m_changed;
-       m_changed = false;
-       return result;
-}
index d3b2e29c036573aa22a06266e9b76cef20911186..dd6b585741ec90bd4b34a285301d9a6a6f4888ad 100644 (file)
@@ -51,9 +51,6 @@ private:
        /// The mutex for locking.
        pthread_mutex_t m_mutex;
 
-       /// Whether the property has been changed.
-       bool m_changed;
-
        // hide copy constructor and operator=
        AUD_AnimateableProperty(const AUD_AnimateableProperty&);
        AUD_AnimateableProperty& operator=(const AUD_AnimateableProperty&);
@@ -80,15 +77,32 @@ public:
         */
        void unlock();
 
+       /**
+        * Writes the properties value and marks it non-animated.
+        * \param data The new value.
+        */
        void write(const float* data);
 
+       /**
+        * Writes the properties value and marks it animated.
+        * \param data The new value.
+        * \param position The position in the animation in frames.
+        * \param count The count of frames to write.
+        */
        void write(const float* data, int position, int count);
 
+       /**
+        * Reads the properties value.
+        * \param position The position in the animation in frames.
+        * \param[out] out Where to write the value to.
+        */
        void read(float position, float* out);
 
+       /**
+        * Returns whether the property is animated.
+        * \return Whether the property is animated.
+        */
        bool isAnimated() const;
-
-       bool hasChanged();
 };
 
 #endif //AUD_ANIMATEABLEPROPERTY
index 1a952b4f4a95c38e87806a06d18e0225f0228ece..612f98a79c3c8f2b054ebc7bd47c06967e4a15c2 100644 (file)
@@ -41,6 +41,7 @@ extern "C" {
 
 #include "AUD_Space.h"
 
+/// Supported output devices.
 typedef enum
 {
        AUD_NULL_DEVICE = 0,
@@ -49,6 +50,7 @@ typedef enum
        AUD_JACK_DEVICE
 } AUD_DeviceType;
 
+/// Sound information structure.
 typedef struct
 {
        AUD_Specs specs;
@@ -459,79 +461,279 @@ extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
  */
 extern AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
 
+/**
+ * Creates a new sequenced sound scene.
+ * \param fps The FPS of the scene.
+ * \param muted Whether the scene is muted.
+ * \return The new sound scene.
+ */
 extern AUD_Sound* AUD_createSequencer(float fps, int muted);
 
+/**
+ * Deletes a sound scene.
+ * \param sequencer The sound scene.
+ */
 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 
+/**
+ * Sets the muting state of the scene.
+ * \param sequencer The sound scene.
+ * \param muted Whether the scene is muted.
+ */
 extern void AUD_setSequencerMuted(AUD_Sound* sequencer, int muted);
 
+/**
+ * Sets the scene's FPS.
+ * \param sequencer The sound scene.
+ * \param fps The new FPS.
+ */
 extern void AUD_setSequencerFPS(AUD_Sound* sequencer, float fps);
 
+/**
+ * Adds a new entry to the scene.
+ * \param sequencer The sound scene.
+ * \param sound The sound this entry should play.
+ * \param begin The start time.
+ * \param end The end time or a negative value if determined by the sound.
+ * \param skip How much seconds should be skipped at the beginning.
+ * \return The entry added.
+ */
 extern AUD_SEntry* AUD_addSequence(AUD_Sound* sequencer, AUD_Sound* sound,
                                                                   float begin, float end, float skip);
 
+/**
+ * Removes an entry from the scene.
+ * \param sequencer The sound scene.
+ * \param entry The entry to remove.
+ */
 extern void AUD_removeSequence(AUD_Sound* sequencer, AUD_SEntry* entry);
 
+/**
+ * Moves the entry.
+ * \param entry The sequenced entry.
+ * \param begin The new start time.
+ * \param end The new end time or a negative value if unknown.
+ * \param skip How many seconds to skip at the beginning.
+ */
 extern void AUD_moveSequence(AUD_SEntry* entry, float begin, float end, float skip);
 
+/**
+ * Sets the muting state of the entry.
+ * \param entry The sequenced entry.
+ * \param mute Whether the entry should be muted or not.
+ */
 extern void AUD_muteSequence(AUD_SEntry* entry, char mute);
 
+/**
+ * Sets whether the entrie's location, velocity and orientation are relative
+ * to the listener.
+ * \param entry The sequenced entry.
+ * \param relative Whether the source is relative.
+ * \return Whether the action succeeded.
+ */
 extern void AUD_setRelativeSequence(AUD_SEntry* entry, char relative);
 
+/**
+ * Sets the sound of the entry.
+ * \param entry The sequenced entry.
+ * \param sound The new sound.
+ */
 extern void AUD_updateSequenceSound(AUD_SEntry* entry, AUD_Sound* sound);
 
+/**
+ * Writes animation data to a sequenced entry.
+ * \param entry The sequenced entry.
+ * \param type The type of animation data.
+ * \param frame The frame this data is for.
+ * \param data The data to write.
+ * \param animated Whether the attribute is animated.
+ */
 extern void AUD_setSequenceAnimData(AUD_SEntry* entry, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
 
+/**
+ * Writes animation data to a sequenced entry.
+ * \param sequencer The sound scene.
+ * \param type The type of animation data.
+ * \param frame The frame this data is for.
+ * \param data The data to write.
+ * \param animated Whether the attribute is animated.
+ */
 extern void AUD_setSequencerAnimData(AUD_Sound* sequencer, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
 
+/**
+ * Updates all non-animated parameters of the entry.
+ * \param entry The sequenced entry.
+ * \param volume_max The maximum volume.
+ * \param volume_min The minimum volume.
+ * \param distance_max The maximum distance.
+ * \param distance_reference The reference distance.
+ * \param attenuation The attenuation.
+ * \param cone_angle_outer The outer cone opening angle.
+ * \param cone_angle_inner The inner cone opening angle.
+ * \param cone_volume_outer The volume outside the outer cone.
+ */
 extern void AUD_updateSequenceData(AUD_SEntry* entry, float volume_max, float volume_min,
                                                                   float distance_max, float distance_reference, float attenuation,
                                                                   float cone_angle_outer, float cone_angle_inner, float cone_volume_outer);
 
+/**
+ * Updates all non-animated parameters of the entry.
+ * \param sequencer The sound scene.
+ * \param speed_of_sound The speed of sound for doppler calculation.
+ * \param factor The doppler factor to control the effect's strength.
+ * \param model The distance model for distance calculation.
+ */
 extern void AUD_updateSequencerData(AUD_Sound* sequencer, float speed_of_sound,
                                                                        float factor, AUD_DistanceModel model);
 
+/**
+ * Sets the audio output specification of the sound scene to the specs of the
+ * current playback device.
+ * \param sequencer The sound scene.
+ */
 extern void AUD_setSequencerDeviceSpecs(AUD_Sound* sequencer);
 
+/**
+ * Sets the audio output specification of the sound scene.
+ * \param sequencer The sound scene.
+ * \param specs The new specification.
+ */
 extern void AUD_setSequencerSpecs(AUD_Sound* sequencer, AUD_Specs specs);
 
+/**
+ * Seeks sequenced sound scene playback.
+ * \param handle Playback handle.
+ * \param time Time in seconds to seek to.
+ */
 extern void AUD_seekSequencer(AUD_Handle* handle, float time);
 
+/**
+ * Returns the current sound scene playback time.
+ * \param handle Playback handle.
+ * \return The playback time in seconds.
+ */
 extern float AUD_getSequencerPosition(AUD_Handle* handle);
 
+/**
+ * Starts the playback of jack transport if possible.
+ */
 extern void AUD_startPlayback(void);
 
+/**
+ * Stops the playback of jack transport if possible.
+ */
 extern void AUD_stopPlayback(void);
 
 #ifdef WITH_JACK
+/**
+ * Sets the sync callback for jack transport.
+ * \param function The callback function.
+ * \param data The data parameter for the callback.
+ */
 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 #endif
 
+/**
+ * Returns whether jack transport is currently playing.
+ * \return Whether jack transport is currently playing.
+ */
 extern int AUD_doesPlayback(void);
 
+/**
+ * Reads a sound into a buffer for drawing at a specific sampling rate.
+ * \param sound The sound to read.
+ * \param buffer The buffer to write to. Must have a size of 3*4*length.
+ * \param length How many samples to read from the sound.
+ * \param samples_per_second How many samples to read per second of the sound.
+ * \return How many samples really have been read. Always <= length.
+ */
 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length, int samples_per_second);
 
+/**
+ * Copies a sound.
+ * \param sound Sound to copy.
+ * \return Copied sound.
+ */
 extern AUD_Sound* AUD_copy(AUD_Sound* sound);
 
+/**
+ * Frees a handle.
+ * \param channel Handle to free.
+ */
 extern void AUD_freeHandle(AUD_Handle* channel);
 
+/**
+ * Creates a new set.
+ * \return The new set.
+ */
 extern void* AUD_createSet(void);
 
+/**
+ * Deletes a set.
+ * \param set The set to delete.
+ */
 extern void AUD_destroySet(void* set);
 
+/**
+ * Removes an entry from a set.
+ * \param set The set work on.
+ * \param entry The entry to remove.
+ * \return Whether the entry was in the set or not.
+ */
 extern char AUD_removeSet(void* set, void* entry);
 
+/**
+ * Adds a new entry to a set.
+ * \param set The set work on.
+ * \param entry The entry to add.
+ */
 extern void AUD_addSet(void* set, void* entry);
 
+/**
+ * Removes one entry from a set and returns it.
+ * \param set The set work on.
+ * \return The entry or NULL if the set is empty.
+ */
 extern void* AUD_getSet(void* set);
 
+/**
+ * Mixes a sound down into a file.
+ * \param sound The sound scene to mix down.
+ * \param start The start frame.
+ * \param length The count of frames to write.
+ * \param buffersize How many samples should be written at once.
+ * \param filename The file to write to.
+ * \param specs The file's audio specification.
+ * \param format The file's container format.
+ * \param codec The codec used for encoding the audio data.
+ * \param bitrate The bitrate for encoding.
+ * \return An error message or NULL in case of success.
+ */
 extern const char* AUD_mixdown(AUD_Sound* sound, unsigned int start, unsigned int length, unsigned int buffersize, const char* filename, AUD_DeviceSpecs specs, AUD_Container format, AUD_Codec codec, unsigned int bitrate);
 
+/**
+ * Opens a read device and prepares it for mixdown of the sound scene.
+ * \param specs Output audio specifications.
+ * \param sequencer The sound scene to mix down.
+ * \param volume The overall mixdown volume.
+ * \param start The start time of the mixdown in the sound scene.
+ * \return The read device for the mixdown.
+ */
 extern AUD_Device* AUD_openMixdownDevice(AUD_DeviceSpecs specs, AUD_Sound* sequencer, float volume, float start);
 
 #ifdef WITH_PYTHON
+/**
+ * Retrieves the python factory of a sound.
+ * \param sound The sound factory.
+ * \return The python factory.
+ */
 extern PyObject* AUD_getPythonFactory(AUD_Sound* sound);
 
+/**
+ * Retrieves the sound factory of a python factory.
+ * \param sound The python factory.
+ * \return The sound factory.
+ */
 extern AUD_Sound* AUD_getPythonSound(PyObject* sound);
 #endif
 
@@ -542,8 +744,16 @@ extern AUD_Sound* AUD_getPythonSound(PyObject* sound);
 class AUD_IDevice;
 class AUD_I3DDevice;
 
+/**
+ * Returns the current playback device.
+ * \return The playback device.
+ */
 AUD_Reference<AUD_IDevice> AUD_getDevice();
 
+/**
+ * Returns the current playback 3D device.
+ * \return The playback 3D device.
+ */
 AUD_I3DDevice* AUD_get3DDevice();
 #endif
 
index ce43c6462de29ed8e9d1cb3c3458a80646603a80..9e1adf09ca9ae35cf585d732e50daf063ce8298d 100644 (file)
@@ -46,6 +46,11 @@ private:
        AUD_ChannelMapperFactory& operator=(const AUD_ChannelMapperFactory&);
 
 public:
+       /**
+        * Creates a new factory.
+        * \param factory The input factory.
+        * \param specs The target specifications.
+        */
        AUD_ChannelMapperFactory(AUD_Reference<AUD_IFactory> factory, AUD_DeviceSpecs specs);
 
        virtual AUD_Reference<AUD_IReader> createReader();
index fa035531763a12eb988bf891f66db10761dba42e..af16f2ff49d1740e5dcce0ad3b09c882de69cbd3 100644 (file)
@@ -119,8 +119,16 @@ public:
         */
        ~AUD_ChannelMapperReader();
 
+       /**
+        * Sets the requested channel output count.
+        * \param channels The channel output count.
+        */
        void setChannels(AUD_Channels channels);
 
+       /**
+        * Sets the angle for mono sources.
+        * \param angle The angle for mono sources.
+        */
        void setMonoAngle(float angle);
 
        virtual AUD_Specs getSpecs() const;
index 8f0221addb79197f3d5d961b0c9aac9d0da9844a..128653c5c54118df6e9f96b58b4713946582c834 100644 (file)
@@ -46,6 +46,11 @@ private:
        AUD_ConverterFactory& operator=(const AUD_ConverterFactory&);
 
 public:
+       /**
+        * Creates a new factory.
+        * \param factory The input factory.
+        * \param specs The target specifications.
+        */
        AUD_ConverterFactory(AUD_Reference<AUD_IFactory> factory, AUD_DeviceSpecs specs);
 
        virtual AUD_Reference<AUD_IReader> createReader();
index 60aec1b5927fab9c389346705201a5b58e98df59..341728ff836f04e0c07a89023212cf1473f793a8 100644 (file)
@@ -40,7 +40,7 @@
 #include "AUD_IReader.h"
 
 /**
- * This factory tries to read a sound file via all available file readers.
+ * This class is able to create IWriter classes as well as write reads to them.
  */
 class AUD_FileWriter
 {
@@ -51,7 +51,24 @@ private:
        AUD_FileWriter& operator=(const AUD_FileWriter&);
 
 public:
+       /**
+        * Creates a new IWriter.
+        * \param filename The file to write to.
+        * \param specs The file's audio specification.
+        * \param format The file's container format.
+        * \param codec The codec used for encoding the audio data.
+        * \param bitrate The bitrate for encoding.
+        * \return The writer to write data to.
+        */
        static AUD_Reference<AUD_IWriter> createWriter(std::string filename, AUD_DeviceSpecs specs, AUD_Container format, AUD_Codec codec, unsigned int bitrate);
+
+       /**
+        * Writes a reader to a writer.
+        * \param reader The reader to read from.
+        * \param writer The writer to write to.
+        * \param length How many samples should be transfered.
+        * \param buffersize How many samples should be transfered at once.
+        */
        static void writeReader(AUD_Reference<AUD_IReader> reader, AUD_Reference<AUD_IWriter> writer, unsigned int length, unsigned int buffersize);
 };
 
index afb8cb29c536b0ee5cc3dc35af9496889b295169..8ef08b18f948208e3ee551ed4ff9c41f560cf258 100644 (file)
@@ -36,7 +36,7 @@
 #include "AUD_3DMath.h"
 
 /**
- * This class represents an output device for 3D sound.
+ * This class represents a playback handle for 3D sources.
  */
 class AUD_I3DHandle
 {
index 86d695ef76448b1ddf3fe97cba238430c789e391..108e7505d841d271a200ee6c37263081aa0472bd 100644 (file)
@@ -34,9 +34,9 @@
 
 #include "AUD_Space.h"
 #include "AUD_Reference.h"
-class AUD_IFactory;
-class AUD_IReader;
-class AUD_IHandle;
+#include "AUD_IFactory.h"
+#include "AUD_IReader.h"
+#include "AUD_IHandle.h"
 
 /**
  * This class represents an output device for sound sources.
index 0ecd3c12dbe38b6c938442807bf1ef8e42348984..90a5df5baf0141d83fce2a02893c76eb9a3638ee 100644 (file)
@@ -45,6 +45,11 @@ private:
        AUD_JOSResampleFactory& operator=(const AUD_JOSResampleFactory&);
 
 public:
+       /**
+        * Creates a new factory.
+        * \param factory The input factory.
+        * \param specs The target specifications.
+        */
        AUD_JOSResampleFactory(AUD_Reference<AUD_IFactory> factory, AUD_DeviceSpecs specs);
 
        virtual AUD_Reference<AUD_IReader> createReader();
index fd811d617c613494cfc35782a14c20b1e4b56a5a..4af892da676fd52c89ac65e1469f970a0a611c84 100644 (file)
 #include <cstring>
 #include <iostream>
 
+/* MSVC does not have lrint */
+#ifdef _MSC_VER
+#ifdef _M_X64
+#include <emmintrin.h>
+static inline int lrint(double d)
+{
+               return _mm_cvtsd_si32(_mm_load_sd(&d));
+}
+#else
+static inline int lrint(double d)
+{
+       int i;
+
+       _asm{
+               fld d
+               fistp i
+       };
+
+       return i;
+}
+#endif
+#endif
+
 #define CC m_channels + channel
 
 #define AUD_RATE_MAX 256
index 1eef290c37f53ef06987c4b7079be9b37e307b46..295fc9373170189731bc2f29ff684262e41eb49a 100644 (file)
@@ -43,8 +43,19 @@ class AUD_JOSResampleReader : public AUD_ResampleReader
 private:
        typedef void (AUD_JOSResampleReader::*AUD_resample_f)(double target_factor, int length, sample_t* buffer);
 
+       /**
+        * The half filter length.
+        */
        static const int m_len = 292874;
+
+       /**
+        * The sample step size for the filter.
+        */
        static const int m_L = 2048;
+
+       /**
+        * The filter coefficients.
+        */
        static const float m_coeff[];
 
        /**
@@ -91,8 +102,17 @@ private:
        AUD_JOSResampleReader(const AUD_JOSResampleReader&);
        AUD_JOSResampleReader& operator=(const AUD_JOSResampleReader&);
 
+       /**
+        * Resets the resampler to its initial state.
+        */
        void reset();
 
+       /**
+        * Updates the buffer to be as small as possible for the coming reading.
+        * \param size The size of samples to be read.
+        * \param factor The next resampling factor.
+        * \param samplesize The size of a sample.
+        */
        void updateBuffer(int size, double factor, int samplesize);
 
        void resample(double target_factor, int length, sample_t* buffer);
index de015610a73e41dc5d32e61bd727b53cad9dbc02..6fb101aa70800f988748eaf0214cd65a2d51dd67 100644 (file)
@@ -45,6 +45,11 @@ private:
        AUD_LinearResampleFactory& operator=(const AUD_LinearResampleFactory&);
 
 public:
+       /**
+        * Creates a new factory.
+        * \param factory The input factory.
+        * \param specs The target specifications.
+        */
        AUD_LinearResampleFactory(AUD_Reference<AUD_IFactory> factory, AUD_DeviceSpecs specs);
 
        virtual AUD_Reference<AUD_IReader> createReader();
index 5ca801b16900e4af433d9c6da07d688528d23e5b..cdcf0d23b6d367d5934f20a43e5888456f8df4c6 100644 (file)
@@ -38,7 +38,7 @@
 class AUD_IReader;
 
 /**
- * This abstract class is able to mix audiosignals of different channel count
+ * This abstract class is able to mix audiosignals with same channel count
  * and sample rate and convert it to a specific output format.
  */
 class AUD_Mixer
index 3ec48e6ebca8958dd6ecb59669416d2b752d2d7e..2d0e37c44c12c97012fd7075a1ca82610a9a3eea 100644 (file)
@@ -80,6 +80,10 @@ public:
         */
        bool read(data_t* buffer, int length);
 
+       /**
+        * Changes the output specification.
+        * \param specs The new audio data specification.
+        */
        void changeSpecs(AUD_Specs specs);
 };
 
index 25cc7bcda58a05e0127a284b3b872d3969f065d6..3977b22a1dd5ad0d3b18e56ba274b8caa57decc4 100644 (file)
 #include <typeinfo>
 #endif
 
+/**
+ * This class handles the reference counting.
+ */
 class AUD_ReferenceHandler
 {
 private:
+       /**
+        * Saves the reference counts.
+        */
        static std::map<void*, int> m_references;
 
 public:
+       /**
+        * Reference increment.
+        * \param reference The reference.
+        */
        static inline void incref(void* reference)
        {
                if(!reference)
@@ -62,6 +72,11 @@ public:
                }
        }
 
+       /**
+        * Reference decrement.
+        * \param reference The reference.
+        * \return Whether the reference has to be deleted.
+        */
        static inline bool decref(void* reference)
        {
                if(!reference)
@@ -193,6 +208,9 @@ public:
                return m_reference;
        }
 
+       /**
+        * Returns the original pointer.
+        */
        inline void* getOriginal() const
        {
                return m_original;
index 4c1a1ece9d92ed9249ed2ab2b4fe32c1806f0d28..0792753f4b3cb00b056e0e2936ce62e8468395d0 100644 (file)
@@ -33,6 +33,9 @@
 
 #include "AUD_EffectReader.h"
 
+/**
+ * This is the base class for all resampling readers.
+ */
 class AUD_ResampleReader : public AUD_EffectReader
 {
 protected:
@@ -41,11 +44,25 @@ protected:
         */
        AUD_SampleRate m_rate;
 
+       /**
+        * Creates a resampling reader.
+        * \param reader The reader to mix.
+        * \param rate The target sampling rate.
+        */
        AUD_ResampleReader(AUD_Reference<AUD_IReader> reader, AUD_SampleRate rate);
 
 public:
+       /**
+        * Sets the sample rate.
+        * \param rate The target sampling rate.
+        */
        virtual void setRate(AUD_SampleRate rate);
-       AUD_SampleRate getRate();
+
+       /**
+        * Retrieves the sample rate.
+        * \return The target sampling rate.
+        */
+       virtual AUD_SampleRate getRate();
 };
 
 #endif // AUD_RESAMPLEREADER
index 71e3f8b8908420f6a412366475517fc81dd775ad..53e3513b1b5a5d31583096b1c60681f79d46c9ea 100644 (file)
 
 #include <pthread.h>
 
+/**
+ * This class represents a sequenced entry in a sequencer factory.
+ */
 class AUD_SequencerEntry
 {
        friend class AUD_SequencerHandle;
 private:
+       /// The status of the entry. Changes every time a non-animated parameter changes.
        int m_status;
+
+       /// The positional status of the entry. Changes every time the entry is moved.
        int m_pos_status;
+
+       /// The sound status, changed when the sound is changed.
        int m_sound_status;
+
+       /// The unique (regarding the factory) ID of the entry.
        int m_id;
 
+       /// The sound this entry plays.
        AUD_Reference<AUD_IFactory> m_sound;
+
+       /// The begin time.
        float m_begin;
+
+       /// The end time.
        float m_end;
+
+       /// How many seconds are skipped at the beginning.
        float m_skip;
+
+       /// Whether the entry is muted.
        bool m_muted;
+
+       /// Whether the position to the listener is relative or absolute
        bool m_relative;
+
+       /// Maximum volume.
        float m_volume_max;
+
+       /// Minimum volume.
        float m_volume_min;
+
+       /// Maximum distance.
        float m_distance_max;
+
+       /// Reference distance;
        float m_distance_reference;
+
+       /// Attenuation
        float m_attenuation;
+
+       /// Cone outer angle.
        float m_cone_angle_outer;
+
+       /// Cone inner angle.
        float m_cone_angle_inner;
+
+       /// Cone outer volume.
        float m_cone_volume_outer;
 
        /// The mutex for locking.
        pthread_mutex_t m_mutex;
 
+       /// The animated volume.
        AUD_AnimateableProperty m_volume;
+
+       /// The animated panning.
        AUD_AnimateableProperty m_panning;
+
+       /// The animated pitch.
        AUD_AnimateableProperty m_pitch;
+
+       /// The animated location.
        AUD_AnimateableProperty m_location;
+
+       /// The animated orientation.
        AUD_AnimateableProperty m_orientation;
 
 public:
+       /**
+        * Creates a new sequenced entry.
+        * \param sound The sound this entry should play.
+        * \param begin The start time.
+        * \param end The end time or a negative value if determined by the sound.
+        * \param skip How much seconds should be skipped at the beginning.
+        * \param id The ID of the entry.
+        */
        AUD_SequencerEntry(AUD_Reference<AUD_IFactory> sound, float begin, float end, float skip, int id);
        virtual ~AUD_SequencerEntry();
 
@@ -85,15 +139,51 @@ public:
         */
        void unlock();
 
+       /**
+        * Sets the sound of the entry.
+        * \param sound The new sound.
+        */
        void setSound(AUD_Reference<AUD_IFactory> sound);
 
+       /**
+        * Moves the entry.
+        * \param begin The new start time.
+        * \param end The new end time or a negative value if unknown.
+        * \param skip How many seconds to skip at the beginning.
+        */
        void move(float begin, float end, float skip);
+
+       /**
+        * Sets the muting state of the entry.
+        * \param mute Whether the entry should be muted or not.
+        */
        void mute(bool mute);
 
+       /**
+        * Retrieves the ID of the entry.
+        * \return The ID of the entry.
+        */
        int getID() const;
 
+       /**
+        * Retrieves one of the animated properties of the entry.
+        * \param type Which animated property to retrieve.
+        * \return A pointer to the animated property, valid as long as the
+        *         entry is.
+        */
        AUD_AnimateableProperty* getAnimProperty(AUD_AnimateablePropertyType type);
 
+       /**
+        * Updates all non-animated parameters of the entry.
+        * \param volume_max The maximum volume.
+        * \param volume_min The minimum volume.
+        * \param distance_max The maximum distance.
+        * \param distance_reference The reference distance.
+        * \param attenuation The attenuation.
+        * \param cone_angle_outer The outer cone opening angle.
+        * \param cone_angle_inner The inner cone opening angle.
+        * \param cone_volume_outer The volume outside the outer cone.
+        */
        void updateAll(float volume_max, float volume_min, float distance_max,
                                   float distance_reference, float attenuation, float cone_angle_outer,
                                   float cone_angle_inner, float cone_volume_outer);
index 753b002ae9a629e3308e6d066664c2d48d49ac90..7eb894b216cdb380d8585c643c3ee0558c887a33 100644 (file)
@@ -192,12 +192,12 @@ void AUD_SequencerFactory::remove(AUD_Reference<AUD_SequencerEntry> entry)
        unlock();
 }
 
-AUD_Reference<AUD_IReader> AUD_SequencerFactory::createReader()
+AUD_Reference<AUD_IReader> AUD_SequencerFactory::createQualityReader()
 {
-       return new AUD_SequencerReader(this);
+       return new AUD_SequencerReader(this, true);
 }
 
-AUD_Reference<AUD_IReader> AUD_SequencerFactory::createQualityReader()
+AUD_Reference<AUD_IReader> AUD_SequencerFactory::createReader()
 {
-       return new AUD_SequencerReader(this, true);
+       return new AUD_SequencerReader(this);
 }
index e2324d777d5ee81e7ccd690434b7bfb47b0f5505..89f2b015929750394abed3476b1e86181bbdd8e8 100644 (file)
 class AUD_SequencerEntry;
 
 /**
- * This factory creates a resampling reader that does simple linear resampling.
+ * This factory represents sequenced entries to play a sound scene.
  */
 class AUD_SequencerFactory : public AUD_IFactory
 {
        friend class AUD_SequencerReader;
 private:
-       /**
-        * The target specification.
-        */
+       /// The target specification.
        AUD_Specs m_specs;
 
+       /// The status of the factory. Changes every time a non-animated parameter changes.
        int m_status;
+
+       /// The entry status. Changes every time an entry is removed or added.
        int m_entry_status;
+
+       /// The next unused ID for the entries.
        int m_id;
+
+       /// The sequenced entries.
        std::list<AUD_Reference<AUD_SequencerEntry> > m_entries;
+
+       /// Whether the whole scene is muted.
        bool m_muted;
 
+       /// The FPS of the scene.
        float m_fps;
 
+       /// Speed of Sound.
        float m_speed_of_sound;
+
+       /// Doppler factor.
        float m_doppler_factor;
+
+       /// Distance model.
        AUD_DistanceModel m_distance_model;
 
+       /// The animated volume.
        AUD_AnimateableProperty m_volume;
+
+       /// The animated listener location.
        AUD_AnimateableProperty m_location;
+
+       /// The animated listener orientation.
        AUD_AnimateableProperty m_orientation;
 
        /// The mutex for locking.
@@ -76,6 +94,12 @@ private:
        AUD_SequencerFactory& operator=(const AUD_SequencerFactory&);
 
 public:
+       /**
+        * Creates a new sound scene.
+        * \param specs The output audio data specification.
+        * \param fps The FPS of the scene.
+        * \param muted Whether the whole scene is muted.
+        */
        AUD_SequencerFactory(AUD_Specs specs, float fps, bool muted);
        ~AUD_SequencerFactory();
 
@@ -89,29 +113,103 @@ public:
         */
        void unlock();
 
+       /**
+        * Sets the audio output specification.
+        * \param specs The new specification.
+        */
        void setSpecs(AUD_Specs specs);
+
+       /**
+        * Sets the scene's FPS.
+        * \param fps The new FPS.
+        */
        void setFPS(float fps);
 
+       /**
+        * Sets the muting state of the scene.
+        * \param muted Whether the scene is muted.
+        */
        void mute(bool muted);
+
+       /**
+        * Retrieves the muting state of the scene.
+        * \return Whether the scene is muted.
+        */
        bool getMute() const;
 
-       void setSpeedOfSound(float speed);
+       /**
+        * Retrieves the speed of sound.
+        * This value is needed for doppler effect calculation.
+        * \return The speed of sound.
+        */
        float getSpeedOfSound() const;
 
-       void setDopplerFactor(float factor);
+       /**
+        * Sets the speed of sound.
+        * This value is needed for doppler effect calculation.
+        * \param speed The new speed of sound.
+        */
+       void setSpeedOfSound(float speed);
+
+       /**
+        * Retrieves the doppler factor.
+        * This value is a scaling factor for the velocity vectors of sources and
+        * listener which is used while calculating the doppler effect.
+        * \return The doppler factor.
+        */
        float getDopplerFactor() const;
 
-       void setDistanceModel(AUD_DistanceModel model);
+       /**
+        * Sets the doppler factor.
+        * This value is a scaling factor for the velocity vectors of sources and
+        * listener which is used while calculating the doppler effect.
+        * \param factor The new doppler factor.
+        */
+       void setDopplerFactor(float factor);
+
+       /**
+        * Retrieves the distance model.
+        * \return The distance model.
+        */
        AUD_DistanceModel getDistanceModel() const;
 
+       /**
+        * Sets the distance model.
+        * \param model distance model.
+        */
+       void setDistanceModel(AUD_DistanceModel model);
+
+       /**
+        * Retrieves one of the animated properties of the factory.
+        * \param type Which animated property to retrieve.
+        * \return A pointer to the animated property, valid as long as the
+        *         factory is.
+        */
        AUD_AnimateableProperty* getAnimProperty(AUD_AnimateablePropertyType type);
 
+       /**
+        * Adds a new entry to the scene.
+        * \param sound The sound this entry should play.
+        * \param begin The start time.
+        * \param end The end time or a negative value if determined by the sound.
+        * \param skip How much seconds should be skipped at the beginning.
+        * \return The entry added.
+        */
        AUD_Reference<AUD_SequencerEntry> add(AUD_Reference<AUD_IFactory> sound, float begin, float end, float skip);
-       void remove(AUD_Reference<AUD_SequencerEntry> entry);
 
-       virtual AUD_Reference<AUD_IReader> createReader();
+       /**
+        * Removes an entry from the scene.
+        * \param entry The entry to remove.
+        */
+       void remove(AUD_Reference<AUD_SequencerEntry> entry);
 
+       /**
+        * Creates a new reader with high quality resampling.
+        * \return The new reader.
+        */
        AUD_Reference<AUD_IReader> createQualityReader();
+
+       virtual AUD_Reference<AUD_IReader> createReader();
 };
 
 #endif //AUD_SEQUENCERFACTORY
index 49d74a85feab825723c4b2bb212b995e83906cd6..9703d2b00597d7ce68d3750c7812d83d37a8d3ab 100644 (file)
 
 class AUD_ReadDevice;
 
+/**
+ * Represents a playing sequenced entry.
+ */
 class AUD_SequencerHandle
 {
 private:
+       /// The entry this handle belongs to.
        AUD_Reference<AUD_SequencerEntry> m_entry;
+
+       /// The handle in the read device.
        AUD_Reference<AUD_IHandle> m_handle;
+
+       /// The 3D handle in the read device.
        AUD_Reference<AUD_I3DHandle> m_3dhandle;
+
+       /// The last read status from the entry.
        int m_status;
+
+       /// The last position status from the entry.
        int m_pos_status;
+
+       /// The last sound status from the entry.
        int m_sound_status;
+
+       /// The read device this handle is played on.
        AUD_ReadDevice& m_device;
 
 public:
+       /**
+        * Creates a new sequenced handle.
+        * \param entry The entry this handle plays.
+        * \param device The read device to play on.
+        */
        AUD_SequencerHandle(AUD_Reference<AUD_SequencerEntry> entry, AUD_ReadDevice& device);
+
+       /**
+        * Destroys the handle.
+        */
        ~AUD_SequencerHandle();
+
+       /**
+        * Compares whether this handle is playing the same entry as supplied.
+        * \param entry The entry to compare to.
+        * \return Whether the entries ID is smaller, equal or bigger.
+        */
        int compare(AUD_Reference<AUD_SequencerEntry> entry) const;
+
+       /**
+        * Stops playing back the handle.
+        */
        void stop();
+
+       /**
+        * Updates the handle for playback.
+        * \param position The current time during playback.
+        * \param frame The current frame during playback.
+        */
        void update(float position, float frame);
+
+       /**
+        * Seeks the handle to a specific time position.
+        * \param position The time to seek to.
+        */
        void seek(float position);
 };
 
index 74aa80969c7a271e9a2568b68db19f1ac6e138f9..9b7aa82dc7e55d31559db768b707ecd45f89ff96 100644 (file)
@@ -38,7 +38,7 @@
 #include "AUD_SequencerHandle.h"
 
 /**
- * This resampling reader uses libsamplerate for resampling.
+ * This reader plays back sequenced entries.
  */
 class AUD_SequencerReader : public AUD_IReader
 {
@@ -58,9 +58,19 @@ private:
         */
        AUD_Reference<AUD_SequencerFactory> m_factory;
 
+       /**
+        * The list of playback handles for the entries.
+        */
        std::list<AUD_Reference<AUD_SequencerHandle> > m_handles;
 
+       /**
+        * Last status read from the factory.
+        */
        int m_status;
+
+       /**
+        * Last entry status read from the factory.
+        */
        int m_entry_status;
 
        // hide copy constructor and operator=
index 69b446408d7fb4a9da4fc71efd6bfe9a7e3aaeb2..214f1dd45d6c547f39efcfbd6fc0dac49ef663d0 100644 (file)
@@ -35,7 +35,7 @@
 #include "AUD_IFactory.h"
 
 /**
- * This factory creates a reader that plays a sine tone.
+ * This factory creates a reader that plays silence.
  */
 class AUD_SilenceFactory : public AUD_IFactory
 {
index 29966aef0a7440094c0c3238e3a92cc849c016a8..823dff10bccca83aff7e4c11eab1121d3f556c22 100644 (file)
 #include "AUD_Buffer.h"
 
 /**
- * This class is used for sine tone playback.
- * The output format is in the 16 bit format and stereo, the sample rate can be
- * specified.
- * As the two channels both play the same the output could also be mono, but
- * in most cases this will result in having to resample for output, so stereo
- * sound is created directly.
+ * This class is used for silence playback.
+ * The signal generated is 44.1kHz mono.
  */
 class AUD_SilenceReader : public AUD_IReader
 {
index 69e9a3ca576ac75b77ed16aec492cdd2d926355b..9becbbd135ab4bb299d1d4e6833673f3e9dfb3c4 100644 (file)
 
 /**
  * This class is used for sine tone playback.
- * The output format is in the 16 bit format and stereo, the sample rate can be
- * specified.
- * As the two channels both play the same the output could also be mono, but
- * in most cases this will result in having to resample for output, so stereo
- * sound is created directly.
+ * The sample rate can be specified, the signal is mono.
  */
 class AUD_SinusReader : public AUD_IReader
 {
index aa2e283ee3d9918c66fb5aeab249febe9fb55b9d..57ca445595b9c8b10831b97914ca20b90f13ffe5 100644 (file)
@@ -143,9 +143,26 @@ protected:
 
        public:
 
+               /**
+                * Creates a new software handle.
+                * \param device The device this handle is from.
+                * \param reader The reader to play.
+                * \param pitch The pitch reader.
+                * \param resampler The resampling reader.
+                * \param mapper The channel mapping reader.
+                * \param keep Whether to keep the handle when the sound ends.
+                */
                AUD_SoftwareHandle(AUD_SoftwareDevice* device, AUD_Reference<AUD_IReader> reader, AUD_Reference<AUD_PitchReader> pitch, AUD_Reference<AUD_ResampleReader> resampler, AUD_Reference<AUD_ChannelMapperReader> mapper, bool keep);
 
+               /**
+                * Updates the handle's playback parameters.
+                */
                void update();
+
+               /**
+                * Sets the audio output specification of the readers.
+                * \param sepcs The output specification.
+                */
                void setSpecs(AUD_Specs specs);
 
                virtual ~AUD_SoftwareHandle() {}
@@ -231,6 +248,10 @@ protected:
         */
        virtual void playing(bool playing)=0;
 
+       /**
+        * Sets the audio output specification of the device.
+        * \param sepcs The output specification.
+        */
        void setSpecs(AUD_Specs specs);
 
 private:
@@ -287,7 +308,17 @@ private:
 
 public:
 
+       /**
+        * Sets the panning of a specific handle.
+        * \param handle The handle to set the panning from.
+        * \param pan The new panning value, should be in the range [-2, 2].
+        */
        static void setPanning(AUD_IHandle* handle, float pan);
+
+       /**
+        * Sets the resampling quality.
+        * \param quality Low (false) or high (true) quality.
+        */
        void setQuality(bool quality);
 
        virtual AUD_DeviceSpecs getSpecs() const;
index 9232864995b2628253be5b90ad159c0175cc311c..6720dd3b4b539cc38b59b4c9b3160176b8ceac4d 100644 (file)
@@ -41,6 +41,7 @@
 /// Throws a AUD_Exception with the provided error code.
 #define AUD_THROW(exception, errorstr) { AUD_Exception e; e.error = exception; e.str = errorstr; throw e; }
 
+/// Compares two audio data specifications.
 #define AUD_COMPARE_SPECS(s1, s2) ((s1.rate == s2.rate) && (s1.channels == s2.channels))
 
 /// Returns the bit for a channel mask.
@@ -162,6 +163,7 @@ typedef enum
        AUD_DISTANCE_MODEL_EXPONENT_CLAMPED
 } AUD_DistanceModel;
 
+/// Possible animatable properties for Sequencer Factories and Entries.
 typedef enum
 {
        AUD_AP_VOLUME,
@@ -171,6 +173,7 @@ typedef enum
        AUD_AP_ORIENTATION
 } AUD_AnimateablePropertyType;
 
+/// Container formats for writers.
 typedef enum
 {
        AUD_CONTAINER_INVALID = 0,
@@ -183,6 +186,7 @@ typedef enum
        AUD_CONTAINER_WAV
 } AUD_Container;
 
+/// Audio codecs for writers.
 typedef enum
 {
        AUD_CODEC_INVALID = 0,
index 2783889ff6cb8e041dc1080327ee7844a3b889bd..894cdc7fe013e3fced5f9ff383992c2a5714faaf 100644 (file)
@@ -34,7 +34,7 @@
 
 #include "AUD_IFactory.h"
 #include "AUD_Reference.h"
-class AUD_Buffer;
+#include "AUD_Buffer.h"
 
 /**
  * This factory creates a buffer out of a reader. This way normally streamed
index 656496405dbe2e5096f4e40d34b21991a2aec202..f0b7573156dcfc7db7a4483e307b435afa33e73b 100644 (file)
@@ -122,12 +122,26 @@ private:
         */
        pthread_t m_mixingThread;
 
+       /**
+        * Mutex for mixing.
+        */
        pthread_mutex_t m_mixingLock;
 
+       /**
+        * Condition for mixing.
+        */
        pthread_cond_t m_mixingCondition;
 
+       /**
+        * Mixing thread function.
+        * \param device The this pointer.
+        * \return NULL.
+        */
        static void* runMixingThread(void* device);
 
+       /**
+        * Updates the ring buffers.
+        */
        void updateRingBuffers();
 
        // hide copy constructor and operator=
@@ -153,11 +167,39 @@ public:
         */
        virtual ~AUD_JackDevice();
 
+       /**
+        * Starts jack transport playback.
+        */
        void startPlayback();
+
+       /**
+        * Stops jack transport playback.
+        */
        void stopPlayback();
+
+       /**
+        * Seeks jack transport playback.
+        * \param time The time to seek to.
+        */
        void seekPlayback(float time);
+
+       /**
+        * Sets the sync callback for jack transport playback.
+        * \param sync The callback function.
+        * \param data The data for the function.
+        */
        void setSyncCallback(AUD_syncFunction sync, void* data);
+
+       /**
+        * Retrieves the jack transport playback time.
+        * \return The current time position.
+        */
        float getPlaybackPosition();
+
+       /**
+        * Returns whether jack transport plays back.
+        * \return Whether jack transport plays back.
+        */
        bool doesPlayback();
 };
 
index 63f9e9e137111e7afa6524685c1a17e4d5a4ab4e..110b7f800cd05f0bece5af54387253c1237e6d3b 100644 (file)
 #define AUD_SNDFILEWRITER
 
 #include "AUD_IWriter.h"
-//#include "AUD_Buffer.h"
 
 #include <string>
 #include <sndfile.h>
 
-typedef sf_count_t (*sf_read_f)(SNDFILE *sndfile, void *ptr, sf_count_t frames);
-
 /**
  * This class writes a sound file via libsndfile.
  */
@@ -69,6 +66,10 @@ public:
        /**
         * Creates a new writer.
         * \param filename The path to the file to be read.
+        * \param specs The file's audio specification.
+        * \param format The file's container format.
+        * \param codec The codec used for encoding the audio data.
+        * \param bitrate The bitrate for encoding.
         * \exception AUD_Exception Thrown if the file specified cannot be written
         *                          with libsndfile.
         */
index 7f8aeb652097265d6c394a634636465537602ea5..2a558da1cb02da705b787ad6bc9eb7e0cf2f9a7a 100644 (file)
@@ -46,7 +46,7 @@
 #ifdef WITH_QUICKTIME
 #include "quicktime_export.h"
 #  ifdef WITH_AUDASPACE
-#    include "AUD_C-API.h"
+#    include "AUD_Space.h"
 #  endif
 #endif