SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, const char *type)
| src | 読み込むSDL_RWops |
| freesrc | 0でないときsrcを自動的に閉じる/解放する. 0のとき開いたままにする |
| type | データの種類を表すファイルの拡張子("BMP", "GIF", "PNG"など) |
// sample.tgaをimageに読み込む
SDL_Surface *image;
image=IMG_LoadTyped_RW(SDL_RWFromFile("sample.tga", "rb"), 1, "TGA");
if(!image) {
printf("IMG_LoadTyped_RW: %s\n", IMG_GetError());
// ここでエラー処理を行う
}
SDL_SurfaceはCPUからアクセスできるメモリ上のピクセルバッファである. 後でデータを他に渡したり, 操作する場合はこれを使うことになる.
生成されたSDL_Surfaceの形式には保証がない. 多くの場合, SDL_imageは画像と完全に一致するサーフェイスを生成しようとするが, 変換される場合もある. (SDLが直接対応していない形式の画像や, 様々な形式で圧縮されていてSDL_imageがそのうちの1つを選択した場合など.) SDL_Surfaceの形式を精査し, その後SDL_ConvertSurface()で必要な形式に変換することもできる.
画像ファイルが透過ピクセルに対応している場合, SDLはサーフェイスにカラーキーを設定する.
以下のようにすると呼び出し後にRLEアクセラレーションを有効にできる:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);
freesrcが0以外の場合, 処理が成功してもしなくてもRWopsは閉じる. この関数を呼んだとき, どのような場合でもSDL_imageは必要ならばRWopsを全て読み込む.
この関数はファイルの種別を指定できるが, 画像データを別の形式として読み込める場合, SDL_imageは別のデコーダを見つけようとする. しかし, 自動検出できない場合は呼び出し側の画像種別文字列を信頼する. typeがNULLのとき, SDL_imageは何も参考にせずに形式を推定する.
SDL_RWopsを使わずにディスクからファイルを読み込む別の関数も存在する.
IMG_Load("filename.jpg")のようにすると, アプリケーションがSDL_RWopsを操作し, 拡張子からファイル形式を判別する.
IMG_Load_RW()関数も存在する. これはSDL_imageがファイル形式を読み込み時に自動的に判別すること以外はこの関数と同じである.
SDLの2DレンダリングAPIを使用する場合, GPUが使用するSDL_Textureに画像を直接読み込むIMG_LoadTextureTyped_RW()をこの関数の代わりに使うこと.
戻されたサーフェイスを使い終えたならば, アプリケーションはSDL_FreeSurface()で破棄する必要がある.