SyncedStream optimization: Allow streams to be reused within one stream graph without recomputation

 * Since it comes with an overhead, it has to be enabled by constructing a SyncedStream
   or calling Stream:sync()
 * Reusing samples works by sharing generator functions and caching samples until a clock signal changes.
   The clock signal is currently a global variable "clock_signal" that oscillates between
   true and false.
 * This means that all sample generating methods like :play() or :totable() will have
   to advance the clock using the global clockCycle() function.
   It is a global function, so it can be invoked more or less efficiently by the :play()
   implementation (currently using the old-school Lua/C API).
   These restrictions might fall when using the LuaJIT way of interacting with
   native code.
 * Since playback must begin from the beginning for every :play(), an explicit reset()
   mechanism has been introduced which can usually be ignored in Stream implementations.
   It does however allow SyncedStream to reset the generator closure.
 * SndfileStream has been simplified since now it is possible to keep the file handle
   open. However as long as Stream synchronization is not automatic, SndfileStreams must
   be explicitly synced when using one stream multiple times.
 * Syncing is thought to be performed automatically by an optimizer when one object
   is used more than once e.g. in a :play() call.
 * Non-synced streams are currently slightly slower than before this commit,
   probably because of the additional clockCycle() call.

1 files changed, 15 insertions, 0 deletions

diff --git a/sndfile.lua b/sndfile.lua
index 263893d..47ea1ff 100644
--- a/sndfile.lua
+++ b/sndfile.lua
@@ -104,7 +104,17 @@ typedef enum SF_MODE {
         SFM_RDWR        = 0x30
 } SF_MODE;
 
+/* These values come from stdio.h */
+typedef enum SF_SEEK {
+	SEEK_SET = 0,
+	SEEK_CUR = 1,
+	SEEK_END = 2
+} SF_SEEK;
+
 SNDFILE* sf_open(const char *path, int mode, SF_INFO *sfinfo);
+
+sf_count_t sf_seek(SNDFILE *sndfile, sf_count_t frames, int whence);
+
 const char* sf_strerror(SNDFILE *sndfile);
 
 int sf_command(SNDFILE *sndfile, int command, void *data, int datasize);
@@ -175,6 +185,11 @@ function sndfile:new(path, mode, samplerate, channels, format)
 	return obj
 end
 
+function sndfile:seek(frames, whence)
+	whence = whence and ffi.new("SF_SEEK", whence) or ffi.C.SEEK_SET
+	return lib.sf_seek(self.handle, frames, whence)
+end
+
 -- TODO: Maybe support reading multiple samples at once.
 function sndfile:read()
 	return lib.sf_read_double(self.handle, double_buffer, 1) == 1 and