目次

Ruby/SDLの概要

SDL::Error

SDL固有のエラーを表わす例外クラスです。StandardErrorを継承しています。

SDL::VERSION

SDLのバージョンを表わす文字列です。"1.0.0"という形になっています。

初期化

Ruby/SDLを使う前には必ずSDL.initで初期化する必要があります。SDL.initは、 ユーザの指定したすべてのサブシステム(ビデオ、オーディオ、ジョイスティック、 タイマー、CD-ROMのいずれかあるいは全部)を初期化することができます。

Methods

SDL.init(flags)

SDLを初期化します。 すべてのRuby/SDLのメソッドを呼び出す前にこの関数が呼ばれなければいけません。 flagsにはSDLのどの部分を初期化するかを指定します。

SDL::INIT_AUDIO
オーディオサブシステム(音声出力機能)を初期化
SDL::INIT_VIDEO
ビデオサブシステム(画像出力機能とキーボード、マウス入力機能)を初期化
SDL::INIT_CDROM
CDROMサブシステム(CD再生機能)を初期化
SDL::INIT_JOYSTICK
ジョイスティックサブシステム(ジョイスティック入力機能)を初期化
SDL::INIT_EVERYTHING
上に挙げた機能を全て初期化します。

失敗すると例外SDL::Errorが発生します。

SDL.quit

全てのSDLサブシステムをシャットダウンし、それらが確保したリソースをすべて解 放します。通常は自動で呼ばれるためユーザが明示的に呼びだす必要はありません。

SDLおよびRuby/SDLの仕様を理解した上で必要な場合のみ使ってください。

SDL.inited_system(flags)
SDL.initedSystem(flags)

これは、どのSDLサブシステムが初期化されているかを報告します。 flagsには、調べたいサブシステムの論理和を指定します (指定できるサブシステムのフラグについてはSDL.initの項を参照してください)。

初期化されているサブシステムの論理和を返します。

EXAMPLE

# SDL.inited_systemの使いかた

# 全てのサブシステムの初期化状態を得ます
subsystem_init = SDL.inited_system(SDL::INIT_EVERYTHING)

if subsystem_init & SDL::INIT_VIDEO
  puts "ビデオは初期化されています。"
else
  puts "ビデオは初期化されていません。"
end



# 1つのサブシステムだけをチェックします

if SDL.inited_system(SDL::INIT_VIDEO) != 0
  puts "ビデオは初期化されています。"
else
  puts "ビデオは初期化されていません。"
end



# 2つのサブシステムをチェックします

subsystem_mask = SDL::INIT_VIDEO|SDL::INIT_AUDIO;

if SDL.inited_system(subsystem_mask) == subsystem_mask
  puts "ビデオとオーディオはどちらも初期化されています。"
else
  puts "ビデオとオーディオのどちらか、または両方が初期化されていません。"
end
SDL.getenv(var)

varで指定した環境変数を得ます。

環境変数の値を文字列で返します。

SDL.putenv(string)

環境変数の追加または値の変更を行います。string は "name=value" という形式を取ります。

Windows上でSDL_WINDOWIDやSDL_VIDEODRIVERといった環境変数を使って SDLの実行に影響を与えたいときに利用します。 SDLの仕様によりWindowsでは ENV を直接変更してもこれらの機能が使え ないためこのような関数が存在しま。Unix上では ENV を使うのと同じ 効果があります。

失敗時には例外SDL::Errorを発生させます。

EXAMPLE

# http://moriq.tdiary.net/20051006.html より
# Ruby/SDL と Apolloの併用
require 'phi'
require 'sdl'

# フォームの生成
form = Phi::Form.new
$terminated = false
form.on_close{ $terminated = true }
form.caption = "Ruby/SDL on Phi::Form"
# パネルをフォームの上に作る
panel = Phi::Panel.new(form)
panel.align = Phi::AL_LEFT

# WINDOWID hackを使い、パネルにSDLのウインドウをのせる
SDL.putenv("SDL_VIDEODRIVER=windib")
SDL.putenv("SDL_WINDOWID=#{panel.handle}")
form.show

# SDL本体の初期化など
SDL.init(SDL::INIT_VIDEO)
screen = SDL.setVideoMode(640, 480, 16, SDL::SWSURFACE)

# メインループ、とりあえず何もしない
unless $terminated
  while event = SDL::Event2.poll
    case event
    when SDL::Event2::KeyDown, SDL::Event2::Quit
      exit
    end
  end

  sleep 0.05
end

Video

Video Subsystem 概要

SDL は表示フレームバッファに対するとてもシンプルなインターフェースを 提供します。 フレームバッファはあなたが直接書くことができる オフスクリーンサーフェスとして表現されます。 スクリーンに書いたものを画面に表示させるには、 画面の必要な部分が更新されることを保証する 更新関数を呼んで下さい。

Ruby/SDL のいかなるビデオ関連メソッドを呼ぶ前に、 最初に SDL.init(SDL::INIT_VIDEO)を呼ばなければいけません。 これは SDL 内のビデオとイベントを初期化します。

アプリケーションでサウンドとビデオを共に使うときは、 サウンドデバイスをオープンする前に SDL.init(SDL::INIT_AUDIO|SDL::INIT_VIDEO) を呼ぶ必要があります。 そうしないと、Win32 の DirectX において フルスクリーン表示モードにセットすることができないでしょう。

ライブラリを初期化した後は、ビデオ表示を順番にスタートさせることができます。 最も簡単な方法は、共通のスクリーン解像度とピクセル深度を選び、 エラーをチェックしつつビデオを初期化することです。 おそらくあなたが望んだものが得られるでしょうが、 SDL はあなたが求めたモードをエミュレートし、 更新の際に変換しているかもしれません。 最もよい方法は、 望まれるものに最も近いビデオモードを 問い合わせ、 そのピクセルフォーマットに合わせて画像を 変換することです。

SDL は現在 1 ピクセル 8 bit 以上のいかなるピクセル深度もサポートしています。 8 bpp のフォーマットは 8 bit のパレットモードとしてみなされ、 12, 15, 16, 24, そして 32 bpp は 「パックドピクセル」モードとしてみなされます。 これは、個々のピクセルが RGB 各チャンネルの輝度を ピクセルのビットの中にパッキングして持っているということです。

ビデオモードを初期化した後は、 返値として得られたサーフェスに対し、他のフレームバッファのように書き込み、 いつものように更新処理を呼ぶことができます。

SDL::Surface

絵のサーフェスを表わすクラスです。

このクラスは描画される「絵」のメモリを表現しています。

メソッドおよびクラスメソッドのリスト

SDL::Screen

画面に対応するサーフェスを表わすクラスです。

このクラスは SDL::Surface のサブクラスであり、実際に画面に表示される サーフェスを表わします。

ビデオフレームバッファは SDL.set_video_mode と SDL.get_video_surface から得られます。

メソッドおよびクラスメソッドのリスト

SDL::VideoInfo

ビデオターゲットの情報を表わすクラスです。 このクラスのインスタンスは SDL.video_info から返り値として得られます。 これは以下のメソッドを持ちます。

SDL::VideoInfo#hw_available
ハードウェアサーフェスを作ることは可能かどうか
SDL::VideoInfo#wm_available
ウィンドウマネージャが利用できるかどうか
SDL::VideoInfo#blit_hw
ハードウェア間の blit はアクセラレーションが有効かどうか
SDL::VideoInfo#blit_hw_CC
ハードウェア間のカラーキー blit はアクセラレーションが有効かどうか
SDL::VideoInfo#blit_hw_A
ハードウェア間のα blit はアクセラレーションが有効かどうか
SDL::VideoInfo#blit_sw
ソフトウェアからハードウェアへの blit はアクセラレーションが有効かどうか
SDL::VideoInfo#blit_sw_CC
ソフトウェアからハードウェアへのカラーキー blit はアクセラレーション が有効かどうか
SDL::VideoInfo#blit_sw_A
ソフトウェアからハードウェアへのα blit はアクセラレーションが有効かどうか
SDL::VideoInfo#blit_fill
色の塗潰しはアクセラレーションが有効かどうか
SDL::VideoInfo#video_mem
ビデオメモリの総容量(Kbyte)
SDL::VideoInfo#bpp
一ピクセルあたりのバイト数

