client API: be explicit about usage rules and deadlocks some more

I think a popular libmpv application did exactly this: enabling advanced
control, and then receiving deadlocks. I didn't confirm it, though. In
any case, the API docs should avoid tricking users into making this easy
mistake.

DOCS/client-api-changes.rst

@@ -37,6 +37,8 @@ API changes
           There were no actual API changes.
           API users on older API versions and mpv releases should set
           "vd-lavc-dr" to "no" to avoid these issues.
+          API users must still adhere to the tricky rules documented in render.h
+          to avoid other deadlocks.
  1.104  - Deprecate struct mpv_opengl_drm_params. Replaced by mpv_opengl_drm_params_v2
         - Deprecate MPV_RENDER_PARAM_DRM_DISPLAY. Replaced by MPV_RENDER_PARAM_DRM_DISPLAY_V2.
  1.103  - redo handling of async commands

libmpv/render.h

@@ -239,6 +239,13 @@ typedef enum mpv_render_param_type {
      *  - Rendering screenshots with the GPU API if supported by the backend
      *    (instead of using a suboptimal software fallback via libswscale).
      *
+     * Warning: do not just add this without reading the "Threading" section
+     *          above, and then wondering that deadlocks happen. The
+     *          requirements are tricky. But also note that even if advanced
+     *          control is disabled, not adhering to the rules will lead to
+     *          playback problems. Enabling advanced controls simply makes
+     *          violating these rules fatal.
+     *
      * Type: int*: 0 for disable (default), 1 for enable
      */
     MPV_RENDER_PARAM_ADVANCED_CONTROL = 10,