From 02d2472baacd8ac091a29392a2bc9ac8693fb5e7 Mon Sep 17 00:00:00 2001 From: Joerg Mueller Date: Tue, 16 Aug 2011 13:00:55 +0000 Subject: 3D Audio GSoC: Code documentation. Also: * Fix: rlint for MSVC. * Minor other small fixes/changes. --- intern/audaspace/FX/AUD_AccumulatorFactory.h | 4 + intern/audaspace/FX/AUD_BaseIIRFilterReader.h | 19 ++ intern/audaspace/FX/AUD_ButterworthFactory.h | 2 +- intern/audaspace/FX/AUD_DelayReader.h | 2 +- intern/audaspace/FX/AUD_DoubleFactory.h | 1 - intern/audaspace/FX/AUD_DoubleReader.h | 10 +- intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h | 16 ++ intern/audaspace/FX/AUD_DynamicIIRFilterReader.h | 4 + intern/audaspace/FX/AUD_HighpassFactory.h | 2 +- intern/audaspace/FX/AUD_LimiterReader.h | 8 +- intern/audaspace/FX/AUD_LowpassFactory.h | 2 +- intern/audaspace/FX/AUD_PingPongFactory.h | 2 +- intern/audaspace/FX/AUD_PitchReader.h | 11 +- intern/audaspace/FX/AUD_ReverseFactory.h | 2 +- intern/audaspace/FX/AUD_ReverseReader.h | 2 +- intern/audaspace/FX/AUD_SuperposeFactory.h | 5 +- intern/audaspace/FX/AUD_SuperposeReader.h | 4 +- intern/audaspace/FX/AUD_VolumeFactory.h | 1 + intern/audaspace/OpenAL/AUD_OpenALDevice.h | 8 + intern/audaspace/SRC/AUD_SRCResampleFactory.h | 5 + intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp | 1 - intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h | 2 +- intern/audaspace/ffmpeg/AUD_FFMPEGReader.h | 2 - intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h | 26 +++ intern/audaspace/intern/AUD_3DMath.h | 61 +++++- .../audaspace/intern/AUD_AnimateableProperty.cpp | 13 +- intern/audaspace/intern/AUD_AnimateableProperty.h | 24 ++- intern/audaspace/intern/AUD_C-API.h | 210 +++++++++++++++++++++ intern/audaspace/intern/AUD_ChannelMapperFactory.h | 5 + intern/audaspace/intern/AUD_ChannelMapperReader.h | 8 + intern/audaspace/intern/AUD_ConverterFactory.h | 5 + intern/audaspace/intern/AUD_FileWriter.h | 19 +- intern/audaspace/intern/AUD_I3DHandle.h | 2 +- intern/audaspace/intern/AUD_IDevice.h | 6 +- intern/audaspace/intern/AUD_JOSResampleFactory.h | 5 + intern/audaspace/intern/AUD_JOSResampleReader.cpp | 23 +++ intern/audaspace/intern/AUD_JOSResampleReader.h | 20 ++ .../audaspace/intern/AUD_LinearResampleFactory.h | 5 + intern/audaspace/intern/AUD_Mixer.h | 2 +- intern/audaspace/intern/AUD_ReadDevice.h | 4 + intern/audaspace/intern/AUD_Reference.h | 18 ++ intern/audaspace/intern/AUD_ResampleReader.h | 19 +- intern/audaspace/intern/AUD_SequencerEntry.h | 90 +++++++++ intern/audaspace/intern/AUD_SequencerFactory.cpp | 8 +- intern/audaspace/intern/AUD_SequencerFactory.h | 116 +++++++++++- intern/audaspace/intern/AUD_SequencerHandle.h | 46 +++++ intern/audaspace/intern/AUD_SequencerReader.h | 12 +- intern/audaspace/intern/AUD_SilenceFactory.h | 2 +- intern/audaspace/intern/AUD_SilenceReader.h | 8 +- intern/audaspace/intern/AUD_SinusReader.h | 6 +- intern/audaspace/intern/AUD_SoftwareDevice.h | 31 +++ intern/audaspace/intern/AUD_Space.h | 4 + intern/audaspace/intern/AUD_StreamBufferFactory.h | 2 +- intern/audaspace/jack/AUD_JackDevice.h | 42 +++++ intern/audaspace/sndfile/AUD_SndFileWriter.h | 7 +- 55 files changed, 874 insertions(+), 90 deletions(-) (limited to 'intern/audaspace') diff --git a/intern/audaspace/FX/AUD_AccumulatorFactory.h b/intern/audaspace/FX/AUD_AccumulatorFactory.h index 5838ccee7f0..95246ef5341 100644 --- a/intern/audaspace/FX/AUD_AccumulatorFactory.h +++ b/intern/audaspace/FX/AUD_AccumulatorFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_BaseIIRFilterReader.h b/intern/audaspace/FX/AUD_BaseIIRFilterReader.h index 644bcffbfaf..6bf877d66da 100644 --- a/intern/audaspace/FX/AUD_BaseIIRFilterReader.h +++ b/intern/audaspace/FX/AUD_BaseIIRFilterReader.h @@ -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); }; diff --git a/intern/audaspace/FX/AUD_ButterworthFactory.h b/intern/audaspace/FX/AUD_ButterworthFactory.h index 16d0b3dbc23..12d28eb4038 100644 --- a/intern/audaspace/FX/AUD_ButterworthFactory.h +++ b/intern/audaspace/FX/AUD_ButterworthFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_DelayReader.h b/intern/audaspace/FX/AUD_DelayReader.h index a89afe73b37..128e589eede 100644 --- a/intern/audaspace/FX/AUD_DelayReader.h +++ b/intern/audaspace/FX/AUD_DelayReader.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_DoubleFactory.h b/intern/audaspace/FX/AUD_DoubleFactory.h index f2be7132442..2db2257244c 100644 --- a/intern/audaspace/FX/AUD_DoubleFactory.h +++ b/intern/audaspace/FX/AUD_DoubleFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_DoubleReader.h b/intern/audaspace/FX/AUD_DoubleReader.h index 86f636e2cb2..750868a9400 100644 --- a/intern/audaspace/FX/AUD_DoubleReader.h +++ b/intern/audaspace/FX/AUD_DoubleReader.h @@ -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 reader1, AUD_Reference reader2); diff --git a/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h b/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h index 19c1a0f0a54..56d56a977d4 100644 --- a/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h +++ b/intern/audaspace/FX/AUD_DynamicIIRFilterFactory.h @@ -34,13 +34,29 @@ #include "AUD_EffectFactory.h" #include +/** + * 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 factory); virtual AUD_Reference 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& b, std::vector& a)=0; diff --git a/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h b/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h index 92f491f04d4..42789726728 100644 --- a/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h +++ b/intern/audaspace/FX/AUD_DynamicIIRFilterReader.h @@ -34,6 +34,10 @@ #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: diff --git a/intern/audaspace/FX/AUD_HighpassFactory.h b/intern/audaspace/FX/AUD_HighpassFactory.h index 51d5f55cb36..c135be27d77 100644 --- a/intern/audaspace/FX/AUD_HighpassFactory.h +++ b/intern/audaspace/FX/AUD_HighpassFactory.h @@ -41,7 +41,7 @@ class AUD_HighpassFactory : public AUD_DynamicIIRFilterFactory { private: /** - * The attack value in seconds. + * The cutoff frequency. */ const float m_frequency; diff --git a/intern/audaspace/FX/AUD_LimiterReader.h b/intern/audaspace/FX/AUD_LimiterReader.h index d9bee6f6463..9cddd4d57ec 100644 --- a/intern/audaspace/FX/AUD_LimiterReader.h +++ b/intern/audaspace/FX/AUD_LimiterReader.h @@ -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 reader, float start = 0, float end = -1); diff --git a/intern/audaspace/FX/AUD_LowpassFactory.h b/intern/audaspace/FX/AUD_LowpassFactory.h index 6558663df4e..644d25ec73d 100644 --- a/intern/audaspace/FX/AUD_LowpassFactory.h +++ b/intern/audaspace/FX/AUD_LowpassFactory.h @@ -41,7 +41,7 @@ class AUD_LowpassFactory : public AUD_DynamicIIRFilterFactory { private: /** - * The attack value in seconds. + * The cutoff frequency. */ const float m_frequency; diff --git a/intern/audaspace/FX/AUD_PingPongFactory.h b/intern/audaspace/FX/AUD_PingPongFactory.h index 908591a6ebe..b023501d45b 100644 --- a/intern/audaspace/FX/AUD_PingPongFactory.h +++ b/intern/audaspace/FX/AUD_PingPongFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_PitchReader.h b/intern/audaspace/FX/AUD_PitchReader.h index 7418531ca55..ed6adbf02fb 100644 --- a/intern/audaspace/FX/AUD_PitchReader.h +++ b/intern/audaspace/FX/AUD_PitchReader.h @@ -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 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); }; diff --git a/intern/audaspace/FX/AUD_ReverseFactory.h b/intern/audaspace/FX/AUD_ReverseFactory.h index b501b4e76c8..f43d37d8f46 100644 --- a/intern/audaspace/FX/AUD_ReverseFactory.h +++ b/intern/audaspace/FX/AUD_ReverseFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_ReverseReader.h b/intern/audaspace/FX/AUD_ReverseReader.h index da0add9464e..197d10dfe00 100644 --- a/intern/audaspace/FX/AUD_ReverseReader.h +++ b/intern/audaspace/FX/AUD_ReverseReader.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_SuperposeFactory.h b/intern/audaspace/FX/AUD_SuperposeFactory.h index ac7ec080134..b12da62b497 100644 --- a/intern/audaspace/FX/AUD_SuperposeFactory.h +++ b/intern/audaspace/FX/AUD_SuperposeFactory.h @@ -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 { diff --git a/intern/audaspace/FX/AUD_SuperposeReader.h b/intern/audaspace/FX/AUD_SuperposeReader.h index a87f1fdb739..07b4b105835 100644 --- a/intern/audaspace/FX/AUD_SuperposeReader.h +++ b/intern/audaspace/FX/AUD_SuperposeReader.h @@ -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 m_reader2; /** - * The playback buffer for the intersecting part. + * Buffer used for mixing. */ AUD_Buffer m_buffer; diff --git a/intern/audaspace/FX/AUD_VolumeFactory.h b/intern/audaspace/FX/AUD_VolumeFactory.h index bcc08e7d04a..0ca0102b790 100644 --- a/intern/audaspace/FX/AUD_VolumeFactory.h +++ b/intern/audaspace/FX/AUD_VolumeFactory.h @@ -61,6 +61,7 @@ public: /** * Returns the volume. + * \return The current volume. */ float getVolume() const; diff --git a/intern/audaspace/OpenAL/AUD_OpenALDevice.h b/intern/audaspace/OpenAL/AUD_OpenALDevice.h index 3e8b05d79e2..a04b483132a 100644 --- a/intern/audaspace/OpenAL/AUD_OpenALDevice.h +++ b/intern/audaspace/OpenAL/AUD_OpenALDevice.h @@ -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 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); diff --git a/intern/audaspace/SRC/AUD_SRCResampleFactory.h b/intern/audaspace/SRC/AUD_SRCResampleFactory.h index 2f5fe30ac47..685dbc0b176 100644 --- a/intern/audaspace/SRC/AUD_SRCResampleFactory.h +++ b/intern/audaspace/SRC/AUD_SRCResampleFactory.h @@ -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 factory, AUD_DeviceSpecs specs); virtual AUD_Reference createReader(); diff --git a/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp b/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp index 909f41302d7..e9d045bd303 100644 --- a/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp +++ b/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.cpp @@ -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) diff --git a/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h b/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h index af95e3a3b81..18510d8db8b 100644 --- a/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h +++ b/intern/audaspace/ffmpeg/AUD_FFMPEGFactory.h @@ -34,7 +34,7 @@ #include "AUD_IFactory.h" #include "AUD_Reference.h" -class AUD_Buffer; +#include "AUD_Buffer.h" #include diff --git a/intern/audaspace/ffmpeg/AUD_FFMPEGReader.h b/intern/audaspace/ffmpeg/AUD_FFMPEGReader.h index 222a3d8581a..a83477b50d6 100644 --- a/intern/audaspace/ffmpeg/AUD_FFMPEGReader.h +++ b/intern/audaspace/ffmpeg/AUD_FFMPEGReader.h @@ -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 { diff --git a/intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h b/intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h index 618ec9402ce..92460eed7ca 100644 --- a/intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h +++ b/intern/audaspace/ffmpeg/AUD_FFMPEGWriter.h @@ -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. */ diff --git a/intern/audaspace/intern/AUD_3DMath.h b/intern/audaspace/intern/AUD_3DMath.h index 007682df291..eb16dcf2d50 100644 --- a/intern/audaspace/intern/AUD_3DMath.h +++ b/intern/audaspace/intern/AUD_3DMath.h @@ -33,10 +33,17 @@ #define AUD_3DMATH #include +#include +/** + * 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), diff --git a/intern/audaspace/intern/AUD_AnimateableProperty.cpp b/intern/audaspace/intern/AUD_AnimateableProperty.cpp index adc71928efd..98d5b4cb6e1 100644 --- a/intern/audaspace/intern/AUD_AnimateableProperty.cpp +++ b/intern/audaspace/intern/AUD_AnimateableProperty.cpp @@ -35,7 +35,7 @@ #include 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; -} diff --git a/intern/audaspace/intern/AUD_AnimateableProperty.h b/intern/audaspace/intern/AUD_AnimateableProperty.h index d3b2e29c036..dd6b585741e 100644 --- a/intern/audaspace/intern/AUD_AnimateableProperty.h +++ b/intern/audaspace/intern/AUD_AnimateableProperty.h @@ -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 diff --git a/intern/audaspace/intern/AUD_C-API.h b/intern/audaspace/intern/AUD_C-API.h index 1a952b4f4a9..612f98a79c3 100644 --- a/intern/audaspace/intern/AUD_C-API.h +++ b/intern/audaspace/intern/AUD_C-API.h @@ -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_getDevice(); +/** + * Returns the current playback 3D device. + * \return The playback 3D device. + */ AUD_I3DDevice* AUD_get3DDevice(); #endif diff --git a/intern/audaspace/intern/AUD_ChannelMapperFactory.h b/intern/audaspace/intern/AUD_ChannelMapperFactory.h index ce43c6462de..9e1adf09ca9 100644 --- a/intern/audaspace/intern/AUD_ChannelMapperFactory.h +++ b/intern/audaspace/intern/AUD_ChannelMapperFactory.h @@ -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 factory, AUD_DeviceSpecs specs); virtual AUD_Reference createReader(); diff --git a/intern/audaspace/intern/AUD_ChannelMapperReader.h b/intern/audaspace/intern/AUD_ChannelMapperReader.h index fa035531763..af16f2ff49d 100644 --- a/intern/audaspace/intern/AUD_ChannelMapperReader.h +++ b/intern/audaspace/intern/AUD_ChannelMapperReader.h @@ -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; diff --git a/intern/audaspace/intern/AUD_ConverterFactory.h b/intern/audaspace/intern/AUD_ConverterFactory.h index 8f0221addb7..128653c5c54 100644 --- a/intern/audaspace/intern/AUD_ConverterFactory.h +++ b/intern/audaspace/intern/AUD_ConverterFactory.h @@ -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 factory, AUD_DeviceSpecs specs); virtual AUD_Reference createReader(); diff --git a/intern/audaspace/intern/AUD_FileWriter.h b/intern/audaspace/intern/AUD_FileWriter.h index 60aec1b5927..341728ff836 100644 --- a/intern/audaspace/intern/AUD_FileWriter.h +++ b/intern/audaspace/intern/AUD_FileWriter.h @@ -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 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 reader, AUD_Reference writer, unsigned int length, unsigned int buffersize); }; diff --git a/intern/audaspace/intern/AUD_I3DHandle.h b/intern/audaspace/intern/AUD_I3DHandle.h index afb8cb29c53..8ef08b18f94 100644 --- a/intern/audaspace/intern/AUD_I3DHandle.h +++ b/intern/audaspace/intern/AUD_I3DHandle.h @@ -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 { diff --git a/intern/audaspace/intern/AUD_IDevice.h b/intern/audaspace/intern/AUD_IDevice.h index 86d695ef764..108e7505d84 100644 --- a/intern/audaspace/intern/AUD_IDevice.h +++ b/intern/audaspace/intern/AUD_IDevice.h @@ -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. diff --git a/intern/audaspace/intern/AUD_JOSResampleFactory.h b/intern/audaspace/intern/AUD_JOSResampleFactory.h index 0ecd3c12dbe..90a5df5baf0 100644 --- a/intern/audaspace/intern/AUD_JOSResampleFactory.h +++ b/intern/audaspace/intern/AUD_JOSResampleFactory.h @@ -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 factory, AUD_DeviceSpecs specs); virtual AUD_Reference createReader(); diff --git a/intern/audaspace/intern/AUD_JOSResampleReader.cpp b/intern/audaspace/intern/AUD_JOSResampleReader.cpp index fd811d617c6..4af892da676 100644 --- a/intern/audaspace/intern/AUD_JOSResampleReader.cpp +++ b/intern/audaspace/intern/AUD_JOSResampleReader.cpp @@ -36,6 +36,29 @@ #include #include +/* MSVC does not have lrint */ +#ifdef _MSC_VER +#ifdef _M_X64 +#include +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 diff --git a/intern/audaspace/intern/AUD_JOSResampleReader.h b/intern/audaspace/intern/AUD_JOSResampleReader.h index 1eef290c37f..295fc937317 100644 --- a/intern/audaspace/intern/AUD_JOSResampleReader.h +++ b/intern/audaspace/intern/AUD_JOSResampleReader.h @@ -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); diff --git a/intern/audaspace/intern/AUD_LinearResampleFactory.h b/intern/audaspace/intern/AUD_LinearResampleFactory.h index de015610a73..6fb101aa708 100644 --- a/intern/audaspace/intern/AUD_LinearResampleFactory.h +++ b/intern/audaspace/intern/AUD_LinearResampleFactory.h @@ -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 factory, AUD_DeviceSpecs specs); virtual AUD_Reference createReader(); diff --git a/intern/audaspace/intern/AUD_Mixer.h b/intern/audaspace/intern/AUD_Mixer.h index 5ca801b1690..cdcf0d23b6d 100644 --- a/intern/audaspace/intern/AUD_Mixer.h +++ b/intern/audaspace/intern/AUD_Mixer.h @@ -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 diff --git a/intern/audaspace/intern/AUD_ReadDevice.h b/intern/audaspace/intern/AUD_ReadDevice.h index 3ec48e6ebca..2d0e37c44c1 100644 --- a/intern/audaspace/intern/AUD_ReadDevice.h +++ b/intern/audaspace/intern/AUD_ReadDevice.h @@ -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); }; diff --git a/intern/audaspace/intern/AUD_Reference.h b/intern/audaspace/intern/AUD_Reference.h index 25cc7bcda58..3977b22a1dd 100644 --- a/intern/audaspace/intern/AUD_Reference.h +++ b/intern/audaspace/intern/AUD_Reference.h @@ -40,12 +40,22 @@ #include #endif +/** + * This class handles the reference counting. + */ class AUD_ReferenceHandler { private: + /** + * Saves the reference counts. + */ static std::map 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; diff --git a/intern/audaspace/intern/AUD_ResampleReader.h b/intern/audaspace/intern/AUD_ResampleReader.h index 4c1a1ece9d9..0792753f4b3 100644 --- a/intern/audaspace/intern/AUD_ResampleReader.h +++ b/intern/audaspace/intern/AUD_ResampleReader.h @@ -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 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 diff --git a/intern/audaspace/intern/AUD_SequencerEntry.h b/intern/audaspace/intern/AUD_SequencerEntry.h index 71e3f8b8908..53e3513b1b5 100644 --- a/intern/audaspace/intern/AUD_SequencerEntry.h +++ b/intern/audaspace/intern/AUD_SequencerEntry.h @@ -38,40 +38,94 @@ #include +/** + * 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 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 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 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); diff --git a/intern/audaspace/intern/AUD_SequencerFactory.cpp b/intern/audaspace/intern/AUD_SequencerFactory.cpp index 753b002ae9a..7eb894b216c 100644 --- a/intern/audaspace/intern/AUD_SequencerFactory.cpp +++ b/intern/audaspace/intern/AUD_SequencerFactory.cpp @@ -192,12 +192,12 @@ void AUD_SequencerFactory::remove(AUD_Reference entry) unlock(); } -AUD_Reference AUD_SequencerFactory::createReader() +AUD_Reference AUD_SequencerFactory::createQualityReader() { - return new AUD_SequencerReader(this); + return new AUD_SequencerReader(this, true); } -AUD_Reference AUD_SequencerFactory::createQualityReader() +AUD_Reference AUD_SequencerFactory::createReader() { - return new AUD_SequencerReader(this, true); + return new AUD_SequencerReader(this); } diff --git a/intern/audaspace/intern/AUD_SequencerFactory.h b/intern/audaspace/intern/AUD_SequencerFactory.h index e2324d777d5..89f2b015929 100644 --- a/intern/audaspace/intern/AUD_SequencerFactory.h +++ b/intern/audaspace/intern/AUD_SequencerFactory.h @@ -41,31 +41,49 @@ 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 > 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 add(AUD_Reference sound, float begin, float end, float skip); - void remove(AUD_Reference entry); - virtual AUD_Reference createReader(); + /** + * Removes an entry from the scene. + * \param entry The entry to remove. + */ + void remove(AUD_Reference entry); + /** + * Creates a new reader with high quality resampling. + * \return The new reader. + */ AUD_Reference createQualityReader(); + + virtual AUD_Reference createReader(); }; #endif //AUD_SEQUENCERFACTORY diff --git a/intern/audaspace/intern/AUD_SequencerHandle.h b/intern/audaspace/intern/AUD_SequencerHandle.h index 49d74a85fea..9703d2b0059 100644 --- a/intern/audaspace/intern/AUD_SequencerHandle.h +++ b/intern/audaspace/intern/AUD_SequencerHandle.h @@ -38,23 +38,69 @@ class AUD_ReadDevice; +/** + * Represents a playing sequenced entry. + */ class AUD_SequencerHandle { private: + /// The entry this handle belongs to. AUD_Reference m_entry; + + /// The handle in the read device. AUD_Reference m_handle; + + /// The 3D handle in the read device. AUD_Reference 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 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 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); }; diff --git a/intern/audaspace/intern/AUD_SequencerReader.h b/intern/audaspace/intern/AUD_SequencerReader.h index 74aa80969c7..9b7aa82dc7e 100644 --- a/intern/audaspace/intern/AUD_SequencerReader.h +++ b/intern/audaspace/intern/AUD_SequencerReader.h @@ -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 m_factory; + /** + * The list of playback handles for the entries. + */ std::list > 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= diff --git a/intern/audaspace/intern/AUD_SilenceFactory.h b/intern/audaspace/intern/AUD_SilenceFactory.h index 69b446408d7..214f1dd45d6 100644 --- a/intern/audaspace/intern/AUD_SilenceFactory.h +++ b/intern/audaspace/intern/AUD_SilenceFactory.h @@ -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 { diff --git a/intern/audaspace/intern/AUD_SilenceReader.h b/intern/audaspace/intern/AUD_SilenceReader.h index 29966aef0a7..823dff10bcc 100644 --- a/intern/audaspace/intern/AUD_SilenceReader.h +++ b/intern/audaspace/intern/AUD_SilenceReader.h @@ -36,12 +36,8 @@ #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 { diff --git a/intern/audaspace/intern/AUD_SinusReader.h b/intern/audaspace/intern/AUD_SinusReader.h index 69e9a3ca576..9becbbd135a 100644 --- a/intern/audaspace/intern/AUD_SinusReader.h +++ b/intern/audaspace/intern/AUD_SinusReader.h @@ -37,11 +37,7 @@ /** * 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 { diff --git a/intern/audaspace/intern/AUD_SoftwareDevice.h b/intern/audaspace/intern/AUD_SoftwareDevice.h index aa2e283ee3d..57ca445595b 100644 --- a/intern/audaspace/intern/AUD_SoftwareDevice.h +++ b/intern/audaspace/intern/AUD_SoftwareDevice.h @@ -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 reader, AUD_Reference pitch, AUD_Reference resampler, AUD_Reference 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; diff --git a/intern/audaspace/intern/AUD_Space.h b/intern/audaspace/intern/AUD_Space.h index 9232864995b..6720dd3b4b5 100644 --- a/intern/audaspace/intern/AUD_Space.h +++ b/intern/audaspace/intern/AUD_Space.h @@ -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, diff --git a/intern/audaspace/intern/AUD_StreamBufferFactory.h b/intern/audaspace/intern/AUD_StreamBufferFactory.h index 2783889ff6c..894cdc7fe01 100644 --- a/intern/audaspace/intern/AUD_StreamBufferFactory.h +++ b/intern/audaspace/intern/AUD_StreamBufferFactory.h @@ -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 diff --git a/intern/audaspace/jack/AUD_JackDevice.h b/intern/audaspace/jack/AUD_JackDevice.h index 656496405db..f0b7573156d 100644 --- a/intern/audaspace/jack/AUD_JackDevice.h +++ b/intern/audaspace/jack/AUD_JackDevice.h @@ -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(); }; diff --git a/intern/audaspace/sndfile/AUD_SndFileWriter.h b/intern/audaspace/sndfile/AUD_SndFileWriter.h index 63f9e9e1371..110b7f800cd 100644 --- a/intern/audaspace/sndfile/AUD_SndFileWriter.h +++ b/intern/audaspace/sndfile/AUD_SndFileWriter.h @@ -33,13 +33,10 @@ #define AUD_SNDFILEWRITER #include "AUD_IWriter.h" -//#include "AUD_Buffer.h" #include #include -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. */ -- cgit v1.2.3