色、ピクセルフォーマット、ピクセル値について

まずは Ruby/SDL において重要なことを先に書きます。 Ruby/SDLにおいて色はRGBAそれぞれ0から255までの値を取ります。 性能のため SDL 内部ではRGBA値を32ビット符号無し整数でパッキングします。 このRGBA値と符号無し32ビット整数との変換規則をピクセルフォーマットと 呼び、変換後の値をピクセル値と呼びます。 ピクセルフォーマットはサーフェスごとに決まっていて、 変換はSDL::Surface#map_rgb、SDL::Surface#map_rgba、 SDL::Surface#get_rgb、SDL::Surface#get_rgbaというメソッドでします。 メソッドの引数などで色を指定する場合、[231, 251, 100] というような 要素が3個の配列(RGB,A=255)、 [231, 251, 100, 128]という要素が4個の配列(RGBA)、もしくはピクセル値の いずれでも使えます。またメソッドの返り値として色情報が得られる場合は 通常ピクセル値が得られます。

以下はより基本的でより詳しい内容です。

Ruby/SDLにおける絵は、ピクセルの集合として表されます。 ピクセルと呼ばれる小さな正方形を縦横に並べ、そのそれぞれに 色をわりあてることで画像を表現します。 例えば 640x480 の絵は 307200個 = 640×480 のピクセルで表わされます。

そして、その色は光の3原色である赤(Red)、緑(Green)、青(Blue)それぞれの値 を0から255までで指定することで決めます。例えば [R,G,B] = [0,0,0] ならば黒、 [255, 255, 0]ならば黄色、[160, 32, 240]で紫、などです。

そしてこの情報をバイト列に変換して保存します。一つのピクセルに対し 8ビット、16ビット、24ビット、もしくは32ビットのメモリを割当て、 R,G,Bの 255*255*255の情報を適当にそのメモリに収まるように変換します。 このビット数をbpp(Bits Per Pixel)と呼びます。 そしてこの色の情報 -> バイト列の変換規則をピクセルフォーマットと呼びます。 また、ピクセル1個分の色データをピクセルフォーマットで変換したものを ピクセル値と呼びます。性能のため SDL 内部ではこのピクセル値を よく利用します。 それぞれのサーフェスは、このピクセルフォーマットと「絵を表わすバイト列」 の組であると解釈できます。

この色データとピクセル値の相互変換は SDL::Surface#map_rgb、SDL::Surface#get_rgbというメソッドでします。

また、各メソッドの引数で色を指定する場合は、[r, g, b]という要素が整数3個の 配列、もしくはそのサーフェスのピクセルフォーマットで変換したピクセル値の どちらでも使える場合がほとんどです。

最後にα値について解説します。この値はある画像と別の画像を重ね合わせる 時に意味のある値です。SDL.blit_surfaceなどで2つの画像が重ね合わされる場合、 通常下の画像は上の画像で完全に隠されてしまいます。しかし上の画像に α値を指定しておくと、上の画像の色と下の画像の色が混ぜ合されます。 この混ぜ合せの割合をα値と呼びます。SDLではα値は0から255までの値をとりえます。 0が完全な透明で、255が完全な不透明です。 この値はbppが32の場合には、各ピクセルごとに指定することができます。 つまりピクセル値には R,G,B のほかアルファ(Alpha)値を含めることができると いうことです。このα値を含めた変換には SDL::Surface#map_rgba、[Surface#get_rgba]を使います。 また各メソッドの引数でアルファ付きの色を指定する場合は、[r,g,b,a]という 要素が整数4個の配列を使うことが可能です。

Methods

SDL.get_video_surface
SDL.getVideoSurface

このメソッドは現在の表示サーフェスを返します。 SDL が表示サーフェス上でフォーマット変換を行っている場合は、 この関数は実際のビデオサーフェスではなく、(SDL を使う側に 見せている) 変換前のサーフェスを返します。

SDL::Screenのインスタンスを返します。

失敗したときには例外SDL::Errorを発生させます。

SDL.video_info
SDL.videoInfo

この関数はビデオハードウェアに関する情報を返します。

SDL.set_video_modeの前にこれが呼ばれると、 返されたオブジェクトのbppアトリビュートには 「最も適した」ビデオモードのピクセルフォーマットが入ります。

情報をSDL::VideoInfoのインスタンスで返します。

失敗したときには例外SDL::Errorを発生させます。

SDL.video_driver_name
SDL.videoDriverName

ドライバ名は "x11" や "windib" のように単なる 1 語の識別子です。

ドライバ名を文字列で返します。

ビデオがまだSDL.initで初期化されていないなら例外SDL::Errorを発生させます。

SDL.list_modes(flags)
SDL.listModes(flags)

与えられたビデオのフラグに対し、 利用可能な画面モードの配列を返します。

フラグはSDL.set_video_mode で使われるものと同じであり、モードが有効かどうかを決定する際に 強い役割を果たします。 SDL::HWSURFACEをフラグとして渡すと、 ハードウェアのビデオサーフェスがサポートするモードだけが返されます。

大きい方から小さい方にソートされています。 ある特定のフォーマットに対し利用可能なモードがない場合は nil を返し、 与えられたフォーマットに対しどのモードでも OK の場合は true を返します。 利用可能なモードが有限個しか存在しない場合は、 [縦方向の解像度, 横方向の解像度]という配列の配列を返します。

EXAMPLE

# 利用可能なフルスクリーンハードウェアモードを取得する
modes = SDL.list_modes(SDL::FULLSCREEN|SDL::HWSURFACE)

# 利用可能なモードがあるかどうかチェック
if modes == nil
  puts "利用可能なモードがありません!"
  exit 1
end

# 解像度が制限されているかどうかチェック
if modes == true
  puts "全解像度が利用可能です。"
else
  # 有効なモードを表示
  puts "利用可能なモード"
  modes.each{|w, h| puts "  #{w} x #{h}"}
end
SDL.check_video_mode(w,h,bpp,flags)
SDL.checkVideoMode(w,h,bpp,flags)

要求されたモードがどのピクセル深度においてもサポートされていない場合は 0を返し、 あるいは与えられた横幅・高さと 要求されたサーフェス フラグ(SDL.set_video_modeを見て下さい) において利用可能な最も近いピクセル深度を返します。

ピクセル深度の値は推奨されるモードに過ぎません。 ビデオモードの設定時に 普通にあなたの望むピクセル深度を要求することができ、 SDL はシャドウビデオサーフェスを使ってそのピクセル深度を エミュレートするでしょう。

EXAMPLE

puts "640x480@16bpp のモードをチェックしています。"
bpp = SDL.check_video_mode(640, 480, 16, SDL::HWSURFACE)
if bpp == 0
  puts "利用可能なモードではありません。"
  exit 1
end

puts "SDL は 640x480@#{bpp}bpp を推奨します。"
screen = SDL.set_video_mode(640, 480, bpp, SDL_HWSURFACE)
SDL.setVideoMode(w,h,bpp,flags)
SDL.set_video_mode(w,h,bpp,flags)

指定された幅・高さ・ピクセル深度(1ピクセルのビット数)を用いて ビデオモードを設定します。 bpp が 0 ならば、現在表示されているピクセル深度として扱われます。

flags パラメータはSDL::Surface#flagsと同じです。 以下の値の OR による組み合わせが有効です。

