最終更新: 2016.11.11

※このページは公式の文書ではなく、 開発者側の認可を受けたものでもありません。 実際の使用方法に関しては、 公式ウェブページや配布パッケージ内の文書などをご確認ください。

sdl-1.2.15

SDL = Simple Direct media Layer, バージョン1.2

概要

名称SDL
バージョン1.2.15
説明ゲームアプリケーション向けのマルチプラットフォームなライブラリ
プログラミング言語C
プロジェクトページhttps://www.libsdl.org/

ドキュメント

ソース

リファレンス

全般

SDLはプログラムで使用することができるようになる前に、 SDL_Initによって初期化する必要があります。 SDL_Initはユーザが要求する、すべてのサブシステム( ビデオ、オーディオ、ジョイスティック、タイマー、そして CD-ROM) を初期化します。 SDL が、一旦、SDL_Init によって初期化されるならば、 サブシステムは必要に応じて、SDL_InitSubSystem と SDL_QuitSubSystem を用いてシャットダウンと初期化をすることができます。

SDLは、正しくクリーンアップするのを確実に行うために、 プログラムを終了する前にシャットダウンする必要もあります。 SDL_Quitを呼び出すことは、すべてのサブシステムをシャットダウンし、 SDLに割り当てられた任意のリソースを解放します。

SDL_InitSDLを初期化する
SDL_InitSubSystemサブシステムを初期化する
SDL_QuitSubSystemサブシステムを終了する
SDL_QuitSDLを終了する
SDL_WasInitサブシステムが初期化されたかの確認をする
SDL_GetErrorSDLエラー文字列を得る
SDL_envvarsSDL環境変数

ビデオ

SDLにはディスプレイ・フレームバッファへの非常に単純なインターフェースが存在します。 フレームバッファは、あなたが直接書き込むことができることのための オフスクリーン・サーフェスとして表現されます。 書き込んだ内容をスクリーンに表示したいならば、 スクリーンの望ましい位置が更新されることを保証するアップデート関数を呼び出してください。

どんなSDLビデオ関数でも呼び出す前に、 SDL_Init(SDL_INIT_VIDEO)を最初に呼び出す必要があります。 これは、SDLライブラリでビデオとイベントを初期化します。 開始するまでに任意のエラーがあるかどうかを見るために、 返り値コードが 0 になっているかを確認してください。

アプリケーションでサウンドとビデオの両方を使用する場合、 サウンドデバイスをオープンする前に、 SDL_Init(SDL_INIT_AUDIO | SDL_INIT_VIDEO)を呼び出す必要があります。 さもなければ、Win32 DirectXでは、 フルスクリーン・ディスプレイ・モードをセットすることができないでしょう。

ライブラリを初期化したあとで、いくつかの方法でビデオ・ディスプレイを 開始することができます。 最も簡単な方法は、一般的なスクリーン解像度と depth を選択して、ビデオを初期化し、エラーを確認することです。 あなたは、たぶん欲しいものを得るでしょう。 しかし、SDL は要求されたモードを エミュレートし、ディスプレイの更新で変換を行なっているかもしれません。 最高の方法は、望ましいビデオモードに一番近い最高のものを問い合わせることで、 そのピクセルフォーマットに、あなたのイメージを変換してください。

SDLは、現在、8 bits per pixel 以上の任意の bit depth をサポートします。 8bppフォーマットは、8bit palettized modes とみなされる、一方で、 12, 15, 16, 24, そして 32 bit per pixel は、 各ピクセルが、ピクセルのビットの中にパックされる RGB カラー成分を 含むことを意味している、"packed pixel" モードとみなされます。

ビデオモードを初期化したあと、あなたは返されたサーフェスを取ることができ、 他のどのフレームバッファと同様に書き込み、更新ルーチンを呼び出してください。

ビデオ・アクセスを完了し、アプリケーションを終了する準備ができているとき、 あなたは ビデオとイベントをシャットダウンするために "SDL_Quit()" を 呼び出すべきです。

