SDL_Surface * IMG_Load_IO(SDL_IOStream *src, bool closeio);
| SDL_IOStream * | src | 読み込むSDL_IOStream |
| bool | closeio | 真のときsrcを自動的に閉じる/解放する. 偽のとき開いたままにする |
SDL_SurfaceはCPUからアクセスできるメモリ上のピクセルバッファである. 後でデータを他に渡したり, 操作する場合はこれを使うことになる.
生成されたSDL_Surfaceの形式には保証がない. 多くの場合, SDL_imageは画像と完全に一致するサーフェイスを生成しようとするが, 変換される場合もある. (SDLが直接対応していない形式の画像や, 様々な形式で圧縮されていてSDL_imageがそのうちの1つを選択した場合など.) SDL_Surfaceの形式を精査し, その後SDL_ConvertSurface()で必要な形式に変換することもできる.
画像ファイルが透過ピクセルに対応している場合, SDLはサーフェイスにカラーキーを設定する.
以下のようにすると呼び出し後にRLEアクセラレーションを有効にできる:
SDL_SetSurfaceColorKey(image, SDL_RLEACCEL, image->format->colorkey);
closeioが真の場合, 処理が成功してもしなくてもsrcは閉じる.
この関数を呼んだとき, どのような場合でもSDL_imageは必要ならばsrcを全て読み込む.
SDL_IOStreamを使わずにディスクからファイルを読み込む別の関数も存在する.
IMG_Load("filename.jpg")のようにすると, アプリケーションがSDL_IOStreamを操作し, 拡張子からファイル形式を判別する.
IMG_LoadTyped_IO()関数も存在する. これはSDL_imageがファイル形式を自動的に判別できない場合に備えてファイル拡張子("BMP", "JPG")を指定できること以外はこの関数と同じである.
SDLの2DレンダリングAPIを使用する場合, GPUが使用するSDL_Textureに画像を直接読み込むIMG_LoadTexture_IO()をこの関数の代わりに使うこと.
戻されたサーフェイスを使い終えたならば, アプリケーションはSDL_DestroySurface()で破棄する必要がある.