SDL::SWSURFACE
システムメモリからビデオサーフェスを作成します。
SDL::HWSURFACE
ビデオメモリからビデオサーフェスを作成します。
SDL::ASYNCBLIT
表示サーフェスの非同期更新の使用を有効にします。 これは通常、単一 CPU における blit 転送は遅くなりますが、 SMP システムにおいてスピードの向上をもたらすかも知れません。
SDL::ANYFORMAT
普通は、もし要求されたピクセル深度のビデオサーフェス (bpp) が使えない場合は、 SDL はシャドウサーフェスでこれをエミュレートします。 SDL::ANYFORMATはこれを禁止し、 SDL はピクセル深度とは無関係にビデオサーフェスを使うことになります。
SDL::HWPALETTE
SDL がパレットに対する排他的なアクセスをできるようにします。 このフラグがないと、 SDL::Surface#set_colorsやSDL::Surface#set_paletteを用いて要求した色が、 常に取得できるとは限りません。
SDL::DOUBLEBUF
ハードウェアによるダブルバッファを有効にします。 (SDL::HWSURFACE と一緒の時のみ) SDL::Screen#flip の呼び出し によってバッファを切り替え、画面を更新します。 全ての描画は、その瞬間に表示されていない方のサーフェスに行われます。 ダブルバッファを有効にできなかった場合は、 SDL::Screen#flip は画面全体に対し単にSDL::Screen#update_rectを行います。
SDL::FULLSCREEN
SDL はフルスクリーンモードの使用を試みます。 どういう理由であれ、ハードウェアによる解像度変更ができない場合は 一段階解像度の高いモードが使われ、黒い背景の中央に表示ウインドウが置かれます。
SDL::OPENGL
OpenGL の描画コンテキストを作成します。 前もってSDL.set_GL_attrによって OpenGL のビデオ属性を 設定しておく必要があります。
SDL::OPENGLBLIT
上と同様に OpenGL の描画コンテキストを作成しますが、 通常の blit 転送を可能にします。 画面(2D)のサーフェスはαチャンネルを持つことが可能で、 画面のサーフェスへの変更を更新するために、 SDL::Screen#update_rectを使わなければいけません。 注意: このオプションは互換性のためにのみ 残されており、新しいコードでこの機能を使うことは 推奨されていません。
SDL::RESIZABLE
リサイズ可能なウィンドウを作成します。 ユーザーの手でウィンドウがリサイズされた場合は、 SDL::Event2::VideoResizeイベントが発生し、 新しいサイズで SDL.set_video_modeが再度呼ばれることがあります。
SDL::NOFRAME
もし可能であれば、 SDL がタイトルバーなし、あるいはフレームによる装飾なしの ウィンドウが生成することになります。 フルスクリーンモードの場合自動的にこのフラグを設定します。

フレームバッファのサーフェスをSDL::Screenのインスタンスで返します。

失敗したときには例外SDL::Errorを発生させます。

SDL::Screen#updateRect(x,y,w,h)
SDL::Screen#update_rect(x,y,w,h)

与えられた領域の画面を更新します。 矩形は画面の境界内の収まっていなければなりません。 (つまりクリッピングはされません)

x、y、w、hがすべて 0 ならば、画面全体を更新します。

この関数はselfがロックされている間は呼んでは いけません。

SDL::Screen#flip

ダブルバッファをサポートするハードウェアにおいて、 この関数は切替を設定して帰ってします。 ハードウェアは垂直帰線区間を待ち、 次のビデオサーフェスの blit 転送やロックが戻る前に ビデオバッファを交換します。 ダブルバッファをサポートしないハードウェアにおいては、 self.update_rect(0, 0, 0, 0) を呼ぶのと同等です。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#set_colors(colors,firstcolor)
SDL::Surface#setColors(colors,firstcolor)

self が現在の表示と関連付けられたサーフェスの場合は、 表示カラーマップは要求された色で更新されます。SDL.set_video_mode フラグに SDL::HWPALETTE がセットされていた場合は、 SDL::Surface#set_colors は常にtrueを返し、 ウィンドウのカラーマップが歪められていたり、 エミュレーションの下で動いている場合でも、 パレットはあなたが望んだ通りにセットされることが保証されています。

colorsとして色情報の配列を与える必要があります。色情報とは R、G、Bそれぞれ0から255までの値を持つ要素が3個の配列です。

SDL::HWPALETTE がセットされた、パレット化された(8 bit) 画面サーフェスには 2 種類のパレット、すなわち サーフェスに対する(あるいはサーフェスからの)マッピング blit に 使われる論理パレットと、 ハードウェアが色を画面にどうマッピングするかを決定する物理パレット とがあります。 SDL::Surface#SDL_set_colors は(存在するなら)双方のパレットを変更します。 これは (SDL::LOGPAL | SDL::PHYSPAL) を flags にセットして SDL::Surface#set_palette を呼ぶのと同等です。

self がパレット化されたサーフェスではない場合は、 この関数は何もせず、false を返します。 全ての色がこのメソッドに 渡した通りにセットされた場合は、true を返します。 必ずしも全ての色エントリが与えられた通りにセットされた訳ではない場合は、 false を返すので、 実際の色パレットを決めるサーフェスパレットを見る必要があります。

EXAMPLE

# グレースケールのパレットでサーフェスを作成

# 色情報で埋める
colors = Array.new(256){|i| [i, i, i]}
# 表示サーフェスを作成
screen = SDL.set_video_mode(640, 480, 8, SDL::HWPALETTE)

# パレットのセット
screen.set_colors(colors, 0)
SDL::Surface#set_palette(flags,colors,firstcolor)
SDL::Surface#setPalette(flags,colors,firstcolor)

与えられた 8 ビットサーフェスに対し、パレットの一部をセットします。

SDL::HWPALETTE フラグがセットされている パレット(8ビット) の画面サーフェスには 2種類のパレットがあります。 すなわち、サーフェスからの(あるいはサーフェスに対する) blit 転送を マッピングする論理パレットと、 ハードウェアが色を画面にマッピングする方法を決定する 物理パレットです。 SDL.blit_surface は サーフェスのピクセルフォーマット間で変換が必要な場合、 サーフェスを blit 転送する際に常に論理パレットを使います。 このため、さまざまな特殊色効果 (画面のフェード・カラーフラッシュ・画面の霞み)を得るために パレットを片方だけ変更することはしばしば有用です。

この関数は SDL::LOGPAL か SDL::PHYSPAL を flags に指定することで、 論理または物理パレットのいずれかを変更することができます。 selfが現在の表示と 関連付けられているサーフェスのときは、 表示のカラーマップは要求された色で更新されます。 SDL.set_video_mode に SDL::HWPALETTE がセットされていた場合は、 このメソッドは常に true を返し、 ウィンドウのカラーマップが歪められなければならない場合や、 エミュレーション下で動いている場合であっても、 パレットにはあなたが望んだ方法でセットされることが保証されます。

colorsとして色情報の配列を与えます。色情報とは R、G、Bそれぞれ0から255までの値を持つ要素が3個の配列です。 256**3 = 16777216色が使えます。

selfがパレット化されたサーフェスでない場合は、 この関数は false を返して何もしません。 全ての色がこのメソッドに渡された通りにセットされると、 true を返します。 必ずしも全ての色エントリが与えられた通りにセットされた訳ではない場合は、 false を返すので、 実際の色パレットを決定するサーフェスパレットを見る必要があります。

EXAMPLE

# グレースケールのパレットでサーフェスを作成

# 色情報で埋める
colors = Array.new(256){|i| [i, i, i]}
# 表示サーフェスを作成
screen = SDL.set_video_mode(640, 480, 8, SDL::HWPALETTE)

# パレットのセット
screen.set_palette(SDL::LOGPAL|SDL::PHYSPAL, colors, 0)
SDL.set_gamma(redgamma,greengamma,bluegamma)
SDL.setGamma(redgamma,greengamma,bluegamma)

