assert: Added SDL_HINT_ASSERT.

Same environment variable, but now accessible as a formal SDL hint.

Reference PR #10171.

include/SDL3/SDL_assert.h

@@ -303,9 +303,6 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * "break" so that your debugger takes control as soon as assert is triggered,
  * instead of risking a bad UI interaction (deadlock, etc) in the application.
  *
- * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
- * Please refer to your platform's documentation for how to set it!
- *
  * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
@@ -335,10 +332,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * an assertion in a background thread, it might be desirable to set this to
  * "break" so that your debugger takes control as soon as assert is triggered,
  * instead of risking a bad UI interaction (deadlock, etc) in the application.
- *
+ * *
- * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
- * Please refer to your platform's documentation for how to set it!
- *
  * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
@@ -366,9 +360,6 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * "break" so that your debugger takes control as soon as assert is triggered,
  * instead of risking a bad UI interaction (deadlock, etc) in the application.
  *
- * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
- * Please refer to your platform's documentation for how to set it!
- *
  * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
@@ -412,9 +403,6 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * "break" so that your debugger takes control as soon as assert is triggered,
  * instead of risking a bad UI interaction (deadlock, etc) in the application.
  *
- * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
- * Please refer to your platform's documentation for how to set it!
- *
  * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.

include/SDL3/SDL_hints.h

@@ -4120,6 +4120,29 @@ extern "C" {
  */
 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
 
+/**
+ * A variable controlling response to SDL_assert failures.
+ *
+ * The variable can be set to the following case-sensitive values:
+ *
+ * - "abort": Program terminates immediately.
+ * - "break": Program triggers a debugger breakpoint.
+ * - "retry": Program reruns the SDL_assert's test again.
+ * - "ignore": Program continues on, ignoring this assertion failure this time.
+ * - "always_ignore": Program continues on, ignoring this assertion failure for the rest of the run.
+ *
+ * Note that SDL_SetAssertionHandler offers a programmatic means to deal with
+ * assertion failures through a callback, and this hint is largely intended to
+ * be used via environment variables by end users and automated tools.
+ *
+ * This hint should be set before an assertion failure is triggered and can
+ * be changed at any time.
+ *
+ * \since This hint is available since SDL 3.0.0.
+ */
+#define SDL_HINT_ASSERT "SDL_ASSERT"
+
+
 /**
  * An enumeration of hint priorities.
  *

src/SDL_assert.c

@@ -149,7 +149,6 @@ static SDL_NORETURN void SDL_AbortAssertion(void)
 
 static SDL_AssertState SDLCALL SDL_PromptAssertion(const SDL_AssertData *data, void *userdata)
 {
-    const char *envr;
     SDL_AssertState state = SDL_ASSERTION_ABORT;
     SDL_Window *window;
     SDL_MessageBoxData messagebox;
@@ -197,21 +196,21 @@ static SDL_AssertState SDLCALL SDL_PromptAssertion(const SDL_AssertData *data, v
     debug_print("\n\n%s\n\n", message);
 
     /* let env. variable override, so unit tests won't block in a GUI. */
-    envr = SDL_getenv("SDL_ASSERT");
+    const char *hint = SDL_GetHint(SDL_HINT_ASSERT);
-    if (envr) {
+    if (hint) {
         if (message != stack_buf) {
             SDL_free(message);
         }
 
-        if (SDL_strcmp(envr, "abort") == 0) {
+        if (SDL_strcmp(hint, "abort") == 0) {
             return SDL_ASSERTION_ABORT;
-        } else if (SDL_strcmp(envr, "break") == 0) {
+        } else if (SDL_strcmp(hint, "break") == 0) {
             return SDL_ASSERTION_BREAK;
-        } else if (SDL_strcmp(envr, "retry") == 0) {
+        } else if (SDL_strcmp(hint, "retry") == 0) {
             return SDL_ASSERTION_RETRY;
-        } else if (SDL_strcmp(envr, "ignore") == 0) {
+        } else if (SDL_strcmp(hint, "ignore") == 0) {
             return SDL_ASSERTION_IGNORE;
-        } else if (SDL_strcmp(envr, "always_ignore") == 0) {
+        } else if (SDL_strcmp(hint, "always_ignore") == 0) {
             return SDL_ASSERTION_ALWAYS_IGNORE;
         } else {
             return SDL_ASSERTION_ABORT; /* oh well. */