Update documentation.

2026-04-22 00:06:59 +02:00 · 2025-09-08 12:02:19 +10:00
parent ceb0d74d6b
commit 9afdcd38d0
10 changed files with 52 additions and 1051 deletions
@@ -275,13 +275,9 @@ the decoder via the decoder config (<span style="font-family:monospace;">ma_deco
 of your custom decoders. See <span style="font-family:monospace;">ma_decoding_backend_vtable</span> for the functions you need to implement.
 The <span style="font-family:monospace;">onInitFile</span>, <span style="font-family:monospace;">onInitFileW</span> and <span style="font-family:monospace;">onInitMemory</span> functions are optional.</p>
 <div style="font-family:monospace; border:solid 1px #003800; border-left:solid 0.5em #003800; margin:1em 0em; width:100%;"><pre style="margin:0.5em 1em; padding:0; line-height:125%; overflow-x:auto;">
-<span style="color:#009900">/*
-For now these need to be declared before miniaudio.c due to some compatibility issues with the old
-MINIAUDIO_IMPLEMENTATION system. This will change from version 0.12.
-*/</span>
+<span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../miniaudio.c&quot;</span>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../extras/decoders/libvorbis/miniaudio_libvorbis.c&quot;</span>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../extras/decoders/libopus/miniaudio_libopus.c&quot;</span>
-<span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../miniaudio.c&quot;</span>

 <span style="color:#666666">#include</span> <span style="color:#cc3300">&lt;stdio.h&gt;</span>

@@ -258,13 +258,9 @@ This is the same as the custom_decoder example, only it&#39;s used with the high
 rather than the low level decoding API. You can use this to add support for Opus to your games, for
 example (via libopus).</p>
 <div style="font-family:monospace; border:solid 1px #003800; border-left:solid 0.5em #003800; margin:1em 0em; width:100%;"><pre style="margin:0.5em 1em; padding:0; line-height:125%; overflow-x:auto;">
-<span style="color:#009900">/*
-For now these need to be declared before miniaudio.c due to some compatibility issues with the old
-MINIAUDIO_IMPLEMENTATION system. This will change from version 0.12.
-*/</span>
+<span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../miniaudio.c&quot;</span>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../extras/decoders/libvorbis/miniaudio_libvorbis.c&quot;</span>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../extras/decoders/libopus/miniaudio_libopus.c&quot;</span>
-<span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../miniaudio.c&quot;</span>

 <span style="color:#666666">#include</span> <span style="color:#cc3300">&lt;stdio.h&gt;</span>

@@ -329,6 +325,9 @@ MINIAUDIO_IMPLEMENTATION system. This will change from version 0.12.
    printf(<span style="color:#cc3300">&quot;Press Enter to quit...&quot;</span>);
    getchar();

+    ma_engine_uninit(&amp;engine);
+    ma_resource_manager_uninit(&amp;resourceManager);
+
    <span style="color:#0033ff">return</span> 0;
 }
 </pre></div></td>
@@ -282,9 +282,6 @@ will track a pointer to the data source in the chain that is currently playing.
 consistently read from the head data source this state will become inconsistent and things won&#39;t
 work correctly. When using a chain, this pointer needs to be reset if you need to play the
 chain again from the start:
-</p>
-<p>
-
 </p>
 <div style="font-family:monospace; border:solid 1px #003800; border-left:solid 0.5em #003800; margin:1em 0em; width:100%;"><pre style="margin:0.5em 1em; padding:0; line-height:125%; overflow-x:auto;">
 ma_data_source_set_current(&amp;headDataSource, &amp;headDataSource);
@@ -277,10 +277,12 @@ head.</p>

 <span style="color:#0033ff">void</span> data_callback(<span style="color:#0033ff">void</span>* pUserData, <span style="color:#0099cc">ma_uint8</span>* pBuffer, <span style="color:#0033ff">int</span> bufferSizeInBytes)
 {
+    <span style="color:#0099cc">ma_uint32</span> bufferSizeInFrames;
+
    (<span style="color:#0033ff">void</span>)pUserData;

    <span style="color:#009900">/* Reading is just a matter of reading straight from the engine. */</span>
-    <span style="color:#0099cc">ma_uint32</span> bufferSizeInFrames = (<span style="color:#0099cc">ma_uint32</span>)bufferSizeInBytes / ma_get_bytes_per_frame(ma_format_f32, ma_engine_get_channels(&amp;g_engine));
+    bufferSizeInFrames = (<span style="color:#0099cc">ma_uint32</span>)bufferSizeInBytes / ma_get_bytes_per_frame(ma_format_f32, ma_engine_get_channels(&amp;g_engine));
    ma_engine_read_pcm_frames(&amp;g_engine, pBuffer, bufferSizeInFrames, NULL);
 }

@@ -274,7 +274,17 @@ of buffering solution to your node.</p>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&quot;../miniaudio.c&quot;</span>

 <span style="color:#666666">#include</span> <span style="color:#cc3300">&lt;stdint.h&gt;</span> <span style="color:#009900">/* Required for uint32_t which is used by STEAMAUDIO_VERSION, and a random use of uint8_t. If there&#39;s a Steam Audio maintainer reading this, that needs to be fixed to use IPLuint32 and IPLuint8. */</span>