各カラーチャンネルについて、表示用の「ガンマ関数」をセットします。 ガンマは画面に表示される色の明るさ・コントラストを制御します。 ガンマ値 1.0 は単位元です。 (つまり、何の調整も行われません)

この関数は「ガンマ関数」のパラメータに基いてガンマを調整します。 SDL.set_gamma_ramp を使うと、 ガンマ調整の参照テーブルを直接指定することができます。

失敗したときには例外SDL::Errorを発生させます。

SDL.get_gamma_ramp
SDL.getGammaRamp

現在表示に使われているガンマ値の変換テーブルを取得します。 それぞれのテーブル(R, G, B)は 256 個の16bit符号なし整数値の配列です。

3個の「256個の16bit符号なし整数値の配列」の配列を返します。

失敗したときには例外SDL::Errorを発生させます。

SDL.set_gamma_ramp(table)
SDL.setGammaRamp(table)

各色チャンネルについて、表示用のガンマ参照テーブルをセットします。 引数 tables は SDL.get_gamma_ramp と同じフォーマットで、 対応するチャンネルの入力と出力間の写像を表現します。 入力は配列に対するインデックスであり、出力はそのインデックスにおける 16 ビットのガンマ値で、出力の色精度に合わせてスケーリングされます。

この関数は参照テーブルに基いてガンマを調整しますが、 SDL.set_gamma を用いて 「ガンマ関数」パラメータに基いて計算されたガンマも持つことができます。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#map_rgb(r,g,b)
SDL::Surface#mapRGB(r,g,b)

RGB カラーの値をselfのピクセルフォーマットに写像し、 ピクセル値を 32bit 符号無し整数 として返します。 r、g、b は0から255までの値をとれます。

フォーマットがパレット (8ビット) を持つ場合は、 パレット内において最も近い色のインデックスが返されます。

指定されたピクセルフォーマットがαチャンネルを持つ場合は、 全て 1 のビット(完全に不透明)として返されます。

与えられたピクセルフォーマット上において、 与えられた RGB カラー値を最も良く近似するピクセル値です。 ピクセルフォーマットのピクセル深度が 32bpp より小さい場合は、 返値の使用されていない上位ビットは安全に無視することができます。 (例えば、16bpp のフォーマットでは返値は 2**16 より小さく、 8bpp では 2**8 より小さい)

SDL::Surface#map_rgba(r,g,b,a)
SDL::Surface#mapRGBA(r,g,b,a)

RGBA カラーの値をselfのピクセルフォーマットに写像し、 ピクセル値を 32bit 符号無し整数 として返します。 r、g、b、a は0から255までの値をとれます。

フォーマットがパレット (8ビット) を持つ場合は、 パレット内において最も近い色のインデックスが返されます。

指定されたピクセルフォーマットがαチャンネルを持たない場合は、 (パレットを持つフォーマットの中でそうであるように) α値は無視されます。

与えられたピクセルフォーマット上において、 与えられた RGBA カラー値を最も良く近似するピクセル値です。 ピクセルフォーマットのピクセル深度が 32bpp より小さい場合は、 返値の使用されていない上位ビットは安全に無視することができます。 (例えば、16bpp のフォーマットでは返値は 2**16 より小さく、 8bpp では 2**8 より小さい)

SDL::Surface#get_rgb(pixel)
SDL::Surface#getRGB(pixel)

selfのピクセルフォーマットによるピクセル値から RGB 各チャンネルの値を要素数3の配列で取得します。

このメソッドは RGB 各チャンネルが 8 ビット未満のピクセルフォーマットから 色チャンネルを変換する際にも 8 ビット全体 [0〜255] の範囲を使います。 (例えば、16 ビット RGB565 フォーマットにおける完全な白色は [0xf8, 0xfc, 0xf8] ではなく [0xff, 0xff, 0xff] を返します)

SDL::Surface#get_rgba(pixel)
SDL::Surface#getRGBA(pixel)

指定されたピクセルフォーマットに格納されたピクセルから RGBA 各チャンネルの値を要素数4の配列で取得します。

RGB 各チャンネルが 8 ビット未満のピクセルフォーマットから 色チャンネルを変換する際にも 8 ビット全体 [0〜255] の範囲を使います。 (例えば、16 ビット RGB565 フォーマットにおける完全な白色は [0xf8, 0xfc, 0xf8] ではなく [0xff, 0xff, 0xff] を返します)

サーフェスにαチャンネルがない場合は、αには 0xff (100% 不透明) が返されます。

SDL::Surface.new(flags,w,h,depth,Rmask,Gmask,Bmask,Amask)

大きさが w x h の空のサーフェスを確保します。 (SDL.set_video_modeの後で呼ばれなければいけません)

depth が 8 ビットの場合は、 サーフェスに空のパレットが確保されます。 そうでない場合は、 与えられたRmask、Gmask、Bmask、Amask を使って 「パッキングされたピクセル」が作られます。 flags は作られるサーフェスのタイプを指定し、 以下の取りうる値の OR による組み合わせとなります。

SDL::SWSURFACE
SDL はシステムメモリからサーフェスを作ります。 ピクセルレベルのアクセスのパフォーマンスを向上されますが、 いくつかのハードウェアによる blit 転送の 利点を得ることができなくなるかも知れません。
SDL::HWSURFACE
SDL はビデオメモリからサーフェスを作ろうとします。 これにより SDL はビデオメモリ同士の bilt 転送 (しばしばアクセラレーションが利きます) の利点を得ることができます。
SDL::SRCCOLORKEY
このフラグはサーフェスを blit する際にカラーキーを有効にします。 SDL::HWSURFACE も指定されており、 カラーキー付きの blit 転送もハードウェアによるアクセラレーションが利く場合は、 SDL はサーフェスをビデオメモリに作ろうとします。 サーフェスを作った後にこのフラグをセット・リセットしたい場合は SDL::Surface#set_color_key を使って下さい。
SDL::SRCALPHA
このフラグはサーフェスからの blit 転送におけるαブレンディングを有効にします。 SDL::HWSURFACE も指定され、 αブレンディング blit 転送がハードウェアによるアクセラレーションが利く場合は サーフェスはなるだけビデオメモリに置かれます。 サーフェスを作った後にこのフラグをセット・リセットしたい場合は SDL::Surface#set_alphaを使って下さい。

SDL::Surfaceのインスタンスを返します。

失敗したときには例外SDL::Errorを発生させます。

EXAMPLE

# テクスチャ用として OpenGL に要求される、
# 個々々のピクセルのバイトが RGBA の順番で並んだ
# 32 ビットのサーフェスを生成

big_endian = ([1].pack("N") == [1].pack("L"))

if big_endian
  rmask = 0xff000000
  gmask = 0x00ff0000
  bmask = 0x0000ff00
  amask = 0x000000ff
else
  rmask = 0x000000ff
  gmask = 0x0000ff00
  bmask = 0x00ff0000
  amask = 0xff000000
end

surface = SDL::Surface.new(SDL::SWSURFACE, width, height, 32,
                           rmask, gmask, bmask, amask);
SDL::Surface.new_from(pixels,w,h,depth,pitch,Rmask,Gmask,Bmask,Amask)

与えられたピクセルデータ(pixels、 Stringのインスタンス)から SDL::Surface のインスタンスを生成します。 pixels に格納されたデータは depth のものであるとみなされます。 pitch は各スキャンラインの長さ(バイト数)です。

他のパラメータについての詳しい記述については、SDL::Surface.newを見てください。

生成されたサーフェスを返します。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#lock

ピクセルに直接アクセスするためにサーフェスをロックします。 SDL::Surface#lock と SDL::Surface#unlock の呼びだしの間、 サーフェスへ直接読み書きができます。 ひとたびサーフェスへのアクセスが終了したら、 SDL::Surface#unlock を使って解放する必要があります。

サーフェスへ直接読み書きをする、ロックが必要なメソッドは 以下の通りです。

またSDL.auto_lock?が真である場合には、ロックが必要なメソッドが呼ばれた 場合自動的にロックの設定と解放をするため、このメソッドを呼ぶ必要 はありません。

すべてのサーフェスがロックを必要とする訳ではありません。 SDL::Surface#must_lock?が偽ならば いつでも読み書きすることができ、サーフェスのピクセルフォーマット は変更されません。

この時間の間にクリティカルなシステムロックが行われることがあるため、 ロック/アンロック間では、いかなる OS システムコールやライブラリコールも 呼ばれるべきではありません。

明記しておくべきことに、 SDL 1.1.8 以降ではサーフェスのロックは再帰的である、という点があります。 これは複数のサーフェスロックをかけることができるということですが、 個々のロックには対応するアンロックがなければいけません。

surface.lock
# サーフェスはロックされている 
# ここでサーフェス上の直接ピクセルアクセス
surface.lock
# さらにサーフェス上の直接ピクセルアクセス
surface.unlock
# サーフェスはまだロックされている
# 注記: バージョンが 1.1.8 以下の場合は、
# この段階でサーフェスはもうロックされていない
surface.unlock
# サーフェスは今アンロックされている

サーフェスのロックができなかった場合は例外SDL::Errorを返します。

SDL::Surface#unlock

SDL::Surface#lockを使ってロックされたサーフェスは このメソッドでロックを解除しなければいけません。 サーフェスのロックはできるだけ早く解除されるべきです。

1.1.8 以降、サーフェスのロックは再帰的であることに注意すべきです。

SDL::Surface#must_lock?
SDL::Surface#mustLock?
サーフェスのピクセルに直接アクセスするときに SDL::Surface#lock による ロックが必要かどうかを true/false で返します。
SDL::Surface.load_bmp(filename)
SDL::Surface.loadBMP(filename)

Windows の BMP ファイルからサーフェスをロードします。

SDL::Surfaceのインスタンスを返します。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#save_bmp(filename)
SDL::Surface#saveBMP(filename)

selfの内容をWindows の BMP ファイル filename にセーブします。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#set_color_key(flag,key)
SDL::Surface#setColorKey(flag,key)

blit 転送可能なサーフェスのカラーキー(透明ピクセル)をセットし、 RLE アクセラレーションを有効または無効にします。 keyはピクセル値もしくは色を表す配列で指定できます。

RLE (Run-length encoding) アクセラレーションは、 透明ピクセル(つまりkeyと同じ値のピクセル)が 水平方向に長く続いている場合に、 画像の blit 転送を実質スピードアップさせることができます。 keyとしてピクセル値を使う場合、selfと 同じピクセルフォーマットのものでなければいけません。

flag が SDL::SRCCOLORKEY ならば、key は転送元の画像の透明色です。

flag に SDL::RLEACCEL が セットされている場合は、 SDL.blit_surface で描かれる時に、 サーフェスは RLE アクセラレーションを使って描きます。 最初にサーフェスに対して SDL.blit_surface か SDL::Surface#display_format が 呼ばれた時に、実際に RLE アクセラレーションのためエンコードされます。

flag が 0 ならば、この関数は現在のカラーキーをクリアします。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#set_alpha(flags,alpha)
SDL::Surface#setAlpha(flags,alpha)

このメソッドはサーフェス単位のα値をセットしたり、 αブレンディングを有効に、また無効にするために使われます。

flags は、αブレンディングが使われるべきかどうか SDL::SRCALPHA、 また blit の際に RLE アクセラレーションを使うべきかどうか SDL::RLEACCELを指定するのに使われます。 flags はこれらの 2 つのオプションの OR による 組み合わせか、どちらか 1 つか、または 0 になり得るでしょう。 SDL::SRCALPHA がフラグとして渡されないと、 サーフェスを blit するときに全てのα情報は無視されます。 alpha パラメータはサーフェス単位のα値です。 つまり、サーフェス単位のαを使うには、サーフェスのαチャンネルは不要であり、 blit は未だ SDL::RLEACCEL によってアクセラレートされる ことが可能です。

αは以下の方法でサーフェスの blit に影響を及ぼします。

RGBA->RGB SDL::SRCALPHA あり
転送元のピクセルはαチャンネルを使って転送先のピクセルとαブレンドされます。
RGBA->RGB SDL::SRCALPHA なし
転送元ピクセルから RGB データがコピーされます。 転送元のαチャンネルとサーフェス単位のα値は無視されます。
RGB->RGBA SDL::SRCALPHA あり
転送元ピクセルはサーフェス単位のα値を使って転送先ピクセルとαブレンドされます。 SDL::SRCCOLORKEY がセットされている場合は、 カラーキーの値と一致しないピクセルだけがコピーされます。 コピーされるピクセルのαチャンネルは不透明にセットされます。
RGB->RGBA SDL::SRCALPHA なし
RGB データは転送元のピクセルからコピーされ、コピーされたピクセルのα値は不透明にセットされます。 SDL::SRCCOLORKEY がセットされている場合は、 カラーキーの値に一致しないピクセルだけがコピーされます。
RGBA->RGBA SDL::SRCALPHA あり
転送元のピクセルはαチャンネルを使って転送先のピクセルとαブレンドされます。 転送先のピクセルのαチャンネルは変更されません。 SDL::SRCCOLORKEY は無視されます。
RGBA->RGBA SDL::SRCALPHA なし
RGBA データが転送先サーフェスにコピーされます。 SDL::SRCCOLORKEY がセットされている場合は、 カラーキーの値と一致しないピクセルだけがコピーされます。
RGB->RGB SDL::SRCALPHA あり
転送元ピクセルはサーフェス単位のα値を使って転送先ピクセルとαブレンドされます。 SDL::SRCCOLORKEY がセットされている場合は、 カラーキーの値と一致しないピクセルだけがコピーされます。
RGB->RGB SDL::SRCALPHA なし
転送元ピクセルから RGB データがコピーされます。 SDL::SRCCOLORKEY がセットされている場合は、 カラーキーの値と一致しないピクセルだけがコピーされます。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#set_clip_rect(x,y,w,h)
SDL::Surface#setClipRect(x,y,w,h)

サーフェスのクリッピング矩形をセットします。 このサーフェスが blit 転送の転送先である場合は、 クリッピング矩形の内部の領域だけが描画されます。

引数によって指定された矩形はサーフェスの端でクリッピングされ、 サーフェスに対するクリッピング矩形がサーフェスの端に出ないようにします。

SDL::Surface#get_clip_rect
SDL::Surface#getClipRect

サーフェスのクリッピング矩形を取得します。 このサーフェスが blit の転送の場合は、 クリッピング矩形の内部の領域のみが描画されます。

[x, y, w, h]という整数4個の配列を返します。

SDL.blit_surface(src,srcX,srcY,srcW,srcH,dst,dstX,dstY)
SDL.blitSurface(src,srcX,srcY,srcW,srcH,dst,dstX,dstY)

転送元サーフェスから転送先サーフェスへ高速 blit 転送を行います srcが転送元、dstが転送先のサーフィスとなります。 srcX、srcY、srcW、srcHがすべて0の場合はsrc 全体がコピーされます。

blit 関数はロックされたサーフェス上で呼ばれるべきではありません。

blit 操作の結果は SDL::SRCAPLHA がセットされているか否かによって 大きく変化します。 これがどのように結果に影響するかについては、 Surface#set_alpha を見て下さい。 以下の擬似コードのようにカラーキーとα属性もサーフェスの blit に作用します。

if 転送元サーフェスに SDL::SRCALPHA がセットされている
  if 転送元サーフェスにαチャンネルがある (つまり Amask != 0)
    ピクセル単位のα値を使い、カラーキーを無視して blit
  elsif 転送元サーフェスに SDL::SRCCOLORKEY がセットされている
    カラーキーとサーフェス単位のα値を使って blit
  else
    サーフェス単位のα値を使って blit
  end