SDL_GetVideoSurface現在のディスプレイ・サーフェスを返す
SDL_GetVideoInfoビデオ・ハードウェアについての情報を返す
SDL_VideoDriverNameビデオ・ドライバの名前を得る
SDL_ListModes指定されたフォーマットとビデオフラグに基づく利用可能なスクリーン解像度を返します
SDL_VideoModeOK特定のビデオモードがサポートされるかどうかを確認する
SDL_SetVideoMode指定の幅、高さ、bits-per-pixelでビデオモードをセットアップする
SDL_UpdateRect与えられたエリアが与えられたスクリーン上で更新する
SDL_UpdateRects与えられた矩形のリストが与えられたスクリーン上で更新する
SDL_Flipスクリーンバッファをスワップする
SDL_SetColors与えられた8ビット・サーフェスのカラーマップの一部を設定する
SDL_SetPalette8ビット・サーフェスのパレットで色を設定する
SDL_SetGammaディスプレイのために色ガンマ関数を設定する
SDL_GetGammaRampディスプレイのために色ガンマ検索テーブルを得る
SDL_SetGammaRampディスプレイのために色ガンマ検索テーブルを設定する
SDL_MapRGBピクセル・フォーマットへRGBカラー値をマップする
SDL_MapRGBAピクセル・フォーマットへRGBAカラー値をマップする
SDL_GetRGB指定のピクセル・フォーマットでピクセルからRGB値を得る
SDL_GetRGBA指定のピクセル・フォーマットでピクセルからRGBA値を得る
SDL_CreateRGBSurface空の SDL_Surface を生成する
SDL_CreateRGBSurfaceFromピクセルデータから SDL_Surface を生成する
SDL_FreeSurfaceSDL_Surface を解放(削除)する
SDL_LockSurface直接アクセスのためにサーフェスをロックする
SDL_UnlockSurface以前にロックされたサーフェスをアンロックする
SDL_LoadBMPSDL_Surface へ Windows BMP ファイルをロードする
SDL_SaveBMPWindows BMP ファイルとして SDL_Surface をセーブする
SDL_SetColorKey転送可能なサーフェスとRLEアクセラレーションでカラーキー(透明ピクセル)を設定する
SDL_SetAlphaサーフェスのアルファ・プロパティを調整する
SDL_SetClipRectサーフェスのクリッピング領域を設定する
SDL_GetClipRectサーフェスのクリッピング領域を得る
SDL_ConvertSurface別のサーフェスとして同じフォーマットにサーフェスを変換する
SDL_BlitSurfaceこれは転送元サーフェスから転送先サーフェスに高速なブリットを実行します
SDL_FillRectこの関数はいくつかの色で与えられた矩形の高速な塗りつぶしを実行します
SDL_DisplayFormatディスプレイ・フォーマットへサーフェスを変換します
SDL_DisplayFormatAlphaディスプレイ・フォーマットへサーフェスを変換します
SDL_WarpMouseマウスカーソルの位置を設置する
SDL_CreateCursor新しいマウスカーソルを生成する
SDL_FreeCursorSDL_CreateCursor で生成されたカーソルを解放する
SDL_SetCursor現在のアクティブなマウスカーソルを設定する
SDL_GetCursor現在のアクティブなマウスカーソルを得る
SDL_ShowCursorカーソルがスクリーンで表示するかどうかを切り替える
SDL_GL_LoadLibraryOpenGLライブラリを指定する
SDL_GL_GetProcAddressGL関数のアドレスを得る
SDL_GL_GetAttribute特殊なSDL/OpenGL属性の値を得る
SDL_GL_SetAttribute特殊なSDL/OpenGL属性を設定する
SDL_GL_SwapBuffersOpenGLフレームバッファをスワップ/ディスプレイを更新する
SDL_CreateYUVOverlayYUVビデオ・オーバーレイを生成する
SDL_LockYUVOverlayオーバーレイをロックする
SDL_UnlockYUVOverlayオーバーレイをアンロックする
SDL_DisplayYUVOverlayディスプレイにオーバーレイを転送する
SDL_FreeYUVOverlayYUVビデオ・オーバーレイを解放する
SDL_GLattrSDL GL属性
SDL_Rect矩形領域を定義する
SDL_Colorフォーマット非依存のカラー記述
SDL_Palette8ビットピクセルフォーマットのためのカラーパレット
SDL_PixelFormatサーフェス・フォーマット情報を格納する
SDL_Surfaceグラフィカル・サーフェス構造体
SDL_VideoInfoビデオ・ターゲット情報
SDL_OverlayYUVビデオ・オーバーレイ

ウィンドウ管理

