From 4fbe12ca19527b946816e9c8aa9ed7a3d67c3711 Mon Sep 17 00:00:00 2001
From: David Reid <mackron@gmail.com>
Date: Sun, 9 Feb 2020 10:32:47 +1000
Subject: [PATCH] Add examples to documentation for ma_device_init().

---
 miniaudio.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 6 deletions(-)

diff --git a/miniaudio.h b/miniaudio.h
index 20c3958b..421c6b1d 100644
--- a/miniaudio.h
+++ b/miniaudio.h
@@ -2453,6 +2453,12 @@ typedef enum
     ma_ios_session_category_option_allow_air_play                             = 0x40,   /* AVAudioSessionCategoryOptionAllowAirPlay */
 } ma_ios_session_category_option;
 
+typedef union
+{
+    ma_int64 counter;
+    double counterD;
+} ma_timer;
+
 typedef union
 {
     wchar_t wasapi[64];             /* WASAPI uses a wchar_t string for identification. */
@@ -2493,12 +2499,6 @@ typedef struct
     ma_uint32 maxSampleRate;
 } ma_device_info;
 
-typedef union
-{
-    ma_int64 counter;
-    double counterD;
-} ma_timer;
-
 typedef struct
 {
     ma_device_type deviceType;
@@ -3879,6 +3879,67 @@ ALSA Specific: When initializing the default device, requesting shared mode will
 If these fail it will try falling back to the "hw" device.
 
 
+Example 1 - Simple Initialization
+---------------------------------
+This example shows how to initialize a simple playback default using a standard configuration. If you are just needing to do simple playback from the default
+playback device this is usually all you need.
+
+```c
+ma_device_config config = ma_device_config_init(ma_device_type_playback);
+config.playback.format   = ma_format_f32;
+config.playback.channels = 2;
+config.sampleRate        = 48000;
+config.dataCallback      = ma_data_callback;
+config.pMyUserData       = pMyUserData;
+
+ma_device device;
+ma_result result = ma_device_init(NULL, &config, &device);
+if (result != MA_SUCCESS) {
+    // Error
+}
+```
+
+
+Example 2 - Advanced Initialization
+-----------------------------------
+This example show how you might do some more advanced initialization. In this hypothetical example we want to control the latency by setting the buffer size
+and period count. We also want to allow the user to be able to choose which device to output from which means we need a context so we can perform device
+enumeration.
+
+```c
+ma_context context;
+ma_result result = ma_context_init(NULL, 0, NULL, &context);
+if (result != MA_SUCCESS) {
+    // Error
+}
+
+ma_device_info* pPlaybackDeviceInfos;
+ma_uint32 playbackDeviceCount;
+result = ma_context_get_devices(&context, &pPlaybackDeviceInfos, &playbackDeviceCount, NULL, NULL);
+if (result != MA_SUCCESS) {
+    // Error
+}
+
+// ... choose a device from pPlaybackDeviceInfos ...
+
+ma_device_config config = ma_device_config_init(ma_device_type_playback);
+config.playback.pDeviceID       = pMyChosenDeviceID;    // <-- Get this from the `id` member of one of the `ma_device_info` objects returned by ma_context_get_devices().
+config.playback.format          = ma_format_f32;
+config.playback.channels        = 2;
+config.sampleRate               = 48000;
+config.dataCallback             = ma_data_callback;
+config.pUserData                = pMyUserData;
+config.bufferSizeInMilliseconds = 30;
+config.periods                  = 3;
+
+ma_device device;
+result = ma_device_init(&context, &config, &device);
+if (result != MA_SUCCESS) {
+    // Error
+}
+```
+
+
 See Also
 --------
 ma_device_config_init()