elsif 転送元サーフェスに SDL::SRCCOLORKEY がセットされている
  カラーキーを使って blit
else
  普通の矩形 blit
end

成功時には0を返します。 どちらかのサーフェスがビデオメモリにあり、このメソッドが -2 を返す場合は、ビデオメモリが失われたため、 画像込みでもう一度ロードして blit する必要があります。

これは DirextX5.0 の下で、 システムがあなたのフルスクリーンアプリケーションを切り換える時に発生します。 あなたがビデオメモリに再度アクセスするまでは サーフェスのロックも失敗するでしょう。

SDL::Surface#fill_rect(x,y,w,h,color)
SDL::Surface#fillRect(x,y,w,h,color)

与えられた矩形領域と color で 高速な塗り潰しを行います。 colorは色、ピクセルフォーマット、ピクセル値についてに書かれて いる方法で指定できます。

色の値がα値を含んでいる場合は、塗り潰し先は単にそのα情報で「塗り潰され」、 ブレンディングは起こりません。 塗り潰し先にクリッピング矩形がある場合(SDL::Surface#set_clip_rectに よってセットされます)は、この関数はクリッピング矩形と 指定した矩形が 重なった領域でクリッピングされます。

失敗したときには例外SDL::Errorを発生させます。

SDL::Surface#display_format
SDL::Surface#displayFormat

このメソッドはselfを表示サーフェス上への高速 blit に適するように、 ビデオフレームバッファのピクセルフォーマットとパレットの 新しいサーフェスを作ります。

ハードウェアによるカラーキーやαの blit 転送のアクセラレーション の利点を得たい場合は、 このメソッドを呼ぶ前にカラーキーとα値をセットしておくべきです。

変換後のサーフェスを返します。

変換に失敗するか、メモリを使い切った時は例外SDL::Errorを返します。

SDL::Surface#display_format_alpha
SDL::Surface#displaFormatAlpha

このメソッドはselfを表示サーフェス上への高速 blit に適するように、 ビデオフレームバッファのピクセルフォーマット・色にαチャンネルを加えた 新しいサーフェスにコピーします。

ハードウェアによるカラーキーやαの blit 転送のアクセラレーション の利点を得たい場合は、 このメソッドを呼ぶ前にカラーキーとα値をセットしておくべきです。

selfに SDL::SRCCOLORKEY フラグがセットされている 場合は、この関数はカラーキーをαチャンネルに変換することに使うことが できます。 そうして生成されたサーフェスは、 カラーキーに一致するピクセルでは透明(α=0)に、 他の場所では不透明(α=255)になります。

変換後のサーフェスを返します。

変換に失敗するか、メモリを使い切った時は例外SDL::Errorを返します。

SDL::Surface#flags

サーフェスにセットされているフラグを返します。以下のフラグが サポートされています。

SDL::SWSURFACE
サーフェスがシステムメモリに格納されます。
SDL::HWSURFACE
サーフェスがビデオメモリに格納されます。
SDL::ASYNCBLIT
可能であればサーフェスは非同期 blit 転送を使用します。
SDL::ANYFORMAT
任意のピクセルフォーマットを許可します。(表示サーフェス)
SDL::HWPALETTE
サーフェスには排他的なパレットがあります。
SDL::DOUBLEBUF
サーフェスはダブルバッファです。(表示サーフェス)
SDL::FULLSCREEN
サーフェスはフルスクリーンです。(表示サーフェス)
SDL::OPENGL
サーフェスには OpenGL コンテキストがあります。(表示サーフェス)
SDL::OPENGLBLIT
サーフェスは OpenGL への blit 転送をサポートします。(表示サーフェス)
SDL::RESIZABLE
サーフェスはサイズ変更が可能です。(表示サーフェス)
SDL::HWACCEL
サーフェスの blit 転送にはハードウェアアクセラレーションを使います。
SDL::SRCCOLORKEY
サーフェスはカラーキー付き blit 転送を使います。
SDL::RLEACCEL
カラーキー付き blit 転送は RLE (ランレングス圧縮)による アクセラレーションが利きます。
SDL::SRCALPHA
サーフェスの blit 転送はαブレンディングを使います。

以上のフラグの OR を取ったものが返されます。

SDL::Surface#w
サーフェスの幅のピクセル数を整数で返します。
SDL::Surface#h
サーフェスの高さのピクセル数を整数で返します。
SDL::Surface#pixels
実際のピクセルデータをStringのインスタンスで返します。 ピクセルデータの形式はSDL::Surface#flags、SDL::Surface#[RGBA]mask、 SDL::Surface#bppによります。
SDL::Surface#Rmask
赤チャンネルの値を取得するのに使われるビットマスクを整数で返します。
SDL::Surface#Gmask
緑チャンネルの値を取得するのに使われるビットマスクを整数で返します。
SDL::Surface#Bmask
青チャンネルの値を取得するのに使われるビットマスクを整数で返します。
SDL::Surface#Amask
αチャンネルの値を取得するのに使われるビットマスクを整数で返します。
SDL::Surface#colorkey
透明ピクセルのピクセル値を正の整数で返します。
SDL::Surface#alpha
サーフェス全体のα値を0から255までの整数で返します。 0が透明で、255が不透明です。
SDL::Surface#bpp
サーフェスの各ピクセルを表わすのに使われるビット数を返します。 通常8、16、24、32のいずれかです。
SDL::Surface.load(filename)

画像のファイルをサーフェスにロードします。 もし画像の形式が透明ピクセルをサポートしているならば、サーフェスに カラーキーがセットされます。

対応しているフォーマットはBMP, PNM (PPM/PGM/PBM), XPM, XCF, PCX, GIF, JPEG, TIFF, TGA, PNG, LBMです。

失敗したときには例外SDL::Errorを発生させます。

このメソッドを使うには SDL_image が必要です。

SDL::Surface#put_pixel(x, y, color)
SDL::Surface#putPixel(x, y, color)
SDL::Surface#[x, y] = color

サーフェスの(x, y)で指定した位置にcolorのピクセルを描画します。 colorとしてピクセル値もしくは色を表わす配列が利用できます。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

SDL::Surface#get_pixel(x, y)
SDL::Surface#getPixel(x, y)
SDL::Surface#[x, y]

サーフェスの(x, y)で指定した位置のピクセル値を得ます。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

SDL::Surface#put(src, x, y)

selfの(x, y)で指定した位置にサーフェス src を高速 blit 転送 します。

これは、

SDL.blit_surface(src, 0, 0, src.w, src.h, self, x, y)

と同じです。

SDL::Surface#copy_rect(x,y,w,h)
SDL::Surface#copyRect(x,y,w,h)

サーフェス self の (x, y, w, h) で指定される矩形を コピーした新しいサーフェスを作り、返します。

失敗したときには例外SDL::Errorを発生させます。

SDL.auto_lock?
SDL.autoLock?
SDL.auto_lock
SDL.autoLock

サーフェスに対するロックが必要な操作をするとき、 Ruby/SDLが自動的にロック/アンロックするか どうかを true/false で返します。デフォルトでは true です。

このメソッドを使うには SGE が必要です。

SDL.auto_lock_on
SDL.autoLockON

自動ロックを利用するようにします。これを呼ぶとSDL.auto_lock?が真に なります。

このメソッドを使うには SGE が必要です。

SDL.auto_lock_off
SDL.autoLockOFF

自動ロックを利用しないようにします。これを呼ぶとSDL.auto_lock?が偽に なります。

このメソッドを使うには SGE が必要です。

SDL.auto_lock=(locking)
SDL.autoLock=(locking)

自動ロックを使うかどうかを設定します。 SDL.auto_lock = true は SDL.auto_lock_on と同じで、 SDL.auto_lock = false は SDL.auto_lock_off と 同じです。

このメソッドを使うには SGE が必要です。

SDL.transform(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)

srcを回転縮小拡大したものをdstに描画します。 angleは回転角度(単位はラジアンではなく度)、xscale、yscaleは それぞれX方向とY方向の倍率、(px, py) は srcにおける回転の 中心で、その点がdstの(qx, qy)にくるように描画されます。 また、flagsとしては以下の値のORを取ったものを与えます。

0
普通
SDL::TRANSFORM_SAFE
src と dst のピクセルフォーマットが異なっていても正しく描画します。 src.bpp と dst.bpp が異なる場合は自動的に有効になります。 ただしれを有効にすると遅くなります。
SDL::TRANSFORM_AA
補完描画をします。遅いがみためが良くなります。
SDL::TRANSFORM_TMAP
テクスチャマッピングを使います。すこし速くなるが見た目は悪くなります。 このフラグを有効にした場合 px 、py や上で挙げたフラグを無視します。

このメソッドを使うには SGE が必要です。

SDL.transform_blit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)
SDL.transformBlit(src,dst,angle,xscale,yscale,px,py,qx,qy,flags)

