From 291edc073c9dead7bd11c32daea23f1bc8d826bc Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Sun, 14 Apr 2024 01:46:42 -0400 Subject: [PATCH] include: Document SDL_TriggerBreakpoint. --- include/SDL3/SDL_assert.h | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 4c16174e3..394d6c7e7 100644 --- a/include/SDL3/SDL_assert.h +++ b/include/SDL3/SDL_assert.h @@ -47,14 +47,32 @@ extern "C" { #endif #endif /* SDL_ASSERT_LEVEL */ -/* -These are macros and not first class functions so that the debugger breaks -on the assertion line and not in some random guts of SDL, and so each -assert can have unique static variables associated with it. -*/ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * Attempt to tell an attached debugger to pause. + * + * This allows an app to programmatically halt ("break") the debugger + * as if it had hit a breakpoint, allowing the developer to examine + * program state, etc. + * + * This is a macro and not first class functions so that the debugger + * breaks on the source code line that used SDL_TriggerBreakpoint and + * not in some random guts of SDL. SDL_assert uses this macro for the + * same reason. + * + * If the program is not running under a debugger, SDL_TriggerBreakpoint + * will likely terminate the app, possibly without warning. If the + * current platform isn't supported (SDL doesn't know how to trigger a + * breakpoint), this macro does nothing. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) -#ifdef _MSC_VER -/* Don't include intrin.h here because it contains C++ code */ +#elif defined(_MSC_VER) + /* Don't include intrin.h here because it contains C++ code */ extern void __cdecl __debugbreak(void); #define SDL_TriggerBreakpoint() __debugbreak() #elif defined(ANDROID)