Star Ruby Ruby extension library for creating 2D games

This is a class which represents 32bit bitmap with 8 bitmap alpha channel.

Star Ruby supports only PNG format file. It supports alpha channel too.

Class methods

Texture.load(path)

Load an image file into a texture. File extension can be omitted.

Texture.new(width, height)

Make a texture of certain size. All pixels RGBA set as StarRuby::Color.new(0, 0, 0, 0).

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

(It is recommended not to use since ver 0.2.0. Please use Texture#transform_in_perspective method instead.)

Get position and scale of an object at position(x, y) with height after you applied perspective transformation to it.

Return value is an array [(X-coordinate), (Y-coordinate), (scale)]. X coordinate and Y coordinate will be Fixnum, scale will be Floor value. If coordinates exceeds range of Fixnum, those will be nil. So when you use this method, you should check whether all return values are not nil. Return scale can be negative.

You need to set Hash for options. Refer Texture#render_in_perspective method for a list of selectable keys and values.

Instance methods

[](x, y)

[]=(x, y, color)

Get the color of a pixel at (x, y).

Different from render_pixel, this method does not take color of target texture into consideration.

change_hue(d_hue)

change_hue!(d_hue)

change_hue method will generate new texture and return it.change_hue! It is a destructive method

d_hue must be set as radian. when the value is 0, the hue will not be changed.

This transformation is irreversible. Be warned that there are minor inaccuracies.

(Before ver 0.1.5, change_hue was a destructive method.)

clear

Clear all pixels. Equal as fill(Color.new(0, 0, 0, 0)) .

clone

dup

Returns a clone of this texture.

dispose

Release the resource of this texture.

disposed?

If the resource has been already disposed by dispose, return true, otherwise return false.

dump(format)

Dump image data. return String object which represents byte of the image. The length of return String object will be "texture width * texture height * length of the format".

format is constructed by at least one character from the list below.

Argument	Meaning
r	Red component
g	Green component
b	Blue component
a	Alpha component

For example if you set format as "rgba", return value will be a String" object where "red, green, blue, alpha" are ordered repeatedly for each pixel.

The order of pixel is left to right, up to down.

Please refer undump too.

fill(color)

Fill this texture with a chosen color(Color).

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

Fill this texture with a chosen color, color(Color) in rectangular shape.

Unlike render_rect method, color of target texture will be ignored.

get_pixel(x, y)

(It is recommended not to use since ver 0.2.0. Please use [] method instead.)

Get the color of a pixel at (x, y).

height

Get height of this texture.

render_in_perspective(texture, options = {})

Execute perspective projection rendering. self as the screen, texture in arguments as an image of the ground.

As options, you need to pass Hash. Keys and values below can be selected.

Key	Value	Default
:camera_x / :camera_y	Camera's position. Origin is the top left of texture.	0
:camera_angle	(It is recommended not to use since ver 0.1.13. Please use :camera_yaw instead.) Camera's angle.	0
:camera_height	Camera's height from the ground. Negative value is also valid. If it is 0, nothing will be rendered.	0
:camera_yaw / :camera_pitch / :camera_roll	Respectively cameras yaw, pitch and roll.	0
:distance	(It is recommended not to use after Ver 0.2.0. Please use :view_angle instead.) Distance between the camera and the screen.	0
:intersection_x / :intersection_y	Intersect point of the camera ray and the screen. Origin is top left of the screen(self).	0
:vanishing_x / :vanishing_y	(It is recommended not to use after Ver 0.1.13. Please use :intersection_x / :intersection_y instead.) The position of vanishing point. Origin is top right of the screen(self).	0
:view_angle	View angle (0 to π).	π / 4
:loop	Render looped texture or not.	false

Please refer Texture#transform_in_perspective method too.

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

Draw a line from (x1, y1) to (x2, y2) with selected color.

render_pixel(x, y, color)

Put a pixel of color at coordinate (x, y).

Different from []=, it takes color of target texture into consideration.

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

Render a rectangle on a texture in color passed in color (Color).

Different from flll_rect, it takes color of target texture into consideration.

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

Render text as text at coordinate (x, y)

For font you pass an instance of Font which represents font of the text. For color you pass an instance of Color. For anti_alias, pass whether or not to anti-alias the text.

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

Render texture at position (x, y)

You can set self as texture too.(In that case self will be copied inside this method.

(Alpha Blending rule will be written later.)

Bigger alpha value for each pixel of render target (self) and this texture will be used.

As options, you need to pass Hash. Keys and values below can be selected.

Key	Value	Default
:alpha	Opaque(0 - 255).	255
:angle	Rotation radian.	0
:blend_type	Type of blending. :alpha is standard alpha blending, :add is addition, :sub is substraction. If :none was chosen, ignore the render target pixels. (Since ver 0.1.16)。	:alpha
:center_x / :center_y	center point (in pixel) of geometry transform. Origin is the left top of texture.	0
:saturation	Saturation(0 - 255). 0 means complete monochrome.	255
:scale_x / :scale_y	Scale of x and y axis. If negative value was passed, texture will be rendered reversed.	1
:src_width / :src_height	Source area's width and height of texture.	Values after texture's width and height are subtracted by :src_x, :src_y
:src_x / :src_y	X, Y coordinates of texture	0
:tone_red / :tone_green / :tone_blue	Components of hue transformation (-255 - 255). Negative values weaken that component and positive values strengthen the component.	0

Geometry transformation will be processed in order below.

1. Scale the texture :center_x, :center_y as center.
2. Rotate the texture :center_x, :center_y as center.
3. Translate the texture for (x, y).

Color transformation will be processed in order below.

1. Saturation transformation will be done by the value of :saturation.
2. Color transformation will be done by the values of :tone_red / :tone_green / :tone_blue.

save(path, alpha = true)

Save the texture to path as PNG. If alpha means a value of false, ignores alpha value.

set_pixel(x, y, color)

(It is recommended not to use since ver 0.2.0. Please use []= method instead.)

Put color (Color) of pixel at (x, y).

Different from render_pixel, this method does not take color of target texture into consideration.

size

Return array of texture size ([(width), (height)]).

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

Get position and scale of an object at position(x, y) with height after you applied perspective transformation to it.

Return value is an array [(X-coordinate), (Y-coordinate), (scale)]. X coordinate and Y coordinate will be Fixnum, scale will be Floor value. If coordinates exceeds range of Fixnum, those will be nil. So when you use this method, you should check whether all return values are not nil. Return scale can be negative.

You need to set Hash for options. Refer Texture#render_in_perspective method for a list of selectable keys and values.

undump(data, format)

Apply String object specified in data following format.

Refer dump about format of data and format.

Data length must be exactly the same as "texture height * texture width * format length"

width

Get texture width.