Added all comments for streaming audio. Added global volume setting. …

…Updated doc files.
finnkuusisto · Aug 21, 2012 · dc780ba · dc780ba
1 parent fb8330b
commit dc780ba
Show file tree

Hide file tree

Showing 40 changed files with 1,012 additions and 526 deletions.
diff --git a/README b/README
@@ -61,6 +61,18 @@ When a Sound is played it is queued to be played from the speakers once.  Of
 course, you can play a Sound multiple times in an overlapping fashion so it is
 generally useful for sound effects.  See the Javadocs for more detail.
 
+Memory Usage
+------------
+The basic loading functions for Music and Sound objects produce implementations
+that store all audio data in memory.  This is good for maintaining low latency,
+but can also require a lot of heap space if you load many, or particularly long,
+audio resources.  There are loading functions available that allow you to
+request that the audio data be streamed from a file.  If this is requested, the
+audio data will first be converted as usual and then written to a temporary file
+from which it will be streamed.  This will dramatically reduce the overall
+memory usage (after loading), but can potentially introduce occasional latency
+when reading from disk.
+
 Example
 -------
 There is a very simple example provided in the example directory.  You'll need

diff --git a/doc/allclasses-frame.html b/doc/allclasses-frame.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:50 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 All Classes
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
 

diff --git a/doc/allclasses-noframe.html b/doc/allclasses-noframe.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:50 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 All Classes
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
 

diff --git a/doc/constant-values.html b/doc/constant-values.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:50 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 Constant Field Values
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
 

diff --git a/doc/deprecated-list.html b/doc/deprecated-list.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:50 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 Deprecated List
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
 

diff --git a/doc/help-doc.html b/doc/help-doc.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:50 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 API Help
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
 

diff --git a/doc/index-all.html b/doc/index-all.html
diff --git a/doc/index.html b/doc/index.html
@@ -2,7 +2,7 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc on Sun Aug 12 21:55:50 CDT 2012-->
+<!-- Generated by javadoc on Mon Aug 20 21:31:05 CDT 2012-->
 <TITLE>
 Generated Documentation (Untitled)
 </TITLE>

diff --git a/doc/kuusisto/tinysound/Music.html b/doc/kuusisto/tinysound/Music.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:49 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:04 CDT 2012 -->
 <TITLE>
 Music
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
 

diff --git a/doc/kuusisto/tinysound/Sound.html b/doc/kuusisto/tinysound/Sound.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:49 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 Sound
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
 

diff --git a/doc/kuusisto/tinysound/TinySound.html b/doc/kuusisto/tinysound/TinySound.html
@@ -2,12 +2,12 @@
 <!--NewPage-->
 <HTML>
 <HEAD>
-<!-- Generated by javadoc (build 1.6.0_11) on Sun Aug 12 21:55:49 CDT 2012 -->
+<!-- Generated by javadoc (build 1.6.0_11) on Mon Aug 20 21:31:05 CDT 2012 -->
 <TITLE>
 TinySound
 </TITLE>
 
-<META NAME="date" CONTENT="2012-08-12">
+<META NAME="date" CONTENT="2012-08-20">
 
 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
 
@@ -158,6 +158,14 @@ <H2>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE>static&nbsp;double</CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../kuusisto/tinysound/TinySound.html#getGlobalVolume()">getGlobalVolume</A></B>()</CODE>
+
+<BR>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Get the global volume for all audio.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>static&nbsp;void</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../kuusisto/tinysound/TinySound.html#init()">init</A></B>()</CODE>
 
@@ -196,7 +204,7 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Music by a File.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -213,7 +221,7 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Music by a resource name.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -230,7 +238,7 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Music by a URL.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -247,7 +255,7 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Sound by a File.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -264,7 +272,7 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Sound by a resource name.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -281,7 +289,15 @@ <H2>
           boolean&nbsp;streamFromFile)</CODE>
 
 <BR>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Load a Sound by a URL.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE>static&nbsp;void</CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../kuusisto/tinysound/TinySound.html#setGlobalVolume(double)">setGlobalVolume</A></B>(double&nbsp;volume)</CODE>
+
+<BR>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set the global volume.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -418,13 +434,42 @@ <H2>
 </DL>
 <HR>
 
