SDLログハンドリング - ぺんぎんノート

本記事は、SDL(Simple DirectMedia Layer)のログ出力機能の仕様について調べた結果である。

SDLのバージョンは記事執筆時の最新である2.0.20を対象とする。

また、Windows 10でVisual Studio Community 2017で試した。(すべてをテストしたわけではない)

SDLログ出力機能

SDLログ出力は、priority x categoryの組み合わせでログ出力を制御できる。
categoryとpriorityでログ出力を制御できることのメリットは、以下の2点であると考えられる。

ログ出力を細かく分類して出力するか選択することができる
priorityはソフト動作中も変更できるため動的にログ出力を変更することができる

priority

priorityはログ出力のレベルである。ソースコードに埋め込むログはpriority毎に関数が用意されている。

SDL_LogPriority	ログ出力関数
SDL_LOG_PRIORITY_VERBOSE	SDL_LogVerbose(int category, format, ...)
SDL_LOG_PRIORITY_DEBUG	SDL_LogDebug(int category, format, ...)
SDL_LOG_PRIORITY_INFO	SDL_LogInfo(int category, format, ...)
SDL_LOG_PRIORITY_WARN	SDL_LogWarn(category, format, ...)
SDL_LOG_PRIORITY_ERROR	SDL_LogError(category, format, ...)
SDL_LOG_PRIORITY_CRITICAL	SDL_LogCritical(category, format, ...)

category

categoryはログ出力の種類である。SDL_Log***()関数の第一引数でpriority毎にcategoryを設定できる。ログは以下のフォーマットでログ出力される。
(出力先はVisual Studioであればデバッグ出力(出力ウィンドウ)に出力される)

category : message

categoryには、次の種類がある。それぞれデフォルトpriorityが設定されている。

SDL_LOG_CATEGORY	デフォルトpriority	説明
SDL_LOG_CATEGORY_APPLICATION	SDL_LOG_PRIORITY_INFO	application log
SDL_LOG_CATEGORY_ERROR	SDL_LOG_PRIORITY_CRITICAL	error log
SDL_LOG_CATEGORY_SYSTEM	SDL_LOG_PRIORITY_CRITICAL	system log
SDL_LOG_CATEGORY_AUDIO	SDL_LOG_PRIORITY_CRITICAL	audio log
SDL_LOG_CATEGORY_VIDEO	SDL_LOG_PRIORITY_CRITICAL	video log
SDL_LOG_CATEGORY_RENDER	SDL_LOG_PRIORITY_CRITICAL	render log
SDL_LOG_CATEGORY_INPUT	SDL_LOG_PRIORITY_CRITICAL	input log
SDL_LOG_CATEGORY_TEST	SDL_LOG_PRIORITY_CRITICAL	test log
SDL_LOG_CATEGORY_RESERVED	SDL_LOG_PRIORITY_CRITICAL	SDL_Libraryの予約領域
SDL_LOG_CATEGORY_CUSTOM	SDL_LOG_PRIORITY_CRITICAL	アプリケーション用に予約されたログ出力 (アプリケーション側のログ出力機能があればそれに合わせて使用する)
SDL_LOG_CATEGORY_ASSERT	SDL_LOG_PRIORITY_WARN	assert log
SDL_LOG_CATEGORY_TEST	SDL_LOG_PRIORITY_VERBOSE	verbose log

出力するログ出力を制御

出力するpriorityとcategoryの組み合わせは以下の関数で設定する。categoryとpriorityの組み合わせが一致したログのみが出力される。

void SDL_LogSetPriority(int category,
                        SDL_LogPriority priority);

例えば、

SDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_ERROR);    //(1) priority = errorにセット

SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "this is information");    //(2) priority = information
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "this is error");    //(3) priority = error

(1)では、category = applicationにpriority = errorを設定している。
(2)(3)の2つのログ出力をソースコード中に埋め込んでいるとする。
どちらもcategory=applicationであるが、priorityが異なる。

このとき、
(2) : ログ出力されない
(3) : ログ出力される
となる。

(1)に対してSDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_INFO)を呼び出し、priority = informationにセットすると、逆に
(2) : ログ出力される
(3) : ログ出力されない
となる。
ソフト起動中にもpriorityは設定しなおせるため、ソフト起動中もログ出力を変更することができる。

便利な関数

関数	説明
SDL_LogSetAllPriority(SDL_LogPriority priority)	すべてのcategoryに一括で同じpriorityを設定する
SDL_LogResetPriorities(void)	すべてのcategoryのpriorityをデフォルトに戻す
SDL_LogGetPriority(int category)	categoryに設定されているpriorityを取得する
SDL_Log(format, ...)	categoryとpriorityを気にせずログ出力をする場合に使う。SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, fmt, ...)と同じである