Prechádzať zdrojové kódy

Created Audio docs (#10059)

* Added audio menu list

* Created docs for Audio

* Created PositionAudio doc

* Created doc for AudioListener

* Created docs for AudioAnalyser

* Spelling
Lewy Blue 8 rokov pred
rodič
commit
2016776214

+ 204 - 0
docs/api/audio/Audio.html

@@ -0,0 +1,204 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Object3D] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+			Create a non-positional ( global ) audio object.<br /><br />
+
+			This uses the [link:https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API Web Audio API].
+		</div>
+
+
+		<h2>Example</h2>
+
+		<div>[example:misc_sound misc / sound ]</div>
+		<code>
+		//Create an AudioListener and add it to the camera
+		var listener = new THREE.AudioListener();
+		camera.add( listener );
+
+		// create a global audio source
+		var sound = new THREE.Audio( listener );
+
+		var audioLoader = new THREE.AudioLoader();
+
+		//Load a sound and set it as the Audio object's buffer
+		audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
+			sound.setBuffer( buffer );
+			sound.setLoop(true);
+			sound.setVolume(0.5);
+			sound.play();
+		});
+		</code>
+
+
+		<h2>Constructor</h2>
+
+
+		<h3>[name]( [page:AudioListener listener] )</h3>
+		<div>
+		listener — (required) [page:AudioListener AudioListener] instance.
+		</div>
+
+
+		<h2>Properties</h2>
+
+		<h3>[property:Boolean autoplay]</h3>
+		<div>Whether to start playback automatically. Default is *false*.</div>
+
+		<h3>[property:AudioContext context]</h3>
+		<div>The [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext AudioContext] of the [page:AudioListener listener] given in the constructor.</div>
+
+		<h3>[property:Array filters]</h3>
+		<div>Whether the audio is currently playing. Default is empty array.</div>
+
+		<h3>[property:GainNode gain]</h3>
+		<div>A [link:https://developer.mozilla.org/en-US/docs/Web/API/GainNode GainNode] created
+		using [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain AudioContext.createGain]().</div>
+		</div>
+
+		<h3>[property:Boolean hasPlaybackControl]</h3>
+		<div>Whether playback can be controlled using the [page:Audio.play play](),
+			[page:Audio.pause pause]() etc. methods. Default is *true*.</div>
+
+		<h3>[property:Number playbackRate]</h3>
+		<div>Speed of playback. Default is *1*.</div>
+
+		<h3>[property:Boolean isPlaying]</h3>
+		<div>Whether the audio is currently playing.</div>
+
+		<h3>[property:Number startTime]</h3>
+		<div>Point at which to start playback. Default is *0*.</div>
+
+		<h3>[property:String source]</h3>
+		<div>An [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode AudioBufferSourceNode] created
+		using [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createBufferSource AudioContext.createBufferSource]().</div>
+
+		<h3>[property:String sourceType]</h3>
+		<div>Type of the audio source. Default is string 'empty'.</div>
+
+		<h3>[property:String type]</h3>
+		<div>String denoting the type, set to 'Audio'.</div>
+
+
+		<h2>Methods</h2>
+
+		<h3>[method:null connect]()</h3>
+		<div>
+		Connect to the [page:Audio.source]. This is used internally on initialisation and when
+		setting / removing filters.
+		</div>
+
+		<h3>[method:null disconnect]()</h3>
+		<div>
+		Disconnect from the [page:Audio.source]. This is used internally when
+		setting / removing filters.
+		</div>
+
+		<h3>[method:Array getFilter]()</h3>
+		<div>
+		Returns the first element of the [page:Audio.filters filters] array.
+		</div>
+
+		<h3>[method:null getFilters]()</h3>
+		<div>
+		Returns the [page:Audio.filters filters] array.
+		</div>
+
+		<h3>[method:Boolean getLoop]()</h3>
+		<div>
+		Return the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loop source.loop]
+		 (whether playback should loop).
+		</div>
+
+		<h3>[method:GainNode getOutput]()</h3>
+		<div>
+		Return the [page:Audio.gain gainNode].
+		</div>
+
+		<h3>[method:Number getPlaybackRate]()</h3>
+		<div>
+		Return the value of [page:Audio.playbackRate playbackRate].
+		</div>
+
+		<h3>[method:Number getVolume]( value )</h3>
+		<div>
+		Return the current volume.
+		</div>
+
+		<h3>[method:null play]()</h3>
+		<div>
+		If [page:Audio.hasPlaybackControl hasPlaybackControl] is true, starts playback.
+		</div>
+
+		<h3>[method:null pause]()</h3>
+		<div>
+		If [page:Audio.hasPlaybackControl hasPlaybackControl] is true, pauses playback.
+		</div>
+
+		<h3>[method:null onEnded]()</h3>
+		<div>
+		Called automatically when playback finished. Sets If [page:Audio.isPlaying isPlaying] to false.
+		</div>
+
+		<h3>[method:Audio setBuffer]( audioBuffer )</h3>
+		<div>
+		Setup the [page:Audio.source source] to the audioBuffer, and sets [page:Audio.sourceType sourceType] to 'buffer'.<br />
+		If [page:Audio.autoplay autoplay], also starts playback.
+		</div>
+
+		<h3>[method:null setFilter]( filter )</h3>
+		<div>
+		Add the filter to the [page:Audio.filters filters] array.
+		</div>
+
+		<h3>[method:Audio setFilters]( [page:Array value] )</h3>
+		<div>
+		value - arrays of filters.<br />
+		Set the [page:Audio.filters filters] array to *value*.
+		</div>
+
+		<h3>[method:null setLoop]( [page:Boolean value] )</h3>
+		<div>
+		Set [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loop source.loop] to *value*
+		(whether playback should loop).
+		</div>
+
+		<h3>[method:null setNodeSource]( audioNode )</h3>
+		<div>
+		Setup the [page:Audio.source source] to the audioBuffer, and sets [page:Audio.sourceType sourceType] to 'audioNode'.<br />
+		Also sets [page:Audio.hasPlaybackControl hasPlaybackControl] to false.
+
+		</div>
+
+		<h3>[method:null setPlaybackRate]( [page:Number value] )</h3>
+		<div>
+		If [page:Audio.hasPlaybackControl hasPlaybackControl] is enabled, set the [page:Audio.playbackRate playbackRate] to *value*.
+		</div>
+
+		<h3>[method:null setVolume]( [page:Number value] )</h3>
+		<div>
+		Set the volume.
+		</div>
+
+		<h3>[method:null stop]()</h3>
+		<div>
+		If [page:Audio.hasPlaybackControl hasPlaybackControl] is enabled, stops playback,
+		resets [page:Audio.startTime startTime] to *0* and sets [page:Audio.isPlaying isPlaying] to false.
+		</div>
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

