e1lama/stk
1
0
Fork 0
mirror of https://github.com/thestk/stk synced 2026-01-13 21:11:53 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c92cf7468de55276abcd2f7597f321708976295b
stk/doc/html/classFileWvIn.html
Gary Scavone 1a8403e203 Release 4.3.0 tarball
2013-09-29 23:41:50 +02:00

384 lines
19 KiB
HTML
Raw Blame History

<HTML>
<HEAD>
<TITLE>The Synthesis ToolKit in C++ (STK)</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>
<img src="princeton.gif"> &nbsp; <img src="ccrma.gif"> &nbsp; <img src="mcgill.gif"><P>
<a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="information.html">Information</a> &nbsp; <a class="qindex" href="classes.html">Classes</a> &nbsp; <a class="qindex" href="download.html">Download</a> &nbsp; <a class="qindex" href="usage.html">Usage</a> &nbsp; <a class="qindex" href="maillist.html">Mail List</a> &nbsp; <a class="qindex" href="system.html">Requirements</a> &nbsp; <a class="qindex" href="links.html">Links</a> &nbsp; <a class="qindex" href="faq.html">FAQ</a> &nbsp; <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
<HR>
<!-- Generated by Doxygen 1.4.4 -->
<h1>FileWvIn Class Reference</h1><!-- doxytag: class="FileWvIn" --><!-- doxytag: inherits="WvIn" --><code>#include &lt;<a class="el" href="FileWvIn_8h-source.html">FileWvIn.h</a>&gt;</code>
<p>
<p>Inheritance diagram for FileWvIn:
<p><center><img src="classFileWvIn.png" usemap="#FileWvIn_map" border="0" alt=""></center>
<map name="FileWvIn_map">
<area href="classWvIn.html" alt="WvIn" shape="rect" coords="0,56,72,80">
<area href="classStk.html" alt="Stk" shape="rect" coords="0,0,72,24">
<area href="classWaveLoop.html" alt="WaveLoop" shape="rect" coords="0,168,72,192">
</map>
<a href="classFileWvIn-members.html">List of all members.</a><hr><a name="_details"></a><h2>Detailed Description</h2>
STK audio file input class.
<p>
This class inherits from <a class="el" href="classWvIn.html">WvIn</a>. It provides a "tick-level" interface to the <a class="el" href="classFileRead.html">FileRead</a> class. It also provides variable-rate "playback" functionality. Audio file support is provided by the <a class="el" href="classFileRead.html">FileRead</a> class. Linear interpolation is used for fractional "read rates".<p>
FileWvIn supports multi-channel data. It is important to distinguish the <a class="el" href="classWvIn.html#a5">tick()</a> methods, which return samples produced by averaging across sample frames, from the <a class="el" href="classWvIn.html#a7">tickFrame()</a> methods, which return references to multi-channel sample frames.<p>
FileWvIn will either load the entire content of an audio file into local memory or incrementally read file data from disk in chunks. This behavior is controlled by the optional constructor arguments <em>chunkThreshold</em> and <em>chunkSize</em>. File sizes greater than <em>chunkThreshold</em> (in sample frames) will be read incrementally in chunks of <em>chunkSize</em> each (also in sample frames).<p>
When the file end is reached, subsequent calls to the <a class="el" href="classWvIn.html#a5">tick()</a> functions return zero-valued data and <a class="el" href="classFileWvIn.html#a10">isFinished()</a> returns <em>true</em>.<p>
See the <a class="el" href="classFileRead.html">FileRead</a> class for a description of the supported audio file formats.<p>
by Perry R. Cook and Gary P. Scavone, 1995 - 2007.
<p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a0"></a><!-- doxytag: member="FileWvIn::FileWvIn" ref="a0" args="(unsigned long chunkThreshold=1000000, unsigned long chunkSize=1024)" -->
&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a0">FileWvIn</a> (unsigned long chunkThreshold=1000000, unsigned long chunkSize=1024)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Default constructor. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a1">FileWvIn</a> (std::string fileName, bool raw=false, bool doNormalize=true, unsigned long chunkThreshold=1000000, unsigned long chunkSize=1024)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Overloaded constructor for file input. <a href="#a1"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a2"></a><!-- doxytag: member="FileWvIn::~FileWvIn" ref="a2" args="()" -->
virtual&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a2">~FileWvIn</a> ()</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Class destructor. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a3">openFile</a> (std::string fileName, bool raw=false, bool doNormalize=true)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Open the specified file and load its data. <a href="#a3"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a4"></a><!-- doxytag: member="FileWvIn::closeFile" ref="a4" args="(void)" -->
void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a4">closeFile</a> (void)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Close a file if one is open. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a5"></a><!-- doxytag: member="FileWvIn::reset" ref="a5" args="(void)" -->
void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a5">reset</a> (void)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Clear outputs and reset time (file) pointer to zero. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a6">normalize</a> (void)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Normalize data to a maximum of +-1.0. <a href="#a6"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a7">normalize</a> (StkFloat peak)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Normalize data to a maximum of <em>+-peak</em>. <a href="#a7"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a8"></a><!-- doxytag: member="FileWvIn::getSize" ref="a8" args="(void) const " -->
unsigned long&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a8">getSize</a> (void) const </td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Return the file size in sample frames. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">StkFloat&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a9">getFileRate</a> (void) const </td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Return the input file sample rate in Hz (not the data read rate). <a href="#a9"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="a10"></a><!-- doxytag: member="FileWvIn::isFinished" ref="a10" args="(void) const " -->
bool&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a10">isFinished</a> (void) const </td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Query whether reading is complete. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a11">setRate</a> (StkFloat rate)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Set the data read rate in samples. The rate can be negative. <a href="#a11"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">virtual void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a12">addTime</a> (StkFloat time)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Increment the read pointer by <em>time</em> samples. <a href="#a12"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classFileWvIn.html#a13">setInterpolate</a> (bool doInterpolate)</td></tr>
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Turn linear interpolation on/off. <a href="#a13"></a><br></td></tr>
</table>
<hr><h2>Constructor &amp; Destructor Documentation</h2>
<a class="anchor" name="a1"></a><!-- doxytag: member="FileWvIn::FileWvIn" ref="a1" args="(std::string fileName, bool raw=false, bool doNormalize=true, unsigned long chunkThreshold=1000000, unsigned long chunkSize=1024)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">FileWvIn::FileWvIn </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">std::string&nbsp;</td>
<td class="mdname" nowrap> <em>fileName</em>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>bool&nbsp;</td>
<td class="mdname" nowrap> <em>raw</em> = <code>false</code>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>bool&nbsp;</td>
<td class="mdname" nowrap> <em>doNormalize</em> = <code>true</code>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>unsigned long&nbsp;</td>
<td class="mdname" nowrap> <em>chunkThreshold</em> = <code>1000000</code>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>unsigned long&nbsp;</td>
<td class="mdname" nowrap> <em>chunkSize</em> = <code>1024</code></td>
</tr>
<tr>
<td class="md"></td>
<td class="md">)&nbsp;</td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Overloaded constructor for file input.
<p>
An <a class="el" href="classStkError.html">StkError</a> will be thrown if the file is not found, its format is unknown, or a read error occurs. </td>
</tr>
</table>
<hr><h2>Member Function Documentation</h2>
<a class="anchor" name="a3"></a><!-- doxytag: member="FileWvIn::openFile" ref="a3" args="(std::string fileName, bool raw=false, bool doNormalize=true)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">void FileWvIn::openFile </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">std::string&nbsp;</td>
<td class="mdname" nowrap> <em>fileName</em>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>bool&nbsp;</td>
<td class="mdname" nowrap> <em>raw</em> = <code>false</code>, </td>
</tr>
<tr>
<td class="md" nowrap align="right"></td>
<td class="md"></td>
<td class="md" nowrap>bool&nbsp;</td>
<td class="mdname" nowrap> <em>doNormalize</em> = <code>true</code></td>
</tr>
<tr>
<td class="md"></td>
<td class="md">)&nbsp;</td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Open the specified file and load its data.
<p>
Data from a previously opened file will be overwritten by this function. An <a class="el" href="classStkError.html">StkError</a> will be thrown if the file is not found, its format is unknown, or a read error occurs. If the file data is to be loaded incrementally from disk and normalization is specified, a scaling will be applied with respect to fixed-point limits. If the data format is floating-point, no scaling is performed.
<p>
Reimplemented in <a class="el" href="classWaveLoop.html#a3">WaveLoop</a>. </td>
</tr>
</table>
<a class="anchor" name="a6"></a><!-- doxytag: member="FileWvIn::normalize" ref="a6" args="(void)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">void FileWvIn::normalize </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">void&nbsp;</td>
<td class="mdname1" valign="top" nowrap> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Normalize data to a maximum of +-1.0.
<p>
This function has no effect when data is incrementally loaded from disk. </td>
</tr>
</table>
<a class="anchor" name="a7"></a><!-- doxytag: member="FileWvIn::normalize" ref="a7" args="(StkFloat peak)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">void FileWvIn::normalize </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">StkFloat&nbsp;</td>
<td class="mdname1" valign="top" nowrap> <em>peak</em> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Normalize data to a maximum of <em>+-peak</em>.
<p>
This function has no effect when data is incrementally loaded from disk. </td>
</tr>
</table>
<a class="anchor" name="a9"></a><!-- doxytag: member="FileWvIn::getFileRate" ref="a9" args="(void) const " --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">StkFloat FileWvIn::getFileRate </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">void&nbsp;</td>
<td class="mdname1" valign="top" nowrap> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap> const<code> [inline]</code></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Return the input file sample rate in Hz (not the data read rate).
<p>
WAV, SND, and AIF formatted files specify a sample rate in their headers. STK RAW files have a sample rate of 22050 Hz by definition. MAT-files are assumed to have a rate of 44100 Hz. </td>
</tr>
</table>
<a class="anchor" name="a11"></a><!-- doxytag: member="FileWvIn::setRate" ref="a11" args="(StkFloat rate)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">void FileWvIn::setRate </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">StkFloat&nbsp;</td>
<td class="mdname1" valign="top" nowrap> <em>rate</em> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Set the data read rate in samples. The rate can be negative.
<p>
If the rate value is negative, the data is read in reverse order.
<p>
Reimplemented in <a class="el" href="classWaveLoop.html#a4">WaveLoop</a>. </td>
</tr>
</table>
<a class="anchor" name="a12"></a><!-- doxytag: member="FileWvIn::addTime" ref="a12" args="(StkFloat time)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">virtual void FileWvIn::addTime </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">StkFloat&nbsp;</td>
<td class="mdname1" valign="top" nowrap> <em>time</em> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap><code> [virtual]</code></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Increment the read pointer by <em>time</em> samples.
<p>
Note that this function will not modify the interpolation flag status.
<p>
Reimplemented in <a class="el" href="classWaveLoop.html#a6">WaveLoop</a>. </td>
</tr>
</table>
<a class="anchor" name="a13"></a><!-- doxytag: member="FileWvIn::setInterpolate" ref="a13" args="(bool doInterpolate)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
<tr>
<td class="mdRow">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top">void FileWvIn::setInterpolate </td>
<td class="md" valign="top">(&nbsp;</td>
<td class="md" nowrap valign="top">bool&nbsp;</td>
<td class="mdname1" valign="top" nowrap> <em>doInterpolate</em> </td>
<td class="md" valign="top">&nbsp;)&nbsp;</td>
<td class="md" nowrap><code> [inline]</code></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
<tr>
<td>
&nbsp;
</td>
<td>
<p>
Turn linear interpolation on/off.
<p>
Interpolation is automatically off when the read rate is an integer value. If interpolation is turned off for a fractional rate, the time index is truncated to an integer value. </td>
</tr>
</table>
<hr>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="FileWvIn_8h-source.html">FileWvIn.h</a></ul>
<HR>
<table>
<tr><td><A HREF="http://ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td>&copy;1995-2007 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink