リファレンスマニュアル

SDL本体

SDLリファレンス日本語版 (ミラー)
(SDL_gfxはドキュメントは無いっぽい。必要ならヘッダファイルを見る事)
SDL_image
SDL_mixer
SDL_ttf

hsSDL

Graphics.UI.SDL (少し古いバージョンのものだが、最新版のドキュメントはまだ準備されてないっぽい) (最新版)
Graphics.UI.SDL.Rotozoomer, Graphics.UI.SDL.Primitives(空), Graphics.UI.SDL.Framerate
Graphics.UI.SDL.Image
Graphics.UI.SDL.Mixer
Graphics.UI.SDL.TTF

チュートリアルっぽいもの

公式サイトのIntroduction日本語版

HSDL

Multimedia.SDL (本家)

注意が必要な点

透過色を持つサーフィスのblit転送

すごいややっこしい。

透過色の扱いは三通り存在していて、それぞれの組み合わせによって挙動が変わってくる。
1. SDL_SetColorKeyによる設定。単に、指定された色を透過色として扱うようにする。
2. SDL_MapRGBAによる設定。ピクセル単位で透過度を指定できる。
3. SDL_SetAlphaによる設定。サーフィス全体の透過度を指定する。前述のSDL_MapRGBAとは排他関係にある事に注意。
  - 要するに、SDL_CreateRGBSurface()でサーフィス作る時に、引数のAmaskに0以外を指定した場合はSDL_SetAlphaによる透過指定は使えなくなるし、Amaskに0を指定した場合はSDL_MapRGBAでの透過指定が使えなくなる、という事。
  - 尚、SDL_SetAlpha関数は、サーフィス全体の透過度を設定する他に、サーフィスのSDL_SRCALPHAフラグを再設定するという大事な機能も持っている(が、ここではあまり大きくは扱わない。というか、一つの関数が二つの機能を持つのは結構なバッドノウハウだ！)。

追記すると、以下のような特徴がある。

SDL_SetColorKeyはシンプル。他の仕組みと混ぜてもほとんどの場合は機能する(但し、例外もある)。
SDL_MapRGBAによる(ピクセル単位の)透過機能は、サーフィスのSDL_SRCALPHAフラグによって有効無効を切り換えられる。
SDL_SetAlphaによる(サーフィス単位の)透過機能も、サーフィスのSDL_SRCALPHAフラグによって有効無効を切り換えられる。

前述の三通りの透過色の扱いは、転送元/転送先Surfaceの透過色設定の組み合わせによって、想定外な動作をするパターンがあるので、事前に、自分の望む動作をするのかどうかチェックする必要がある。

具体的には、以下の条件により、2*2*2*2=16通りのパターンが存在する。

転送元surfaceのSrcAlphaの有無。
転送元surfaceのsetColorKeyの有無。
転送元surfaceのAmask値の有無(つまり、ピクセル単位の透過機能を使うのか、サーフィス単位の透過機能を使うのか)。
転送先surfaceのAmask値の有無。

以下のサイトの表で、組み合わせによってどのような動作をするのかをある程度確認できる。

もし、自分の望む動作をしない場合は、転送前に一時的に状態を変えたりしても良い(その場合は、転送後に設定を元に戻すのを忘れないようにする事)。

SDL_ttfで生成したサーフィスをblit転送する時の注意点は、下の方の「SDL_ttf」の項目を参照。

色を指定する方法について

SDLでは色を指定する方法が何通りかあり、しかも、関数によって、どの形式の色指定を受け付けるかがまちまち。どれかに統一しないと非常に困る。

SDL_Color
```
typedef struct{
  Uint8 r;
  Uint8 g;
  Uint8 b;
  Uint8 unused;
} SDL_Color;
```
「フォーマットに依存しない色表現」との事。
- このフォーマットを採用する場合、alpha値を保持する事が出来ない。
  - unusedに突っ込む事も可能だが、hsSDLではunusedが定義されていないので、別途に用意しなくてはならない。
