From 3f978c0f9307e57fcbe7b167dc34ab9ef245f344 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 18 Nov 2021 15:56:16 -0500
Subject: [PATCH] include: Improved documentation of SDL_RegisterApp and
SDL_UnregisterApp.
---
include/SDL_main.h | 36 +++++++++++++++++++++++++++++++++++-
1 file changed, 35 insertions(+), 1 deletion(-)
diff --git a/include/SDL_main.h b/include/SDL_main.h
index 0717d6aeb2..0d0af771a0 100644
--- a/include/SDL_main.h
+++ b/include/SDL_main.h
@@ -139,11 +139,45 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
#ifdef __WIN32__
/**
- * This can be called to set the application class at startup
+ * Register a win32 window class for SDL's use.
+ *
+ * This can be called to set the application window class at startup.
+ * It is safe to call this multiple times, as long as every call is
+ * eventually paired with a call to SDL_UnregisterApp, but a second
+ * registration attempt while a previous registration is still active
+ * will be ignored, other than to increment a counter.
+ *
+ * Most applications do not need to, and should not, call this directly;
+ * SDL will call it when initializing the video subsystem.
+ *
+ * \param name the window class name, in UTF-8 encoding. If NULL,
+ * SDL currently uses "SDL_app" but this isn't guaranteed.
+ * \param style the value to use in WNDCLASSEX::style. If `name` is
+ * NULL, SDL currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)`
+ * regardless of what is specified here.
+ * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero,
+ * SDL will use `GetModuleHandle(NULL)` instead.
+ * \returns 0 on success, -1 on error. SDL_GetError() may have details.
*
* \since This function is available since SDL 2.0.2.
*/
extern DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst);
+
+/**
+ * Deregister the win32 window class from an SDL_RegisterApp call.
+ *
+ * This can be called to undo the effects of SDL_RegisterApp.
+ *
+ * Most applications do not need to, and should not, call this directly;
+ * SDL will call it when deinitializing the video subsystem.
+ *
+ * It is safe to call this multiple times, as long as every call is
+ * eventually paired with a prior call to SDL_RegisterApp. The window
+ * class will only be deregistered when the registration counter in
+ * SDL_RegisterApp decrements to zero through calls to this function.
+ *
+ * \since This function is available since SDL 2.0.2.
+ */
extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
#endif /* __WIN32__ */