SDLは、ウィンドウ管理関数の小さなセットを提供します。 これは、アプリケーションが、そのタイトルを変更し、 ウィンドウ・モードからフルスクリーンへトグルする(利用可能であるならば) ことが可能です。

SDL_WM_SetCaptionウィンドウのタイルとアイコンの名前を設定する
SDL_WM_GetCaptionウィンドウのタイトルとアイコンの名前を得る
SDL_WM_SetIconディスプレイ・ウィンドウのためのアイコンを設定する
SDL_WM_IconifyWindowウィンドウをアイコン化/最小化する
SDL_WM_ToggleFullScreenフルスクリーンモードをトグルする
SDL_WM_GrabInputマウスとキーボード入力をグラブする

イベント

イベント処理は、あなたのアプリケーションに、 ユーザからの入力を受け取ることを可能にします。 イベント処理は以下への呼び出しによって(ビデオと一緒に) 初期化されます:

SDL_Init(SDL_INIT_VIDEO);

内部的に、SDLはイベントキューで処理されることを待っているすべてのイベントを 格納します。 SDL_PollEvent と SDL_PeepEvent のような関数を使うことは、 待機している入力イベントを監視し処理することができます。

SDLにおけるイベント処理のキーは、SDL_Event共用体です。 イベントキューそれ自身は、待機している各イベントのための 一連のSDL_Event共用体から構成されています。 SDL_Event unions are read from the queue with the SDL_PollEvent function and it is then up to the application to process the information stored with them.

SDL_PumpEvents入力デバイスからイベントを集めているイベントループをポンプします
SDL_PeepEventsイベントキューを確認します
SDL_PollEvent現在、保留しているイベントをポーリングします
SDL_WaitEvent次に利用可能なイベントまで無期限に待ちます
SDL_PushEventイベントキューにイベントをプッシュします
SDL_SetEventFilterイベントキューへポストされる前に、すべてのイベントを処理するフィルタをセットアップします
SDL_GetEventFilterイベントフィルタへのポインタを得ます
SDL_EventState-
SDL_GetKeyState現在のキーボード状態のスナップショットを取得します
SDL_GetModState修飾キーの状態を取得します
SDL_SetModState現在のキー修飾子状態を設定します
SDL_GetKeyNameSDL仮想キーシンボルの名前を取得します
SDL_EnableUNICODEUNICODE変換を有効にします
SDL_EnableKeyRepeatキーボード・リピート・レートを設定します
SDL_GetMouseStateマウスの現在の状態を得ます
SDL_GetRelativeMouseState現在のマウスの状態を得ます
SDL_GetAppStateアプリケーションの状態を取得します
SDL_JoystickEventStateジョイスティック・イベントのポーリングを有効/無効にします
SDL_Event全般的なイベント構造体
SDL_ActiveEventアプリケーション可視化イベント構造体
SDL_KeyboardEventキーボード・イベント構造体
SDL_MouseMotionEventマウス動作イベント構造体
SDL_MouseButtonEventマウスボタン・イベント構造体
SDL_JoyAxisEventジョイスティック軸動作イベント構造体
SDL_JoyButtonEventジョイスティックボタン・イベント構造体
SDL_JoyHatEventジョイスティックハット位置変更イベント構造体
SDL_JoyBallEventジョイスティックトラックボール動作イベント構造体
SDL_ResizeEventウィンドウサイズ変更イベント構造体
SDL_ExposeEvent-
SDL_SysWMEventプラットフォーム依存のウィンドウマネージャ・イベント
SDL_UserEventユーザ定義イベント型
SDL_QuitEvent終了リクエスト・イベント
SDL_keysymキーシンボル構造体
SDLKeyキーシンボル定義

ジョイスティック

ジョイスティックと他の類似の入力デバイスは、 ゲーム・プレイングにおいて非常に重要な役割を持ち、 SDLはそれらのために包括的なサポートを提供します。 軸、ボタン、POV Hats そして、トラックボールは、 すべてサポートされます。

ジョイスティック・サポートは、SDL_Init に SDL_INIT_JOYSTICK フラグを 渡すことによって初期化されます。 一度、ジョイスティックが初期化されるならば、 SDL_JoystickOpen を用いてオープンする必要があります。