+ 96 - 0
docs/api/audio/AudioAnalyser.html

@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		<h1>[name]</h1>
+
+		<div class="desc">
+			Create a AudioAnalyser object, which uses an [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode AnalyserNode]
+			to analyse audio data.<br /><br />
+
+			This uses the [link:https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API Web Audio API].
+
+		</div>
+
+
+		<h2>Example</h2>
+
+		<div>[example:misc_sound misc / sound ]</div>
+		<code>
+		//Create an AudioListener and add it to the camera
+		var listener = new THREE.AudioListener();
+		camera.add( listener );
+
+		// create an Audio source
+		var sound = new THREE.Audio( listener );
+
+		var audioLoader = new THREE.AudioLoader();
+
+		//Load a sound and set it as the Audio object's buffer
+		audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
+			sound.setBuffer( buffer );
+			sound.setLoop(true);
+			sound.setVolume(0.5);
+			sound.play();
+		});
+
+		//Create an AudioAnalyser, passing in the sound and desired fftSize
+		var analyser = new THREE.AudioAnalyser( sound, 32 );
+
+		//Get the average frequency of the sound
+		analyser.getAverageFrequency();
+		</code>
+
+
+		<h2>Constructor</h2>
+
+
+		<h3>[name]( audio, [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize fftSize] )</h3>
+		<div>
+		Create a new [page:AudioAnalyser AudioAnalyser].
+		</div>
+
+
+		<h2>Properties</h2>
+
+		<h3>[property:AnalyserNode analyser]</h3>
+		<div>An [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode AnalyserNode] used to analyze audio.</div>
+
+		<h3>[property:Integer fftSize]</h3>
+		<div>
+		A non-zero power of two up to 2048, representing the size of the FFT (Fast Fourier Transform) to be used to determine the frequency domain.<br />
+		See [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize this page] for details.
+		</div>
+
+		<h3>[property:Uint8Array data]</h3>
+		<div>
+		A Uint8Array with size determined by [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/frequencyBinCount analyser.frequencyBinCount]
+		used to hold analysis data.
+		</div>
+
+
+		<h2>Methods</h2>
+
+
+		<h3>[method:Uint8Array getFrequencyData]()</h3>
+		<div>
+		Uses the Web Audio's [link:https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData getByteFrequencyData] method.
+		See that page.
+		</div>
+
+		<h3>[method:Number getAverageFrequency]()</h3>
+		<div>
+		Get the average of the frequencies returned by the [page:AudioAnalyser.getFrequencyData getFrequencyData] method.
+		</div>
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

