include/SDL_log.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 31 Dec 2011 09:28:07 -0500
changeset 6138 4c64952a58fb
parent 6038 3e0f5912363d
child 6616 4f272256d172
permissions -rw-r--r--
Happy New Year!
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2012 Sam Lantinga <slouken@libsdl.org>
     4 
     5   This software is provided 'as-is', without any express or implied
     6   warranty.  In no event will the authors be held liable for any damages
     7   arising from the use of this software.
     8 
     9   Permission is granted to anyone to use this software for any purpose,
    10   including commercial applications, and to alter it and redistribute it
    11   freely, subject to the following restrictions:
    12 
    13   1. The origin of this software must not be misrepresented; you must not
    14      claim that you wrote the original software. If you use this software
    15      in a product, an acknowledgment in the product documentation would be
    16      appreciated but is not required.
    17   2. Altered source versions must be plainly marked as such, and must not be
    18      misrepresented as being the original software.
    19   3. This notice may not be removed or altered from any source distribution.
    20 */
    21 
    22 /**
    23  *  \file SDL_log.h
    24  *  
    25  *  Simple log messages with categories and priorities.
    26  *
    27  *  By default logs are quiet, but if you're debugging SDL you might want:
    28  *
    29  *      SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
    30  *
    31  *  Here's where the messages go on different platforms:
    32  *      Windows: debug output stream
    33  *      Android: log output
    34  *      Others: standard error output (stderr)
    35  */
    36 
    37 #ifndef _SDL_log_h
    38 #define _SDL_log_h
    39 
    40 #include "SDL_stdinc.h"
    41 
    42 #include "begin_code.h"
    43 /* Set up for C function definitions, even when using C++ */
    44 #ifdef __cplusplus
    45 /* *INDENT-OFF* */
    46 extern "C" {
    47 /* *INDENT-ON* */
    48 #endif
    49 
    50 
    51 /**
    52  *  \brief The maximum size of a log message
    53  *
    54  *  Messages longer than the maximum size will be truncated
    55  */
    56 #define SDL_MAX_LOG_MESSAGE 4096
    57 
    58 /**
    59  *  \brief The predefined log categories
    60  *
    61  *  By default the application category is enabled at the INFO level,
    62  *  and all other categories are enabled at the CRITICAL level.
    63  */
    64 enum
    65 {
    66     SDL_LOG_CATEGORY_APPLICATION,
    67     SDL_LOG_CATEGORY_ERROR,
    68     SDL_LOG_CATEGORY_SYSTEM,
    69     SDL_LOG_CATEGORY_AUDIO,
    70     SDL_LOG_CATEGORY_VIDEO,
    71     SDL_LOG_CATEGORY_RENDER,
    72     SDL_LOG_CATEGORY_INPUT,
    73 
    74     /* Reserved for future SDL library use */
    75     SDL_LOG_CATEGORY_RESERVED1,
    76     SDL_LOG_CATEGORY_RESERVED2,
    77     SDL_LOG_CATEGORY_RESERVED3,
    78     SDL_LOG_CATEGORY_RESERVED4,
    79     SDL_LOG_CATEGORY_RESERVED5,
    80     SDL_LOG_CATEGORY_RESERVED6,
    81     SDL_LOG_CATEGORY_RESERVED7,
    82     SDL_LOG_CATEGORY_RESERVED8,
    83     SDL_LOG_CATEGORY_RESERVED9,
    84     SDL_LOG_CATEGORY_RESERVED10,
    85 
    86     /* Beyond this point is reserved for application use, e.g.
    87        enum {
    88            MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM,
    89            MYAPP_CATEGORY_AWESOME2,
    90            MYAPP_CATEGORY_AWESOME3,
    91            ...
    92        };
    93      */
    94     SDL_LOG_CATEGORY_CUSTOM
    95 };
    96 
    97 /**
    98  *  \brief The predefined log priorities
    99  */
   100 typedef enum
   101 {
   102     SDL_LOG_PRIORITY_VERBOSE = 1,
   103     SDL_LOG_PRIORITY_DEBUG,
   104     SDL_LOG_PRIORITY_INFO,
   105     SDL_LOG_PRIORITY_WARN,
   106     SDL_LOG_PRIORITY_ERROR,
   107     SDL_LOG_PRIORITY_CRITICAL,
   108     SDL_NUM_LOG_PRIORITIES
   109 } SDL_LogPriority;
   110 
   111 
   112 /**
   113  *  \brief Set the priority of all log categories
   114  */
   115 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
   116 
   117 /**
   118  *  \brief Set the priority of a particular log category
   119  */
   120 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
   121                                                 SDL_LogPriority priority);
   122 
   123 /**
   124  *  \brief Get the priority of a particular log category
   125  */
   126 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
   127 
   128 /**
   129  *  \brief Reset all priorities to default.
   130  *
   131  *  \note This is called in SDL_Quit().
   132  */
   133 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
   134 
   135 /**
   136  *  \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
   137  */
   138 extern DECLSPEC void SDLCALL SDL_Log(const char *fmt, ...);
   139 
   140 /**
   141  *  \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
   142  */
   143 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, const char *fmt, ...);
   144 
   145 /**
   146  *  \brief Log a message with SDL_LOG_PRIORITY_DEBUG
   147  */
   148 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, const char *fmt, ...);
   149 
   150 /**
   151  *  \brief Log a message with SDL_LOG_PRIORITY_INFO
   152  */
   153 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, const char *fmt, ...);
   154 
   155 /**
   156  *  \brief Log a message with SDL_LOG_PRIORITY_WARN
   157  */
   158 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, const char *fmt, ...);
   159 
   160 /**
   161  *  \brief Log a message with SDL_LOG_PRIORITY_ERROR
   162  */
   163 extern DECLSPEC void SDLCALL SDL_LogError(int category, const char *fmt, ...);
   164 
   165 /**
   166  *  \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
   167  */
   168 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, const char *fmt, ...);
   169 
   170 /**
   171  *  \brief Log a message with the specified category and priority.
   172  */
   173 extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
   174                                             SDL_LogPriority priority,
   175                                             const char *fmt, ...);
   176 
   177 /**
   178  *  \brief Log a message with the specified category and priority.
   179  */
   180 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
   181                                              SDL_LogPriority priority,
   182                                              const char *fmt, va_list ap);
   183 
   184 /**
   185  *  \brief The prototype for the log output function
   186  */
   187 typedef void (*SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
   188 
   189 /**
   190  *  \brief Get the current log output function.
   191  */
   192 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
   193 
   194 /**
   195  *  \brief This function allows you to replace the default log output
   196  *         function with one of your own.
   197  */
   198 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
   199 
   200 
   201 /* Ends C function definitions when using C++ */
   202 #ifdef __cplusplus
   203 /* *INDENT-OFF* */
   204 }
   205 /* *INDENT-ON* */
   206 #endif
   207 #include "close_code.h"
   208 
   209 #endif /* _SDL_log_h */
   210 
   211 /* vi: set ts=4 sw=4 expandtab: */