|
1 | 1 | /* |
2 | 2 | Simple DirectMedia Layer |
3 | | - Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org> |
| 3 | + Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org> |
4 | 4 |
|
5 | 5 | This software is provided 'as-is', without any express or implied |
6 | 6 | warranty. In no event will the authors be held liable for any damages |
@@ -53,8 +53,10 @@ assert can have unique static variables associated with it. |
53 | 53 | #define SDL_TriggerBreakpoint() __debugbreak() |
54 | 54 | #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) ) |
55 | 55 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) |
56 | | -#elif ( defined(__APPLE__) && defined(__arm64__) ) /* this might work on other ARM targets, but this is a known quantity... */ |
| 56 | +#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */ |
57 | 57 | #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) |
| 58 | +#elif defined(__APPLE__) && defined(__arm__) |
| 59 | + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) |
58 | 60 | #elif defined(__386__) && defined(__WATCOMC__) |
59 | 61 | #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } |
60 | 62 | #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) |
@@ -187,92 +189,121 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *, |
187 | 189 | #define SDL_assert_always(condition) SDL_enabled_assert(condition) |
188 | 190 |
|
189 | 191 |
|
| 192 | +/** |
| 193 | + * A callback that fires when an SDL assertion fails. |
| 194 | + * |
| 195 | + * \param data a pointer to the SDL_AssertData structure corresponding to the |
| 196 | + * current assertion |
| 197 | + * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler() |
| 198 | + * \returns an SDL_AssertState value indicating how to handle the failure. |
| 199 | + */ |
190 | 200 | typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( |
191 | 201 | const SDL_AssertData* data, void* userdata); |
192 | 202 |
|
193 | 203 | /** |
194 | | - * \brief Set an application-defined assertion handler. |
| 204 | + * Set an application-defined assertion handler. |
195 | 205 | * |
196 | | - * This allows an app to show its own assertion UI and/or force the |
197 | | - * response to an assertion failure. If the app doesn't provide this, SDL |
198 | | - * will try to do the right thing, popping up a system-specific GUI dialog, |
199 | | - * and probably minimizing any fullscreen windows. |
| 206 | + * This function allows an application to show its own assertion UI and/or |
| 207 | + * force the response to an assertion failure. If the application doesn't |
| 208 | + * provide this, SDL will try to do the right thing, popping up a |
| 209 | + * system-specific GUI dialog, and probably minimizing any fullscreen windows. |
200 | 210 | * |
201 | | - * This callback may fire from any thread, but it runs wrapped in a mutex, so |
202 | | - * it will only fire from one thread at a time. |
| 211 | + * This callback may fire from any thread, but it runs wrapped in a mutex, so |
| 212 | + * it will only fire from one thread at a time. |
203 | 213 | * |
204 | | - * Setting the callback to NULL restores SDL's original internal handler. |
| 214 | + * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! |
205 | 215 | * |
206 | | - * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! |
| 216 | + * \param handler the SDL_AssertionHandler function to call when an assertion |
| 217 | + * fails or NULL for the default handler |
| 218 | + * \param userdata a pointer that is passed to `handler` |
207 | 219 | * |
208 | | - * Return SDL_AssertState value of how to handle the assertion failure. |
| 220 | + * \since This function is available since SDL 2.0.0. |
209 | 221 | * |
210 | | - * \param handler Callback function, called when an assertion fails. |
211 | | - * \param userdata A pointer passed to the callback as-is. |
| 222 | + * \sa SDL_GetAssertionHandler |
212 | 223 | */ |
213 | 224 | extern DECLSPEC void SDLCALL SDL_SetAssertionHandler( |
214 | 225 | SDL_AssertionHandler handler, |
215 | 226 | void *userdata); |
216 | 227 |
|
217 | 228 | /** |
218 | | - * \brief Get the default assertion handler. |
| 229 | + * Get the default assertion handler. |
219 | 230 | * |
220 | | - * This returns the function pointer that is called by default when an |
221 | | - * assertion is triggered. This is an internal function provided by SDL, |
222 | | - * that is used for assertions when SDL_SetAssertionHandler() hasn't been |
223 | | - * used to provide a different function. |
| 231 | + * This returns the function pointer that is called by default when an |
| 232 | + * assertion is triggered. This is an internal function provided by SDL, that |
| 233 | + * is used for assertions when SDL_SetAssertionHandler() hasn't been used to |
| 234 | + * provide a different function. |
224 | 235 | * |
225 | | - * \return The default SDL_AssertionHandler that is called when an assert triggers. |
| 236 | + * \returns the default SDL_AssertionHandler that is called when an assert |
| 237 | + * triggers. |
| 238 | + * |
| 239 | + * \since This function is available since SDL 2.0.2. |
| 240 | + * |
| 241 | + * \sa SDL_GetAssertionHandler |
226 | 242 | */ |
227 | 243 | extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void); |
228 | 244 |
|
229 | 245 | /** |
230 | | - * \brief Get the current assertion handler. |
| 246 | + * Get the current assertion handler. |
| 247 | + * |
| 248 | + * This returns the function pointer that is called when an assertion is |
| 249 | + * triggered. This is either the value last passed to |
| 250 | + * SDL_SetAssertionHandler(), or if no application-specified function is set, |
| 251 | + * is equivalent to calling SDL_GetDefaultAssertionHandler(). |
231 | 252 | * |
232 | | - * This returns the function pointer that is called when an assertion is |
233 | | - * triggered. This is either the value last passed to |
234 | | - * SDL_SetAssertionHandler(), or if no application-specified function is |
235 | | - * set, is equivalent to calling SDL_GetDefaultAssertionHandler(). |
| 253 | + * The parameter `puserdata` is a pointer to a void*, which will store the |
| 254 | + * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value |
| 255 | + * will always be NULL for the default handler. If you don't care about this |
| 256 | + * data, it is safe to pass a NULL pointer to this function to ignore it. |
236 | 257 | * |
237 | | - * \param puserdata Pointer to a void*, which will store the "userdata" |
238 | | - * pointer that was passed to SDL_SetAssertionHandler(). |
239 | | - * This value will always be NULL for the default handler. |
240 | | - * If you don't care about this data, it is safe to pass |
241 | | - * a NULL pointer to this function to ignore it. |
242 | | - * \return The SDL_AssertionHandler that is called when an assert triggers. |
| 258 | + * \param puserdata pointer which is filled with the "userdata" pointer that |
| 259 | + * was passed to SDL_SetAssertionHandler() |
| 260 | + * \returns the SDL_AssertionHandler that is called when an assert triggers. |
| 261 | + * |
| 262 | + * \since This function is available since SDL 2.0.2. |
| 263 | + * |
| 264 | + * \sa SDL_SetAssertionHandler |
243 | 265 | */ |
244 | 266 | extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata); |
245 | 267 |
|
246 | 268 | /** |
247 | | - * \brief Get a list of all assertion failures. |
| 269 | + * Get a list of all assertion failures. |
| 270 | + * |
| 271 | + * This function gets all assertions triggered since the last call to |
| 272 | + * SDL_ResetAssertionReport(), or the start of the program. |
248 | 273 | * |
249 | | - * Get all assertions triggered since last call to SDL_ResetAssertionReport(), |
250 | | - * or the start of the program. |
| 274 | + * The proper way to examine this data looks something like this: |
251 | 275 | * |
252 | | - * The proper way to examine this data looks something like this: |
| 276 | + * ```c |
| 277 | + * const SDL_AssertData *item = SDL_GetAssertionReport(); |
| 278 | + * while (item) { |
| 279 | + * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", |
| 280 | + * item->condition, item->function, item->filename, |
| 281 | + * item->linenum, item->trigger_count, |
| 282 | + * item->always_ignore ? "yes" : "no"); |
| 283 | + * item = item->next; |
| 284 | + * } |
| 285 | + * ``` |
253 | 286 | * |
254 | | - * <code> |
255 | | - * const SDL_AssertData *item = SDL_GetAssertionReport(); |
256 | | - * while (item) { |
257 | | - * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", |
258 | | - * item->condition, item->function, item->filename, |
259 | | - * item->linenum, item->trigger_count, |
260 | | - * item->always_ignore ? "yes" : "no"); |
261 | | - * item = item->next; |
262 | | - * } |
263 | | - * </code> |
| 287 | + * \returns a list of all failed assertions or NULL if the list is empty. This |
| 288 | + * memory should not be modified or freed by the application. |
264 | 289 | * |
265 | | - * \return List of all assertions. |
266 | | - * \sa SDL_ResetAssertionReport |
| 290 | + * \since This function is available since SDL 2.0.0. |
| 291 | + * |
| 292 | + * \sa SDL_ResetAssertionReport |
267 | 293 | */ |
268 | 294 | extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); |
269 | 295 |
|
270 | 296 | /** |
271 | | - * \brief Reset the list of all assertion failures. |
| 297 | + * Clear the list of all assertion failures. |
| 298 | + * |
| 299 | + * This function will clear the list of all assertions triggered up to that |
| 300 | + * point. Immediately following this call, SDL_GetAssertionReport will return |
| 301 | + * no items. In addition, any previously-triggered assertions will be reset to |
| 302 | + * a trigger_count of zero, and their always_ignore state will be false. |
272 | 303 | * |
273 | | - * Reset list of all assertions triggered. |
| 304 | + * \since This function is available since SDL 2.0.0. |
274 | 305 | * |
275 | | - * \sa SDL_GetAssertionReport |
| 306 | + * \sa SDL_GetAssertionReport |
276 | 307 | */ |
277 | 308 | extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); |
278 | 309 |
|
|
0 commit comments