client API: add MPV_ENABLE_DEPRECATED symbol

(Of course this is on by default, because otherwise we'd randomly break
downstream applications.)

DOCS/client-api-changes.rst

@@ -32,6 +32,9 @@ API changes
 
 ::
 
+ --- mpv 0.25.0 ---
+ 1.24   - add a MPV_ENABLE_DEPRECATED preprocessor symbol, which can be defined
+          by the user to exclude deprecated API symbols from the C headers
  --- mpv 0.23.0 ---
  1.24   - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing.
  --- mpv 0.22.0 ---

libmpv/client.h

@@ -207,6 +207,16 @@ extern "C" {
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
 #define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 24)
 
+/**
+ * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before
+ * including any libmpv headers. Then deprecated symbols will be excluded
+ * from the headers. (Of course, deprecated properties and commands and
+ * other functionality will still work.)
+ */
+#ifndef MPV_ENABLE_DEPRECATED
+#define MPV_ENABLE_DEPRECATED 1
+#endif
+
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
  */
@@ -499,6 +509,8 @@ mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name);
  */
 int mpv_load_config_file(mpv_handle *ctx, const char *filename);
 
+#if MPV_ENABLE_DEPRECATED
+
 /**
  * This does nothing since mpv 0.23.0 (API version 1.24). Below is the
  * description of the old behavior.
@@ -532,6 +544,8 @@ void mpv_suspend(mpv_handle *ctx);
  */
 void mpv_resume(mpv_handle *ctx);
 
+#endif
+
 /**
  * Return the internal time in microseconds. This has an arbitrary start offset,
  * but will never wrap or go backwards.
@@ -812,7 +826,7 @@ void mpv_free_node_contents(mpv_node *node);
  *              - deprecated options shadowed by properties:
  *                - chapter (option deprecated in 0.21.0)
  *                - playlist-pos (option deprecated in 0.21.0)
- *       The deprecated properties will be removed in mpv 0.23.0.
+ *       The deprecated properties were removed in mpv 0.23.0.
  *
  * @param name Option name. This is the same as on the mpv command line, but
  *             without the leading "--".
@@ -1132,6 +1146,7 @@ typedef enum mpv_event_id {
      * decoding starts.
      */
     MPV_EVENT_FILE_LOADED       = 8,
+#if MPV_ENABLE_DEPRECATED
     /**
      * The list of video/audio/subtitle tracks was changed. (E.g. a new track
      * was found. This doesn't necessarily indicate a track switch; for this,
@@ -1150,6 +1165,7 @@ typedef enum mpv_event_id {
      *             and might be removed in the far future.
      */
     MPV_EVENT_TRACK_SWITCHED    = 10,
+#endif
     /**
      * Idle mode was entered. In this mode, no file is played, and the playback
      * core waits for new commands. (The command line player normally quits
@@ -1157,6 +1173,7 @@ typedef enum mpv_event_id {
      * was started with mpv_create(), idle mode is enabled by default.)
      */
     MPV_EVENT_IDLE              = 11,
+#if MPV_ENABLE_DEPRECATED
     /**
      * Playback was paused. This indicates the user pause state.
      *
@@ -1186,6 +1203,7 @@ typedef enum mpv_event_id {
      *             removed in the far future.
      */
     MPV_EVENT_UNPAUSE           = 13,
+#endif
     /**
      * Sent every time after a video frame is displayed. Note that currently,
      * this will be sent in lower frequency if there is no video, or playback
@@ -1193,6 +1211,7 @@ typedef enum mpv_event_id {
      * restricted to video frames only.
      */
     MPV_EVENT_TICK              = 14,
+#if MPV_ENABLE_DEPRECATED
     /**
      * @deprecated This was used internally with the internal "script_dispatch"
      *             command to dispatch keyboard and mouse input for the OSC.
@@ -1202,6 +1221,7 @@ typedef enum mpv_event_id {
      *             header only for compatibility.
      */
     MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15,
+#endif
     /**
      * Triggered by the script-message input command. The command uses the
      * first argument of the command as client name (see mpv_client_name()) to
@@ -1226,6 +1246,7 @@ typedef enum mpv_event_id {
      * because there is no such thing as audio output embedding.
      */
     MPV_EVENT_AUDIO_RECONFIG    = 18,
+#if MPV_ENABLE_DEPRECATED
     /**
      * Happens when metadata (like file tags) is possibly updated. (It's left
      * unspecified whether this happens on file start or only when it changes
@@ -1236,6 +1257,7 @@ typedef enum mpv_event_id {
      *             be removed in the far future.
      */
     MPV_EVENT_METADATA_UPDATE   = 19,
+#endif
     /**
      * Happens when a seek was initiated. Playback stops. Usually it will
      * resume with MPV_EVENT_PLAYBACK_RESTART as soon as the seek is finished.
@@ -1253,6 +1275,7 @@ typedef enum mpv_event_id {
      * See also mpv_event and mpv_event_property.
      */
     MPV_EVENT_PROPERTY_CHANGE   = 22,
+#if MPV_ENABLE_DEPRECATED
     /**
      * Happens when the current chapter changes.
      *
@@ -1261,6 +1284,7 @@ typedef enum mpv_event_id {
      *             be removed in the far future.
      */
     MPV_EVENT_CHAPTER_CHANGE    = 23,
+#endif
     /**
      * Happens if the internal per-mpv_handle ringbuffer overflows, and at
      * least 1 event had to be dropped. This can happen if the client doesn't
@@ -1414,12 +1438,14 @@ typedef struct mpv_event_end_file {
     int error;
 } mpv_event_end_file;
 
+#if MPV_ENABLE_DEPRECATED
 /** @deprecated see MPV_EVENT_SCRIPT_INPUT_DISPATCH for remarks
  */
 typedef struct mpv_event_script_input_dispatch {
     int arg0;
     const char *type;
 } mpv_event_script_input_dispatch;
+#endif
 
 typedef struct mpv_event_client_message {
     /**

libmpv/opengl_cb.h

@@ -286,6 +286,7 @@ int mpv_opengl_cb_init_gl(mpv_opengl_cb_context *ctx, const char *exts,
  */
 int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h);
 
+#if MPV_ENABLE_DEPRECATED
 /**
  * Deprecated. Use mpv_opengl_cb_draw(). This function is equivalent to:
  *
@@ -298,6 +299,7 @@ int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h);
  * was never marked as stable).
  */
 int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4]);
+#endif
 
 /**
  * Tell the renderer that a frame was flipped at the given time. This is

libmpv/qthelper.hpp

@@ -226,6 +226,8 @@ struct node_autofree {
     ~node_autofree() { mpv_free_node_contents(ptr); }
 };
 
+#if MPV_ENABLE_DEPRECATED
+
 /**
  * Return the given property as mpv_node converted to QVariant, or QVariant()
  * on error.
@@ -283,6 +285,8 @@ static inline QVariant command_variant(mpv_handle *ctx, const QVariant &args)
     return node_to_variant(&res);
 }
 
+#endif
+
 /**
  * This is used to return error codes wrapped in QVariant for functions which
  * return QVariant.