cubeb.h: Document device switching policy.devchg_docs

Following the discussion in https://github.com/djg/cubeb-pulse-rs/pull/54
and elsewhere, document the interaction between cubeb_stream_init parameters
and cubeb's intended device switching policy.

1 files changed, 15 insertions, 0 deletions

diff --git a/include/cubeb/cubeb.h b/include/cubeb/cubeb.h
index b3fc56d..31bc85d 100644
--- a/include/cubeb/cubeb.h
+++ b/include/cubeb/cubeb.h
@@ -482,6 +482,21 @@ CUBEB_EXPORT int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rat
 CUBEB_EXPORT void cubeb_destroy(cubeb * context);
 
 /** Initialize a stream associated with the supplied application context.
+
+    @note A NULL @p output_device or @p input_device will cause cubeb to use
+    the OS default device for that direction.  In this case, cubeb will
+    automatically switch to a new OS default if a device change is detected.
+    To disable automatic switching, set @ref
+    CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING on @ref
+    cubeb_stream_params.prefs.
+
+    @note If @p output_device or @p input_device is a valid non-NULL @ref
+    cubeb_devid, cubeb will only ever use the specified device and never
+    follow device changes automatically.  In this case, the application may
+    manage device changes using @ref
+    cubeb_stream_register_device_changed_callback or @ref
+    cubeb_register_device_collection_changed.
+
     @param context A pointer to the cubeb context.
     @param stream An out parameter to be filled with the an opaque pointer to a
                   cubeb stream.