+ 42 - 0
docs/api/audio/AudioContext.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+		This contains methods for setting up an [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext AudioContext].<br /><br />
+
+		Used internally by the [page:AudioListener AudioListener] and [page:AudioLoader AudioLoader] classes.<br /><br />
+
+		This uses the [link:https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API Web Audio API].
+		</div>
+
+
+
+		<h2>Methods</h2>
+
+		<h3>[method:AudioContext getContext]()</h3>
+		<div>
+		Return the value of the variable *context* in the outer scope, if defined,
+		otherwise set it to a new [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext AudioContext].
+		</div>
+
+		<h3>[method:AudioContext setContext]( [page:AudioConetxt value] )</h3>
+		<div>
+		 Set the variable *context* in the outer scope to *value*.
+		</div>
+
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

+ 107 - 0
docs/api/audio/AudioListener.html

@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Object3D] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+			Create a non-positional ( global ) audio object.<br /><br />
+
+			This uses the [link:https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API Web Audio API].
+
+		</div>
+
+
+		<h2>Example</h2>
+
+		<div>[example:misc_sound misc / sound ]</div>
+		<code>
+		//Create an AudioListener and add it to the camera
+		var listener = new THREE.AudioListener();
+		camera.add( listener );
+
+		// create a global audio source
+		var sound = new THREE.Audio( listener );
+
+		var audioLoader = new THREE.AudioLoader();
+
+		//Load a sound and set it as the Audio object's buffer
+		audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
+			sound.setBuffer( buffer );
+			sound.setLoop(true);
+			sound.setVolume(0.5);
+			sound.play();
+		});
+		</code>
+
+
+		<h2>Constructor</h2>
+
+
+		<h3>[name](  )</h3>
+		<div>
+		Create a new AudioListener.
+		</div>
+
+
+		<h2>Properties</h2>
+
+		<h3>[property:AudioContext context]</h3>
+		<div>The [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext AudioContext] of the [page:AudioListener listener] given in the constructor.</div>
+
+		<h3>[property:GainNode gain]</h3>
+		<div>A [link:https://developer.mozilla.org/en-US/docs/Web/API/GainNode GainNode] created
+		using [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain AudioContext.createGain]().</div>
+		</div>
+
+		<h3>[property:AudioNode filter]</h3>
+		<div>Default is *null*.</div>
+
+
+		<h2>Methods</h2>
+
+
+		<h3>[method:GainNode getInput]()</h3>
+		<div>
+		Return the [page:AudioListener.gain gainNode].
+		</div>
+
+		<h3>[method:null removeFilter]()</h3>
+		<div>
+		Set the [page:AudioListener.filter filter] property to *null*.
+		</div>
+
+		<h3>[method:AudioNode getFilter]()</h3>
+		<div>
+		Returns the value of the [page:AudioListener.filter filter] property.
+		</div>
+
+		<h3>[method:null setFilter]( [page:AudioNode value] )</h3>
+		<div>
+		Set the [page:AudioListener.filter filter] property to *value*.
+		</div>
+
+		<h3>[method:Number getMasterVolume]()</h3>
+		<div>
+		Return the volume.
+		</div>
+
+		<h3>[method:null getMasterVolume]( [page:Number value] )</h3>
+		<div>
+		Set the volume.
+		</div>
+
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

+ 125 - 0
docs/api/audio/PositionalAudio.html

@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Object3D] &rarr; [page:Audio] &rarr;
+
+		<h1>[name]</h1>
+
+		<div class="desc">
+			Create a positional audio object.<br /><br />
+
+			This uses the [link:https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API Web Audio API].
+		</div>
+
+
+		<h2>Example</h2>
+
+		<div>[example:misc_sound misc / sound ]</div>
+		<code>
+		//Create an AudioListener and add it to the camera
+		var listener = new THREE.AudioListener();
+		camera.add( listener );
+
+		//Create the PositionalAudio object (passing in the listener)
+		var sound = new THREE.PositionalAudio( listener );
+
+		//Load a sound and set it as the PositionalAudio object's buffer
+		var audioLoader = new THREE.AudioLoader();
+		audioLoader.load( 'sounds/song.ogg', function( buffer ) {
+			sound1.setBuffer( buffer );
+			sound1.setRefDistance( 20 );
+			sound1.play();
+		});
+
+		//Create an object for the sound to play from
+		var sphere = new THREE.SphereGeometry( 20, 32, 16 );
+		var material = new THREE.MeshPhongMaterial( { color: 0xff2200 } );
+		var mesh = new THREE.Mesh( sphere, material );
+		scene.add( mesh );
+
+		//Finally add the sound to the mesh
+		mesh.add( sound );
+		</code>
+
+
+		<h2>Constructor</h2>
+
+		<h3>[name]( [page:AudioListener listener] )</h3>
+		<div>
+		listener — (required) [page:AudioListener AudioListener] instance.
+		</div>
+
+
+		<h2>Properties</h2>
+
+		<div>
+			See the [page:Audio Audio] class for inherited properties.
+		</div>
+
+		<h3>[property:PannerNode panner]</h3>
+		<div>The PositionalAudio's [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode PannerNode].</div>
+
+
+		<h2>Methods</h2>
+
+		<div>
+			See the [page:Audio Audio] class for inherited methods.
+		</div>
+
+		<h3>[method:PannerNode getOutput]()</h3>
+		<div>
+		Returns the [page:PositionalAudio.panner panner].
+		</div>
+
+		<h3>[method:Number getRefDistance]()</h3>
+		<div>
+		Returns the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/refDistance panner.refDistance].
+		</div>
+
+		<h3>[method:PannerNode setRefDistance]( [page:Number value] )</h3>
+		<div>
+		Sets the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/refDistance panner.refDistance].
+		</div>
+
+		<h3>[method:PannerNode getRolloffFactor]()</h3>
+		<div>
+		Returns the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/rolloffFactor panner.rolloffFactor].
+		</div>
+
+		<h3>[method:PannerNode setRolloffFactor]( [page:Number value] )</h3>
+		<div>
+		Sets the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/rolloffFactor panner.rolloffFactor].
+		</div>
+
+		<h3>[method:String getDistanceModel]()</h3>
+		<div>
+		Returns the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel panner.distanceModel].
+		</div>
+
+		<h3>[method:String setDistanceModel]( [page:String value] )</h3>
+		<div>
+		Sets the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel panner.distanceModel].
+		</div>
+
+		<h3>[method:PannerNode getMaxDistance]()</h3>
+		<div>
+		Returns the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/maxDistance panner.distanceModel].
+		</div>
+
+		<h3>[method:PannerNode setMaxDistance]( [page:Number value] )</h3>
+		<div>
+		Sets the value of [link:https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/maxDistance panner.distanceModel].
+		</div>
+
+		<h2>Source</h2>
+
+		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	</body>
+</html>

+ 8 - 0
docs/list.js

@@ -8,6 +8,14 @@ var list = {
 	},
 	},
 
 
 	"Reference": {
 	"Reference": {
+		"Audio": [
+			[ "Audio", "api/audio/Audio" ],
+			[ "AudioAnalyser", "api/audio/AudioAnalyser" ],
+			[ "AudioContext", "api/audio/AudioContext" ],
+			[ "AudioListener", "api/audio/AudioListener" ],
+			[ "PositionalAudio", "api/audio/PositionalAudio" ]
+		],
+
 		"Constants": [
 		"Constants": [
 			[ "Animation", "api/constants/Animation" ],
 			[ "Animation", "api/constants/Animation" ],
 			[ "CustomBlendingEquation", "api/constants/CustomBlendingEquations" ],
 			[ "CustomBlendingEquation", "api/constants/CustomBlendingEquations" ],