Star Ruby Ruby extension library for creating 2D games

32bit αチャンネル付きの画像を表すクラスです。

対応形式は PNG のみです。αチャンネルつきの形式もサポートします。

(今考えると Texture という名前は妙なので、メジャーバージョンを上げるタイミングでクラス名を変えるかもしれません。)

パレットについて

Ver 0.3.0 からパレット画像のパレット情報を利用することができるようになりました。

ロード時に以下のようにオプションを指定する必要があります。

Texture.load("foo", :palette => true)

パレットを持つテクスチャには、以下の制約があります。

• ピクセルを直接変更するようなメソッドを呼ぶとエラーになります。
• パレットテクスチャを複製 (dup/clone) したテクスチャもパレットテクスチャになります。

クラスメソッド

Texture.load(path_or_io, options = {})

画像を指定したファイル名または IO オブジェクトから読み込み、テクスチャを生成します。拡張子を省略することができます。

options には Hash を指定します。指定できるキーと値は、以下の通りです。

キー	値	デフォルト値
:io_length	読み込むバイト数。 nil の場合は EOF に達するまで読みます。path_or_io に IO オブジェクトを指定した場合にのみ有効です。	nil
:palette	パレット情報を保持するかどうかをあらわす真偽値。この値が真値で、かつロードしようとする画像がパレット画像である場合、パレットを保持します。	false

Texture.new(width, height)

指定した大きさの新しいテクスチャを生成します。画素は全て、 StarRuby::Color.new(0, 0, 0, 0) と表される値です。

インスタンスメソッド

[](x, y)

[]=(x, y, color)

(x, y) 座標のピクセルの色 (Color) を取得または設定します。

render_pixel メソッドとは異なり、設定時に下地を考慮しません。

change_hue(d_hue)

change_hue!(d_hue)

色相を変化させます。 change_hue メソッドは新しいテクスチャを生成して返します。 change_hue! メソッドは self を破壊的に変更します。

d_hue はラジアンで指定します。 Numeric#degree メソッドを利用するとあたかも 360 度系で指定したかのように書けます。

0 の場合色相を変化させません。

変換は不可逆変換で、多少の誤差を含みます。

パレット画像に対してこのメソッドを呼び出した場合、パレットの色相を変更した後にピクセルを変化させます。

(Ver 0.1.5 以前は、 change_hue が破壊的メソッドでした。)

change_palette(palette)

change_palette!(palette)

パレットを変更します。 change_palette メソッドは新しいテクスチャを生成して返します。 change_palette! メソッドは self を破壊的に変更します。パレットを変更すると、それに合わせてピクセルも変更されます。

palette は Color オブジェクトの配列を指定します。

パレットを持たない画像に対してこれらのメソッドを呼び出すとエラーになります。

clear

画素を全て消去します。 fill(Color.new(0, 0, 0, 0)) と等価です。

self を返します (Ver 0.3.1 から)。

clone

dup

テクスチャの複製を返します。

パレット情報を持っていた場合、それもコピーされます。

dispose

テクスチャのリソースを解放します。

disposed?

dispose によってリソースが解放済みならば true、それ以外の場合は false を返します。

dump(format)

ピクセルデータをダンプします。バイト列を表す String オブジェクトを返します。返値の String オブジェクトの長さは、「テクスチャの幅×テクスチャの高さ×フォーマットの長さ」です。

format は以下の文字一文字以上から構成される文字列です。

文字	意味
r	赤色成分。
g	緑色成分。
b	青色成分。
a	α値の成分。

たとえば format に "rgba" と指定した場合、返り値は「赤色、緑色、青色、α」とピクセル分並んだ String オブジェクトとなります。

ピクセルの並び順は、左から右、上から下です。

undump も参照してください。

fill(color)

color で指定した色 (Color) でテクスチャを塗りつぶします。描画先 (self) のもともとの色は無視されます。

self を返します (Ver 0.3.1 から)。

fill_rect(x, y, width, height, color)

color で指定した色 (Color) でテクスチャを矩形状に塗りつぶします。

render_rect メソッドとは異なり、塗りつぶされる範囲内では、描画先 (self) のもともと色は無視されます。

self を返します (Ver 0.3.1 から)。

height

高さを取得します。

palette

パレットをあらわす Color オブジェクトの frozen な配列を返します。

render_in_perspective(texture, options = {})

透視変換描画を行います。 self を描画先のスクリーン、引数の texture を地面の画像と見立てます。

self を返します (Ver 0.3.1 から)。

options には Hash を指定します。指定できるキーと値は、以下の通りです。

キー	値	デフォルト値
:blur	水平線近くのぼかし方。:background を指定すると、水平線のα値が 0 になるようなグラデーションになります。 Color オブジェクトを指定すると、水平線がその色になるようなグラデーションになります。 (Ver 0.1.17 から)	nil
:camera_x / :camera_y	カメラの座標。原点は texture の左上点です。	0
:camera_height	カメラの地面からの高さ。負の値も指定できます。 0 のときは何も描画されません。	0
:camera_yaw / :camera_pitch / :camera_roll	それぞれカメラの左右方向の角度、上下方向の角度、視線を軸とした回転角度。	0
:intersection_x / :intersection_y	カメラの視線とスクリーンとの交点の座標。原点はスクリーン (self) の左上点です。	0 (Ver 0.3.1 以前)、 テクスチャの幅または高さの半分 (Ver 0.3.2 以降)
:view_angle	視野角 (ラジアンで 0 より大きく π より小さい値)。	π/4
:loop	テクスチャをループして描画するか否かを表す真偽値。	false

