include/SDL_assert.h
changeset 3670 62b6a5b99918
parent 3668 6952d2b783e6
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_assert.h	Wed Jan 13 16:58:24 2010 +0000
     1.2 +++ b/include/SDL_assert.h	Wed Jan 13 19:29:33 2010 +0000
     1.3 @@ -109,7 +109,7 @@
     1.4      const char *filename;
     1.5      int linenum;
     1.6      const char *function;
     1.7 -    struct SDL_assert_data *next;
     1.8 +    const struct SDL_assert_data *next;
     1.9  } SDL_assert_data;
    1.10  
    1.11  /* Never call this directly. Use the SDL_assert* macros. */
    1.12 @@ -166,6 +166,68 @@
    1.13  #   error Unknown assertion level.
    1.14  #endif
    1.15  
    1.16 +
    1.17 +typedef SDL_assert_state (SDLCALL *SDL_AssertionHandler)(
    1.18 +                                    const SDL_assert_data *, void *userdata);
    1.19 +
    1.20 +/**
    1.21 + *  \brief Set an application-defined assertion handler.
    1.22 + *
    1.23 + *  This allows an app to show its own assertion UI and/or force the
    1.24 + *  response to an assertion failure. If the app doesn't provide this, SDL
    1.25 + *  will try to do the right thing, popping up a system-specific GUI dialog,
    1.26 + *  and probably minimizing any fullscreen windows.
    1.27 + *
    1.28 + *  This callback may fire from any thread, but it runs wrapped in a mutex, so
    1.29 + *  it will only fire from one thread at a time.
    1.30 + *
    1.31 + *  Setting the callback to NULL restores SDL's original internal handler.
    1.32 + *
    1.33 + *  This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
    1.34 + *
    1.35 + *  \return SDL_assert_state value of how to handle the assertion failure.
    1.36 + *  
    1.37 + *  \param handler Callback function, called when an assertion fails.
    1.38 + *  \param userdata A pointer passed to the callback as-is.
    1.39 + */
    1.40 +extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
    1.41 +                                            SDL_AssertionHandler handler,
    1.42 +                                            void *userdata);
    1.43 +
    1.44 +/**
    1.45 + *  \brief Get a list of all assertion failures.
    1.46 + *
    1.47 + *  Get all assertions triggered since last call to SDL_ResetAssertionReport(),
    1.48 + *  or the start of the program.
    1.49 + *
    1.50 + *  The proper way to examine this data looks something like this:
    1.51 + *
    1.52 + *  <code>
    1.53 + *  const SDL_assert_data *item = SDL_GetAssertionReport();
    1.54 + *  while (item->condition) {
    1.55 + *      printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\n",
    1.56 + *             item->condition, item->function, item->filename,
    1.57 + *             item->linenum, item->trigger_count,
    1.58 + *             item->always_ignore ? "yes" : "no");
    1.59 + *      item = item->next;
    1.60 + *  }
    1.61 + *  </code>
    1.62 + *
    1.63 + *  \return List of all assertions. This never returns NULL,
    1.64 + *          even if there are no items.
    1.65 + *  \sa SDL_ResetAssertionReport
    1.66 + */
    1.67 +extern DECLSPEC const SDL_assert_data * SDLCALL SDL_GetAssertionReport(void);
    1.68 +
    1.69 +/**
    1.70 + *  \brief Reset the list of all assertion failures.
    1.71 + *
    1.72 + *  Reset list of all assertions triggered.
    1.73 + *
    1.74 + *  \sa SDL_GetAssertionReport
    1.75 + */
    1.76 +extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
    1.77 +
    1.78  /* Ends C function definitions when using C++ */
    1.79  #ifdef __cplusplus
    1.80  /* *INDENT-OFF* */