wayland: Add support for images in clipboard.

Re-writes the clipboard data handling in wayland to an on demand
solution where callbacks are provided to generate/provide the clipboard
data when requested by the OS.

include/SDL3/SDL_clipboard.h

@@ -129,6 +129,96 @@ extern DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
 
+/**
+ * Callback function that will be called when data for the specified mime-type
+ * is requested by the OS.
+ *
+ * \param size      The length of the returned data
+ * \param mime_type The requested mime-type
+ * \param userdata  A pointer to provided user data
+ * \returns a pointer to the data for the provided mime-type. Returning NULL or
+ *          setting length to 0 will cause no data to be sent to the "receiver". It is
+ *          up to the receiver to handle this. Essentially returning no data is more or
+ *          less undefined behavior and may cause breakage in receiving applications.
+ *          The returned data will not be freed so it needs to be retained and dealt
+ *          with internally.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetClipboardData
+ */
+typedef void *(SDLCALL *SDL_ClipboardDataCallback)(size_t *size, const char *mime_type, void *userdata);
+
+/**
+ * \brief Offer clipboard data to the OS
+ *
+ * Tell the operating system that the application is offering clipboard data
+ * for each of the proivded mime-types. Once another application requests the
+ * data the callback function will be called allowing it to generate and
+ * respond with the data for the requested mime-type.
+ *
+ * The userdata submitted to this function needs to be freed manually. The
+ * following scenarios need to be handled:
+ *
+ * - When the programs clipboard is replaced (cancelled) SDL_EVENT_CLIPBOARD_CANCELLED
+ * - Before calling SDL_Quit()
+ *
+ * \param callback      A function pointer to the function that provides the clipboard data
+ * \param mime_count    The number of mime-types in the mime_types list
+ * \param mime_types    A list of mime-types that are being offered
+ * \param userdata      An opaque pointer that will be forwarded to the callback
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_ClipboardDataCallback
+ * \sa SDL_GetClipboardUserdata
+ * \sa SDL_SetClipboardData
+ * \sa SDL_GetClipboardData
+ * \sa SDL_HasClipboardData
+ */
+extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, size_t mime_count,
+                                                 const char **mime_types, void *userdata);
+
+/**
+ * Retrieve previously set userdata if any.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \returns a pointer to the data or NULL if no data exists
+ */
+extern DECLSPEC void *SDLCALL SDL_GetClipboardUserdata(void);
+
+/**
+ * Get the data from clipboard for a given mime type
+ *
+ * \param[out] length   A pointer to hold the buffer length
+ * \param mime_type     The mime type to read from the clipboard
+ * \returns the retrieved data buffer or NULL on failure; call
+ *          SDL_GetError() for more information. Caller must call
+ *          SDL_free() on the returned pointer when done with it.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetClipboardData
+ */
+extern DECLSPEC void *SDLCALL SDL_GetClipboardData(size_t *length, const char *mime_type);
+
+/**
+ * Query whether there is data in the clipboard for the provided mime type
+ *
+ * \param mime_type The mime type to check for data for
+ *
+ * \returns SDL_TRUE if there exists data in clipboard for the provided mime
+ *          type, SDL_FALSE if it does not.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetClipboardData
+ * \sa SDL_GetClipboardData
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL3/SDL_events.h

@@ -172,6 +172,7 @@ typedef enum
 
     /* Clipboard events */
     SDL_EVENT_CLIPBOARD_UPDATE = 0x900, /**< The clipboard or primary selection changed */
+    SDL_EVENT_CLIPBOARD_CANCELLED,      /**< The clipboard or primary selection cancelled */
 
     /* Drag and drop events */
     SDL_EVENT_DROP_FILE        = 0x1000, /**< The system requests a file open */
@@ -530,6 +531,18 @@ typedef struct SDL_DropEvent
     float y;            /**< Y coordinate, relative to window (not on begin) */
 } SDL_DropEvent;
 
+/**
+ * \brief An event triggered when the applications active clipboard content is cancelled by new clipboard content
+ * \note Primary use for this event is to free any userdata you may have provided when setting the clipboard data.
+ *
+ * \sa SDL_SetClipboardData
+ */
+typedef struct SDL_ClipboardCancelled
+{
+    Uint32 type;        /**< ::SDL_EVENT_CLIPBOARD_CANCELLED or ::SDL_EVENT_CLIPBOARD_UPDATE */
+    Uint64 timestamp;   /**< In nanoseconds, populated using SDL_GetTicksNS() */
+    void *userdata;     /**< User data if any has been set. NULL for ::SDL_EVENT_CLIPBOARD_UPDATE */
+} SDL_ClipboardEvent;
 
 /**
  *  \brief Sensor event structure (event.sensor.*)
@@ -624,6 +637,7 @@ typedef union SDL_Event
     SDL_SysWMEvent syswm;                   /**< System dependent window event data */
     SDL_TouchFingerEvent tfinger;           /**< Touch finger event data */
     SDL_DropEvent drop;                     /**< Drag and drop event data */
+    SDL_ClipboardEvent clipboard;       /**< Clipboard cancelled event data */
 
     /* This is necessary for ABI compatibility between Visual C++ and GCC.
        Visual C++ will respect the push pack pragma and use 52 bytes (size of