カメラの角度の単位はラジアンです。 Numeric#degree メソッドを利用するとあたかも 360 度系で指定したかのように書けます。

Texture#transform_in_perspective メソッドも参照してください。

render_line(x1, y1, x2, y2, color)

(x1, y1) を始点、 (x2, y2) を終点として、色 color の線分を描画します。

self を返します (Ver 0.3.1 から)。

render_pixel(x, y, color)

座標 (x, y) に、色 color の点を描画します。

[] メソッドとは異なり、 colorのアルファ値が 255 未満の場合に、下地を考慮して描画します。

self を返します (Ver 0.3.1 から)。

render_rect(x, y, width, height, color)

color で指定した色 (Color) でテクスチャを矩形状に描画します。

flll_rect メソッドとは異なり、 color のアルファ値が 255 未満の場合に、下地を考慮して描画します。

self を返します (Ver 0.3.1 から)。

render_text(text, x, y, font, color, anti_alias = false)

位置 (x, y) に文字列 text を描画します。

font には文字のフォントを表す Font オブジェクトを指定します。 color には描画色を表す Color オブジェクトを指定します。 anti_alias には、アンチエイリアスをかけるかどうかを表す真偽値を指定します。

文字 text は UTF-8 である必要があります。

self を返します (Ver 0.3.1 から)。

render_texture(texture, x, y, options = {})

位置 (x, y) にテクスチャ texture を描画します。

texture に self を指定することもできます。

(αブレンディングのルールをあとで書く)

転送先 (self) のピクセルごとのα値は、転送元 (texture) と転送先のα値のうち、小さくない方が用いられます。

self を返します (Ver 0.3.1 から)。

options には Hash を指定します。指定できるキーと値は、以下の通りです。

キー	値	デフォルト値
:alpha	不透明度 (0 〜 255)。	255
:angle	回転角度。単位はラジアンです。 Numeric#degree メソッドを利用するとあたかも 360 度系で指定したかのように書けます。	0
:blend_type	ブレンドの種類。 :alpha で通常のα合成、 :add で加算合成、 :sub で減算合成を行います。 :mask を指定すると、 texture を白黒のマスク画像 (白が 255 で黒が 0) と見なし、 self の α 値をセットします (Ver 0.2.0 から)。他 :none を指定した場合、描画先を無視して描画します (Ver 0.1.16 から)。	:alpha
:center_x / :center_y	幾何変換の中心の X、 Y 座標。原点はテクスチャの転送元矩形の左上点です。	0
:matrix	幾何変換のための二次正方行列を指定します。 4 要素の配列または 2 要素の配列 2 つが要素となる配列を指定します。 (Ver 0.3.2 から)	[1, 0, 0, 1]
:saturation	彩度 (0 〜 255)。 0 で完全にモノクロになります。	255
:scale_x / :scale_y	X、 Y 軸方向の拡大率。負の値を指定すると反転描画します。	1
:src_width / :src_height	描画元矩形の幅、高さ。	描画元画像幅、高さから、それぞれ :src_x、 :src_y で指定した値を引いた値
:src_x / :src_y	描画元矩形の X、 Y 座標。	0
:tone_red / :tone_green / :tone_blue	色調変換の成分 (-255 〜 255)。負の値を指定するとその成分を弱め、正の値を指定するとその成分を強めます。	0

幾何変換は、以下の順に行われます。

1. :center_x、 :center_y で指定した座標を中心に :matrix で指定した行列による幾何変換を行う。
2. :center_x、 :center_y で指定した座標を中心に拡大縮小変換を行う。
3. :center_x、 :center_y で指定した座標を中心に回転変換を行う。
4. (x, y) だけ平行移動する。

色調変換は、以下の順に行われます。

1. :saturation で指定した彩度変換を行う。
2. :tone_red / :tone_green / :tone_blue で指定した色調変換を行う。

save(path)

テクスチャを、 path に PNG 形式で保存します。

(過去のバージョンで第 2 引数がありましたが、撤廃されました。)

size

大きさを表す配列 ([(幅), (高さ)]) を返します。

transform_in_perspective(x, y, height, options = {})

透視変換を行ったときの、スクリーン (self) における座標およびスケール (拡大率) を取得します。物体が地面の座標 (x, y) および地面からの高さ height の位置にある場合の、スクリーンに投影した座標およびスケールです。

返り値は [(X 座標), (Y 座標), (スケール)] と表される配列です。 X 座標、 Y 座標は Fixnum、スケールは Floor の値となります。座標値が Fixnum の範囲を超える場合、その要素は nil となります。そのため実際に使う場合は、すべての値が nil でないことを確認する必要があります。スケールは負の値の場合もあります。

options には Hash を指定します。指定できるキーと値は、 Texture#render_in_perspective メソッドを参照してください。

undump(data, format)

data で指定されたピクセルデータを表す String オブジェクトを、 format の形式に従ってピクセルデータに適用します。

data および format の形式は、それぞれ dump メソッドの返り値、引数を参照してください。

データの長さは「テクスチャの幅×テクスチャの高さ×フォーマットの長さ」で、過不足なくなければなりません。

dump も参照してください。

width

幅を取得します。