回転縮小拡大描画をします。引数の意味などは SDL.transform と同様です。 SDL.transform との違いは src に設定されたカラーキー(抜き色) およびアルファブレンディングが有効になることです。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_line(x1,x2,y1,y2,color)
SDL::Surface#drawLine(x1,x2,y1,y2,color)

(x1, y1)から(x2, y2)までの直線を color で指定した色で 描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_line(x1,x2,y1,y2,color)
SDL::Surface#drawAALine(x1,x2,y1,y2,color)

(x1, y1)から(x2, y2)までの直線を color で指定した色で アンチエイリアスして描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_line_alpha(x1,x2,y1,y2,color,alpha)
SDL::Surface#drawLineAlpha(x1,x2,y1,y2,color,alpha)

(x1, y1)から(x2, y2)までの直線を color で指定した色、 alphaで指定したα値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_line_alpha(x1,x2,y1,y2,color,alpha)
SDL::Surface#drawAALineAlpha(x1,x2,y1,y2,color,alpha)

(x1, y1)から(x2, y2)までの直線を color で指定した色、 alphaで指定したα値でアンチエイリアスをかけて描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_rect(x,y,w,h,color)
SDL::Surface#drawRect(x,y,w,h,color)

(x, y)が左上の点でwが幅、hが高さの長方形を color で 指定した色で描画します。中を塗り潰しません。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_rect_alpha(x,y,w,h,color,alpha)
SDL::Surface#drawRectAlpha(x,y,w,h,color,alpha)

(x, y)が左上の点でwが幅、hが高さの長方形を color で 指定した色、alpha で指定したα値で描画します。中を塗り潰しません。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_filled_rect_alpha(x,y,w,h,color,alpha)
SDL::Surface#drawFilledRectAlpha(x,y,w,h,color,alpha)

(x, y)が左上の点でwが幅、hが高さの中を塗り潰した 長方形を color で指定した色、alpha で指定したα値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_circle(x,y,r,color)
SDL::Surface#drawCircle(x,y,r,color)

中心 (x,y)、半径 rの円を color で指定した色で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_filled_circle(x,y,r,color)
SDL::Surface#drawFilledCircle(x,y,r,color)

中心 (x,y)、半径 rの円を color で指定した色で中を 塗り潰して描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_circle(x,y,r,color)
SDL::Surface#drawAACircle(x,y,r,color)

中心 (x,y)、半径 rの円を color で指定した色で アンチエイリアスをかけて描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_filled_circle(x,y,r,color)
SDL::Surface#drawAAFilledCircle(x,y,r,color)

中心 (x,y)、半径 rの円を color で指定した色で 中を塗り潰しアンチエイリアスをかけて描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_circle_alpha(x,y,r,color,alpha)
SDL::Surface#drawCircleAlpha(x,y,r,color,alpha)

中心 (x,y)、半径 rの円を color で指定した色、 alphaで指定したアルファ値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_filled_circle_alpha(x,y,r,color,alpha)
SDL::Surface#drawFilledCircleAlpha(x,y,r,color,alpha)

中心 (x,y)、半径 rの中を塗り潰した円を color で指定した色、 alphaで指定したアルファ値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_circle_alpha(x,y,r,color,alpha)
SDL::Surface#drawAACircleAlpha(x,y,r,color,alpha)

中心 (x,y)、半径 rの円を color で指定した色、 alphaで指定したアルファ値でアンチエイリアスで描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_ellipse(x,y,rx,ry,color)
SDL::Surface#drawEllipse(x,y,rx,ry,color)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_filled_ellipse(x,y,rx,ry,color)
SDL::Surface#drawFilledEllipse(x,y,rx,ry,color)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色で中を 塗り潰して描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_ellipse(x,y,rx,ry,color)
SDL::Surface#drawAAEllipse(x,y,rx,ry,color)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色で アンチエイリアスをかけて描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_filled_ellipse(x,y,rx,ry,color)
SDL::Surface#drawAAFilledEllipse(x,y,rx,ry,color)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色で 中を塗り潰しアンチエイリアスをかけて描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_ellipse_alpha(x,y,rx,ry,color,alpha)
SDL::Surface#drawEllipseAlpha(x,y,rx,ry,color,alpha)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色、 alphaで指定したアルファ値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_filled_ellipse_alpha(x,y,rx,ry,color,alpha)
SDL::Surface#drawFilledEllipseAlpha(x,y,rx,ry,color,alpha)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の中を塗り潰した楕円を color で指定した色、 alphaで指定したアルファ値で描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_ellipse_alpha(x,y,rx,ry,color,alpha)
SDL::Surface#drawAAEllipseAlpha(x,y,rx,ry,color,alpha)

中心 (x,y)、X方向の半径 xr、Y方向の半径 ry の楕円を color で指定した色、 alphaで指定したアルファ値でアンチエイリアスで描画します。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_bezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)
SDL::Surface#drawBezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)

(x1, y1) から (x4, y4)までのベジエ曲線を (x2, y2) と (x3, y3) をコントロールポイントとして colorで指定した色で 描画する。leve は曲線の近似度で、4から7を使うと良い。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_bezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)
SDL::Surface#drawAABezier(x1,y1,x2,y2,x3,y3,x4,y4,level,color)

(x1, y1) から (x4, y4)までのベジエ曲線を (x2, y2) と (x3, y3) をコントロールポイントとして colorで指定した色でアンチエイリアスして 描画する。leve は曲線の近似度で、4から7を使うと良い。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_bezier_alpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)
SDL::Surface#drawBezierAlpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)

(x1, y1) から (x4, y4)までのベジエ曲線を (x2, y2) と (x3, y3) をコントロールポイントとして colorで指定した色、alphaで指定したα値で 描画する。leve は曲線の近似度で、4から7を使うと良い。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#draw_aa_bezier_alpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)
SDL::Surface#drawAABezierAlpha(x1,y1,x2,y2,x3,y3,x4,y4,level,color,alpha)

(x1, y1) から (x4, y4)までのベジエ曲線を (x2, y2) と (x3, y3) をコントロールポイントとして colorで指定した色、alphaで指定したα値でアンチエイリアス 描画する。leve は曲線の近似度で、4から7を使うと良い。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。

このメソッドを使うには SGE が必要です。

SDL::Surface#transform_surface(bgcolor,angle,xscale,yscale,flags)
SDL::Surface#transformSurface(bgcolor,angle,xscale,yscale,flags)

self を拡大縮小変形したサーフェスを生成し返す。 回転によって生じた隙間は bgcolor で指定した色で埋められる。 引数 angle、xscale、yscale、flags は SDL.transform と同じ意味である。

新しいサーフェスは self と同じ bpp およびピクセルフォーマットを 持つ。

