diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h index 8d16b06995..f7dd252c54 100644 --- a/interface/src/scripting/Audio.h +++ b/interface/src/scripting/Audio.h @@ -26,7 +26,7 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { SINGLETON_DEPENDENCY /**jsdoc - * The Audio API features tools to help control audio contexts and settings. + * The Audio API ... TODO * * @namespace Audio * @@ -35,12 +35,13 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { * @hifi-server-entity * @hifi-assignment-client * - * @property {boolean} muted - * @property {boolean} noiseReduction - * @property {number} inputVolume - * @property {number} inputLevel Read-only. - * @property {string} context Read-only. - * @property {} devices Read-only. + * @property {boolean} muted - true if TODO, otherwise false. + * @property {boolean} noiseReduction - true if TODO, otherwise false. + * @property {number} inputVolume - TODO + * @property {number} inputLevel - TODO Read-only. + * @property {string} context - TODO Read-only. + * @property {object} devices Read-only. Deprecated: This property is deprecated and will be + * removed. */ Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged) @@ -69,87 +70,100 @@ public: /**jsdoc * @function Audio.setInputDevice - * @param {} device + * @param {object} device * @param {boolean} isHMD + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setInputDevice(const QAudioDeviceInfo& device, bool isHMD); /**jsdoc * @function Audio.setOutputDevice - * @param {} device + * @param {object} device * @param {boolean} isHMD + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD); /**jsdoc + * TODO * @function Audio.setReverb - * @param {boolean} enable + * @param {boolean} enable - TODO */ Q_INVOKABLE void setReverb(bool enable); /**jsdoc + * TODO * @function Audio.setReverbOptions - * @param {AudioEffectOptions} options + * @param {AudioEffectOptions} options - TODO */ Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options); /**jsdoc + * TODO * @function Audio.startRecording - * @param {string} filename - * @returns {boolean} + * @param {string} filename - TODO + * @returns {boolean} true if TODO, otherwise false. */ Q_INVOKABLE bool startRecording(const QString& filename); /**jsdoc + * TODO * @function Audio.stopRecording */ Q_INVOKABLE void stopRecording(); /**jsdoc + * TODO * @function Audio.getRecording - * @returns {boolean} + * @returns {boolean} true if TODO, otherwise false. */ Q_INVOKABLE bool getRecording(); signals: /**jsdoc + * Triggered when ... TODO * @function Audio.nop * @returns {Signal} */ void nop(); /**jsdoc + * Triggered when ... TODO * @function Audio.mutedChanged - * @param {boolean} isMuted + * @param {boolean} isMuted - TODO * @returns {Signal} */ void mutedChanged(bool isMuted); /**jsdoc + * Triggered when ... TODO * @function Audio.noiseReductionChanged - * @param {boolean} isEnabled + * @param {boolean} isEnabled - TODO * @returns {Signal} */ void noiseReductionChanged(bool isEnabled); /**jsdoc + * Triggered when ... TODO * @function Audio.inputVolumeChanged - * @param {number} volume + * @param {number} volume - TODO * @returns {Signal} */ void inputVolumeChanged(float volume); /**jsdoc + * Triggered when ... TODO * @function Audio.inputLevelChanged - * @param {number} level + * @param {number} level - TODO * @returns {Signal} */ void inputLevelChanged(float level); /**jsdoc + * Triggered when ... TODO * @function Audio.contextChanged - * @param {string} context + * @param {string} context - TODO * @returns {Signal} */ void contextChanged(const QString& context); @@ -158,7 +172,7 @@ public slots: /**jsdoc * @function Audio.onContextChanged - * @returns {Signal} + * @deprecated This function is deprecated and will be removed. */ void onContextChanged(); diff --git a/libraries/audio/src/AudioEffectOptions.cpp b/libraries/audio/src/AudioEffectOptions.cpp index edb0ff52ae..3ed1296b63 100644 --- a/libraries/audio/src/AudioEffectOptions.cpp +++ b/libraries/audio/src/AudioEffectOptions.cpp @@ -59,28 +59,29 @@ static void setOption(QScriptValue arguments, const QString name, float defaultV } /**jsdoc + * TODO * @typedef {object} AudioEffectOptions.ReverbOptions - * @property {number} bandwidth - * @property {number} preDelay - * @property {number} lateDelay - * @property {number} reverbTime - * @property {number} earlyDiffusion - * @property {number} lateDiffusion - * @property {number} roomSize - * @property {number} density - * @property {number} bassMult - * @property {number} bassFreq - * @property {number} highGain - * @property {number} highFreq - * @property {number} modRate - * @property {number} modDepth - * @property {number} earlyGain - * @property {number} lateGain - * @property {number} earlyMixLeft - * @property {number} earlyMixRight - * @property {number} lateMixLeft - * @property {number} lateMixRight - * @property {number} wetDryMix + * @property {number} bandwidth - TODO + * @property {number} preDelay - TODO + * @property {number} lateDelay - TODO + * @property {number} reverbTime - TODO + * @property {number} earlyDiffusion - TODO + * @property {number} lateDiffusion - TODO + * @property {number} roomSize - TODO + * @property {number} density - TODO + * @property {number} bassMult - TODO + * @property {number} bassFreq - TODO + * @property {number} highGain - TODO + * @property {number} highFreq - TODO + * @property {number} modRate - TODO + * @property {number} modDepth - TODO + * @property {number} earlyGain - TODO + * @property {number} lateGain - TODO + * @property {number} earlyMixLeft - TODO + * @property {number} earlyMixRight - TODO + * @property {number} lateMixLeft - TODO + * @property {number} lateMixRight - TODO + * @property {number} wetDryMix - TODO */ AudioEffectOptions::AudioEffectOptions(QScriptValue arguments) { setOption(arguments, BANDWIDTH_HANDLE, BANDWIDTH_DEFAULT, _bandwidth); diff --git a/libraries/audio/src/AudioEffectOptions.h b/libraries/audio/src/AudioEffectOptions.h index 1afd4e21be..0e2e017d49 100644 --- a/libraries/audio/src/AudioEffectOptions.h +++ b/libraries/audio/src/AudioEffectOptions.h @@ -16,35 +16,38 @@ #include /**jsdoc + * TODO + * Used in the {@link Audio} API. + * * @class AudioEffectOptions - * @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null] + * @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null] - TODO * * @hifi-interface * @hifi-client-entity * @hifi-server-entity * @hifi-assignment-client * - * @property {number} bandwidth=10000 - * @property {number} preDelay=20 - * @property {number} lateDelay=0 - * @property {number} reverbTime=2 - * @property {number} earlyDiffusion=100 - * @property {number} lateDiffusion=100 - * @property {number} roomSize=50 - * @property {number} density=100 - * @property {number} bassMult=1.5 - * @property {number} bassFreq=250 - * @property {number} highGain=-6 - * @property {number} highFreq=3000 - * @property {number} modRate=2.3 - * @property {number} modDepth=50 - * @property {number} earlyGain=0 - * @property {number} lateGain=0 - * @property {number} earlyMixLeft=20 - * @property {number} earlyMixRight=20 - * @property {number} lateMixLeft=90 - * @property {number} lateMixRight=90 - * @property {number} wetDryMix=50 + * @property {number} bandwidth=10000 - TODO + * @property {number} preDelay=20 - TODO + * @property {number} lateDelay=0 - TODO + * @property {number} reverbTime=2 - TODO + * @property {number} earlyDiffusion=100 - TODO + * @property {number} lateDiffusion=100 - TODO + * @property {number} roomSize=50 - TODO + * @property {number} density=100 - TODO + * @property {number} bassMult=1.5 - TODO + * @property {number} bassFreq=250 - TODO + * @property {number} highGain=-6 - TODO + * @property {number} highFreq=3000 - TODO + * @property {number} modRate=2.3 - TODO + * @property {number} modDepth=50 - TODO + * @property {number} earlyGain=0 - TODO + * @property {number} lateGain=0 - TODO + * @property {number} earlyMixLeft=20 - TODO + * @property {number} earlyMixRight=20 - TODO + * @property {number} lateMixLeft=90 - TODO + * @property {number} lateMixRight=90 - TODO + * @property {number} wetDryMix=50 - TODO */ class AudioEffectOptions : public QObject { diff --git a/libraries/audio/src/AudioInjectorOptions.cpp b/libraries/audio/src/AudioInjectorOptions.cpp index 2f82cae137..8691432bcd 100644 --- a/libraries/audio/src/AudioInjectorOptions.cpp +++ b/libraries/audio/src/AudioInjectorOptions.cpp @@ -45,6 +45,18 @@ QScriptValue injectorOptionsToScriptValue(QScriptEngine* engine, const AudioInje return obj; } +/**jsdoc + * TODO + * @typedef {object} AudioInjector.AudioInjectorOptions + * @property {Vec3} position=Vec3.ZERO - TODO + * @property {Quat} orientation=Quat.IDENTITY - TODO + * @property {number} volume=1 - TODO + * @property {boolean} loop=false - true if TODO, otherwise false. + * @property {boolean} ignorePenumbra=false - true if TODO, otherwise false. + * @property {boolean} localOnly=false - true if TODO, otherwise false. + * @property {number} secondOffset=0 - TODO + * @property {number} pitch=1 - TODO + */ void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) { if (!object.isObject()) { qWarning() << "Audio injector options is not an object."; diff --git a/libraries/audio/src/Sound.h b/libraries/audio/src/Sound.h index 061c4a2417..0edcb59cca 100644 --- a/libraries/audio/src/Sound.h +++ b/libraries/audio/src/Sound.h @@ -79,6 +79,9 @@ private: typedef QSharedPointer SharedSoundPointer; /**jsdoc + * TODO + * Created by {@link SoundCache.getSound}. + * * @class SoundObject * * @hifi-interface @@ -86,8 +89,8 @@ typedef QSharedPointer SharedSoundPointer; * @hifi-server-entity * @hifi-assignment-client * - * @property {boolean} downloaded - * @property {number} duration + * @property {boolean} downloaded - true if TODO, otherwise false. + * @property {number} duration - TODO */ class SoundScriptingInterface : public QObject { Q_OBJECT @@ -103,6 +106,7 @@ public: float getDuration() { return _sound->getDuration(); } /**jsdoc + * Triggered when TODO * @function SoundObject.ready * @returns {Signal} */ diff --git a/libraries/script-engine/src/AudioScriptingInterface.h b/libraries/script-engine/src/AudioScriptingInterface.h index 20ca977da1..6b87b0ee67 100644 --- a/libraries/script-engine/src/AudioScriptingInterface.h +++ b/libraries/script-engine/src/AudioScriptingInterface.h @@ -35,91 +35,96 @@ protected: // these methods are protected to stop C++ callers from calling, but invokable from script /**jsdoc + * TODO * @function Audio.playSound - * @param {} sound - * @param {} [injectorOptions=null] - * @returns {object} + * @param {SoundObject} sound - TODO + * @param {AudioInjector.AudioInjectorOptions} [injectorOptions={}] - TODO + * @returns {AudioInjector} TODO */ Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions()); /**jsdoc + * TODO * @function Audio.playSystemSound - * @param {} sound - * @param {} position - * @returns {object} + * @param {SoundObject} sound - TODO + * @param {Vec3} position - TODO + * @returns {AudioInjector} TODO */ // FIXME: there is no way to play a positionless sound Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound, const QVector3D& position); /**jsdoc + * TODO * @function Audio.setStereoInput - * @param {boolean} stereo + * @param {boolean} stereo - TODO */ Q_INVOKABLE void setStereoInput(bool stereo); /**jsdoc + * TODO * @function Audio.isStereoInput - * @returns {boolean} + * @returns {boolean} true if TODO, otherwise false. */ Q_INVOKABLE bool isStereoInput(); signals: /**jsdoc - * The client has been muted by the mixer. + * Triggered when the client is muted by the mixer. * @function Audio.mutedByMixer * @returns {Signal} */ void mutedByMixer(); /**jsdoc - * The entire environment has been muted by the mixer. + * Triggered when the entire environment is muted by the mixer. TODO: What is the "whole environment"? * @function Audio.environmentMuted * @returns {Signal} */ void environmentMuted(); /**jsdoc - * The client has received its first packet from the audio mixer. + * Triggered when the client receives its first packet from the audio mixer. * @function Audio.receivedFirstPacket * @returns {Signal} */ void receivedFirstPacket(); /**jsdoc - * The client has been disconnected from the audio mixer. + * Triggered when the client is disconnected from the audio mixer. * @function Audio.disconnected * @returns {Signal} */ void disconnected(); /**jsdoc - * The noise gate has opened. + * Triggered when the noise gate is opened. TODO: Description of noise gate. * @function Audio.noiseGateOpened * @returns {Signal} */ void noiseGateOpened(); /**jsdoc - * The noise gate has closed. + * Triggered when the noise gate is closed. TODO: Description of noise gate. * @function Audio.noiseGateClosed * @returns {Signal} */ void noiseGateClosed(); /**jsdoc - * A frame of mic input audio has been received and processed. + * Triggered when a frame of microphone audio input is processed. * @function Audio.inputReceived - * @param {} inputSamples + * @param {Int16Array} inputSamples - TODO * @returns {Signal} */ void inputReceived(const QByteArray& inputSamples); /**jsdoc - * @function Audio.isStereoInputChanged - * @param {boolean} isStereo - * @returns {Signal} - */ + * TODO + * @function Audio.isStereoInputChanged + * @param {boolean} isStereo - TODO + * @returns {Signal} + */ void isStereoInputChanged(bool isStereo); private: diff --git a/libraries/script-engine/src/ScriptAudioInjector.h b/libraries/script-engine/src/ScriptAudioInjector.h index 4c2871dd34..5d66461160 100644 --- a/libraries/script-engine/src/ScriptAudioInjector.h +++ b/libraries/script-engine/src/ScriptAudioInjector.h @@ -16,6 +16,21 @@ #include +/**jsdoc + * TODO + * Used in the {@link Audio} API. + * + * @class AudioInjector + * + * @hifi-interface + * @hifi-client-entity + * @hifi-server-entity + * @hifi-assignment-client + * + * @property {boolean} playing - true if TODO, otherwise false. Read-only. + * @property {number} loudness - TODO Read-only. + * @property {AudioInjector.AudioInjectorOptions} options - TODO + */ class ScriptAudioInjector : public QObject { Q_OBJECT @@ -26,19 +41,62 @@ public: ScriptAudioInjector(const AudioInjectorPointer& injector); ~ScriptAudioInjector(); public slots: + + /**jsdoc + * TODO + * @function AudioInjector.restart + */ void restart() { _injector->restart(); } + + /**jsdoc + * TODO + * @function AudioInjector.stop + */ void stop() { _injector->stop(); } + /**jsdoc + * TODO + * @function AudioInjector.getOptions + * @returns {AudioInjector.AudioInjectorOptions} TODO + */ const AudioInjectorOptions& getOptions() const { return _injector->getOptions(); } + + /**jsdoc + * TODO + * @function AudioInjector.setOptions + * @param {AudioInjector.AudioInjectorOptions} options - TODO + */ void setOptions(const AudioInjectorOptions& options) { _injector->setOptions(options); } + /**jsdoc + * TODO + * @function AudioInjector.getLoudness + * @returns {number} TODO + */ float getLoudness() const { return _injector->getLoudness(); } + + /**jsdoc + * TODO + * @function AudioInjector.isPlaying + * @returns {boolean} true if TODO, otherwise false. + */ bool isPlaying() const { return _injector->isPlaying(); } signals: + + /**jsdoc + * Triggered when TODO + * @function AudioInjector.finished + * @returns {Signal} + */ void finished(); protected slots: + + /**jsdoc + * TODO + * @function AudioInjector.stopInjectorImmediately + */ void stopInjectorImmediately(); private: AudioInjectorPointer _injector;