このセクションで述べている関数を使用する間、ジョイスティックへの アクセスと読み出すことの最高の方法に見えるかもしれませんが、 ほとんどの場合、そうではありません。 理想的には、ジョイスティックはイベント・システムを使って読み出されるべきです。 これを有効にするには、あなたは SDL_JoystickEventState で ジョイスティック・イベント処理状態をセットしなければなりません。 ジョイスティックは、もちろん、使用することができるようになる前に、 オープンされる必要があります。

注意: あなたがイベントキューを通してジョイスティックを処理していないならば、 あなたは SDL_JoystickUpdate を呼び出すことによって明示的に ジョイスティック更新を要求しなければなりません。

Note: Force Feedback is not yet support. Sam (slouken@libsdl.org) is soliciting suggestions from people with force-feedback experience on the best wat to desgin the API.

SDL_NumJoysticks利用可能なジョイスティックを数える
SDL_JoystickNameジョイスティックの名前を得る
SDL_JoystickOpen使用するためにジョイスティックをオープンする
SDL_JoystickOpenedジョイスティックがオープンされたかどうか判断する
SDL_JoystickIndexSDL_Joystickのインデックスを得る
SDL_JoystickNumAxesジョイスティックの軸の数を得る
SDL_JoystickNumBallsジョイスティックのトラックボールの数を得る
SDL_JoystickNumHatsジョイスティックのハットの数を得る
SDL_JoystickNumButtonsジョイスティックのボタンの数を得る
SDL_JoystickUpdateすべてのジョイスティックの状態を更新する
SDL_JoystickGetAxis現在の軸の状態を得る
SDL_JoystickGetHat現在のジョイスティックのハットの状態を得る
SDL_JoystickGetButton与えられたジョイスティックで与えられたボタンの現在の状態を得る
SDL_JoystickGetBall相対的なトラックボールの移動を得る
SDL_JoystickClose以前にオープンされたジョイスティックを閉じる

オーディオ

Sound on the computer is translated from waves that you hear into a series of values, or samples, each representing the amplitude of the wave. When these samples are sent in a stream to a sound card, an approximation of the original wave can be recreated. The more bits used to represent the amplitude, and the greater frequency these samples are gathered, the closer the approximated sound is to the original, and the better the quality of sound.

ライブラリは、根本的なハードウェアに依存している、11025Hz から 44100Hzまでの範囲の 周波数で、8ビットと16ビットの両方の signed と unsigned サウンド・サンプルを サポートします。 ハードウェアが望ましいオーディオ・フォーマットまたは周波数を サポートしないならば、それは望ましい場合、エミュレートされることができます (SDL_OpenAudio()を参照してください)。

一般的にサポートされるオーディオ・フォーマットは、 22050Hz の 16 bits per sample です。

SDL_AudioSpecオーディオ仕様構造体
SDL_OpenAudio望ましいパラメータでオーディオ・デバイスをオープンする
SDL_PauseAudioオーディオ・コールバック処理をポーズ、アンポーズする
SDL_GetAudioStatus現在のオーディオ状態を得る
SDL_LoadWAVWAVEファイルをロードする
SDL_FreeWAV以前にオープンされたWAVデータを解放する
SDL_AudioCVTオーディオ変換構造体
SDL_BuildAudioCVT変換のために SDL_AudioCVT 構造体を初期化する
SDL_ConvertAudio望ましいオーディオ・フォーマットにオーディオデータを変換する
SDL_MixAudioオーディオデータをミックスする
SDL_LockAudioコールバック関数をロックアウトする
SDL_UnlockAudioコールバック関数をアンロックする
SDL_CloseAudioオーディオ処理をシャットダウンし、オーディオデバイスを閉じる

CD-ROM

SDLは、一度に32までのローカル CD-ROM ドライブのオーディオ制御をサポートします。

あなたは、CD-ROMのトラックをリストする、再生する、停止する、そして、 取り出すことを含む、CDプレイヤーのすべての基本関数を実行するための このAPIを使用します。 (現在、multi-changer CD ドライブはサポートされません。)

どのようなSDL CD-ROM関数でも呼び出す前に、 "SDL_Init(SDL_INIT_CDROM)" を最初に呼び出す必要があります。 これは、CD-ROMドライブのためにシステムを スキャンし、オーディオ制御のためにプログラムを設定します。 開始するまでに任意のエラーがあるかどうかを見るため、 返り値コードが 0 になっているかを確認してください。