このメソッドを使うにはサーフェスをロックする必要があります。 SDL.auto_lock?が真の場合はシステムが自動的にロック/アンロックします。 失敗したときには例外SDL::Errorを発生させます。

このメソッドを使うには SGE が必要です。

Event

Event system概要

イベント処理によってあなたのアプリケーションはユーザーからの 入力を受け取ることができます。 イベント処理は次のメソッドを呼ぶことで、(ビデオと一緒に)初期化されます。

SDL.init(SDL::INIT_VIDEO)

内部的には、SDL は処理されるまで待機している全てのイベントをイベントキューに 格納します。

SDL::Event2.poll や SDL::Event2.wait のようなメソッドを使うことで、 待機している入力イベントを見たり、処理することができます。

Ruby/SDLにおけるイベント処理の鍵は、SDL::Event2のサブクラス群です。 イベントキュー自身はSDL::Event2(のサブクラス)のインスタンスの列と みなすことができます。それらのオブジェクトはSDL::Event2.pollを使って キューから読みだされ、 そしてそこに格納された情報の処理をアプリケーションがします。

SDL::Event2のサブクラスは以下の通りです。

イベントクラスには以下の二つの用途があります。

キューからイベントを読み出すには、 SDL::Event2.poll を使います。 ここでは、 SDL::Event2.poll を使った例を示します。

while event = SDL::Event2.poll

SDL::Event2.poll はイベントキューから次のイベントを 取り出して、キューから削除します。キューにイベントがないときは nil を返し、それ以外の場合は上に挙げたイベントクラスのインスタンス を返します。

次に、イベントの種類を判別するために case〜when 文を使います。

case event

次に、どの種類のイベントを知りたいのかということと、起こった イベントの種類を知らなければいけません。 ここでは、アプリケーション内のマウスポインタの動きを知りたいとします。 求めているイベントに対応するクラスはSDL::Event2::MouseMotion であることがわかります。case〜when 文の when の所にクラスを書くと、 そのクラスのインスタンスをcaseに与えたときに分岐することうぃ利用します

when SDL::Event2::MouseMotion

ここでは event は SDL::Event2::MouseMotion のインスタンスなので そのメソッドを使って情報を得ることができます。

puts "マウスカーソルが移動するイベントを受信しました。"
puts "カーソルの位置は(#{event.x}, #{event.y})です。"
else
  puts "ハンドルしていないイベントです!"
end
end
puts "イベントキューは空です。"

イベントキューにイベントを送ることもできますので、 イベントキューを双方向通信に利用することもできます。 SDL::Event2.pushでイベントキューにイベントを送ることができます。 偽の入力イベントを作り出したりするために使うことができます。 ユーザイベントは Ruby/SDL では利用できません。

SDL::Event2

イベントを取り扱うためのクラスです。実際のクラスはこのクラスのサブクラス として表されます。

Event2という名前は互換性のためのものです。これが気にいらない場合は、 ライブラリ読み込みの直後に

module SDL
  remove_const :Event2
  Event = Event2
end

と書いてください。これで SDL::Event という名前で SDL::Event2 に アクセスできます。

SDL::Event2::Active

アプリケーションの可視性に関するイベントのクラスです。

マウスカーソルのウインドウの出入り、 キーボードフォーカスの得失、および 最小化/アイコン化されたり元に戻ったときに発生します。

上のいずれが生じたのかは SDL::Event2::Active#state でわかります。

SDL::Event2::KeyDown

キーボードを押したときに発生するイベントのクラスです。

SDL::Event2::KeyUp

キーボードを離したときに発生するイベントのクラスです。

SDL::Event2::MouseMotion

SDL::Event2::MouseButtonDown

SDL::Event2::MouseButtonUp

SDL::Event2::JoyAxis

SDL::Event2::JoyBall

SDL::Event2::JoyHat

SDL::Event2::JoyButtonUp

SDL::Event2::JoyButtonDown

SDL::Event2::Quit

SDL::Event2::SysWM

SDL::Event2::VideoResize

Methods

SDL::Event2.poll

現在留まっているイベントを取り出し、イベントがあるときはそのイベントを、 無いときは nil を返します。イベントが取り出されたときは キューからそのイベントを削除します。

EXAMPLE

while event = SDL::Event2.poll #キューに残っているイベントがなくなるまでループ
  case event # 適切なイベントタイプを処理
  when SDL::Event2::KeyDown # キー押下イベントを処理
    puts "あ! キーを押しましたね"
  when SDL::Event2::MouseMotion
    .
    .
    .
  else # 未処理のイベントを報告
    puts 私にはよく分からないイベントです!"
  end
end
SDL::Event2.wait

次の利用可能なイベントが来るまで無限に待機し、 イベントが来たらそのイベントを返します。

返したイベントはキューから削除されます。

イベントを待っている間にエラーがあった場合は例外 SDL::Error を 発生させます。

SDL::Event2.push(event)

event で指定したイベントをイベントキューにプッシュします。

失敗したときには例外SDL::Errorを発生させます。

SDL::Event2.app_state
SDL::Event2.appState
アプリケーションの現在の状態を返します。戻り値は以下のビット和です。
SDL::Event2::APPMOUSEFOCUS
マウスのフォーカスがあります。
SDL::Event2::APPINPUTFOCUS
キーボードのフォーカスがあります。
SDL::Event2::APPACTIVE
アプリケーションは可視状態です。
SDL::Event2.enable_unicode
SDL::Event2.enableUNICODE
キーイベントに対応した文字コードを得るために、 まずこの関数を呼び出してUnicode変換を有効にしなければいけません。 変換を有効にすると、キーボードイベントのたびにちょっとした オーバーヘッドが発生するため、デフォルトでは変換は無効になっています。 変換を有効にすると、以後のキーダウンイベントでは、 SDL::Event2::KeyDown#unicode から対応する文字コードが得られます。 対応する文字コードが見つからないときは0が入ります。
SDL::Event2.disable_unicode
SDL::Event2.disableUNICODE
UNICODE変換を無効にします。詳しくは SDL::Event2.enable_unicode を見てください。
SDL::Event2.enable_unicode?
SDL::Event2.enableUNICODE?
UNICODE変換が有効かどうか調べます。詳しくは SDL::Event2.enable_unicode を見てください。
SDL::Event2::Active#gain
可視性を得たことに対応するイベントなら true を、 失ったことに対応するイベントなら false を返します。
SDL::Event2::Active#state

マウスカーソルがウインドウの外に出たり(gain=false)、ウインドウ内に 入ったり(gain=true)したときは、SDL::Event2::APPMOUSEFOCUS を返します。

アプリケーションがキーボードフォーカスを得たり(gain=true) 失ったり(gain=false)したときは、SDL::Event2::APPINPUTFOCUS を 返します。これは通常他のアプリケーションがアクティブに なったときに発生します。

アプリケーションが最小化/アイコン化されたり(gain=false) 元に戻ったとき(gain=true)には SDL::Event2::APPACTIVE を返します。

SDL::Event2::KeyDown#press
常に true を返します。
SDL::Event2::KeyDown#sym
何のキーを押したかをキーシンボルで返します。
SDL::Event2::KeyDown#mod
キー押下時のキーモディファイアの状態を返します。 返り値は SDL::Key.mod_state で得られるものと同じです。
SDL::Event2::KeyDown#unicode

SDL::Event2.enable_unicode によって UNICODE 変換が有効にされた時には、 キーの押下に対応する UNICODE 文字を返します。 文字の上位 9 ビットが 0 の場合は、 ASCII 文字に対応しています。

変換が有効でない場合には0 を返します。

SDL::Event2::KeyUp#press
常に false を返します。
SDL::Event2::KeyUp#sym
何のキーを離したかをキーシンボルで返します。
SDL::Event2::KeyUp#mod
キーモディファイアの状態を返します。 返り値は SDL::Key.mod_state で得られるものと同じです。