client API: add function to create new mpv_handles from existing ones

This may or may not be useful for client API users.

Fold this API extension into the previous API bump. The previous bump
was only yesterday, so it's ok.

DOCS/client-api-changes.rst

@@ -26,6 +26,9 @@ API changes
 ::
 
  1.12   - add class Handle to qthelper.hpp
+        - improve opengl_cb.h API uninitialization behavior, and fix the qml
+          example
+        - add mpv_create_client() function
  1.11   - add OpenGL rendering interop API - allows an application to combine
           its own and mpv's OpenGL rendering
           Warning: this API is not stable yet - anything in opengl_cb.h might

libmpv/client.h

@@ -392,6 +392,32 @@ void mpv_detach_destroy(mpv_handle *ctx);
  */
 void mpv_terminate_destroy(mpv_handle *ctx);
 
+/**
+ * Create a new client handle connected to the same player core as ctx. This
+ * context has its own event queue, its own mpv_request_event() state, its own
+ * mpv_request_log_messages() state, its own set of observed properties, and
+ * its own state for asynchronous operations. Otherwise, everything is shared.
+ *
+ * This handle should be destroyed with mpv_detach_destroy() if no longer
+ * needed. The core will live as long as there is at least 1 handle referencing
+ * it. Any handle can make the core quit, which will result in every handle
+ * receiving MPV_EVENT_SHUTDOWN.
+ *
+ * This function can not be called before the main handle was initialized with
+ * mpv_initialize(). The new handle is always initialized, unless ctx=NULL was
+ * passed.
+ *
+ * @param ctx Used to get the reference to the mpv core; handle-specific
+ *            settings and parameters are not used.
+ *            If NULL, this function behaves like mpv_create() (ignores name).
+ * @param name The client name. This will be returned by mpv_client_name(). If
+ *             the name is already in use, or contains non-alphanumeric
+ *             characters (other than '_'), the name is modified to fit.
+ *             If NULL, an arbitrary name is automatically chosen.
+ * @return a new handle, or NULL on error
+ */
+mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name);
+
 /**
  * Load a config file. This loads and parses the file, and sets every entry in
  * the config file's default section as if mpv_set_option_string() is called.

libmpv/mpv.def

@@ -6,6 +6,7 @@ mpv_command_node
 mpv_command_node_async
 mpv_command_string
 mpv_create
+mpv_create_client
 mpv_detach_destroy
 mpv_error_string
 mpv_event_name

player/client.c

@@ -201,6 +201,8 @@ struct mpv_handle *mp_new_client(struct mp_client_api *clients, const char *name
 {
     char nname[MAX_CLIENT_NAME];
     for (int n = 1; n < 1000; n++) {
+        if (!name)
+            name = "client";
         snprintf(nname, sizeof(nname) - 3, "%s", name); // - space for number
         for (int i = 0; nname[i]; i++)
             nname[i] = mp_isalnum(nname[i]) ? nname[i] : '_';
@@ -463,6 +465,18 @@ mpv_handle *mpv_create(void)
     return ctx;
 }
 
+mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name)
+{
+    if (!ctx)
+        return mpv_create();
+    if (!ctx->mpctx->initialized)
+        return NULL;
+    mpv_handle *new = mp_new_client(ctx->mpctx->clients, name);
+    if (new)
+        mpv_wait_event(new, 0); // set fuzzy_initialized
+    return new;
+}
+
 static void *playback_thread(void *p)
 {
     struct MPContext *mpctx = p;