/usr/share/doc/libambix/apiref/usage.html is in libambix-doc 0.1.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libambix: Usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="mathjax/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libambix
</div>
<div id="projectbrief">the AMBIsonics eXchange library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Usage </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="read_usage"></a>
Reading ambix files</h1>
<p>When opening a file for read, the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct should be set to 0. On successful open, all fields are filled by the library. If the open fails, the state of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> fields is undefined.</p>
<p>The only exception to this is, if you want to force the ambix file to be read as either "BASIC" or "EXTENDED", e.g. because you don't want to care about adaptor matrices or because you do. In this case you must set the fileformat field the requested format.</p>
<h2><a class="anchor" id="readbasic_usage"></a>
Reading BASIC ambix files</h2>
<p>You can read any ambix file as "BASIC" by setting the 'fileformat' member of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct to <a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a> prior to opening the file. This will automatically do any conversion needed, by pre-multiplying the raw ambisonics data with an embedded adaptor matrix.</p>
<p>Real "BASIC" files lack extra audio channels. However, when opening a file that is not a "BASIC" ambix file (e.g. an "EXTENDED" ambix file) as a "BASIC" one, by forcing the 'fileformat' member to '<a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a>', extra channels might be readable.</p>
<div class="fragment"><div class="line"><a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"><a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>));</div><div class="line"></div><div class="line">ambix->fileformat = <a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a>;</div><div class="line"></div><div class="line">ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faa794da2987d75cc4bb207fa76d09a980d">AMBIX_READ</a>, info);</div><div class="line"><span class="keywordflow">if</span>(ambix) {</div><div class="line"> uint64_t frames = info-><a class="code" href="structambix__info__t.html#a4fac5ed056e5bb7bedca0c003d2f21b9">frames</a>;</div><div class="line"> uint64_t blocksize = 1024;</div><div class="line"></div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*ambidata = calloc(info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*extradata = calloc(info-><a class="code" href="structambix__info__t.html#a634350c74599ccad94c557b1f7d74251">extrachannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span>(frames>blocksize) {</div><div class="line"> uint64_t blocks = <a class="code" href="group__ambix__readf.html#ga2e5aa1ff58e5991009f055f6e073ec5f">ambix_readf_float32</a>(ambix, ambidata, extradata, blocksize);</div><div class="line"></div><div class="line"> <span class="comment">// process blocks frames of interleaved ambidata and interleaved extradata</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> frames-=blocks;</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix__readf.html#ga2e5aa1ff58e5991009f055f6e073ec5f">ambix_readf_float32</a>(ambix, ambidata, extradata, frames);</div><div class="line"></div><div class="line"> <span class="comment">// process last block of interleaved ambidata and interleaved extradata</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line"> free(ambidata);</div><div class="line"> free(extradata);</div><div class="line">}</div><div class="line">free(info);</div></div><!-- fragment --><h2><a class="anchor" id="readextended_usage"></a>
Reading EXTENDED ambix files</h2>
<p>You can read an ambix file as "EXTENDED" by setting the 'fileformat' member of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct to <a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abdb142f028c2b82558a73552d8f7f59d">AMBIX_EXTENDED</a> prior to opening the file. You will then have to retrieve the adaptor matrix from the file, in order to be able to reconstruct the full ambisonics set. You can also analyze the matrix to make educated guesses about the original channel layout.</p>
<div class="fragment"><div class="line"> <a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"> <a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>));</div><div class="line"></div><div class="line"> <span class="comment">/* setting the fileformat to AMBIX_EXTENDED forces the ambi data</span></div><div class="line"><span class="comment"> * be delivered as stored in the file</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> ambix->fileformat = <a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abdb142f028c2b82558a73552d8f7f59d">AMBIX_EXTENDED</a>;</div><div class="line"></div><div class="line"> ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faa794da2987d75cc4bb207fa76d09a980d">AMBIX_READ</a>, info);</div><div class="line"> <span class="keywordflow">if</span>(ambix) {</div><div class="line"> uint64_t frames = info-><a class="code" href="structambix__info__t.html#a4fac5ed056e5bb7bedca0c003d2f21b9">frames</a>;</div><div class="line"> uint64_t blocksize = 1024;</div><div class="line"></div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*ambidata = calloc(info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*extradata = calloc(info-><a class="code" href="structambix__info__t.html#a634350c74599ccad94c557b1f7d74251">extrachannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"></div><div class="line"> <span class="keyword">const</span> <a class="code" href="structambix__matrix__t.html">ambix_matrix_t</a>*adaptormatrix=<a class="code" href="group__ambix.html#ga74fdb923b83a9aa8fd653fdf7ffb7869">ambix_get_adaptormatrix</a>(ambix);</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span>(frames>blocksize) {</div><div class="line"> uint64_t blocks = <a class="code" href="group__ambix__readf.html#ga2e5aa1ff58e5991009f055f6e073ec5f">ambix_readf_float32</a>(ambix, ambidata, extradata, blocksize);</div><div class="line"></div><div class="line"> <span class="comment">// process blocks frames of interleaved ambidata and interleaved extradata,</span></div><div class="line"> <span class="comment">// using the adaptormatrix</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> frames-=blocks;</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix__readf.html#ga2e5aa1ff58e5991009f055f6e073ec5f">ambix_readf_float32</a>(ambix, ambidata, extradata, frames);</div><div class="line"></div><div class="line"> <span class="comment">// process last block of interleaved ambidata and interleaved extradata</span></div><div class="line"> <span class="comment">// using the adaptormatrix</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line"> free(ambidata);</div><div class="line"> free(extradata);</div><div class="line"> }</div><div class="line"> free(info);</div><div class="line">* </div></div><!-- fragment --><h2><a class="anchor" id="readunknown_usage"></a>
Reading any ambix files</h2>
<p>If you do not specify the format prior to opening, you can query the format of the file from the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct.</p>
<div class="fragment"><div class="line"><a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"><a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>)); <span class="comment">/* initialize the format field (among others) to 0 */</span></div><div class="line"></div><div class="line">ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faa794da2987d75cc4bb207fa76d09a980d">AMBIX_READ</a>, info);</div><div class="line"></div><div class="line"><span class="keywordflow">if</span>(ambix) {</div><div class="line"> <span class="keywordflow">switch</span>(ambix->fileformat) {</div><div class="line"> <span class="keywordflow">case</span>(<a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a>):</div><div class="line"> printf(<span class="stringliteral">"this file is ambix basic\n"</span>);</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">case</span>(<a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abdb142f028c2b82558a73552d8f7f59d">AMBIX_EXTENDED</a>):</div><div class="line"> printf(<span class="stringliteral">"this file is ambix extended\n"</span>);</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">case</span>(<a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42a4d864c5c76e968f262c4ecb4458fc1e1">AMBIX_NONE</a>):</div><div class="line"> printf(<span class="stringliteral">"this file is not an ambix file\n"</span>);</div><div class="line"> <span class="keywordflow">break</span>;</div><div class="line"> <span class="keywordflow">default</span>:</div><div class="line"> printf(<span class="stringliteral">"this file is of unknown format...\n"</span>);</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line">}</div><div class="line">free(info);</div></div><!-- fragment --><h1><a class="anchor" id="write_usage"></a>
Writing ambix files</h1>
<p>To write data to an ambix file, you have to open it with the <a class="el" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faafbbdf1e779cf4cf905f78db42f39d41f">AMBIX_WRITE</a> flag. You also need to specify some global properties of the output data, namely the samplerate and the sampleformat, as well as the number of ambisonics channels and the number of extra channels that are physically stored on the disk.</p>
<h2><a class="anchor" id="writebasic_usage"></a>
Writing BASIC ambix files</h2>
<p>You can write "BASIC" ambix files by setting the 'fileformat' member of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct to <a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a> prior to opening the file.</p>
<p>You will need to provide a full set of ambisonics channels when writing data to the file, and must not set an adaptor matrix (see also <a class="el" href="usage.html#writebasic2extended_usage">Writing EXTENDED ambix files using the BASIC interface</a>). A full set of ambisonics must always satisfy the formula \(channels=(order_{ambi}+1)^2\).</p>
<p>You cannot write extra audio channels into a "BASIC" ambix file.</p>
<div class="fragment"><div class="line"><a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"><a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>));</div><div class="line"></div><div class="line"><span class="comment">/* need to specify samplerate and sampleformat */</span></div><div class="line">ambix->samplerate = 44100;</div><div class="line">ambix->sampleformat = <a class="code" href="ambix_8h.html#a3dba8ae1c6a50c9f533517276e3545f0a64884188068950ac1eeac9ffb8617f3e">AMBIX_SAMPLEFORMAT_PCM24</a>;</div><div class="line">ambix->fileformat = <a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a>;</div><div class="line">ambix->ambichannels = 16; <span class="comment">/* 16 channels means 3rd order ambisonics, according to L=(2N+1)^2 */</span></div><div class="line"></div><div class="line">ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faafbbdf1e779cf4cf905f78db42f39d41f">AMBIX_WRITE</a>, info);</div><div class="line"><span class="keywordflow">if</span>(ambix) {</div><div class="line"> uint64_t frames = info-><a class="code" href="structambix__info__t.html#a4fac5ed056e5bb7bedca0c003d2f21b9">frames</a>;</div><div class="line"> uint64_t blocksize = 1024;</div><div class="line"> uint64_t block;</div><div class="line"></div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*ambidata = calloc(info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span>(haveData) {</div><div class="line"> <span class="comment">// acquire blocksize samples of a full set of 3rd order ambisonics data (16 channels)</span></div><div class="line"> <span class="comment">// into ambidata (interleaved)</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> block = <a class="code" href="group__ambix__writef.html#gad4cd37705d53043ced8c031663156937">ambix_writef_float32</a>(ambix, ambidata, NULL, blocksize);</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line"> free(ambidata);</div><div class="line">}</div><div class="line">free(info);</div></div><!-- fragment --><h2><a class="anchor" id="writeextended_usage"></a>
Writing EXTENDED ambix files</h2>
<p>You can write "EXTENDED" ambix files by setting the 'fileformat' member of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct to <a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abdb142f028c2b82558a73552d8f7f59d">AMBIX_EXTENDED</a> prior to opening the file.</p>
<p>You MUST set an adaptormatrix (to convert the reduced set to a full ambisonics set) using <a class="el" href="group__ambix.html#gaa6890a0640c08e627ae0cdd464957bf7" title="Set a matrix to be pre-multiplied. ">ambix_set_adaptormatrix()</a>. It gets written to disk prior to writing any samples to the file (or closing the ambix file). It is an error to call <a class="el" href="group__ambix.html#gaa6890a0640c08e627ae0cdd464957bf7" title="Set a matrix to be pre-multiplied. ">ambix_set_adaptormatrix()</a> after starting to write samples.</p>
<div class="fragment"><div class="line"><a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"><a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>));</div><div class="line"></div><div class="line"><span class="comment">/* need to specify samplerate and sampleformat */</span></div><div class="line">ambix->samplerate = 44100;</div><div class="line">ambix->sampleformat = <a class="code" href="ambix_8h.html#a3dba8ae1c6a50c9f533517276e3545f0a64884188068950ac1eeac9ffb8617f3e">AMBIX_SAMPLEFORMAT_PCM24</a>;</div><div class="line">ambix->fileformat = <a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abdb142f028c2b82558a73552d8f7f59d">AMBIX_EXTENDED</a>;</div><div class="line">ambix->ambichannels = 8; <span class="comment">/* a reduced ambisonics set */</span></div><div class="line">ambix->extrachannels = 1; <span class="comment">/* an extrachannel, e.g. click-track */</span></div><div class="line"></div><div class="line">ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faafbbdf1e779cf4cf905f78db42f39d41f">AMBIX_WRITE</a>, info);</div><div class="line"><span class="keywordflow">if</span>(ambix) {</div><div class="line"> uint64_t frames = info-><a class="code" href="structambix__info__t.html#a4fac5ed056e5bb7bedca0c003d2f21b9">frames</a>;</div><div class="line"> uint64_t blocksize = 1024;</div><div class="line"> uint64_t block;</div><div class="line"></div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*ambidata = calloc(info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*extradata = calloc(info-><a class="code" href="structambix__info__t.html#a634350c74599ccad94c557b1f7d74251">extrachannels</a> * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"></div><div class="line"> <span class="comment">/* create an adaptormatrix: */</span></div><div class="line"> <a class="code" href="structambix__matrix__t.html">ambix_matrix_t</a> adaptormatrix = {0, 0, NULL};</div><div class="line"> <a class="code" href="group__ambix__matrix.html#gae42712fa68ef3f1aa0a169d990445d59">ambix_matrix_init</a>(16, 8, &adaptormatrix);</div><div class="line"> <span class="comment">// fill the adaptormatrix, that expands our 8 channels to a full 3D 3rd-order set (16 channels)</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> ambix_set_adapatormatrix(ambix, &adaptormatrix);</div><div class="line"> ambix_write_header(ambix);</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span>(haveData) {</div><div class="line"> <span class="comment">// acquire blocksize samples of a full set of reduced ambisonics data (8 channels)</span></div><div class="line"> <span class="comment">// into ambidata (interleaved), and a some (1) extra channels</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> block = <a class="code" href="group__ambix__writef.html#gad4cd37705d53043ced8c031663156937">ambix_writef_float32</a>(ambix, ambidata, extradata, blocksize);</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line"> <a class="code" href="group__ambix__matrix.html#gaa385a0026fb534646591fddd9f906a28">ambix_matrix_deinit</a>(&adaptormatrix);</div><div class="line"> free(ambidata);</div><div class="line"> free(extradata);</div><div class="line">}</div><div class="line">free(info);</div></div><!-- fragment --><h2><a class="anchor" id="writebasic2extended_usage"></a>
Writing EXTENDED ambix files using the BASIC interface</h2>
<p>Finally, you can create "EXTENDED" ambix files from a full set of ambisonics channels and an adaptor matrix. This can be useful if you have a setup that works with full ambisonics sets (e.g. a DAW project) and you want to create a size-optimized ambix file that only stores a reduced set.</p>
<p>This can be achieved by setting the 'fileformat' member of the <a class="el" href="structambix__info__t.html">ambix_info_t</a> struct to <a class="el" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a> (because you will provide the full ambisonics set as if the file were opened in "BASIC" mode) and the 'ambichannels' member to the (reduced) number of ambisonics channel as will be written to the disk, and then setting an adaptor matrix <a class="el" href="group__ambix.html#gaa6890a0640c08e627ae0cdd464957bf7" title="Set a matrix to be pre-multiplied. ">ambix_set_adaptormatrix()</a>, that will convert the reduced set back to the full set. libambix will internally reduce the full ambisonics set (as passed to <a class="el" href="group__ambix__writef.html">ambix_writef()</a>) using the (pseudo) inverse of the adaptor-matrix.</p>
<dl class="section note"><dt>Note</dt><dd>You must ensure yourself that the adaptor matrix is inversible.</dd></dl>
<p>The adaptor matrix gets written to disk prior to writing any samples to the file (or closing the ambix file). It is an error to call <a class="el" href="group__ambix.html#gaa6890a0640c08e627ae0cdd464957bf7" title="Set a matrix to be pre-multiplied. ">ambix_set_adaptormatrix()</a> after starting to write samples.</p>
<dl class="section note"><dt>Note</dt><dd>If you pass an adaptor matrix that expands a reduced set to full ambisonics (e.g. converting from 1st order horizontal-only ambisonics set to a 2nd order fully periphonic set) the reconstructed ambisonics channels (when reading the ambix file later), might be different from the ambisonics channels you passed in when writing the file (e.g. channels that contain 3rd-order and/or Z-axis components will be muted).</dd></dl>
<div class="fragment"><div class="line"><a class="code" href="ambix_8h.html#ad29b22bfc61f9d9517484617299c15c6">ambix_t</a>*ambix = NULL;</div><div class="line"><a class="code" href="structambix__info__t.html">ambix_info_t</a>*info = calloc(1, <span class="keyword">sizeof</span>(<a class="code" href="structambix__info__t.html">ambix_info_t</a>));</div><div class="line"></div><div class="line"><span class="comment">/* need to specify samplerate and sampleformat */</span></div><div class="line">info-><a class="code" href="structambix__info__t.html#a4d12850d1784125b024293307a72f269">samplerate</a> = 44100;</div><div class="line">info-><a class="code" href="structambix__info__t.html#abc6766bcc0cf9b0a81f38d535ed0a918">sampleformat</a> = <a class="code" href="ambix_8h.html#a3dba8ae1c6a50c9f533517276e3545f0a64884188068950ac1eeac9ffb8617f3e">AMBIX_SAMPLEFORMAT_PCM24</a>;</div><div class="line">info-><a class="code" href="structambix__info__t.html#a088b71debbb155f123fc7abdddd24462">fileformat</a> = <a class="code" href="ambix_8h.html#aa079d38c1d269ac5dfbe4dd4251b3e42abb44830701a07dc50814f69ec74050d5">AMBIX_BASIC</a>;</div><div class="line">info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a> = 7; <span class="comment">/* 3rd-order horizontal-only(!) */</span></div><div class="line"></div><div class="line">ambix = <a class="code" href="group__ambix.html#gaaf5dcae7c0ea7321e612a7bbe982e056">ambix_open</a>(<span class="stringliteral">"ambixfile.caf"</span>, <a class="code" href="ambix_8h.html#abecfbc0978dd169538565e07d431d0faafbbdf1e779cf4cf905f78db42f39d41f">AMBIX_WRITE</a>, info);</div><div class="line"><span class="keywordflow">if</span>(ambix) {</div><div class="line"> uint64_t fullambichannels = 16;</div><div class="line"> uint64_t frames = info-><a class="code" href="structambix__info__t.html#a4fac5ed056e5bb7bedca0c003d2f21b9">frames</a>;</div><div class="line"> uint64_t blocksize = 1024;</div><div class="line"> uint64_t block;</div><div class="line"></div><div class="line"> <a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>*ambidata = calloc(fullambichannels * blocksize, <span class="keyword">sizeof</span>(<a class="code" href="ambix_8h.html#a4611b605e45ab401f02cab15c5e38715">float32_t</a>));</div><div class="line"></div><div class="line"> <span class="comment">/* on disk, the data is stored as 3rd-order horizontal-only Furse-Malham</span></div><div class="line"><span class="comment"> * set (7 channels); we need to provide an adaptor matrix that converts</span></div><div class="line"><span class="comment"> * from the 7 FuMa-channels to the 16 AMBIX channels</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> <a class="code" href="structambix__matrix__t.html">ambix_matrix_t</a>*mtx = NULL;</div><div class="line"> mtx = <a class="code" href="group__ambix__matrix.html#gae42712fa68ef3f1aa0a169d990445d59">ambix_matrix_init</a>(fullambichannels, info-><a class="code" href="structambix__info__t.html#a615d125aaa9f1acaef9e6598a4cca722">ambichannels</a>, mtx);</div><div class="line"> mtx = <a class="code" href="group__ambix__matrix.html#ga108d3d26586a42a29d07ddde5ab8da62">ambix_matrix_fill</a>(mtx, ABIX_MATRIX_FUMA); <span class="comment">/* fuma->ambix matrix [16x7] */</span></div><div class="line"> <a class="code" href="group__ambix.html#gaa6890a0640c08e627ae0cdd464957bf7">ambix_set_adaptormatrix</a>(ambix, mtx);</div><div class="line"> <a class="code" href="group__ambix__matrix.html#ga1ea787bb53abfefad7650ea741c391d9">ambix_matrix_destroy</a>(mtx);</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span>(haveData) {</div><div class="line"> <span class="comment">// acquire blocksize samples of a full set of 3rd order ambisonics data (16 channels)</span></div><div class="line"> <span class="comment">// into ambidata (interleaved)</span></div><div class="line"> <span class="comment">// ...</span></div><div class="line"></div><div class="line"> block = ambix_write_float32(ambix, ambidata, NULL, blocksize);</div><div class="line"> }</div><div class="line"></div><div class="line"> <a class="code" href="group__ambix.html#ga5986e1bb6e6042ce262db23b78602e86">ambix_close</a>(ambix);</div><div class="line"> free(ambidata);</div><div class="line">}</div><div class="line">free(info);</div></div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.12
</small></address>
</body>
</html>
|