Merge branch 'master' of github.com:zeh/usfxr

Author: zeh

README.md

@@ -3,21 +3,19 @@ usfxr
 
 usfxr is a C# library used to generate game-like procedural audio effects inside Unity. With usfxr, one can easily synthesize sound in real time for actions such as item pickups, jumps, lasers, hits, explosions, and more.
 
-It also included an in-editor window to easily generate and test sounds inside Unity.
-
 usfxr is a port of Thomas Vian's [as3sfxr](https://code.google.com/p/as3sfxr/), which itself is an ActionScript 3 port of Tomas Pettersson's [sfxr](http://www.drpetter.se/project_sfxr.html).
 
 [This video](https://vimeo.com/15769163) explains the ideas behind as3sfxr, and the ideas that I want to support with usfxr.
 
-Despite my name not being Thomas or a variant of it, I found myself wishing for a (free) library to procedurally generate audio inside Unity in real time, and usfxr is the result.
+Despite my name not being Thomas or a variant of it, I found myself wishing for a (free) library to procedurally generate audio inside Unity in real time, and usfxr is the result. Since it is a Unity project, usfxr also includes an in-editor window to easily generate and test sounds without leaving the Unity.
 
 
 Introduction
 ------------
 
-First things first: if you're just looking for a few good 16 bit-style sound effects to use in games, anyone can use sound files generated by [the original sfxr](http://www.drpetter.se/project_sfxr.html) or [as3sfxr's online version](http://www.superflashbros.net/as3sfxr/) without any changes, since both applications generate ready-to-be-used audio files.
+First things first: if you're just looking for a few good (but static) 16 bit-style sound effects to use in games, anyone can use sound files generated by [the original sfxr](http://www.drpetter.se/project_sfxr.html) or [as3sfxr's online version](http://www.superflashbros.net/as3sfxr/) without any changes, since both applications generate ready-to-be-used audio files.
 
-However, by using a runtime library like usfxr, you can generate the same audio samples in real time, or re-synthesize effects generated in any of those tools by using a small list of parameters (a short string). The advantages of this approach are twofold:
+However, by using a runtime library like usfxr, you can generate the same audio samples in real time, or re-synthesize effects generated in any of those tools by using a small list of parameters (encoded as a short string). The advantages of this approach are twofold:
 
 * Audio is generated in real time; there's no storage of audio files as assets necessary, making compiled project sizes smaller
 * Easily play variations of every sound you play; adds more flavor to the gameplay experience
@@ -28,12 +26,12 @@ I make no claims in regards to the source code or interface, since it was simply
 * Ability to cache sounds the first time they're played
 * Completely asynchronous caching and playback: sound is generated on a separate, non-blocking thread with minimal impact on gameplay
 * Minimal setup: as a full code-based solution, no drag-and-drop or additional game object placement is necessary
-
+* In-editor interface to test and generate audio parameters
 
 Installation
 ------------
 
-Download the latest "usfxr" zip file from the "/build" folder of the GitHub repository and extract the contents of this file into the "Scripts" (or equivalent) folder of your Unity project.
+Download the latest "usfxr" zip file from the "/build" folder of the GitHub repository and extract the contents of this file into the "Scripts" (or equivalent) folder of your Unity project. After doing that, you should have the usfxr interface available inside Unity, as well as being able to instantiate and play SfxrSyth objects inside your project.
 
 
 Usage
@@ -42,8 +40,14 @@ Usage
 Typically, the workflow for using usfxr inside a project is as such:
 
 1. Use the menu "Window" > "Generate usfxr Sound Effects" to open the sound effects window
+
+ [<img src="http://hosted.zehfernando.com/ludumdare/usfxr/images/usfxr_img1.png" width="220" height="268">](http://hosted.zehfernando.com/ludumdare/usfxr/images/usfxr_img1.png)
+
 2. Play around with the sound parameters until you generate a sound effect that you want to use
-3. Click "COPY" to copy the effect to the clipboard (as a string)
+
+ [<img src="http://hosted.zehfernando.com/ludumdare/usfxr/images/usfxr_img2a.png" width="233" height="223">](http://hosted.zehfernando.com/ludumdare/usfxr/images/usfxr_img2.png)
+
+3. Click "COPY" to copy the effect parameters to the clipboard (as a string)
 4. Write some code to store your sound effect, pasting the correct string
 
 <!-- hack to allow code formatting -->
@@ -55,13 +59,13 @@ Finally, to play your audio effect, you call its `Play()` method where appropria
 
 	synth.Play();
 
-With usfxr, all audio data is generated the first time an effect is played. That way, any potential heavy load in generating audio doesn't have to be repeated the next time the sound is played, since it will already be cached.
+With usfxr, all audio data is generated and cached internally the first time an effect is played, in real time. That way, any potential heavy load in generating audio doesn't have to be repeated the next time the sound is played, since it will already be in memory.
 
 Because of that, while it's possible to generate new SfxrSynth instances every time they need to be played, it's usually a better idea to keep them around and reuse them as needed.
 
-It's also important to notice that audio data generation does not occur all at once. This is a good thing: the audio data is generated as necessary, before playback of each 20ms chunk (more or less), so long audio effects won't take a lot of time to be generated. Audio is also generated on a separate thread, so impact on actual game execution should be minimal. Check [`OnAudioFilterRead`](http://docs.unity3d.com/Documentation/ScriptReference/MonoBehaviour.OnAudioFilterRead.html) for more details.
+It's also important to notice that audio data generation does not occur all at once. This is a good thing: the audio data is generated as necessary, in batches, before playback of each 20ms chunk (more or less), so long audio effects won't take a lot of time to be generated. Audio is also generated on a separate thread, so impact on actual game execution should be minimal. Check [`OnAudioFilterRead`](http://docs.unity3d.com/Documentation/ScriptReference/MonoBehaviour.OnAudioFilterRead.html) for more details on how this happens.
 
-Notice that, alternatively, you can also use the [online version of as3sfxr](http://www.superflashbros.net/as3sfxr/) to generate the sound string. Strings generated by as3sfxr use the same format as usfxr.
+Notice that, alternatively, you can also use the [online version of as3sfxr](http://www.superflashbros.net/as3sfxr/) to generate the parameter string that can be used when creating SfxrSynth instances. Strings generated by as3sfxr use the same format as usfxr so they're interchangeable.
 
 #### Advanced usage: caching
 
@@ -81,9 +85,9 @@ This caches the audio synchronously, that is, code execution is interrupted unti
 
 In the above case, the `CacheSound()` method will immediately return, and audio start to be generated in parallel with other code (as a coroutine). When the audio is cached, the callback function (`Play()`, in this case) will be called.
 
-As a reference, it typically takes around 7ms-70ms for an audio effect to be cached on a desktop computer, depending on its length and complexity. Therefore, sometimes it's better to let the game cache audio as it's played, or to stack the caching of all audio in the beginning of the gameplay, such as before a level starts.
+As a reference, it typically takes around 7ms-70ms for an audio effect to be cached on a desktop, depending on its length and complexity. Therefore, sometimes it's better to let the game cache audio as it's played, or to stack the caching of all audio in the beginning of the gameplay, such as before a level starts.
 
-An important notice when comparing to as3sfxr: the ActionScript 3 virtual machine doesn't normally support multi-threading, or parallel execution of code. Because of this, the asynchronous caching methods of as3sfxr are somewhat different from what is adopted with usfxr, since Unity does execute code in parallel (through [Coroutines](http://docs.unity3d.com/Documentation//ScriptReference/index.Coroutines_26_Yield.html) or in a separate thread entirely (through [`OnAudioFilterRead`](http://docs.unity3d.com/Documentation/ScriptReference/MonoBehaviour.OnAudioFilterRead.html)). As such, the caching strategy on Unity normally won't have to be as robust as an ActionScript 3 project; in the vast majority of the cases, it's better to ignore caching altogether and let the library handle it itself.
+An important notice when comparing to as3sfxr: the ActionScript 3 virtual machine doesn't normally support multi-threading, or parallel execution of code. Because of this, the asynchronous caching methods of as3sfxr are somewhat different from what is adopted with usfxr, since Unity does execute code in parallel (through [Coroutines](http://docs.unity3d.com/Documentation//ScriptReference/index.Coroutines_26_Yield.html) or in a separate thread entirely (through [`OnAudioFilterRead`](http://docs.unity3d.com/Documentation/ScriptReference/MonoBehaviour.OnAudioFilterRead.html)). As such, your caching strategy on Unity normally won't have to be as robust as an ActionScript 3 project; in the vast majority of the cases, it's better to ignore caching altogether and let the library handle it itself by using `Play()` with no custom caching calls.
 
 
 #### Advanced usage: setting the audio position