ライブラリを初期化したあと、SDL_CDNumDrives()関数を用いて、いくつのドライブが利用可能 であるか見つけることができます。 最初にリストされるドライブは、システムのデフォルトの CD-ROMドライブです。 ドライブを選択し、SDL_CDOpen()でそれをオープンしたあと、 あなたはステータスを確認し、ドライブにCDがあるならば再生を始めることができます。

CD-ROMは、一定数の "frames" から各々が成り立っている1つ以上のトラックで構成されます。 各フレームは、〜2Kのサイズで、通常の再生速度で、CDは1秒間に75フレームを再生します。 SDLは、CDのフレーム数で動作しますが、これは、FRAMES_TO_MSF()マクロを使うことによって more familiar minutes/seconds format へ簡単に変換することができます。

SDL_CDNumDrivesシステム上のCD-ROMドライブの数を返す
SDL_CDNameCD-ROMのための人間が読むことができるシステム依存識別子を返す
SDL_CDOpenアクセスのためにCD-ROMドライブをオープンする
SDL_CDStatus与えられたドライブの現在の状態を返す
SDL_CDPlayCDを再生する
SDL_CDPlayTracks与えられたCDトラックを再生する
SDL_CDPauseCDROMをポーズ(一時停止)する
SDL_CDResumeCDROMをレジューム(一時停止からの再開)する
SDL_CDStopCDROMを停止する
SDL_CDEjectCDROMをイジェクト(取り出す)する
SDL_CDCloseSDL_CDハンドルを閉じる
SDL_CDCDROMドライブ情報
SDL_CDtrackCDトラック情報構造体

マルチスレッド

SDLはスレッド、ミューテックス、セマフォ、そして、条件変数を作成するための 関数を提供します。

一般に、あなたはマルチスレッドのプログラムを書くとき、 並行性とデータ整合性の問題を非常に意識する必要があります。 いくつかの良いガイドラインは、以下のようなものが含まれます:

注意: SDLのスレッディングは、preemptive のスレッド・サポートが欠如しているため、 MacOS上で実装されません。

SDL_CreateThread親のプロパティを共有する実行の新しいスレッドを生成する
SDL_ThreadID現在のスレッドの32ビット・スレッド識別子を得る
SDL_GetThreadIDSDL_ThreadのSDLスレッドIDを得る
SDL_WaitThreadスレッドが完了するのを待つ
SDL_KillThreadスレッドを終了する
SDL_CreateMutexミューテックスを生成する
SDL_DestroyMutexミューテックスを破棄する
SDL_mutexPミューテックスをロックする
SDL_mutexVミューテックスをアンロックする
SDL_CreateSemaphore新しいセマフォを生成し、それに初期値を割り当てる
SDL_DestroySemaphoreSDL_CreateSemaphoreによって生成されたセマフォを破棄する
SDL_SemWaitセマフォをロックし、セマフォ値がゼロならば、スレッドをサスペンドする
SDL_SemTryWaitセマフォをロックすることを試みるが、スレッドをサスペンドしない
SDL_SemWaitTimeoutセマフォをロックするが、指定の最大時間までだけ待つ
SDL_SemPostセマフォをアンロックする
SDL_SemValueセマフォの現在の値を返す
SDL_CreateCond条件変数を生成する
SDL_DestroyCond条件変数を破棄する
SDL_CondSignal条件変数上で待つスレッドを再開する
SDL_CondBroadcast条件変数上で待っているすべてのスレッドを再開する
SDL_CondWait条件変数上で待つ
SDL_CondWaitTimeoutタイムアウト付きで条件変数上で待つ

時間

SDLは時間を扱うための、いくつかのクロスプラットフォーム関数を提供します。 それは、現在時刻を得る方法、少しの間を待つ方法、そして、 単純なタイマー・メカニズムを提供します。 これらの関数は、あなたに x ミリ秒ごとにオブジェクトを移動する2つの方法を 与えます:

SDL_GetTicksSDLライブラリ初期化の時点からのミリ秒数を得る
SDL_Delay復帰する前に指定のミリ秒数待つ
SDL_AddTimer指定のミリ秒数が経過したあとにコールバックを呼び出すタイマーを追加する
SDL_RemoveTimerSDL_AddTimerで追加されたタイマーを削除する
SDL_SetTimer指定のミリ秒数が経過したあとに実行されるコールバックをセットする