+
+<span style="color:#009900">/* Need to silence some warnings from the Steam Audio headers. */</span>
+<span style="color:#666666">#if</span> defined(__clang__) || (defined(__GNUC__) &amp;&amp; (__GNUC__ &gt; 4 || (__GNUC__ == 4 &amp;&amp; __GNUC_MINOR__ &gt;= 6)))
+    <span style="color:#666666">#pragma</span> GCC diagnostic push
+    <span style="color:#666666">#pragma</span> GCC diagnostic ignored <span style="color:#cc3300">&quot;-Wlong-long&quot;</span>
+    <span style="color:#666666">#pragma</span> GCC diagnostic ignored <span style="color:#cc3300">&quot;-Wpedantic&quot;</span>
+<span style="color:#666666">#endif</span>
 <span style="color:#666666">#include</span> <span style="color:#cc3300">&lt;phonon.h&gt;</span> <span style="color:#009900">/* Steam Audio */</span>
+<span style="color:#666666">#if</span> defined(__clang__) || (defined(__GNUC__) &amp;&amp; (__GNUC__ &gt; 4 || (__GNUC__ == 4 &amp;&amp; __GNUC_MINOR__ &gt;= 6)))
+    <span style="color:#666666">#pragma</span> GCC diagnostic pop
+<span style="color:#666666">#endif</span>

 <span style="color:#666666">#define</span> FORMAT      ma_format_f32   <span style="color:#009900">/* Must be floating point. */</span>
 <span style="color:#666666">#define</span> CHANNELS    2               <span style="color:#009900">/* Must be stereo for this example. */</span>
@@ -279,9 +279,6 @@ node graph.
 <p>

 This example will be using the following node graph set up:
-</p>
-<p>
-
 </p>
 <div style="font-family:monospace; margin:1em 0em;"><pre style="margin:0.5em 1em; padding:0; line-height:125%; overflow-x:auto;">
 &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt; Data flows left to right &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
@@ -300,6 +300,10 @@ being merged into miniaudio.h (it&#39;s currently in miniaudio_engine.h).
        <span style="color:#0099cc">ma_uint8</span> temp[MA_DATA_CONVERTER_STACK_BUFFER_SIZE];
        <span style="color:#0099cc">ma_uint64</span> tempCapInFrames = <span style="color:#0033ff">sizeof</span>(temp) / ma_get_bytes_per_frame(dataSourceFormat, dataSourceChannels);

+        <span style="color:#0033ff">if</span> (pFramesRead != NULL) {
+            *pFramesRead = 0;
+        }
+        
        totalFramesRead = 0;
        <span style="color:#0033ff">while</span> (totalFramesRead &lt; frameCount) {
            <span style="color:#0099cc">ma_uint64</span> framesJustRead;
@@ -308,7 +312,10 @@ being merged into miniaudio.h (it&#39;s currently in miniaudio_engine.h).
                framesToRead = tempCapInFrames;
            }

-            result = ma_data_source_read_pcm_frames(pDataSource, pFramesOut, framesToRead, &amp;framesJustRead);
+            result = ma_data_source_read_pcm_frames(pDataSource, temp, framesToRead, &amp;framesJustRead);
+            <span style="color:#0033ff">if</span> (result != MA_SUCCESS) {
+                <span style="color:#0033ff">break</span>;
+            }

            ma_convert_pcm_frames_format(ma_offset_pcm_frames_ptr_f32(pFramesOut, totalFramesRead, dataSourceChannels), ma_format_f32, temp, dataSourceFormat, framesJustRead, dataSourceChannels, ma_dither_mode_none);
            totalFramesRead += framesJustRead;
@@ -318,6 +325,10 @@ being merged into miniaudio.h (it&#39;s currently in miniaudio_engine.h).
            }
        }

+        <span style="color:#0033ff">if</span> (pFramesRead != NULL) {
+            *pFramesRead = totalFramesRead;
+        }
+
        <span style="color:#0033ff">return</span> MA_SUCCESS;
    }
 }
@@ -258,9 +258,6 @@ When mixing multiple sounds together, you should not create multiple devices. In
 device and then mix your sounds together which you can do by simply summing their samples together. The simplest way to
 do this is to use floating point samples and use miniaudio&#39;s built-in clipper to handling clipping for you. (Clipping
 is when sample are clamped to their minimum and maximum range, which for floating point is -1..1.)
-</p>
-<p>
-
 </p>
 <div style="font-family:monospace; margin:1em 0em;"><pre style="margin:0.5em 1em; padding:0; line-height:125%; overflow-x:auto;">
 Usage:   simple_mixing [input file 0] [input file 1] ... [input file n]
@@ -326,7 +326,7 @@ orbiting effect. Terminate the program with Ctrl+C.</p>
    <span style="color:#009900">/* Rotate the listener on the spot to create an orbiting effect. */</span>
    <span style="color:#0033ff">for</span> (;;) {
        listenerAngle += 0.01f;
-        ma_engine_listener_set_direction(&amp;engine, 0, sinf(listenerAngle), 0, cosf(listenerAngle));
+        ma_engine_listener_set_direction(&amp;engine, 0, (<span style="color:#0033ff">float</span>)sin(listenerAngle), 0, (<span style="color:#0033ff">float</span>)cos(listenerAngle));

        ma_sleep(1);
    }