+<A NAME="getGlobalVolume()"><!-- --></A><H3>
+getGlobalVolume</H3>
+<PRE>
+public static double <B>getGlobalVolume</B>()</PRE>
+<DL>
+<DD>Get the global volume for all audio.
+<P>
+<DD><DL>
+
+<DT><B>Returns:</B><DD>the global volume for all audio, -1.0 if TinySound has not been
+ initialized or has subsequently been shutdown</DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="setGlobalVolume(double)"><!-- --></A><H3>
+setGlobalVolume</H3>
+<PRE>
+public static void <B>setGlobalVolume</B>(double&nbsp;volume)</PRE>
+<DL>
+<DD>Set the global volume.  This is an extra multiplier, not a replacement,
+ for all Music and Sound volume settings.  It starts at 1.0.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>volume</CODE> - the global volume to set</DL>
+</DD>
+</DL>
+<HR>
+
 <A NAME="loadMusic(java.lang.String)"><!-- --></A><H3>
 loadMusic</H3>
 <PRE>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>&nbsp;name)</PRE>
 <DL>
 <DD>Load a Music by a resource name.  The resource must be on the classpath
- for this to work.
+ for this to work.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the Music resource
@@ -439,8 +484,13 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>&nbsp;name,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Music by a resource name.  The resource must be on the classpath
+ for this to work.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the Music resource<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Music resource as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <HR>
@@ -450,7 +500,7 @@ <H2>
 <PRE>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/io/File.html?is-external=true" title="class or interface in java.io">File</A>&nbsp;file)</PRE>
 <DL>
-<DD>Load a Music by a File.
+<DD>Load a Music by a File.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>file</CODE> - the Music file to load
@@ -465,8 +515,12 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/io/File.html?is-external=true" title="class or interface in java.io">File</A>&nbsp;file,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Music by a File.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>file</CODE> - the Music file to load<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Music from file as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <HR>
@@ -476,7 +530,7 @@ <H2>
 <PRE>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/net/URL.html?is-external=true" title="class or interface in java.net">URL</A>&nbsp;url)</PRE>
 <DL>
-<DD>Load a Music by a URL.
+<DD>Load a Music by a URL.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>url</CODE> - the URL of the Music
@@ -491,8 +545,12 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Music.html" title="interface in kuusisto.tinysound">Music</A> <B>loadMusic</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/net/URL.html?is-external=true" title="class or interface in java.net">URL</A>&nbsp;url,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Music by a URL.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>url</CODE> - the URL of the Music<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Music from URL as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <HR>
@@ -503,7 +561,7 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>&nbsp;name)</PRE>
 <DL>
 <DD>Load a Sound by a resource name.  The resource must be on the classpath
- for this to work.
+ for this to work.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the Sound resource
@@ -518,8 +576,13 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</A>&nbsp;name,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Sound by a resource name.  The resource must be on the classpath
+ for this to work.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the Sound resource<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Sound resource as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <HR>
@@ -529,7 +592,7 @@ <H2>
 <PRE>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/io/File.html?is-external=true" title="class or interface in java.io">File</A>&nbsp;file)</PRE>
 <DL>
-<DD>Load a Sound by a File.
+<DD>Load a Sound by a File.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>file</CODE> - the Sound file to load
@@ -544,8 +607,12 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/io/File.html?is-external=true" title="class or interface in java.io">File</A>&nbsp;file,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Sound by a File.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>file</CODE> - the Sound file to load<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Sound from file as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <HR>
@@ -555,7 +622,7 @@ <H2>
 <PRE>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/net/URL.html?is-external=true" title="class or interface in java.net">URL</A>&nbsp;url)</PRE>
 <DL>
-<DD>Load a Sound by a URL.
+<DD>Load a Sound by a URL.  This will store audio data in memory.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>url</CODE> - the URL of the Sound
@@ -570,8 +637,12 @@ <H2>
 public static <A HREF="../../kuusisto/tinysound/Sound.html" title="interface in kuusisto.tinysound">Sound</A> <B>loadSound</B>(<A HREF="http://docs.oracle.com/javase/7/docs/api/java/net/URL.html?is-external=true" title="class or interface in java.net">URL</A>&nbsp;url,
                               boolean&nbsp;streamFromFile)</PRE>
 <DL>
+<DD>Load a Sound by a URL.  This will store audio data in memory.
+<P>
 <DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>url</CODE> - the URL of the Sound<DD><CODE>streamFromFile</CODE> - true if this Music should be streamed from a
+ temporary file to reduce memory overhead
+<DT><B>Returns:</B><DD>Sound from URL as specified, null if not found/loaded</DL>
 </DD>
 </DL>
 <!-- ========= END OF CLASS DATA ========= -->