Add docs for GTK::Args#audio

2 files changed, 91 insertions, 0 deletions

diff --git a/dragon/args_docs.rb b/dragon/args_docs.rb
new file mode 100644
index 0000000..819ae5e
--- /dev/null
+++ b/dragon/args_docs.rb
@@ -0,0 +1,90 @@
+# coding: utf-8
+# Copyright 2020 DragonRuby LLC
+# MIT License
+# args_docs.rb has been released under MIT (*only this file*).
+
+module ArgsDocs
+  def docs_method_sort_order
+    [
+      :docs_audio
+    ]
+  end
+
+  def docs_audio
+    <<-S
+* DOCS: ~GTK::Args#audio~
+
+Hash that contains audio sources that are playing. If you want to add a new sound add a hash with following
+
+#+begin_src
+  def tick args
+    # The values below (except for input of course) are the default values that apply if you don't
+    # specify the value in the hash.
+    args.audio[:my_audio] = {
+      input: 'sound/boom.wav',  # Filename
+      x: 0.0, y: 0.0, z: 0.0,   # Relative position to the listener, x, y, z from -1.0 to 1.0
+      gain: 1.0,                # Volume (0.0 to 1.0)
+      pitch: 1.0,               # Pitch of the sound (1.0 = original pitch)
+      paused: false,            # Set to true to pause the sound at the current playback position
+      looping: false,           # Set to true to loop the sound/music until you stop it
+    }
+  end
+#+end_src
+
+Sounds that don't specify ~looping: true~ will be removed automatically from the hash after the playback ends.
+Looping sounds or sounds that should stop early must be removed manually.
+
+** Audio synthesis (Pro only)
+
+Instead of a path to a audio file you can specify an array ~[channels, sample_rate, sound_source]~ for ~input~
+to procedurally generate sound. You do this by providing an array of float values between -1.0 and 1.0 that
+describe the waveform you want to play.
+
+- ~channels~ is the number of channels: 1 = mono, 2 = stereo
+- ~sample_rate~ is the number of values per seconds you will provide to describe the audio wave
+- ~sound_source~ The source of your sound. See below
+
+*** Sound source
+
+A sound source can be one of two things:
+
+- A ~Proc~ object that is called on demand to generate the next samples to play. Every call should generate
+  enough samples for at least 0.1 to 0.5 seconds to get continuous playback without audio skips.
+  The audio will continue playing endlessly until removed, so the ~looping~ option will have no effect.
+
+- An array of sample values that will be played back once. This is useful for procedurally generated one-off SFX.
+  ~looping~ will work as expected
+
+When you specify 2 for ~channels~, then the generated sample array will be played back in an interleaved manner.
+The first element is the first sample for the left channel, the second element is the first sample for the right
+channel, the third element is the second sample for the left channel etc.
+
+*** Example:
+
+#+begin_src
+  def tick args
+    sample_rate = 48000
+
+    generate_sine_wave = lambda do
+      frequency = 440.0 # A5
+      samples_per_period = (sample_rate / frequency).ceil
+      one_period = samples_per_period.map_with_index { |i|
+        Math.sin((2 * Math::PI) * (i / samples_per_period))
+      }
+      one_period * frequency # Generate 1 second worth of sound
+    end
+
+    args.audio[:my_audio] ||= {
+      input: [1, sample_rate, generate_sine_wave]
+    }
+  end
+#+end_src
+
+S
+  end
+end
+
+class GTK::Args
+  extend Docs
+  extend ArgsDocs
+end
diff --git a/dragon/docs.rb b/dragon/docs.rb
index 049ff81..fd1c6c9 100644
--- a/dragon/docs.rb
+++ b/dragon/docs.rb
@@ -29,6 +29,7 @@ module DocsOrganizer
       GTK::ReadMe,
       GTK::Runtime,
       Array,
+      GTK::Args,
       GTK::Outputs,
       GTK::Mouse,
       GTK::OpenEntity,