SDL_MapRGB() / SDL_MapRGBA()の返り値(実体はUint32)
- SDL_GetRGB() / SDL_GetRGBA()で、元のr, g, b, aの値に戻せる(が、その際にSurfaceのformat情報も必要になる)。
  - 但し、formatのbit幅(depth)が32以外だった場合は、最初にSDL_MapRGB()等を実行した時のr, g, bの値から、色のずれが発生する場合がある。32の場合は問題無いっぽいが……。
- hsSDLではPixel型として定義されている。
- SDL_gfxのprimitivesで定義されている各関数の内、*Color()となっているものは、SDL_Color形式ではなく、この形式で受け取るようだ。
- この形式で扱うのが一番汎用性があるか？しかしSurfaceに依存してしまう問題がある。
  - 要は、あるSurfaceのformatを使って作ったPixel型(SDL_MapRGB()の結果)は、別のSurfaceには流用できないという事(実際には、formatが同じであれば流用可能だが、そうでない場合はまず正しい描画結果にならない)。
r, g, b, aの個別指定
- SDL_gfxのprimitivesの*RGBA()など。
- 確実だが微妙。

まとめると、以下のようになるっぽい。

-	SDL_Color (Color型)	SDL_MapRGB()の返り値 (Pixel型)	rgba個別指定(Uint8四つ) (Word8型が四つ)
SDL_SetColorKey	×	○	×
SDL_FillRect	×	○	×
SDL_gfxの各関数	×	○	○
SDL_ttfの各関数	○	×	×

これだけ見るならば、普段はPixel型で色情報を管理し、SDL_ttfを使う時だけSDL_GetRGB()等を使ってColor型に変換するのが良さそうに見える。
しかし、Pixel型を使う際には、違うsurface間でそのまま色情報をやりとりできない事に常に気をつける必要がある。これはちょっと面倒だ。
- たまたま二つのsurfaceのformatが同じであれば正しく機能するが、一致しない時は正しく描画されない。これは、気付きにくいバグの元になる。

しかし、Pixel型が一番プリミティブだと思われるので、とりあえず今のところはPixel型をメインに使っていく事にする。

SDL_ttf

SDL_ttfを使って生成したサーフィスは、まだ内部で元フォントオブジェクトの何かに依存しているらしく、サーフィスよりも先にフォントオブジェクトをcloseすると例外が発生する事がある。
- 生成したサーフィスはblitしてすぐfreeするか、或いはフォントオブジェクトの方を開きっぱなしにしておく。

SDL_ttfが生成したサーフィスのformatは、Renderの種別(SolidかShadedかBlendedか)によって全然違うので、透過色を考慮したblit転送を行う際には細心の注意が必要になる。
- どのような注意が必要なのかについては、このページの上の方にある「透過色を持つサーフィスのblit転送」を参照。
- 具体的な問題としては、気軽に「SolidをBlendedにしてみよう」とかすると、想定する結果にならない事が多い。
- 実際のサーフィスの設定は、以下のようになってるっぽい。
  - Solidは、SrcAlpha無し、Amask無し、colorKey有りのsurfaceを生成するっぽい。
  - Shadedは、SrcAlpha無し、Amask無し、colorKey無しのsurfaceを生成するっぽい。
  - Blendedは、SrcAlpha有り、Amask有り、colorKey無しのsurfaceを生成するっぽい。

SDL_mixer

SDL_mixerの再生回数の解釈は注意が必要。
- Mix_PlayChannelの第三引数(再生回数)は、-1で無限繰り返し、それ以外は指定数値+1回再生。つまり、0を指定すると一回再生。
- Mix_PlayMusicの第二引数(再生回数)は、-1で無限繰り返し、0で再生しない、1で一回再生。

midi再生時に、SDLの仕様かmidiドライバの仕様の為か、とにかくosのmidiボリュームが勝手に最大化されてしまう場合がある。
- これは結構迷惑なので(他のwav等とのボリュームバランスが崩れてしまう)、midiは使わないようにする。
- ゲーム用途には、サイズが小さく扱いやすいmidiは便利だが……とりあえず今は諦める。

SDL_gfx

どうも、描画関係の関数の動作が怪しい気が……
- サーフィスのフォーマットによっては、ピクセル値を指定してもRGBA値を指定しても正しく色が描画されない気がする。
- 単に使い方を間違えているだけ？

最終更新 : 2008/01/31 23:24:05 JST